Stateflow.EMChart

Stateflow interface to MATLAB Function block

Description

Use Stateflow.EMChart objects to configure MATLAB Function (Simulink) blocks through the Stateflow^® programmatic interface.

MATLAB Function blocks define custom functionality in Simulink^® models. Use these blocks when:

• You have an existing MATLAB^® function that models custom functionality, or it is easy for you to create such a function.

• Your model requires custom functionality that is not or cannot be captured in the Simulink graphical language.

• You find it easier to model custom functionality by using a MATLAB function than by using a Simulink block diagram.

• The custom functionality that you want to model does not include continuous or discrete dynamic states. To model dynamic states, use S-functions. See Author Blocks Using MATLAB S-Functions (Simulink).

For more information, see Implement MATLAB Functions in Simulink with MATLAB Function Blocks (Simulink).

Tip

You can also configure the properties of a MATLAB Function block programmatically by using a MATLABFunctionConfiguration (Simulink) object. This object provides a direct interface to the properties of a MATLAB Function block. For more information, see Configure MATLAB Function Blocks Programmatically (Simulink).

Creation

Each MATLAB Function block has its own Stateflow.EMChart object. When you add a MATLAB Function block to a Simulink model, a Stateflow.EMChart object is automatically created for it. For example, you can use the function add_block (Simulink) to add a MATLAB Function with the name MATLAB Function to a model called myModel:

add_block("simulink/User-Defined Functions/MATLAB Function", ...
   "myModel/MATLAB Function")

Then, to access the Stateflow.EMChart object, call the find function for the Simulink.Root object:

block = find(sfroot,"-isa","Stateflow.EMChart", ...
    "Path","myModel/MATLAB Function");

Properties

Stateflow API objects have properties that correspond to the values you set in the Stateflow Editor. To access or modify a property, use dot notation. To access or modify multiple properties for multiple API objects, use the get and set functions, respectively. For more information, see Modify Properties and Call Functions of Stateflow Objects.

Content

Name — Name of MATLAB Function block

"MATLAB Function" (default) | string scalar | character vector

Name of the MATLAB Function block, specified as a string scalar or character vector.

Script — Code for MATLAB Function block

string scalar | character vector

Code for the MATLAB Function block, specified as a string scalar or character vector. To enter multiple lines of code, you can:

• Call the MATLAB function sprintf and use \n to insert newline characters:

  str = sprintf("function y=f(x)\ny=x+1;\nend");
  block.Script = str;

• Enter a concatenated text expression that uses the function newline to create newline characters:

  str = "function y=f(x)" + newline + ...
      "y=x+1;" + newline + ...
      "end";
  block.Script = str;

SupportVariableSizing — Whether MATLAB Function block supports variable-size data

true or 1 (default) | false or 0

Whether the MATLAB Function block supports variable-size data, specified as a numeric or logical 1 (true) or 0 (false). For more information, see Declare Variable-Size MATLAB Function Block Variables (Simulink).

AllowDirectFeedthrough — Whether MATLAB Function block supports direct feedthrough semantics

true or 1 (default) | false or 0

Whether the MATLAB Function block supports direct feedthrough semantics, specified as a numeric or logical 1 (true) or 0 (false). For more information, see Allow direct feedthrough (Simulink).

VectorOutputs1D — Whether MATLAB Function block outputs column vectors as one-dimensional data

false or 0 (default) | true or 1

Since R2021b

Whether the MATLAB Function block outputs column vectors as one-dimensional data, specified as a numeric or logical 0 (false) or 1 (true). For more information, see Interpret output column vectors as one-dimensional data (Simulink).

TreatDimensionOfLengthOneAsFixedSize — Whether MATLAB Function block treats output variables with dimension of length 1 as fixed size

true or 1 (default) | false or 0

Since R2023a

