TOC PREV NEXT

8  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 set . The functions currently available are shown in the tables in the appendix, which also show the argument types and return types.
Table 2: The classes whose static methods are available as functions in the expression langauge
java.lang.Math ptolemy.math.IntegerMatrixMath
java.lang.Double ptolemy.math.DoubleMatrixMath
java.lang.Integer ptolemy.math.ComplexMatrixMath
java.lang.Long ptolemy.math.LongMatrixMath
java.lang.String ptolemy.math.IntegerArrayMath
ptolemy.data.MatrixToken. ptolemy.math.DoubleArrayStat
ptolemy.data.RecordToken. ptolemy.math.ComplexArrayMath
ptolemy.data.expr.UtilityFunctions ptolemy.math.LongArrayMath
ptolemy.data.expr.FixPointFunctions ptolemy.math.SignalProcessing
ptolemy.math.Complex ptolemy.math.FixPoint
ptolemy.math.ExtendedMath ptolemy.data.ObjectToken
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, short, 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, short 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 10 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, short 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 10 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 matrices. Table 11 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.

8.0.1  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.

8.0.2  random(), gaussian()

random() and gaussian() shown in Table 10 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.

8.0.3  property()

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