3 Expressions

This version is in HTML, a PDF version can be found in Chapter 3 of Volume 1: Introduction to Ptolemy II.

Authors: Edward A. Lee
Xiaojun Liu
Steve Neuendorffer
Neil Smyth
Yuhong Xiong

3.1 Introduction

In Ptolemy II, models specify computations by composing actors. Many computations, however, are awkward to specify this way. A common situation is where we wish to evaluate a simple algebraic expression, such as "sin(2π(x-1))." It is possible to express this computation by composing actors in a block diagram, but it is far more convenient to give it textually.

The Ptolemy II expression language provides infrastructure for specifying algebraic expressions textually and for evaluating them. The expression language is used to specify the values of parameters, guards and actions in state machines, and for the calculation performed by the Expression actor. In fact, the expression language is part of the generic infrastructure in Ptolemy II, and it can be used by programmers extending the Ptolemy II system. In this chapter, we describe how to use expressions from the perspective of a user rather than a programmer.

3.1.1 Expression Evaluator

Vergil provides an interactive expression evaluator, which is accessed through the File:New menu. This operates like an interactive command shell, and is shown in figure 3.1. It supports a command history. To access the previously entered expression, type the up arrow or Control-P. To go back, type the down arrow or Control-N. The expression evaluator is useful for experimenting with expressions.

3.2 Simple Arithmetic Expressions

3.2.1 Constants and Literals

The simplest expression is a constant, which can be given either by the symbolic name of the constant, or by a literal. By default, the symbolic names of constants supported are PI, pi, E, e, true, false, i, j, NaN, Infinity, PositiveInfinity, NegativeInfinity, MaxUnsignedByte, MinUnsignedByte, MaxInt, MinInt, MaxLong, MinLong, MaxDouble, MinDouble. For example,

 
PI/2.0 
 
is a valid expression that refers to the symbolic name "PI" and the literal "2.0." The constants i and j are the imaginary number with value equal to the square root of -1. The constant NaN is "not a number," which for example is the result of dividing 0.0/0.0. The constant Infinity is the result of dividing 1.0/0.0. The constants that start with "Max" and "Min" are the maximum and minimum values for their corresponding types.

Numerical values without decimal points, such as "10" or "-3" are integers (type int). Numerical values with decimal points, such as "10.0" or "3.14159" are of type double. Numerical values without decimal points followed by the character "l" (el) or "L" are of type long. Unsigned integers followed by "ub" or "UB" are of type unsignedByte, as in "5ub". An unsignedByte has a value between 0 and 255; note that it not quite the same as the Java byte, which has a value between -128 and 127.

Numbers of type int, long, or unsignedByte can be specified in decimal, octal, or hexadecimal. Numbers beginning with a leading "0" are octal numbers. Numbers beginning with a leading "0x" are hexadecimal numbers. For example, "012" and "0xA" are both equal to the integer 10.

A complex is defined by appending an "i" or a "j" to a double for the imaginary part. This gives a purely imaginary complex number which can then leverage the polymorphic operations in the Token classes to create a general complex number. Thus "2 + 3i" will result in the expected complex number. You can optionally write this "2 + 3*i".

Literal string constants are also supported. Anything between double quotes, "...", is interpreted as a string constant. The following built-in string-valued constants are defined:
TABLE 1: String-valued constants defined in the expression language.
Variable name Meaning Property name Example under Windows
PTII The directory in which Ptolemy II is installed ptolemy.ptII.dir c:\tmp
HOME The user home directory user.home c:\Documents and Settings\you
CWD The current working directory user.dir c:\ptII
TMPDIR The temporary directory java.io.tmpdir c:\Documents and Settings\you\Local Settings\Temp

The value of these variables is the value of the Java virtual machine property, such as user.home. The properties user.dir and user.home are standard in Java. Their values are platform dependent; see the documentation for the java.lang.System.getProperties() method for details. Note that user.dir and user.home are usually not readable in unsigned applets, in which case, attempts to use these variables in an expression will result in an exception. Vergil will display all the Java properties if you invoke JVM Properties in the View menu of a Graph Editor.

The ptolemy.ptII.dir property is set automatically when Vergil or any other Ptolemy II executable is started up. You can also set it when you start a Ptolemy II process using the java command by a syntax like the following:

 
java -Dptolemy.ptII.dir=${PTII} classname 
 
where classname is the full class name of a Java application.

The constants() utility function returns a record with all the globally defined constants. If you open the expression evaluator and invoke this function, you will see that its value is something like:

 
{CWD="C:\ptII\ptolemy\data\expr", E=2.718281828459,
 HOME="C:\Documents and Settings\eal", Infinity=Infinity,
 MaxDouble=1.7976931348623E308, MaxInt=2147483647,
 MaxLong=9223372036854775807L, MaxUnsignedByte=255ub,
 MinDouble=4.9E-324, MinInt=-2147483648, MinLong=-9223372036854775808L,
 MinUnsignedByte=0ub, NaN=NaN, NegativeInfinity=-Infinity, PI=3.1415926535898,
 PTII="c:\ptII", PositiveInfinity=Infinity, boolean=false, complex=0.0 + 0.0i,
 double=0.0, e=2.718281828459, false=false, fixedpoint=fix(0.0,2,1),
 general=present, i=0.0 + 1.0i, int=0, j=0.0 + 1.0i, long=0L, matrix=[],
 object=object(null),pi=3.1415926535898, scalar=present, string="",
 true=true, unknown=present, unsignedByte=0ub} 

3.2.2 Variables

Expressions can contain identifiers that are references to variables within the scope of the expression. For example,

 
PI*x/2.0 
 
is valid if "x" is a variable in scope. In the expression evaluator, the variables that are in scope include the built-in constants plus any assignments that have been previously made. For example,
 
>> x = pi/2 
1.5707963267949 
>> sin(x) 
1.0 
>> 
 
In the context of Ptolemy II models, the variables in scope include all parameters defined at the same level of the hierarchy or higher. So for example, if an actor has a parameter named "x" with value 1.0, then another parameter of the same actor can have an expression with value "PI*x/2.0", which will evaluate to π/2.

Consider a parameter P in actor X which is in turn contained by composite actor Y. The scope of an expression for P includes all the parameters contained by X and Y, plus those of the container of Y, its container, etc. That is, the scope includes any parameters defined above in the hierarchy.

