For C charts, you can call MATLAB^{®} functions and access MATLAB workspace
variables in Stateflow^{®} actions, using the ml
namespace
operator or the ml
function.
For charts that use MATLAB as the action language, you can call MATLAB functions supported for code generation directly.
Caution
Because MATLAB functions are not available in a target
environment, do not use the |
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.matfunc(arg1, arg2,...)
For example, the statement [a, b, c] = ml.
passes the return values from the MATLAB function matfunc
(x,
y)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. 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.
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.
For C charts, you can use the ml
function
to specify calls to MATLAB functions through a string expression.
The format for the ml
function call uses this notation:
ml(evalString, arg1, arg2,...);
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 (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 string literals in the following command:arg1
, arg2
,...
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 How Charts Infer the Return Size for ml Expressions.
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
argument
(evalString
'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
argument
(evalString
'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 '
is the matfunc
(%g,
''abcdefg'', x, %f)'
shown
in the preceding format statement. Stateflow data evalString
d1
and d2
are
inserted into that string with the format specifiers %g
and %f
,
respectively. The string ''abcdefg''
is a string
literal enclosed with two single pairs of quotation marks 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.
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:
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 and Bitwise 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 during parsing of 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 How Charts Infer the Return Size for ml Expressions.
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:
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.
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.
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.
Note:
The preceding rule does not apply to |
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 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 C chart; that is, you cannot define the scope of ml
data
as Input to Simulink or Output to Simulink.
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.
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 call
For 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 | ||
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 | |
Array indices The expression for an array index is an independent level of expression that must be scalar in size. | In the expression | ||
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 | ||
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 | ||
| 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 | ||
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 | ||
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
| 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, 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
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 |