Stateflow®

Using MATLAB^® Functions and Data in Actions

MATLAB^® Functions and Stateflow^® Code Generation

You can call MATLAB^® functions and access MATLAB workspace variables in Stateflow^® actions, using the ml namespace operator or the ml function.

Caution   Because MATLAB functions are not available in a target environment, do not use the ml namespace operator and the ml function if you plan to build a code generation target.

Back to Top

ml Namespace Operator

The ml namespace operator uses standard dot (.) notation to reference MATLAB variables and functions in action language. For example, the statement a = ml.x returns the value of the MATLAB workspace variable x to the Stateflow data a.

For functions, the syntax is as follows:

[return_val1, return_val2,...] = ml.matfunc(arg1, arg2,...)

For example, the statement [a, b, c] = ml.matfunc(x, y) passes the return values from the MATLAB function matfunc to the Stateflow data a, b, and c.

If the MATLAB function you call does not require arguments, you must still include the parentheses, as shown in the preceding examples. If you omit the parentheses, Stateflow software interprets the function name as a workspace variable, which, when not found, generates a run-time error during simulation.

Examples

In these examples, x, y, and z are workspace variables and d1 and d2 are Stateflow data:

• a = ml.sin(ml.x)

  In this example, the MATLAB function sin evaluates the sine of x, which is then assigned to Stateflow data variable a. However, because x is a workspace variable, you must use the namespace operator to access it. Hence, ml.x is used instead of just x.

• a = ml.sin(d1)

  In this example, the MATLAB function sin evaluates the sine of d1, which is assigned to Stateflow data variable a. Because d1 is Stateflow data, you can access it directly.

• ml.x = d1*d2/ml.y

  The result of the expression is assigned to x. If x does not exist prior to simulation, it is automatically created in the MATLAB workspace.

• ml.v[5][6][7] = ml.matfunc(ml.x[1][3], ml.y[3], d1, d2, 'string')

  The workspace variables x and y are arrays. x[1][3] is the (1,3) element of the two-dimensional array variable x. y[3] is the third element of the one-dimensional array variable y. The last argument, 'string', is a literal string.

  The return from the call to matfunc is assigned to element (5,6,7) of the workspace array, v. If v does not exist prior to simulation, it is automatically created in the MATLAB workspace.

Back to Top

ml Function

You can use the ml function to specify calls to MATLAB functions through a string expression in the action language. The format for the ml function call uses this notation:

ml(evalString, arg1, arg2,...);

evalString is a string expression that is evaluated in the MATLAB workspace. It contains a MATLAB command (or a set of commands, each separated by a semicolon) to execute along with format specifiers (%g, %f, %d, etc.) that provide formatted substitution of the other arguments (arg1, arg2, etc.) into evalString.

The format specifiers used in ml functions are the same as those used in the C functions printf and sprintf. The ml function call is equivalent to calling the MATLAB eval function with the ml namespace operator if the arguments arg1,arg2,... are restricted to scalars or string literals in the following command:

ml.eval(ml.sprintf(evalString, arg1, arg2,...))

Stateflow software assumes scalar return values from ml namespace operator and ml function calls when they are used as arguments in this context. See Inferring Return Size for ml Expressions.

Examples

In these examples, x is a MATLAB workspace variable, and d1 and d2 are Stateflow data:

• a = ml('sin(x)')

  In this example, the ml function calls the MATLAB function sin to evaluate the sine of x in the MATLAB workspace. The result is then assigned to Stateflow data variable a. Because x is a workspace variable, and sin(x) is evaluated in the MATLAB workspace, you enter it directly in the evalString argument ('sin(x)').

• a = ml('sin(%f)', d1)

  In this example, the MATLAB function sin evaluates the sine of d1 in the MATLAB workspace and assigns the result to Stateflow data variable a. Because d1 is Stateflow data, its value is inserted in the evalString argument ('sin(%f)') using the format expression %f. This means that if d1 = 1.5, the expression evaluated in the MATLAB workspace is sin(1.5).

• a = ml('matfunc(%g, ''abcdefg'', x, %f)', d1, d2)

  In this example, the string 'matfunc(%g, ''abcdefg'', x, %f)' is the evalString shown in the preceding format statement. Stateflow data d1 and d2 are inserted into that string with the format specifiers %g and %f, respectively. The string ''abcdefg'' is a string literal with two single pairs of quotation marks used to enclose it because it is part of the evaluation string, which is already enclosed in single quotation marks.

• sfmat_44 = ml('rand(4)')

  In this example, a square 4-by-4 matrix of random numbers between 0 and 1 is returned and assigned to the Stateflow data sf_mat44. Stateflow data sf_mat44 must be defined as a 4-by-4 array before simulation. If its size is different, a size mismatch error is generated during run-time.