You can add parameters to actors (composite or not) by right clicking on the actor, selecting "Configure" and then clicking on "Add", or by dragging in a parameter from the utilities library. Thus, you can add variables to any scope, a capability that serves the same role as the "let" construct in many functional programming languages.

3.2.3 Operators

The arithmetic operators are +, -, *, /, ^, and %. Most of these operators operate on most data types, including arrays, records, and matrices. The ^ operator computes "to the power of" or exponentiation where the exponent can only be an int or an unsignedByte.

The unsignedByte, int and long types can only represent integer numbers. Operations on these types are integer operations, which can sometimes lead to unexpected results. For instance, 1/2 yields 0 if 1 and 2 are integers, whereas 1.0/2.0 yields 0.5. The exponentiation operator '^' when used with negative exponents can similarly yield unexpected results. For example, 2^-1 is 0 because the result is computed as 1/(2^1).

The % operation is a modulo or remainder operation. The result is the remainder after division. The sign of the result is the same as that of the dividend (the left argument). For example,

 
>> 3.0 % 2.0 
1.0 
>> -3.0 % 2.0 
-1.0 
>> -3.0 % -2.0 
-1.0 
>> 3.0 % -2.0 
1.0 
 
The magnitude of the result is always less than the magnitude of the divisor (the right argument). Note that when this operator is used on doubles, the result is not the same as that produced by the remainder() function (see Table 5). For instance,
 
>> remainder(-3.0, 2.0) 
1.0 
 
The remainder() function calculates the IEEE 754 standard remainder operation. It uses a rounding division rather than a truncating division, and hence the sign can be positive or negative, depending on complicated rules (see remainder()). For example, counter intuitively,
 
>> remainder(3.0, 2.0) 
-1.0 
 

When an operator involves two distinct types, the expression language has to make a decision about which type to use to implement the operation. If one of the two types can be converted without loss into the other, then it will be. For instance, int can be converted losslessly to double, so 1.0/2 will result in 2 being first converted to 2.0, so the result will be 0.5. Among the scalar types, unsignedByte can be converted to anything else, int can be converted to double, and double can be converted to complex. Note that long cannot be converted to double without loss, nor vice versa, so an expression like 2.0/2L yields the following error message:

 
Error evaluating expression "2.0/2L" 
 in .Expression.evaluator 
Because: 
divide method not supported between ptolemy.data.DoubleToken '2.0' and ptolemy.data.LongToken '2L'
because the types are incomparable. 
 

All scalar types have limited precision and magnitude. As a result of this, arithmetic operations are subject to underflow and overflow.

The bitwise operators are &, |, #, and ~. They operate on boolean, unsignedByte, int and long (but not fixedpoint, double or complex). The operator & is bitwise AND, ~ is bitwise NOT, and | is bitwise OR, and # is bitwise XOR (exclusive or, after MATLAB).

The relational operators are <, <=, >, >=, == and !=. They return type boolean. Note that these relational operators check the values when possible, irrespective of type. So, for example,

 
1 == 1.0 
 
returns true. If you wish to check for equality of both type and value, use the equals() method, as in
 
>> 1.equals(1.0) 
false 
 

Boolean-valued expressions can be used to give conditional values. The syntax for this is

 
boolean ? value1 : value2 
 
If the boolean is true, the value of the expression is value1; otherwise, it is value2.

The logical boolean operators are &&, ||, !, & and |. They operate on type boolean and return type boolean. The difference between logical && and logical & is that & evaluates all the operands regardless of whether their value is now irrelevant. Similarly for logical || and |. This approach is borrowed from Java. Thus, for example, the expression "false && x" will evaluate to false irrespective of whether x is defined. On the other hand, "false & x" will throw an exception.

The << and >> operators performs arithmetic left and right shifts respectively. The >>> operator performs a logical right shift, which does not preserve the sign. They operate on unsignedByte, int, and long.

3.2.4 Comments

In expressions, anything inside /*...*/ is ignored, so you can insert comments.

3.3 Uses of Expressions

3.3.1 Parameters

The values of most parameters of actors can be given as expressions1. The variables in the expression refer to other parameters that are in scope, which are those contained by the same container or some container above in the hierarchy. They can also reference variables in a scope-extending attribute, which includes variables defining units, as explained below in section 3.9. Adding parameters to actors is straightforward, as explained in the previous chapter.

3.3.2 Port Parameters

It is possible to define a parameter that is also a port. Such a PortParameter provides a default value, which is specified like the value of any other parameter. When the corresponding port receives data, however, the default value is overridden with the value provided at the port. Thus, this object functions like a parameter and a port. The current value of the PortParameter is accessed like that of any other parameter. Its current value will be either the default or the value most recently received on the port.

A PortParameter might be contained by an atomic actor or a composite actor. To put one in a composite actor, drag it into a model from the utilities library, as shown in figure 3.2. The resulting icon is actually a combination of two icons, one representing the port, and the other representing the parameter. These can be moved separately, but doing so might create confusion, so we recommend selecting both by clicking and dragging over the pair and moving both together.

To be useful, a PortParameter has to be given a name (the default name, "portParameter," is not very compelling). To change the name, right click on the icon and select "Customize Name," as shown in figure 3.2. In the figure, the name is set to "noiseLevel." Then set the default value by either double clicking or selecting "Configure." In the figure, the default value is set to 10.0.

An example of a library actor that uses a PortParameter is the Sinewave actor, which is found in the sources library in Vergil. It is shown in figure 3.3. If you double click on this actor, you can set the default values for frequency and phase. But both of these values can also be set by the corresponding ports, which are shown with grey fill.

3.3.3 String Parameters

Some parameters have values that are always strings of characters. Such parameters support a simple string substitution mechanism where the value of the string can reference other parameters in scope by name using the syntax $name, where name is the name of the parameter in scope. For example, the StringCompare actor in figure 3.4 has as the value of firstString "The answer is $PI". This references the built-in constant PI. The value of secondString is "The answer is 3.1415926535898". As shown in the figure, these two strings are deemed to be equal because $PI is replaced with the value of PI.

3.3.4 Expression Actor

