Reuse MATLAB Code by Defining MATLAB Functions

A MATLAB® function in a Stateflow® chart is a graphical element that you use to write algorithms that are easier to implement by calling built-in MATLAB functions. Typical applications include:

  • Matrix-oriented calculations

  • Data analysis and visualization

This type of function is useful for coding algorithms that are more easily expressed by using MATLAB instead of the graphical Stateflow constructs. MATLAB functions also provide optimizations for generating efficient, production-quality C code for embedded applications.

A MATLAB function can reside anywhere in a chart, state, or subchart. The location of the function determines the set of states and transitions that can call the function.

  • If you want to call the function only within one state or subchart and its substates, put your MATLAB function in that state or subchart. That function overrides any other functions of the same name in the parents and ancestors of that state or subchart.

  • If you want to call the function anywhere in that chart, put your MATLAB function at the chart level.

  • If you want to call the function from any chart in your model, put your MATLAB function at the chart level and enable exporting of chart-level functions. For more information, see Export Stateflow Functions for Reuse.

For example, this MATLAB function has the name stdevstats. It takes an argument vals and returns an output value stdevout.

To compute the standard deviation of the values in vals, the function uses this code.

function stdevout = stdevstats(vals)
%#codegen

% Calculates the standard deviation for vals

len = length(vals);
stdevout = sqrt(sum(((vals-avg(vals,len)).^2))/len);

function mean = avg(array,size)
mean = sum(array)/size;

Define a MATLAB Function in a Chart

  1. In the object palette, click the MATLAB function icon . Move your pointer to the location for the new MATLAB function in your chart.

  2. Enter the signature label for the function, as described in Declare Function Arguments and Return Values.

  3. To program the function, open the MATLAB editor by double-clicking the function box. For more information, see Program a MATLAB Function in a Chart.

  4. In the editor, enter the MATLAB code implementing your function.

  5. In the Model Explorer, expand the chart object and select the MATLAB function. The arguments and return values of the function signature appear as data items that belong to your function. Arguments have the scope Input. Return values have the scope Output.

  6. In the Data properties dialog box for each argument and return value, specify the data properties, as described in Set Data Properties.

  7. Create any additional data items required by your function. For more information, see Add Data Through the Model Explorer.

    Your function can access its own data or data belonging to parent states or the chart. The data items in the function can have one of these scopes:

    • Local — Local data persists from one function call to the next function call. Valid for C charts only.

    • Constant — Constant data retains its initial value through all function calls.

    • Parameter — Parameter data retains its initial value through all function calls.

    • Temporary — Temporary data initializes at the start of every function call. Valid for C charts only.

Initialize Function Data

You can initialize your function data (other than arguments and return values) from the MATLAB workspace. For more information, see Initialize Data from the MATLAB Base Workspace.

Define Temporary Data

In charts that use C as the action language, define temporary data when you want to use data that is only valid while a function executes. For example, you can designate a loop counter to have Temporary scope if the counter value does not need to persist after the function completes.

In charts that use MATLAB as the action language, you do not need to define temporary function data. If you use an undefined variable, Stateflow creates a temporary variable. The variable is available to the rest of the function.

Use Enumerated and Variable-Size Data

In Stateflow charts in Simulink® models, you can use enumerated data and variable-size data in MATLAB functions. For more information, see Code Generation for Enumerations (Simulink) and Declare Variable-Size Inputs and Outputs (Simulink).

Declare Function Arguments and Return Values

The function signature label specifies a name for your function and the formal names for its arguments and return values. A signature label has this syntax:

[return_val1,return_val2,...] = function_name(arg1,arg2,...)
You can specify multiple return values and multiple input arguments. Each return value and input argument can be a scalar, vector, or matrix of values. For functions with only one return value, omit the brackets in the signature label.

You can use the same variable name for both arguments and return values. For example, a function with this signature label uses the variables y1 and y2 as both inputs and outputs:

[y1,y2,y3] = f(y1,u,y2)
If you export this function to C code, y1 and y2 are passed by reference (as pointers), and u is passed by value. Passing inputs by reference reduces the number of times that the generated code copies intermediate data, resulting in more optimal code.

Call MATLAB Functions in States and Transitions

You can call MATLAB functions from the actions of any state or transition. You can also call MATLAB functions from other functions. If you export a MATLAB function, you can call it from any chart in the model.

The syntax for a call to a MATLAB function is the same as the function signature, with actual arguments replacing the formal ones specified in a signature. If the data types of an actual and formal argument differ, a function casts the actual argument to the type of the formal argument.

Tip

If the formal arguments of a function signature are scalars, verify that inputs and outputs of function calls follow the rules of scalar expansion. For more information, see Assign Values to All Elements of a Matrix.

Specify MATLAB Function Properties in a Chart

You can set general properties for your MATLAB function through its properties dialog box. To open the function properties dialog box, right-click the MATLAB function box and select Properties from the context menu.

Name

Function name. Click the function name link to open your function in the MATLAB editor.

Function Inline Option

Controls the inlining of your function in generated code:

  • Auto — Determines whether to inline your function based on an internal calculation.

  • Inline — Inlines your function if you do not export it to other charts and it is not part of a recursion. (A recursion exists if your function calls itself directly or indirectly through another function call.)

  • Function — Does not inline your function.

Label

Signature label for your function. For more information, see Declare Function Arguments and Return Values.

Saturate on Integer Overflow

Specifies whether integer overflows saturate in the generated code. For more information, see Handle Integer Overflow for Chart Data.

MATLAB Function fimath

Defines the fimath properties for the MATLAB function. The fimath properties specified are associated with all fi and fimath objects constructed in the MATLAB function. Choose one of these options:

  • Same as MATLAB — The function uses the same fimath properties as the current global fimath. The edit box appears dimmed and displays the current global fimath in read-only form. For more information on the global fimath and fimath objects, see the Fixed-Point Designer™ documentation.

  • Specify Other — Specify your own fimath object by one of these methods:

    • Construct the fimath object inside the edit box.

    • Construct the fimath object in the MATLAB or model workspace and enter its variable name in the edit box.

Description

Function description. You can enter brief descriptions of functions in the hierarchy.

Document Link

Link to online documentation for the function. You can enter a web URL address or a MATLAB command that displays documentation in a suitable online format, such as an HTML file or text in the MATLAB Command Window. When you click the Document link hyperlink, Stateflow displays the documentation.

Related Topics

Stateflow Documentation
Support