Back to Top

ml Expressions

You can mix ml namespace operator and ml function expressions along with Stateflow data in larger expressions. The following example squares the sine and cosine of an angle in workspace variable X and adds them:

ml.power(ml.sin(ml.X),2) + ml('power(cos(X),2)')

The first operand uses the ml namespace operator to call the sin function. Its argument is ml.X, since X is in the MATLAB workspace. The second operand uses the ml function. Because X is in the workspace, it is included in the evalString expression as X. The squaring of each operand is performed with the MATLAB power function, which takes two arguments: the value to square, and the power value, 2.

Expressions using the ml namespace operator and the ml function can be used as arguments for ml namespace operator and ml function expressions. The following example nests ml expressions at three different levels:

a = ml.power(ml.sin(ml.X + ml('cos(Y)')),2)

In composing your ml expressions, follow the levels of precedence set out in Binary and Bitwise Operations. To repeat a warning note in that section, be sure to use parentheses around power expressions with the ^ operator when you use them in conjunction with other arithmetic operators.

Stateflow software checks expressions for data size mismatches in your action language during parsing of your charts and during run-time. Because the return values for ml expressions are not known until run-time, Stateflow software must infer the size of their return values. See Inferring Return Size for ml Expressions.

Back to Top

Which ml Should I Use?

In most cases, the notation of the ml namespace operator is more straightforward. However, using the ml function call does offer a few advantages:

• Use the ml function to dynamically construct workspace variables.

  The following example creates four new MATLAB matrices:

  

  This example demonstrates the use of a Stateflow for loop to create four new matrix variables in the MATLAB workspace. The default transition initializes the Stateflow counter i to 0 while the transition segment between the top two junctions increments it by 1. If i is less than 5, the transition segment back to the top junction is taken and evaluates the ml function call ml('A%d = rand(%d)',i,i) for the current value of i. When i is greater than or equal to 5, the transition segment between the bottom two junctions is taken and execution stops.

  This results in the following MATLAB commands, which create a workspace scalar (A1) and three matrices (A2, A3, A4):

  A1 = rand(1)
  A2 = rand(2)
  A3 = rand(3)
  A4 = rand(4)
  

• Use the ml function with full MATLAB notation.

  You cannot use full MATLAB notation with the ml namespace operator, as demonstrated by the following example:

  ml.A = ml.magic(4)
  B = ml('A + A''')
  

  This example sets the workspace variable A to a magic 4-by-4 matrix using the ml namespace operator. Stateflow data B is then set to the addition of A and its transpose matrix, A', which produces a symmetric matrix. Because the ml namespace operator cannot evaluate the expression A', the ml function is used instead. However, you can call the MATLAB function transpose with the ml namespace operator in the following equivalent expression:

  B = ml.A + ml.transpose(ml.A)
  

  As another example, you cannot use arguments with cell arrays or subscript expressions involving colons with the ml namespace operator. However, these can be included in an ml function call.

Back to Top

ml Data Type

Stateflow data of type ml is typed internally with the MATLAB type mxArray. You can assign (store) any type of data available in the Stateflow hierarchy to a data of type ml. These types include any data type defined in the Stateflow hierarchy or returned from the MATLAB workspace with the ml namespace operator or ml function.

Rules for Using ml Data Type

These rules apply to Stateflow data of type ml:

• You can initialize ml data from the MATLAB workspace just like other data in the Stateflow hierarchy (see Initializing Data from the MATLAB^® Base Workspace).

• Any numerical scalar or array of ml data in the Stateflow hierarchy can participate in any kind of unary operation and any kind of binary operation with any other data in the hierarchy.

  If ml data participates in any numerical operation with other data, the size of the ml data must be inferred from the context in which it is used, just as return data from the ml namespace operator and ml function are. See Inferring Return Size for ml Expressions.

  Note   The preceding rule does not apply to ml data storing MATLAB 64-bit integers. You can use ml data to store 64-bit MATLAB integers but you cannot use 64-bit integers in Stateflow action language.

• You cannot define ml data with the scope Constant.

  This option is disabled in the Data properties dialog and in the Model Explorer for Stateflow data of type ml.

• You can use ml data to build a simulation target (sfun) but not to build a code generation target (rtw).