The Expression actor is a particularly useful actor found in the math library. By default, it has one output and no inputs, as shown in Figure 3.5(a). The first step in using it is to add ports, as shown in (b) and (c), resulting in a new icon as shown in (d). Note: In (c) when you click on Add, you will be prompted for a Name (pick one) and a Class. Leave the Class entry blank and click OK. You then specify an expression using the port names, as shown in (e), resulting in the icon shown in (f).

3.3.5 State Machines

Expressions give the guards for state transitions, as well as the values used in actions that produce outputs and actions that set values of parameters in the refinements of destination states. This mechanism was explained in the previous chapter.

3.4 Composite Data Types

3.4.1 Arrays

Arrays are specified with curly brackets, e.g., "{1, 2, 3}" is an array of int, while "{"x", "y", "z"}" is an array of string. The types are denoted "{int}" and "{string}" respectively. An array is an ordered list of tokens of any type, with the only constraint being that the elements all have the same type. If an array is given with mixed types, the expression evaluator will attempt to losslessly convert the elements to a common type. Thus, for example,

 
{1, 2.3} 
 
has value
 
{1.0, 2.3} 
 
Its type is {double}. The elements of the array can be given by expressions, as in the example "{2*pi, 3*pi}." Arrays can be nested; for example, "{{1, 2}, {3, 4, 5}}" is an array of arrays of integers. The elements of an array can be accessed as follows:
 
>> {1.0, 2.3}(1) 
2.3 
 
which yields 2.3. Note that indexing begins at 0. Of course, if name is the name of a variable in scope whose value is an array, then its elements may be accessed similarly, as shown in this example:
 
>> x = {1.0, 2.3} 
{1.0, 2.3} 
>> x(0) 
1.0 
 

Arithmetic operations on arrays are carried out element-by-element, as shown by the following examples:

 
>> {1, 2}*{2, 2} 
{2, 4} 
>> {1, 2}+{2, 2} 
{3, 4} 
>> {1, 2}-{2, 2} 
{-1, 0} 
>> {1, 2}^2 
{1, 4} 
>> {1, 2}%{2, 2} 
{1, 0} 
 
An array can be checked for equality with another array as follows:
 
>> {1, 2}=={2, 2} 
false 
>> {1, 2}!={2, 2} 
true 
 
For other comparisons of arrays, use the compare() function (see Table 5). As with scalars, testing for equality using the == or != operators tests the values, independent of type. For example,
 
>> {1, 2}=={1.0, 2.0} 
true 

3.4.2 Matrices

In Ptolemy II, arrays are ordered sets of tokens. Ptolemy II also supports matrices, which are more specialized than arrays. They contain only certain primitive types, currently boolean, complex, double, fixedpoint, int, and long. Currently unsignedByte matrices are not supported. Matrices cannot contain arbitrary tokens, so they cannot, for example, contain matrices. They are intended for data intensive computations.

Matrices are specified with square brackets, using commas to separate row elements and semicolons to separate rows. E.g., "[1, 2, 3; 4, 5, 5+1]" gives a two by three integer matrix (2 rows and 3 columns). Note that an array or matrix element can be given by an expression. A row vector can be given as "[1, 2, 3]" and a column vector as "[1; 2; 3]". Some MATLAB-style array constructors are supported. For example, "[1:2:9]" gives an array of odd numbers from 1 to 9, and is equivalent to "[1, 3, 5, 7, 9]." Similarly, "[1:2:9; 2:2:10]" is equivalent to "[1, 3, 5, 7, 9; 2, 4, 6, 8, 10]." In the syntax "[p:q:r]", p is the first element, q is the step between elements, and r is an upper bound on the last element. That is, the matrix will not contain an element larger than r. If a matrix with mixed types is specified, then the elements will be converted to a common type, if possible. Thus, for example, "[1.0, 1]" is equivalent to "[1.0, 1.0]," but "[1.0, 1L]" is illegal (because there is no common type to which both elements can be converted losslessly).

Reference to elements of matrices have the form "matrix(n, m)" or "name(n, m)" where name is the name of a matrix variable in scope, n is the row index, and m is the column index. Index numbers start with zero, as in Java, not 1, as in MATLAB. For example,

 
>> [1, 2; 3, 4](0,0) 
1 
>> a = [1, 2; 3, 4] 
[1, 2; 3, 4] 
>> a(1,1) 
4 
 

Matrix multiplication works as expected. For example, as seen in the expression evaluator (see figure 3.1),

 
>> [1, 2; 3, 4]*[2, 2; 2, 2] 
[6, 6; 14, 14] 
 
Of course, if the dimensions of the matrix don't match, then you will get an error message. To do element wise multiplication, use the multipyElements() function (see Table 6). Matrix addition and subtraction are element wise, as expected, but the division operator is not supported. Element wise division can be accomplished with the divideElements() function, and multiplication by a matrix inverse can be accomplished using the inverse() function (see Table 6). A matrix can be raised to an int or unsignedByte power, which is equivalent to multiplying it by itself some number of times. For instance,
 
>> [3, 0; 0, 3]^3 
[27, 0; 0, 27] 
 
A matrix can also be multiplied or divided by a scalar, as follows:
 
>> [3, 0; 0, 3]*3 
[9, 0; 0, 9] 
 
A matrix can be added to a scalar. It can also be subtracted from a scalar, or have a scalar subtracted from it. For instance,
 
>> 1-[3, 0; 0, 3] 
[-2, 1; 1, -2] 
 
A matrix can be checked for equality with another matrix as follows:
 
>> [3, 0; 0, 3]!=[3, 0; 0, 6] 
true 
>> [3, 0; 0, 3]==[3, 0; 0, 3] 
true 
 
For other comparisons of matrices, use the compare() function (see Table 5). As with scalars, testing for equality using the == or != operators tests the values, independent of type. For example,
 
>> [1, 2]==[1.0, 2.0] 
true 
 
To get type-specific equality tests, use the equals() method, as in the following examples:
 
>> [1, 2].equals([1.0, 2.0]) 
false 
>> [1.0, 2.0].equals([1.0, 2.0]) 
true 
>>  

3.4.3 Records

