Access MATLAB Functions and Workspace Data in C Charts - MATLAB & Simulink (original) (raw)

Stateflow® charts in Simulink® models have an action language property that defines the syntax for state and transition actions. An icon in the lower-left corner of the chart canvas indicates the action language for the chart.

• MATLAB® as the action language.
• C as the action language.

In charts that use C as the action language, you can call built-in MATLAB functions and access MATLAB workspace variables by using the ml namespace operator or theml function.

Caution

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

ml Namespace Operator

For C charts, the ml namespace operator uses standard dot(.) notation to reference MATLAB variables and functions. 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.function_name(arg1,arg2,...)

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

If the MATLAB function you call does not require arguments, you must still include the parentheses. 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, andz are workspace variables and d1 andd2 are Stateflow data:

• a = ml.sin(ml.x)
  In this example, the MATLAB function sin evaluates the sine ofx, which is then assigned to Stateflow data variable a. However, becausex is a workspace variable, you must use the namespace operator to access it. Hence, ml.x is used instead of justx.
• a = ml.sin(d1)
  In this example, the MATLAB function sin evaluates the sine ofd1, 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. Ifx does not exist prior to simulation, it is automatically created in the MATLAB workspace.
• ml.v[5][6][7] = ml.f(ml.x[1][3],ml.y[3])
  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 variabley
  The value returned by the call to f is assigned to element(5,6,7) of the workspace array, v. Ifv does not exist prior to simulation, it is automatically created in the MATLAB workspace.

ml Function

For C charts, you can use the ml function to specify calls to MATLAB functions. The format for the ml function call uses this notation:

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

_`evalString`_ is an 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. Theml function call is equivalent to calling the MATLABeval function with the ml namespace operator if the arguments _`arg1`_,_`arg2`_,... are restricted to scalars or literals in the following command:

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

Format specifiers used in the ml function must either match the data types of the arguments or the arguments must be of types that can be promoted to the type represented by the format specifier.

Stateflow software assumes scalar return values from ml namespace operator and ml function calls when they are used as arguments in this context. For more information, see How Charts Infer the 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 ofx in the MATLAB workspace. The result is then assigned to Stateflow data object a. Because x is a workspace variable, and sin(x) is evaluated in the MATLAB workspace, you enter it directly as the string"sin(x)".
• 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 object sf_mat44. you must define this data object as a 4-by-4 array before simulation. Otherwise, a size mismatch error occurs during run-time.
• a = ml("sin(%f)",d1)
  In this example, the MATLAB function sin evaluates the sine ofd1 in the MATLAB workspace and assigns the result to Stateflow data object a. Because d1 is Stateflow data, its value is inserted in the string argument"sin(%f)" using the format expression %f. Ifd1 = 1.5, the expression evaluated in the MATLAB workspace is sin(1.5).
• a = ml("f(%g,x,%f)",d1,d2)
  In this example, the expression is the_`evalString`_ shown in the preceding format statement. Stateflow data d1 and d2 are inserted into the expression "_`f`_(%g,x,%f)" by using the format specifiers %g and %f, respectively.

ml Expressions

For C charts, you can mix ml namespace operator andml function expressions along with Stateflow data in larger expressions. The following example squares thesine and cosine of an angle in workspace variableX and adds them:

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

The first operand uses the ml namespace operator to call thesin function. Its argument is ml.X, sinceX is in the MATLAB workspace. The second operand uses the ml function. BecauseX is in the workspace, it appears in the_`evalString`_ expression asX. The squaring of each operand is performed with the MATLABpower function, which takes two arguments: the value to square, and the power value, 2.

Expressions using the ml namespace operator and theml 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 Operations. 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 actions when you update or simulate the model. Because the return values for ml expressions are not known until run time, Stateflow software must infer the size of their return values. For more information, seeHow Charts Infer the Return Size for ml Expressions.

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 flow chart creates four new MATLAB matrices:
  
  The for loop creates 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 evaluates the ml function call ml("A%d = rand(%d)",i,i) for the current value ofi. When i is greater than or equal to 5, the transition segment between the bottom two junctions occurs and execution stops.
  The transition executes 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 the following example shows:
  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 ofA 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:
  ml.A = ml.magic(4);
  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.

ml Data Type

Stateflow data of type ml is typed internally with the MATLAB type mxArray for C charts. 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 orml 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 Initialize 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. For more information, see How Charts Infer the Return Size for ml Expressions.
• You cannot define ml data with the scope Constant.
  This option is disabled in the Data properties dialog box and in the Model Explorer for Stateflow data of type ml.
• You can use ml data to build a simulation target but not to build an embeddable code generation target.
• 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, andws_str_array is a 2-by-2 MATLAB workspace array with character vector 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 character vector data of type ml*/
• ml data cannot have a scope outside a C chart; that is, you cannot define the scope of ml data as Input from 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 C 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 maintainml data in a chart and use it for MATLAB computations in C charts.

As an example, in the following statements, mldata1 andmldata2 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 Stateflowml 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.

How Charts Infer the Return Size for ml Expressions

In C charts, Stateflow expressions using the ml namespace operator and theml function evaluate in the MATLAB workspace at run time. 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 expressionsml._`var`_,ml._`func`_(), orml(_`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 these expressions appear in actions, Stateflow code generation creates temporary data to hold intermediate returns for evaluation of the full expression of which they are a part. Because the size of these return values is unknown until run time, Stateflow software must employ context rules to infer the sizes for 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 that stores it, a size mismatch error appears. To prevent run-time errors, use the following guidelines to write actions with MATLAB commands or ml data:

Special cases exist, in which no size checking occurs to resolve the size of MATLAB command or data expressions that are part of larger expressions. Use of the following expressions does not require enforcement of size checking at run-time:

• ml._`var`_
• ml._`func`_()
• ml(_`evalString`_, _`arg1`_,_`arg2`_,...)
• Stateflow data of type ml
• Graphical function returning a Stateflow data of type ml

In these cases, assignment of a return to the left-hand side of an assignment statement or a function argument occurs without checking 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, character vector, and so on).
• An assignment in which the left-hand side is a data of typeml
  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. Although size checking does not occur for 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 you replace the inputs in the preceding cases with non-MATLAB numeric Stateflow data, conversion to an ml type occurs.