## Access MATLAB Functions and Workspace Data in C Charts

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

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

passes the return values from the
MATLAB function * function*(x, y)

*to the Stateflow data*

`function`

`a`

, `b`

, and
`c`

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

, 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.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 variable`y`

The value returned by the call to

`f`

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.

`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,...);

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 (`evalString`

`%g`

, `%f`

, `%d`

,
etc.) that provide formatted substitution of the other arguments
(

,
`arg1`

, etc.) into
`arg2`

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

are restricted to scalars or literals in the
following command:* arg1*,

*,...*

`arg2`

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. 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 of`x`

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 of`d1`

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`

. If`d1`

= 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

shown in the preceding format statement. Stateflow data`evalString`

`d1`

and`d2`

are inserted into the expression`"`

by using the format specifiers(%g,x,%f)"`f`

`%g`

and`%f`

, respectively.

`ml`

Expressions

For C charts, 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:

`a = 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 appears in the

expression as
`evalString`

`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 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. See How 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 of`i`

. 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 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: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 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 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. 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:You can index only arrays with numerical elements.

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.

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 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 maintain
`ml`

data in a chart and use it for MATLAB computations in C charts.

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

### How Charts Infer the Return Size for `ml`

Expressions

In C charts, Stateflow expressions using the `ml`

namespace operator and the
`ml`

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 callFor example, the size of the return values from the expressions

`ml.`

,`var`

`ml.`

, or()`func`

`ml(`

, where,`evalString`

,`arg1`

,...)`arg2`

is a MATLAB workspace variable and`var`

is a MATLAB function, cannot be known until run-time.`func`

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:

Guideline | Example | |
---|---|---|

Return sizes of MATLAB commands or data in an expression must match return sizes of peer expressions. | In the expression `x` is a 3-by-2 matrix, then
`ml.` 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. | |

Expressions that return a scalar never produce an error. You can combine matrices and scalars in larger expressions because MATLAB commands use scalar expansion. | In the expression The same rule
applies to subtraction ( | |

MATLAB commands or Stateflow data of type | Arguments The expression for each function argument is a
larger expression for which the return size of MATLAB commands or Stateflow data of type | In the expression `ml.y` is independent of the size of `z` ,
because `ml.y` is used at the function argument level. However,
the return size for
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 must be scalar in size. | In the expression `y`
is independent of the size of `x` because `y`
and `x` are at different levels of expression. Also,
`y` must be a scalar. | |

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

MATLAB command or data elements used in an expression for the input
argument of a MATLAB function called through the | In the function call `x` is a 3-by-2 array,
`ml.y` must return a 3-by-2 array or a scalar. | |

MATLAB command or data elements used for the input argument for a graphical function in an expression are resolved for size by the function prototype. | If the graphical function
)`arg1` is a 2-by-3 Stateflow data array, the calling expression,
, requires that
both `ml.y` and `x` evaluate to 2-by-3 arrays
(or scalars) during run-time. | |

| In the expression | |

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 | In the expression `x` is a
3-by-2 matrix and `s` is scalar Stateflow data, `ml.` 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. | |

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. | In the expression `ml.` returns a 1-by-3
matrix, if `s` is a vector of size `3` , the
assignment is valid. | |

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. | In the expression | |

The
preceding rules for resolving the size of member MATLAB commands or Stateflow data of type
Member MATLAB commands or data of type | The expression |

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

,(m_x, ml.x,`func`

())`gfunc`

`m_x`

is a Stateflow data of type`ml`

,`ml.x`

is a MATLAB workspace variable of any size and type, and

is a Stateflow graphical function that returns a Stateflow data of type()`gfunc`

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