A record token is a composite type containing named fields, where each field has a value. The value of each field can have a distinct type. Records are delimited by curly braces, with each field given a name. For example, "{a=1, b="foo"}" is a record with two fields, named "a" and "b", with values 1 (an integer) and "foo" (a string), respectively. The value of a field can be an arbitrary expression, and records can be nested (a field of a record token may be a record token).

Fields may be accessed using the period operator. For example,

 
{a=1,b=2}.a 
 
yields 1. You can optionally write this as if it were a method call:
 
{a=1,b=2}.a() 
 
The arithmetic operators +, -, *, /, and % can be applied to records. If the records do not have identical fields, then the operator is applied only to the fields that match, and the result contains only the fields that match. Thus, for example,
 
{foodCost=40, hotelCost=100} + {foodCost=20, taxiCost=20} 
 
yields the result
 
{foodCost=60} 
 
You can think of an operation as a set intersection, where the operation specifies how to merge the values of the intersecting fields. You can also form an intersection without applying an operation. In this case, using the intersect() function, you form a record that has only the common fields of two specified records, with the values taken from the first record. For example,
 
>> intersect({a=1, c=2}, {a=3, b=4}) 
{a=1} 
 

Records can be joined (think of a set union) without any operation being applied by using the merge() function. This function takes two arguments, both of which are record tokens. If the two record tokens have common fields, then the field value from the first record is used. For example,

 
merge({a=1, b=2}, {a=3, c=3}) 
 
yields the result {a=1, b=2, c=3}.

Records can be compared, as in the following examples:

 
>> {a=1, b=2}!={a=1, b=2} 
false 
>> {a=1, b=2}!={a=1, c=2} 
true 
 
Note that two records are equal only if they have the same field labels and the values match. As with scalars, the values match irrespective of type. For example:
 
>> {a=1, b=2}=={a=1.0, b=2.0+0.0i} 
true 
 
The order of the fields is irrelevant. Hence
 
>> {a=1, b=2}=={b=2, a=1} 
true 
 
Moreover, record fields are reported in alphabetical order, irrespective of the order in which they are defined. For example,
 
>> {b=2, a=1} 
{a=1, b=2} 
 
To get type-specific equality tests, use the equals() method, as in the following examples:
 
>> {a=1, b=2}.equals({a=1.0, b=2.0+0.0i}) 
false 
>> {a=1, b=2}.equals({b=2, a=1}) 
true 
>>  

3.5 Invoking Methods

Every element and subexpression in an expression represents an instance of the Token class in Ptolemy II (or more likely, a class derived from Token). The expression language supports invocation of any method of a given token, as long as the arguments of the method are of type Token and the return type is Token (or a class derived from Token, or something that the expression parser can easily convert to a token, such as a string, double, int, etc.). The syntax for this is (token).methodName(args), where methodName is the name of the method and args is a comma-separated set of arguments. Each argument can itself be an expression. Note that the parentheses around the token are not required, but might be useful for clarity. As an example, the ArrayToken and RecordToken classes have a length() method, illustrated by the following examples:

 
{1, 2, 3}.length() 
{a=1, b=2, c=3}.length() 
 
each of which returns the integer 3.

The MatrixToken classes have three particularly useful methods, illustrated in the following examples:

 
[1, 2; 3, 4; 5, 6].getRowCount() 
 
which returns 3, and
 
[1, 2; 3, 4; 5, 6].getColumnCount() 
 
which returns 2, and
 
[1, 2; 3, 4; 5, 6].toArray() 
 
which returns {1, 2, 3, 4, 5, 6}. The latter function can be particularly useful for creating arrays using MATLAB-style syntax. For example, to obtain an array with the integers from 1 to 100, you can enter:
 
[1:1:100].toArray() 
 

3.6 Defining Functions

The expression language supports definition of functions. The syntax is:
 
function(arg1:Type, arg2:Type...) 
    function body  
 
where "function" is the keyword for defining a function. The type of an argument can be left unspecified, in which case the expression language will attempt to infer it. The function body gives an expression that defines the return value of the function. The return type is always inferred based on the argument type and the expression. For example:
 
function(x:double) x*5.0 
 
defines a function that takes a double argument, multiplies it by 5.0, and returns a double. The return value of the above expression is the function itself. Thus, for example, the expression evaluator yields:
 
>> function(x:double) x*5.0 
(function(x:double) (x*5.0)) 
>>  
 
To apply the function to an argument, simply do
 
>> (function(x:double) x*5.0) (10.0) 
50.0 
>>  
 
Alternatively, in the expression evaluator, you can assign the function to a variable, and then use the variable name to apply the function. For example,
 
>> f = function(x:double) x*5.0 
(function(x:double) (x*5.0)) 
>> f(10) 
50.0 
>>  
 

Functions can be passed as arguments to certain "higher-order functions" that have been defined (see table Table 9). For example, the iterate() function takes three arguments, a function, an integer, and an initial value to which to apply the function. It applies the function first to the initial value, then to the result of the application, then to that result, collecting the results into an array whose length is given by the second argument. For example, to get an array whose values are multiples of 3, try

 
>> iterate(function(x:int) x+3, 5, 0) 
{0, 3, 6, 9, 12} 
 
The function given as an argument simply adds three to its argument. The result is the specified initial value (0) followed by the result of applying the function once to that initial value, then twice, then three times, etc.

Another useful higher-order function is the map() function. This one takes a function and an array as arguments, and simply applies the function to each element of the array to construct a result array. For example,

 
>> map(function(x:int) x+3, {0, 2, 3}) 
{3, 5, 6} 
 

A typical use of functions in a Ptolemy II model is to define a parameter in a model whose value is a function. Suppose that the parameter named "f" has value "function(x:double) x*5.0". Then within the scope of that parameter, the expression "f(10.0)" will yield result 50.0.

Functions can also be passed along connections in a Ptolemy II model. Consider the model shown in figure 3.6. In that example, the Const actor defines a function that simply squares the argument. Its output, therefore, is a token with type function. That token is fed to the "f" input of the Expression actor. The expression uses this function by applying it to the token provided on the "y" input. That token, in turn, is supplied by the Ramp actor, so the result is the curve shown in the plot on the right.

A more elaborate use is shown in figure 3.7. In that example, the Const actor produces a function, which is then used by the Expression actor to create new function, which is then used by Expression2 to perform a calculation. The calculation performed here adds the output of the Ramp to the square of the output of the Ramp.