• If data of type ml contains an array, you can access the elements of the array via indexing with these rules:

  1. You can index only arrays with numerical elements.

  2. You can index numerical arrays only by their dimension.

     In other words, you can access only one-dimensional arrays by a single index value. You cannot access a multidimensional array with a single index value.

  3. The first index value for each dimension of an array is 1, and not 0, as in C-language arrays.

  In the examples that follow, mldata is a Stateflow data of type ml, ws_num_array is a 2-by-2 MATLAB workspace array with numerical values, and ws_str_array is a 2-by-2 MATLAB workspace array with string values.

  mldata = ml.ws_num_array; /* OK */
  n21 = mldata[2][1]; /* OK for numerical data of type ml */
  n21 = mldata[3]; /* NOT OK for 2-by-2 array data */
  mldata = ml.ws_str_array; /* OK */
  s21 = mldata[2][1]; /* NOT OK for string data of type ml*/
  

• ml data cannot have a scope outside a Stateflow chart; that is, you cannot define the scope of ml data as Input to Simulink or Output to Simulink.

Place Holder for Workspace Data

Both the ml namespace operator and the ml function can access data directly in the MATLAB workspace and return it to a Stateflow chart. However, maintaining data in the MATLAB workspace can present Stateflow users with conflicts with other data already resident in the workspace. Consequently, with the ml data type, you can maintain ml data in a Stateflow chart and use it for MATLAB computations in Stateflow action language.

As an example, in the following Stateflow action language statements, mldata1 and mldata2 are Stateflow data of type ml:

mldata1 = ml.rand(3);
mldata2 = ml.transpose(mldata1);

In the first line of this example, mldata1 receives the return value of the MATLAB function rand, which, in this case, returns a 3-by-3 array of random numbers. Note that mldata1 is not specified as an array or sized in any way. It can receive any MATLAB workspace data or the return of any MATLAB function because it is defined as a Stateflow data of type ml.

In the second line of the example, mldata2, also of Stateflow data type ml, receives the transpose matrix of the matrix in mldata1. It is assigned the return value of the MATLAB function transpose in which mldata1 is the argument.

Note the differences in notation if the preceding example were to use MATLAB workspace data (wsdata1 and wsdata2) instead of Stateflow ml data to hold the generated matrices:

ml.wsdata1 = ml.rand(3);
ml.wsdata2 = ml.transpose(ml.wsdata1);

In this case, each workspace data must be accessed through the ml namespace operator.

Back to Top

Inferring Return Size for ml Expressions

Stateflow expressions using the ml namespace operator and the ml function are evaluated in the MATLAB workspace at run-time. This means that the actual size of the data returned from the following expression types is known only at run-time:

• MATLAB workspace data or functions using the ml namespace operator or the ml function call

  For example, the size of the return values from the expressions ml.var, ml.func(), or ml(evalString, arg1, arg2,...), where var is a MATLAB workspace variable and func is a MATLAB function, cannot be known until run-time.

• Stateflow data of type ml

• Graphical functions that return Stateflow data of type ml

When any of these expressions is used in action language, Stateflow code generation must create temporary Stateflow data, invisible to the user, to hold their intermediate returns for evaluation of the full expression of which they are a part. Because the size of these return values is not known until run-time, Stateflow software must employ context rules to infer their size for the creation of the temporary data.

During run-time, if the actual returned value from one of these commands differs from the inferred size of the temporary variable chosen to store it, a size mismatch error appears. To prevent these run-time errors, use these guidelines to write action language statements with MATLAB commands or ml data:

1. The return sizes of MATLAB commands or data in an expression must match the return sizes of peer expressions.

   For example, in the expression ml.func() * (x + ml.y), if x is a 3-by-2 matrix, then ml.func() and ml.y are also assumed to evaluate to 3-by-2 matrices. If either returns a value of different size (other than a scalar), an error results during run-time.

2. Expressions that return a scalar never produce an error.

   You can combine matrices and scalars in larger expressions because MATLAB commands practice scalar expansion. For example, in the larger expression ml.x + y, if y is a 3-by-2 matrix and ml.x returns a scalar, the resulting value is determined by adding the scalar value of ml.x to every member of y to produce a matrix with the size of y, that is, a 3-by-2. The same rule applies to subtraction (-), multiplication (*), division (/), and any other binary operations.

3. MATLAB commands or Stateflow data of type ml can be members of the following independent levels of expression, for which the return size must be resolved:

   • Arguments

     The expression for each function argument is a larger expression for which the return size of MATLAB commands or Stateflow data of type ml must be determined. For example, in the expression z + func(x + ml.y), the size of ml.y has nothing to do with the size of z, because ml.y is used at the function argument level. However, the return size for func(x + ml.y) must match the size of z, because they are both at the same expression level.

   • Array indices

     The expression for an array index is an independent level of expression that is required to be scalar in size. For example, in the expression x + arr[y], the size of y has nothing to do with the size of x because y and x are at different levels of expression, and y must be a scalar.

