Matlab Processor

Creation

To create a new Matlab Processor, select Processors from the menu in the Tools window and then drag "Matlab Interpreter" to an interface window in any open area. A drawer should open from the window and should have the "Interface" tab selected, and "Processors" selected from the menu at the top of the drawer. The Matlab Interpreter should appear in the list. You can change the name of the processor by double-clicking its name in the list.

Configuration

Click the "Configure" button within the drawer, with the processor selected, to open its configuration window. The window has three tabs, corresponding to the three major tasks associated with setting up a processor. The first tab, "Inputs", is where you can set up the data points that the processor uses for input values. In addition to any inputs that are set up, a "time" input is always available within the script which will contain the current UNIX timestamp (seconds since Jan 1, 1970).

Inputs

All input points are associated with an alias; that alias is the name by which the value of the input can be referenced within the matlab script. To add an input, drag a data point from the Data window onto the Inputs table. Once the input is added, set the desired alias, which must be a valid Matlab variable name. Inputs can also be removed by clicking the "-" button below the table.

The inputs tab also contains the control for changing the update rate of the processor. Only a fixed rate is currently supported; use this field to specify how often the processor should run and produce new output values.

Outputs

The outputs tab allows you to create the outputs to which you will assign values within your script. Clicking the small "+" button below the main table will open a sheet that allows you to specify the location that the new output should appear within the data heirarchy, and to give it a name. The output will initially be given an alias identical to the name you gave the output; this can be changed by double-clicking the name in the alias column.

Details of the currently selected output are found in the fields below the main table. It is important to note, first, the "Finalized" checkbox. When this is checked, the output is fully created and can no longer be substantially modified, so it is important to be certain of the output's setup before clicking this box. However, it must be checked before the output can be used in a script.

In addition to finalization, the detail allows the type, units, description and attributes of the output to be set. The Rows and Columns parameters are relevant only to matrices.

Script

The Script tab is very simple: the top box provides space for the script to be entered; the bottom provides logged messages of warnings or errors. The "Check Syntax" button does a syntax check on the code; if the code passes the syntax check, the "Enabled" checkbox will become available to check. When that box is checked, the processor will be active and will produce data. When an error occurs, the processor will automatically disable and a description of the error will print in the bottom text box.

The acceptable syntax for the processor is described below. The important point relative to the processor is the presence of variables for each input and output alias set up in the Inputs and Outputs tab. All inputs are available via their alias, and and Output's value can be set simply by assigning to their alias. Any output not assigned to will not have its value set for that update period.

Language Details

This section describes the language features of the Matlab Processor. The language is based on Matlab, and is a strict subset of it. Not all Matlab language features are included in the expression language, and some language differences exist between it and Matlab.

The reserved words, built-in variables, data types, statements, operators, and built-in functions of this language are described next. Some important differences from Matlab are also described.

Reserved words

The following words are reserved, and cannot be used as variable names. They must be used as expected in their proper place, as in Matlab: break, case, catch, continue, else, elseif, end, for, function, global, if, otherwise, persistent, return, switch, try, and while.

The following reserved words are not currently supported. They will be recognized as tokens, but will not parse correctly: case, catch, elseif, function, global, otherwise, persistent, return, switch, and try.

Implementation notes:

• try-catch is not implemented
• elseif is not implemented (but can be done with nested if-then-else statements)
• switch-case-otherwise is not implemented (but can be done with nested if-then-else statements)
• user-defined functions (and the associated return) are not yet supported
• functions (user-defined and built-in) can only return single values (matrices or doubles), and not multiple return values as in Matlab
• all variables are global in scope, and symbols are first searched for in the data base associated tables
• persistent variables are not supported