Functions can be recursive, as illustrated by the following (rather arcane) example:

 
>> fact = function(x:int,f:(function(x,f) int)) (x<1?1:x*f(x-1,f)) 
(function(x:int, f:function(a0:general, a1:general) int) (x<1)?1:(x*f((x-1), f))) 
>> factorial = function(x:int) fact(x,fact) 
(function(x:int) (function(x:int, f:function(a0:general, a1:general) int) 
   (x<1)?1:(x*f((x-1), f)))
     (x, (function(x:int, f:function(a0:general, a1:general) int)
         (x<1)?1:(x*f((x-1), f))))) 
>> map(factorial, [1:1:5].toArray()) 
{1, 2, 6, 24, 120} 
>>  
 
The first expression defines a function named "fact" that takes a function as an argument, and if the argument is greater than or equal to 1, uses that function recursively. The second expression defines a new function "factorial" using "fact." The final command applies the factorial function to an array to compute factorials.

3.7 Built-In Functions

The expression language includes a set of functions, such as sin(), cos(), etc. The functions that are built in include all static methods of the classes shown in Table 2, which together provide a rich set2. The functions currently available are shown in the tables in the appendix, which also show the argument types and return types.

In most cases, a function that operates on scalar arguments can also operate on arrays and matrices. Thus, for example, you can fill a row vector with a sine wave using an expression like

 
sin([0.0:PI/100:1.0]) 
 
Or you can construct an array as follows,
 
sin({0.0, 0.1, 0.2, 0.3}) 
 
Functions that operate on type double will also generally operate on int or unsignedByte, because these can be losslessly converted to double, but not generally on long or complex.

Tables of available functions are shown in the appendix. For example, Table 4 shows trigonometric functions. Note that these operate on double or complex, and hence on int and unsignedByte, which can be losslessly converted to double. The result will always be double. For example,

 
>> cos(0) 
1.0 
 
These functions will also operate on matrices and arrays, in addition to the scalar types shown in the table, as illustrated above. The result will be a matrix or array of the same size as the argument, but always containing elements of type double

Table 5 shows other arithmetic functions beyond the trigonometric functions. As with the trigonometric functions, those that indicate that they operate on double will also work on int and unsignedByte, and unless they indicate otherwise, they will return whatever they return when the argument is double. Those functions in the table that take scalar arguments will also operate on matrices and arrays. For example, since the table indicates that the max() function can take int, int as arguments, then by implication, it can also take {int}, {int}. For example,

 
>> max({1, 2}, {2, 1}) 
{2, 2} 
 
Notice that the table also indicates that max() can take {int} as an argument. E.g.
 
>> max({1, 2, 3}) 
3 
 
In the former case, the function is applied pointwise to the two arguments. In the latter case, the returned value is the maximum over all the contents of the single argument.

Table 6 shows functions that only work with matrices, arrays, or records (that is, there is no corresponding scalar operation). Recall that most functions that operate on scalars will also operate on arrays and matricesTable 7 shows utility functions for evaluating expressions given as strings or representing numbers as strings. Of these, the eval()) function is the most flexible.

A few of the functions have sufficiently subtle properties that they require further explanation. That explanation is here.
eval() and traceEvaluation()

The built-in function eval() will evaluate a string as an expression in the expression language. For example,

 
eval("[1.0, 2.0; 3.0, 4.0]") 
 
will return a matrix of doubles. The following combination can be used to read parameters from a file:
 
eval(readFile("filename")) 
 
where the filename can be relative to the current working directory (where Ptolemy II was started, as reported by the property user.dir), the user's home directory (as reported by the property user.home), or the classpath, which includes the directory tree in which Ptolemy II is installed.

Note that if eval() is used in an Expression actor, then it will be impossible for the type system to infer any more specific output type than general. If you need the output type to be more specific, then you will need to cast the result of eval(). For example, to force it to type double:

 
>> cast(double, eval("pi/2")) 
1.5707963267949 
 
The traceEvaluation() function evaluates an expression given as a string, much like eval(), but instead of reporting the result, reports exactly how the expression was evaluated. This can be used to debug expressions, particularly when the expression language is extended by users.
random(), gaussian()

The functions random() and gaussian() shown in Table 5 return one or more random numbers. With the minimum number of arguments (zero or two, respectively), they return a single number. With one additional argument, they return an array of the specified length. With a second additional argument, they return a matrix with the specified number of rows and columns.

There is a key subtlety when using these functions in Ptolemy II. In particular, they are evaluated only when the expression within which they appear is evaluated. The result of the expression may be used repeatedly without re-evaluating the expression. Thus, for example, if the value parameter of the Const actor is set to "random()", then its output will be a random constant, i.e., it will not change on each firing. The output will change, however, on successive runs of the model. In contrast, if this is used in an Expression actor, then each firing triggers an evaluation of the expression, and consequently will result in a new random number.

property()

The property() function accesses system properties by name. Some possibly useful system properties are:

remainder()
This function computes the remainder operation on two arguments as prescribed by the IEEE 754 standard, which is not the same as the modulo operation computed by the % operator. The result of remainder(x, y) is , where is the integer closest to the exact value of . If two integers are equally close, then is the integer that is even. This yields results that may be surprising, as indicated by the following examples:
 
>> remainder(1,2) 
1.0 
>> remainder(3,2) 
-1.0 
 
Compare this to
 
>> 3%2 
1 
which is different in two ways. The result numerically different and is of type int, whereas remainder() always yields a result of type double. The remainder() function is implemented by the java.lang.Math class, which calls it IEEEremainder(). The documentation for that class gives the following special cases:
DCT() and IDCT()

The DCT function can take one, two, or three arguments. In all three cases, the first argument is an array of length and the DCT returns an

(4)
for from 0 to , where is the size of the specified array and is the size of the DCT. If only one argument is given, then is set to equal the next power of two larger than . If a second argument is given, then its value is the order of the DCT, and the size of the DCT is . If a third argument is given, then it specifies the scaling factors according to the following table:
TABLE 3: Normalization options for the DCT function
Name Third argument Normalization
Normalized
0
Unnormalized
1
Orthonormal
2