Whether the MATLAB Function block treats output variables with a dimension of length 1 as fixed size, specified as a numeric or logical 0 (false) or 1 (true). When this property is true, the MATLAB Function block treats output variables that have at least one dimension of length 1 as fixed size, regardless of whether you specify the variables as having variable size. When this property is false, the MATLAB Function block treats output variables as variable size if you specify the variables as having variable size. For more information, see Variable size (Simulink).

Interface

Inputs — Input arguments

array of Stateflow.Data objects

This property is read-only.

Input arguments of the MATLAB Function block, specified as an array of Stateflow.Data objects. The value of this property depends on the inputs defined in the Script property for the block.

Outputs — Output arguments

array of Stateflow.Data objects

This property is read-only.

Output arguments of the MATLAB Function block, specified as an array of Stateflow.Data objects. The value of this property depends on the outputs defined in the Script property for the block.

Discrete and Continuous-Time Semantics

ChartUpdate — Activation method for MATLAB Function block

"INHERITED" (default) | "CONTINUOUS" | "DISCRETE"

Activation method for the MATLAB Function block, specified as "CONTINUOUS", "DISCRETE", or "INHERITED". For more information, see Update method (Simulink).

SampleTime — Sample time for activating MATLAB Function block

"-1" (default) | string scalar | character vector

Sample time for activating the MATLAB Function block, specified as a string scalar or character vector. This property applies only when the ChartUpdate property is "DISCRETE".

Integer and Fixed-Point Data

SaturateOnIntegerOverflow — Whether data saturates on integer overflow

true or 1 (default) | false or 0

Whether the data in the MATLAB Function block saturates on integer overflow, specified as a numeric or logical 1 (true) or 0 (false). When this property is disabled, the data in the function wraps on integer overflow. For more information, see Saturate on integer overflow (Simulink).

TreatAsFi — Inherited Simulink signals to treat as fi objects

"Fixed-point" (default) | "Fixed-point & Integer"

Inherited Simulink signals to treat as Fixed-Point Designer™ fi objects, specified as one of these values:

• "Fixed-point" — The MATLAB Function block treats all fixed-point inputs as fi objects.

• "Fixed-point & Integer" — The MATLAB Function block treats all fixed-point and integer inputs as fi objects.

EmlDefaultFimath — Default fimath properties

"Same as MATLAB Default" (default) | "Other:UserSpecified"

Default fimath properties for the MATLAB Function block, specified as one of these values:

• "Same as MATLAB Default" — Use the same fimath properties as the current default fimath object.

• "Other:UserSpecified" — Use the InputFimath property to specify the default fimath object.

InputFimath — Default fimath object

string scalar | character vector

Default fimath object, specified as a string scalar or character vector. When the EmlDefaultFimath property for the MATLAB Function block is "Other:UserSpecified", you can use this property to:

• Enter an expression that constructs a fimath object.

• Enter the variable name for a fimath object in the MATLAB or model workspace.

Hierarchy

Machine — Machine that contains MATLAB Function block

Stateflow.Machine object

This property is read-only.

Machine that contains the MATLAB Function block, specified as a Stateflow.Machine object.

Path — Location of MATLAB Function block in model hierarchy

string scalar | character vector

This property is read-only.

Location of the MATLAB Function block in the model hierarchy, specified as a character vector.

Dirty — Whether MATLAB Function block has changed

true or 1 | false or 0

Whether the MATLAB Function block has changed after being opened or saved, specified as a numeric or logical 1 (true) or 0 (false).

Locked — Whether MATLAB Function block is locked

false or 0 (default) | true or 1

Whether the MATLAB Function block is locked, specified as a numeric or logical 1 (true) or 0 (false). Enable this property to prevent changes in the MATLAB Function block.

Iced — Whether MATLAB Function block is locked

false or 0 (default) | true or 1

This property is read-only.

Whether the MATLAB Function block is locked, specified as a numeric or logical 1 (true) or 0 (false). This property is equivalent to the property Locked, but is used internally to prevent changes in the MATLAB Function block during simulation.