Free-form syntax is implemented as in Matlab (statement separators are usually optional (see below for exceptions), statements can span multiple lines, and one line can contain multiple statements. When defining matrices, either semicolons or line breaks can signify the start of new rows.

Built-in variables

The following variable and value names are special, and cannot be assigned new values: ans, eps, intmax, intmin, realmax, realmin, pi, i, j, inf, nan, computer, version, false, and true.

The following variable and value names are not supported. They will also be recognized as tokens, but will not parse properly: ans, i, j, computer, and version.

Implementation notes:

• the Matlab Processor does not currently work with complex numbers (as per MatrixLib)
• because of this, as in Matlab, i and j cannot be used as variable names

Data types

The Matlab Processor language currently supports double (IEEE 754 floating point double precision values), one- and two-dimensional matrices of doubles, and boolean (true or false). Character strings, single-precision floating point values, and strictly integer values are not supported.

Programmer's note: if one is using the MatlabEvaluator C++ object, and defines an input symbol table, any integer sd\_values in that table will be auto converted to doubles before being used.}

Statements

The following statement types are supported in the Matlab Processor:

• statement block: A statement block is a sequence of statements, separated by spaces, semicolons, or commas (no distinction is made in the Matlab Processor, since no textual output is generated). The value of a statement block is the value of the last statement it contains.
• expression: An expression is any valid expression. Some examples include variable names, constants, function calls (to built-in or (later) user-defined functions), or matrix accesses (single elements, or submatrices, using 1-dimensional, 2-dimensional, or linear indexing).
• assignment: An assignment statement gives a variable a new value. Any old value is overwritten. The left hand side of an assignment can be a variable, or a submatrix (single element, or submatrix). The value of the assignment is the value assigned to the left-hand side.
• for/while loop: A for/while loop iterates over a statement block zero or more times. The value of a loop is the value of the last iteration of the statement block (or a special null value if no iterations occur). A maximum loop iteration count is implemented to prevent infinite loops (currently set to 10000).
• if statement: An if statement evaluates its boolean expression, and executes its true statement block if true. It can optionally execute its false statement block if the boolean expression is false. The return value of an if statement is the value of the executed block (or a special null value if no block is executed). If statements can be nested.
• break/continue: A break/continue statement is used inside loops. The break statement exits its enclosing loop, whereas the continue statement skips the rest of the current iteration of its enclosing loop. The value of a break/continue statement alone is a special null value.

Operators

The complete suite of Matlab operators that operate on doubles, matrices and booleans is implemented. The precedence rules are the same as for Matlab. The operators are listed in the following table.

Matrices can only have doubles as elements; because of this, embedded matrices (stacking rows or appending columns) are not supported.

Operators supported in the Matlab Processor.

operator	description	class
.	transpose	arithmetic
^	exponentiation	arithmetic
*	multiplication	arithmetic
/ \	division (and left division)	arithmetic
+ -	addition, subtraction	arithmetic
:	sequence generation	arithmetic
& |	bitwise AND, OR	arithmetic
< <= > >= == ~=	comparison	comparison
~	unary negation	logical
&& ||	logical AND, OR (short-circuit)	logical

Built-in functions

None of the Matlab built-in functions are available. The built-in functions that are available are based on the standard C math library math.h, and Princeton Satellite Systems, Inc. MatrixLib class library.

Matrix versions of functions (those that are implemented via MatrixLib) are prepended with the letter m. All functions return a single value.

The available functions are listed in the following table.

Function supported in the Matlab Processor.

function names	number of inputs	input argument type	return type
acos, asin, atan, cos, sin, tan
acosh, asinh, atanh, cosh, sinh, tanh
exp, exp2, expm1, log, log10, log2	1	double	double
log1p, logb, fabs, cbrt, sqrt
erf, erfc, lgamma, tgamma
ceil, floor, nearbyint, rint, round, trunc
atan2, hypot, pow, fmod, remainder, fmax, fmin	2	double	double
mabs, mceil, mfloor, mround, mrint, msqrt
mexp, mexpm1, mlog, mlog10, mlog1p, mlog2, mlogb
msin, mcos, mtan, mcsc, msec, mcot
masin, macos, matan, macsc, masec, macot	1	matrix	matrix
msinh, mcosh, mtanh, mcsch, msech, mcoth
masinh, macosh, matanh, macsch, masech, macoth
msign, mtranspose, minv, mmag, mq_pose
matan2, mcross, msolve_ax_eq_b	2	matrix	matrix
mq_mult, mq_form, mq_tform

Differences from Matlab

Even in the parts of Matlab that are implemented, there are some differences between the Matlab Processor and in Matlab.

• Space sensitivity. Spaces are not handled exactly as they are in Matlab. An example: the expression 2./x, with no spaces, will be interpreted as 2 ./ x by Matlab, but as 2.\ / x by the Matlab Processor, which is different. To solve this, simply add the spaces around the operator.
• Expression separation. When unary operators appear in a statement list, the statements sometimes need to be separated by commas and not spaces, otherwise the operator can be interpreted as a binary operator (in some cases). As an example, the matrix [2, -2 ; 3 4] requires that comma in the first row, otherwise the Matlab Processor would interpret it as 2-2 which makes the first row only have one element.
• Boolean constants. The Matlab Processor requires the use of true and false, and does not accept numeric values where boolean expressions are expected. In addition, it does not allow the use of matrices (empty = false, non-empty = true) like in Matlab. However, when relational operators operate on matrices, numeric values are returned (as in Matlab); false values are represented as 0, and true values are represented as 1.
• Matrix division. Matlab allows the expression x/y, where x and y are column vectors of the same length; it evaluates the expression to be the solution of the matrix equation in the least squares sense (see the Matlab function mldivide). The Matlab Processor evaluates this as an error, because the underlying MatrixLib routine converts this to x*inv(y), and y is not square.
• Matrix transpose. The Matlab Processor treats the ! and . operators identically, since MatrixLib does not support complex numbers. In Matlab, ' performs a conjugate transpose operation.
• break / continue. If a break or continue statement appears inside a statement block that is not enclosed inside a loop, the Matlab Processor skips the rest of the statement block. In Matlab, this construct is undefined.
• Colon operator. The Matlab Processor handles the statement a:b, where a>b slightly differently than Matlab does. The Matlab Processor evaluates this expression as [a b], so that it can be used in the triple argument version a:b:c. Matlab will return [a] (or in some cases []).
• Submatrix ``last element''. In Matlab, when accessing submatrices, an expression like a(3,5:end) is valid, and returns the fifth through the last elements of the third row of a. The Matlab Processor also supports such a construct, but requires inf instead of end to indicate the "last element".
• Linear indexing. The Matlab Processor supports linear indexing as in Matlab (using a single index to access a two-dimensional matrix). In Matlab, elements are returned in column major order. In the Matlab Processor, they are returned in MatrixLib's order (column major or row major, a compile time option. The current build uses column major order.)

Unsupported language features

The following Matlab language features are not supported in the Matlab Processor.

• ... line continuation
• %{ %} multiline comments
• cell arrays
• structs
• multidimensional arrays of dimension greater than 2
• sparse matrices
• Java classes
• function handles
• deletion of submatrices by assignment to the empty matrix
• operating system shell escapes
• regular expressions