The default, if a third argument is not given, is "Normalized."

The IDCT function is similar, and can also take one, two, or three arguments. The formula in this case is

(5) .

3.8 Fixed Point Numbers

Ptolemy II includes a preliminary fixed point data type. We represent a fixed point value in the expression language using the following format:
 
fix(value, totalBits, integerBits) 
 
Thus, a fixed point value of 5.375 that uses 8 bit precision of which 4 bits are used to represent the (signed) integer part can be represented as:
 
fix(5.375, 8, 4) 
 
The value can also be a matrix of doubles. The values are rounded, yielding the nearest value representable with the specified precision. If the value to represent is out of range, then it is saturated, meaning that the maximum or minimum fixed point value is returned, depending on the sign of the specified value. For example,
 
fix(5.375, 8, 3) 
 
will yield 3.968758, the maximum value possible with the (8/3) precision.

In addition to the fix() function, the expression language offers a quantize() function. The arguments are the same as those of the fix() function, but the return type is a DoubleToken or DoubleMatrixToken instead of a FixToken or FixMatrixToken. This function can therefore be used to quantize double-precision values without ever explicitly working with the fixed-point representation.

To make the FixToken accessible within the expression language, the following functions are available:

fix(5.34, 10, 4) 
This will create a FixToken. In this case, we try to fit the number 5.34 into a 10 bit representation with 4 bits used in the integer part. This may lead to quantization errors. By default the round quantizer is used.
fix([ -.040609, -.001628, .17853 ], 10, 2)  
This will create a FixMatrixToken with 1 row and 3 columns, in which each element is a FixPoint value with precision(10/2). The resulting FixMatrixToken will try to fit each element of the given double matrix into a 10 bit representation with 2 bits used for the integer part. By default the round quantizer is used.
quantize(5.34, 10, 4) 
This will create a DoubleToken. The resulting DoubleToken contains the double value obtained by fitting the number 5.34 into a 10 bit representation with 4 bits used in the integer part. This may lead to quantization errors. By default the round quantizer is used.
quantize([ -.040609, -.001628, .17853 ], 10, 2)  
This will create a DoubleMatrixToken with 1 row and 3 columns. The elements of the token are obtained by fitting the given matrix elements into a 10 bit representation with 2 bits used for the integer part. Instead of being a fixed point value, the values are converted back to their double representation and by default the round quantizer is used.

3.9 Units

Ptolemy II supports units systems, which are built on top of the expression language. Units systems allow parameter values to be expressed with units, such as "1.0 * cm", which is equal to "0.01 * meters". These are expressed this way (with the * for multiplication) because "cm" and "meters" are actually variables that become in scope when a units system icon is dragged in to a model. A few simple units systems are provided (mainly as examples) in the utilities library.

A model using one of the simple provided units systems is shown in figure 3.8. This unit system is called BasicUnits; the units it defines can be examined by double clicking on its icon, or by invoking Configure, as shown in figure 3.9. In that figure, we see that "meters", "meter", and "m" are defined, and are all synonymous. Moreover, "cm" is defined, and given value "0.01*meters", and "in", "inch" and "inches" are defined, all with value "2.54*cm".

In the example in figure 3.8, a constant with value "1.0 * meter" is fed into a Scale actor with scale factor equal to "2.0/ms". This produces a result with dimensions of length over time. If we feed this result directly into a Display actor, then it is displayed as "2000.0 meters/seconds", as shown in figure 3.10, top display. The canonical units for length are meters, and for time are seconds.

In figure 3.8, we also take the result and feed it to the InUnitsOf actor, which performs divides its input by its argument, and checks to make sure that the result is unitless. This tells us that 2 meters/ms is equal to about 78,740 inches/second.

The InUnitsOf actor can be used to ensure that numbers are interpreted correctly in a model, which can be effective in catching certain kinds of critical errors. For example, if in figure 3.8 we had entered "seconds/inch" instead of "inches/second" in the InUnitsOf actor, we would have gotten the exception in figure 3.11 instead of the execution in figure 3.10.

Units systems are built entirely on the expression language infrastructure in Ptolemy II. The units system icons actually represent instances of scope-extending attributes, which are attributes whose parameters are in scope as if those parameters were directly contained by the container of the scope-extending attribute. That is, scope-extending attributes can define a collection of variables and constants that can be manipulated as a unit. In version 2.0 of Ptolemy II, two fairly extensive units systems are provided, CGSUnitBase and ElectronicUnitBase. Nonetheless, these are intended as examples only, and can no doubt be significantly improved and extended.

Appendix A. Tables of Functions
In this appendix, we tabulate the functions available in the expression language. Further explanation of many of these functions is given in section section 3.7 above.
A.1 Trigonometric Functions
TABLE 4: Trigonometric functions.
function argument type(s) return type description
acos double in the range[-1.0, 1.0] or complex double in the range[0.0, pi] or NaN if out of range or complex arc cosine complex case:
asin double in the range[-1.0, 1.0] or complex double in the range[-pi/2, pi/2] or NaN if out of range or complex arc sine complex case:
atan double or complex double in the range [-pi/2, pi/2] or complex arc tangent complex case:
atan2 double, double double in the range [-pi, pi] angle of a vector (note: the arguments are (y, x), not (x, y) as one might expect).
acosh double greater than 1 or complex double or complex hyperbolic arc cosine, defined for both double and complex case by:
asinh double or complex double or complex hyperbolic arc sine complex case:
cos double or complex double in the range , or complex cosine complex case:
cosh double or complex double or complex hyperbolic cosine, defined for double or complex by:
sin double or complex double or complex sine function complex case:
sinh double or complex double or complex hyperbolic sine, defined for double or complex by:
tan double or complex double or complex tangent function, defined for double or complex by:
tanh double or complex double or complex hyperbolic tangent, defined for double or complex by:

