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
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 (see page 112). 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 (see page 112) real complex double real part remainder double, double double remainder after division, according to the IEEE 754 floating-point standard (see page 113). 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.
A.4 Functions for Evaluating Expressions
A.5 Signal Processing Functions
TABLE 7: Utility functions for evaluating expressions function argument type(s) return type description eval string any type evaluate the specified expression (see page 112). 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 page 112).
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 page 113). 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 page 113). 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
![]() |
![]() |