Identification

Description — Description

"" (default) | string scalar | character vector

Description for the MATLAB Function block, specified as a string scalar or character vector.

Document — Document link

"" (default) | string scalar | character vector

Document link for the MATLAB Function block, specified as a string scalar or character vector.

Tag — User-defined tag

[] (default) | any data type

User-defined tag for the MATLAB Function block, specified as data of any type.

Id — Unique identifier

scalar

This property is read-only.

Unique identifier, specified as an integer scalar. Use this property to distinguish the MATLAB Function block from other objects in the model. The value of this property is reassigned every time you start a new MATLAB session and may be recycled after an object is deleted.

Object Functions

find	Identify specified objects in hierarchy
getChildren	Identify children of object
dialog	Open properties dialog box
view	Display object in editing environment

Examples

Program MATLAB Function Block

Access the Stateflow.EMChart object for a MATLAB Function block named My Function in a model called myModel.

block = find(sfroot,"-isa","Stateflow.EMChart", ...
    "Path","myModel/My Function");

Store the MATLAB code to calculate the mean and standard deviation for a vector of values as a string scalar.

str = "function [mean,stdev] = stats(vals)" + newline + ...
    "% Calculates a statistical mean and a standard" + newline + ...
    "% deviation for the values in vals." + newline + newline + ...
    "len = length(vals);" + newline + ...
    "mean = avg(vals,len);" + newline + ...
    "stdev = sqrt(sum(((vals-avg(vals,len)).^2))/len);" + newline + ...
    "plot(vals,""-+"");" + newline + newline + ...
    "function mean = avg(array,size)" + newline + ...
    "mean = sum(array)/size;";

Populate the block with code by modifying the Script property of the corresponding Stateflow.EMChart object.

block.Script = str;

Open the function in the MATLAB Function Block Editor (Simulink).

view(block)

The editor shows this code.

function [mean,stdev] = stats(vals)
% Calculates a statistical mean and a standard
% deviation for the values in vals.

len = length(vals);
mean = avg(vals,len);
stdev = sqrt(sum(((vals-avg(vals,len)).^2))/len);
plot(vals,"-+");

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

Import Code from MATLAB Function

Open a Simulink model called myModel.

open_system("myModel")

Add a MATLAB Function block to myModel named My Function.

blockPath = "myModel/My Function";
add_block("simulink/User-Defined Functions/MATLAB Function",blockPath)

Populate the block with code from the MATLAB function myFunction.m.

block = find(sfroot,"-isa","Stateflow.EMChart", ...
    "Path",blockPath);
block.Script = fileread("myFunction.m");

Find Number of MATLAB Function Blocks in Model

Open a Simulink model called myModel.

open_system("myModel")

Find the MATLAB Function blocks in the model, including the block in the library.

blocks = find(sfroot,"-isa","Stateflow.EMChart");

Note

This command finds objects for the MATLAB Function blocks in all open models and libraries. To find only the MATLAB Function blocks in myModel, close every file except myModel or replace sfroot with get_param("myModel","Object").

Count the number of blocks.

numel(blocks)

Version History

Introduced in R2011a

R2023a: Specify how to treat output variables with dimension of length 1

With the new property TreatDimensionOfLengthOneAsFixedSize, you can specify how MATLAB Function blocks treat output variables when at least one dimension has length 1. Prior to R2023a, MATLAB Function blocks treat output variables with a dimension of length 1 as fixed size, regardless of whether you specify the variables as having variable size.

R2021b: Change to output column vectors

You can output column vectors in MATLAB Function blocks as two-dimensional or one-dimensional data with the VectorOutputs1D property.

Before R2021b, MATLAB Function blocks always output column vectors as one-dimensional data. After R2021b, MATLAB Function blocks output column vectors as two-dimensional data by default. To maintain the original behavior of the block, set the VectorOutputs1D property to true.