A.2 Basic Mathematical Functions
TABLE 5: Basic mathematical functions
function argument type(s) return type description
abs double or int or long or complex double or int or long (complex returns double) absolute value complex case:
angle complex double in the range [-pi, pi] angle or argument of the complex number:
ceil double double ceiling function, which returns the smallest (closest to negative infinity) double value that is not less than the argument and is an integer.
compare double, double int compare two numbers, returning -1, 0, or 1 if the first argument is less than, equal to, or greater than the second.
conjugate complex complex complex conjugate
exp double or complex double in the range[0.0, infinity] or complex exponential function (e^argument) complex case:
floor double double floor function, which is the largest (closest to positive infinity) value not greater than the argument that is an integer.
gaussian double, double or double, double, int, or double, double, int, int double or {double} or [double] one or more Gaussian random variables with the specified mean and standard deviation.
imag complex double imaginary part
isInfinite double boolean return true if the argument is infinite
isNaN double boolean return true if the argument is "not a number"
log double or complex double or complex natural logarithm complex case:
log10 double double log base 10
log2 double double log base 2
max double, double or int, int or long, long or unsignedByte, unsignedByte or {double} or {int} or {long} or {unsignedByte} double or int or long or unsignedByte maximum
min double, double or int, int or long, long or unsignedByte, unsignedByte or {double} or {int} or {long} or {unsignedByte} double or int or long or unsignedByte minimum
neighborhood type, type, double boolean return true if the first argument is in the neighborhood of the second, meaning that the distance is less than or equal to the third argument. The first two arguments can be any type for which such a distance is defined. For composite types, arrays, records, and matrices, then return true if the first two arguments have the same structure, and each corresponding element is in the neighborhood.
pow double, double or complex, complex double or complex first argument to the power of the second
random no arguments or int or int, int double or {double} or [double] one or more random numbers between 0.0 and 1.0
real complex double real part
remainder double, double double remainder after division, according to the IEEE 754 floating-point standard (see remainder()).
round double long round to the nearest long, choosing the next greater integer when exactly in between, and throwing an exception if out of range. If the argument is NaN, the result is 0L. If the argument is out of range, the result is either MaxLong or MinLong, depending on the sign.
roundToInt double int round to the nearest int, choosing the next greater integer when exactly in between, and throwing an exception if out of range. If the argument is NaN, the result is 0. If the argument is out of range, the result is either MaxInt or MinInt, depending on the sign.
sgn double int -1 if the argument is negative, 1 otherwise
sqrt double or complex double or complex square root. If the argument is double with value less than zero, then the result is NaN. complex case:
toDegrees double double convert radians to degrees
toRadians double double convert degrees to radians

A.3 Matrix, Array, and Record Functions.
TABLE 6: Functions that take or return matrices, arrays, or records.
function argument type(s) return type description
arrayToMatrix {type}, int, int [type] Create a matrix from the specified array with the specified number of rows and columns
conjugateTranspose [complex] [complex] Return the conjugate transpose of the specified matrix.
createSequence type, type, int {type} Create an array with values starting with the first argument, incremented by the second argument, of length given by the third argument.
crop [int], int, int, int, int or [double], int, int, int, int or [complex], int, int, int, int or [long], int, int, int, int or [int] or [double] or [complex] or [long] or Given a matrix of any type, return a submatrix starting at the specified row and column with the specified number of rows and columns.
determinant [double] or [complex] double or complex Return the determinant of the specified matrix.
diag {type} [type] Return a diagonal matrix with the values along the diagonal given by the specified array.
divideElements [type], [type] [type] Return the element-by-element division of two matrices
hilbert int [double] Return a square Hilbert matrix, where . A Hilbert matrix is nearly, but not quite singular.
identityMatrixComplex int [complex] Return an identity matrix with the specified dimension.
identityMatrixDouble int [double] Return an identity matrix with the specified dimension.
identityMatrixInt int [int] Return an identity matrix with the specified dimension.
identityMatrixLong int [long] Return an identity matrix with the specified dimension.
intersect record, record record Return a record that contains only fields that are present in both arguments, where the value of the field is taken from the first record.
inverse [double] or [complex] [double] or [complex] Return the inverse of the specified matrix, or throw an exception if it is singular.
matrixToArray [type] {type} Create an array containing the values in the matrix
merge record, record record Merge two records, giving priority to the first one when they have matching record labels.
multiplyElements [type], [type] [type] Multiply element wise the two specified matrices.
orthogonalizeColumns [double] or [complex] [double] or [complex] Return a similar matrix with orthogonal columns.
orthogonalizeRows [double] or [complex] [double] or [complex] Return a similar matrix with orthogonal rows.
orthonormalizeColumns [double] or [complex] [double] or [complex] Return a similar matrix with orthonormal columns.
orthonormalizeRows [double] or [complex] [double] or [complex] Return a similar matrix with orthonormal rows.
repeat int, type {type} Create an array by repeating the specified token the specified number of times.
sort {string}or {realScalar} {string} or {realScalar} Return the specified array, but sorted in ascending order. realScalar is any scalar token except complex.
sortAscending {string}or {realScalar} {string} or {realScalar} Return the specified array, but sorted in ascending order. realScalar is any scalar token except complex.
sortDescending {string}or {realScalar} {string} or {realScalar} Return the specified array, but sorted in descending order. realScalar is any scalar token except complex.
sum {type} or [type] type Sum the elements of the specified array or matrix. This throws an exception if the elements do not support addition or if the array is empty (an empty matrix will return zero).
trace [type] type Return the trace of the specified matrix.
transpose [type] [type] Return the transpose of the specified matrix.
zeroMatrixComplex int, int [complex] Return a zero matrix with the specified number of rows and columns.
zeroMatrixDouble int, int [double] Return a zero matrix with the specified number of rows and columns.
zeroMatrixInt int, int [int] Return a zero matrix with the specified number of rows and columns.
zeroMatrixLong int, int [long] Return a zero matrix with the specified number of rows and columns.

A.4 Functions for Evaluating Expressions

TABLE 7: Utility functions for evaluating expressions
function argument type(s) return type description
eval string any type evaluate the specified expression (see eval()).
parseInt string or string, int int return an int read from a string, using the given radix if a second argument is provided.
parseLong string or string, int int return a long read from a string, using the given radix if a second argument is provided.
toBinaryString int or long string return a binary representation of the argument
toOctalString int or long string return an octal representation of the argument
toString double or int or int, int or long or long, int string return a string representation of the argument, using the given radix if a second argument is provided.
traceEvaluation string string evaluate the specified expression and report details on how it was evaluated (see eval()).