4. The return size for an indexed array element access must be a scalar.

   For example, the expression x[1][1], where x is a 3-by-2 array, must evaluate to a scalar.

5. MATLAB command or data elements used in an expression for the input argument for a MATLAB function called through the ml namespace operator are resolved for size using the rule for peer expressions (preceding rule 1) for the expression itself, because there is no size definition prototype available.

   For example, in the function call ml.func(x + ml.y), if x is a 3-by-2 array, ml.y must return a 3-by-2 array or a scalar.

6. MATLAB command or data elements used for the input argument for a graphical function in an expression are resolved for size by the function's prototype.

   For example, if the graphical function gfunc has the prototype gfunc(arg1), where arg1 is a 2-by-3 Stateflow data array, then the calling expression, gfunc(ml.y + x), requires that both ml.y and x evaluate to 2-by-3 arrays (or scalars) during run-time.

7. ml function calls can take only scalar or string literal arguments. Any MATLAB command or data used to specify an argument for the ml function must return a scalar value.

8. In an assignment, the size of the right-hand expression must match the size of the left-hand expression, with one exception: if the left-hand expression is a single MATLAB variable such as ml.x or a single Stateflow data of type ml, then the sizes of both left-hand expression and right-hand expression are determined by the right-hand expression.

   For example, in the expression s = ml.func(x), where x is a 3-by-2 matrix and s is scalar Stateflow data, ml.func(x) must return a scalar to match the left-hand expression, s. However, in the expression ml.y = x + s, where x is a 3-by-2 data array and s is scalar, the left-hand expression, workspace variable y, is assigned the size of a 3-by-2 array to match the size of the right-hand expression, x+s, a 3-by-2 array.

9. In an assignment, Stateflow column vectors on the left-hand side are compatible with MATLAB row or column vectors of the same size on the right-hand side.

   A matrix you define with a row dimension of 1 is considered a row vector. A matrix you define with one dimension or with a column dimension of 1 is considered a column vector. For example, in the expression s = ml.func(), where ml.func() returns a 1-by-3 matrix, if s is a vector of size 3, the assignment is valid.

10. If you cannot resolve the return size of MATLAB command or data elements in a larger expression by any of the preceding rules, they are assumed to return scalar values.

    For example, in the expression ml.x = ml.y + ml.z, none of the preceding rules can be used to infer a common size among ml.x, ml.y, and ml.z. In this case, both ml.y and ml.z are assumed to return scalar values. And even if ml.y and ml.z return matching sizes at run-time, if they return nonscalar values, a size mismatch error results.

11. The preceding rules for resolving the size of member MATLAB commands or Stateflow data of type ml in a larger expression apply only to cases in which numeric values are expected for that member. For nonnumeric returns, a run-time error results.

    For example, the expression x + ml.str, where ml.str is a string workspace variable, produces a run-time error stating that ml.str is not a numeric type.

    Note   Member MATLAB commands or data of type ml in a larger expression are limited to numeric values (scalar or array) only if they participate in numeric expressions.

12. There are special cases in which no size checking is done to resolve the size of MATLAB command or data expressions that are members of larger expressions. In the cases shown, use of a singular MATLAB element such as ml.var, ml.func(), ml(evalString, arg1, arg2,...), Stateflow data of type ml, or a graphical function returning a Stateflow data of type ml, does not require that size checking be enforced at run-time. In these cases, assignment of a return to the left-hand side of an assignment statement or to a function argument is made without consideration for a size mismatch between the two:

    • An assignment in which the left-hand side is a MATLAB workspace variable

      For example, in the expression ml.x = ml.y, ml.y is a MATLAB workspace variable of any size and type (structure, cell array, string, and so on).

    • An assignment in which the left-hand side is a data of type ml

      For example, in the expression m_x = ml.func(), m_x is a Stateflow data of type ml.

    • Input arguments of a MATLAB function

      For example, in the expression ml.func(m_x, ml.x, gfunc()), m_x is a Stateflow data of type ml, ml.x is a MATLAB workspace variable of any size and type, and gfunc() is a Stateflow graphical function that returns a Stateflow data of type ml. Even though nothing is done to check the size of the input type, if the passed-in data is not of the expected type, an error results from the function call ml.func().

    • Arguments for a graphical function that are specified as Stateflow data of type ml in its prototype statement

      Note   If inputs in the preceding cases are replaced with non-MATLAB numeric Stateflow data, a conversion to an ml type is performed.

Back to Top

Calling C Functions in Actions

Using Data and Event Arguments in Actions