A.5 Signal Processing Functions
TABLE 8: Functions performing signal processing operations
function argument type(s) return type description
convolve {double}, {double} or {complex}, {complex} {double} or {complex} Convolve two arrays and return an array whose length is sum of the lengths of the two arguments minus one. Convolution of two arrays is the same as polynomial multiplication.
DCT {double} or {double}, int or {double}, int, int {double} Return the discrete cosine transform of the specified array, using the specified (optional) length and normalization strategy (see DCT() and IDCT()).
downsample {double}, int or {double}, int, int {double} Return a new array with every -th element of the argument array, where is the second argument. If a third argument is given, then it must be between 0 and , and it specifies an offset into the array (by giving the index of the first output).
FFT {double} or {complex} or {double}, int {complex}, int {complex} Return the fast Fourier transform of the specified array. If the second argument is given with value , then the length of the transform is . Otherwise, the length is the next power of two greater than or equal to the length of the input array. If the input length does not match this length, then input is padded with zeros.
generateBartlettWindow int {double} Return a Bartlett (rectangular) window with the specified length. The end points have value 0.0, and if the length is odd, the center point has value 1.0. For length M + 1, the formula is:
generateBlackmanWindow int {double} Return a Blackman window with the specified length. For length M + 1, the formula is:
generateBlackmanHarrisWindow int {double} Return a Blackman-Harris window with the specified length. For length M + 1, the formula is:
generateGaussianCurve double, double, int {double} Return a Gaussian curve with the specified standard deviation, extent, and length. The extent is a multiple of the standard deviation. For instance, to get 100 samples of a Gaussian curve with standard deviation 1.0 out to four standard deviations, use generateGaussianCurve(1.0, 4.0, 100).
generateHammingWindow int {double} Return a Hamming window with the specified length. For length M + 1, the formula is:
generateHanningWindow int {double} Return a Hanning window with the specified length. For length M + 1, the formula is:
generatePolynomialCurve {double}, double, double, int {double} Return samples of a curve specified by a polynomial. The first argument is an array with the polynomial coefficients, beginning with the constant term, the linear term, the squared term, etc. The second argument is the value of the polynomial variable at which to begin, and the third argument is the increment on this variable for each successive sample. The final argument is the length of the returned array.
generateRaisedCosinePulse double, double, int {double} Return an array containing a symmetric raised-cosine pulse. This pulse is widely used in communication systems, and is called a "raised cosine pulse" because the magnitude its Fourier transform has a shape that ranges from rectangular (if the excess bandwidth is zero) to a cosine curved that has been raised to be non-negative (for excess bandwidth of 1.0). The elements of the returned array are samples of the function:
,
where x is the excess bandwidth (the first argument) and T is the number of samples from the center of the pulse to the first zero crossing (the second argument). The samples are taken with a sampling interval of 1.0, and the returned array is symmetric and has a length equal to the third argument. With an excessBandwidth of 0.0, this pulse is a sinc pulse.
generateRectangularWindow int {double} Return an array filled with 1.0 of the specified length. This is a rectangular window.
IDCT {double} or {double}, int or {double}, int, int {double} Return the inverse discrete cosine transform of the specified array, using the specified (optional) length and normalization strategy (see DCT() and IDCT()).
IFFT {double} or {complex} or {double}, int {complex}, int {complex} Return the inverse fast Fourier transform of the specified array. If the second argument is given with value , then the length of the transform is . Otherwise, the length is the next power of two greater than or equal to the length of the input array. If the input length does not match this length, then input is padded with zeros.
nextPowerOfTwo double int Return the next power of two larger than or equal to the argument.
poleZeroToFrequency {complex}, {complex}, complex, int {complex} Given an array of pole locations, an array of zero locations, a gain term, and a size, return an array of the specified size representing the frequency response specified by these poles, zeros, and gain. This is calculated by walking around the unit circle and forming the product of the distances to the zeros, dividing by the product of the distances to the poles, and multiplying by the gain.
sinc double double Return the sinc function, , where special care is taken to ensure that 1.0 is returned if the argument is 0.0.
toDecibels double double Return , where is the argument.
unwrap {double} {double} Modify the specified array to unwrap the angles. That is, if the difference between successive values is greater than in magnitude, then the second value is modified by multiples of until the difference is less than or equal to . In addition, the first element is modified so that its difference from zero is less than or equal to in magnitude.
upsample {double}, int {double} Return a new array that is the result of inserting zeroes between each successive sample in the input array, where is the second argument. The returned array has length , where L is the length of the argument array. It is required that .

A.6 I/O Functions and Other Miscellaneous Functions
TABLE 9: Miscellaneous functions.
function argument type(s) return type description
asURL string string Return a URL representation of the argument.
cast type1, type2 type1 Return the second argument converted to the type of the first, or throw an exception if the conversion is invalid.
constants none record Return a record identifying all the globally defined constants in the expression language.
findFile string string Given a file name relative to the user directory, current directory, or classpath, return the absolute file name of the first match, or return the name unchanged if no match is found.
freeMemory none long Return the approximate number of bytes available for future memory allocation.
iterate function, int, type {type} Return an array that results from first applying the specified function to the third argument, then applying it to the result of that application, and repeating to get an array whose length is given by the second argument.
map function, {type} {type} Return an array that results from applying the specified function to the elements of the specified array.
property string string Return a system property with the specified name from the environment, or an empty string if there is none. Some useful properties are java.version, ptolemy.ptII.dir, ptolemy.ptII.dirAsURL, and user.dir.
readFile string string Get the string text in the specified file, or throw an exception if the file cannot be found. The file can be absolute, or relative to the current working directory (user.dir), the user's home directory (user.home), or the classpath.
readResource string string Get the string text in the specified resource (which is a file found relative to the classpath), or throw an exception if the file cannot be found.
totalMemory none long Return the approximate number of bytes used by current objects plus those available for future object allocation.

1 The exceptions are parameters that are strictly string parameters, in which case the value of the parameter is the literal string, not the string interpreted as an expression, as for example the function parameter of the TrigFunction actor, which can take on only "sin," "cos," "tan", "asin", "acos", and "atan" as values.

2 Moreover, the set of available can easily be extended if you are writing Java code by registering another class that includes static methods (see the PtParser class in the ptolemy.data.expr package).