MATLAB Function
Include MATLAB code in Simulink models
Libraries:
Simulink /
User-Defined Functions
HDL Coder /
User-Defined Functions
Description
The MATLAB Function block enables you to write MATLAB® functions that execute in Simulink® models. The MATLAB function executes during simulation at each time step. For more information about integrating MATLAB code into your Simulink models, see Implement MATLAB Functions in Simulink with MATLAB Function Blocks. If you have a Simulink Coder™ license, you can also generate C/C++ code from a MATLAB Function block for a Simulink Coder target.
Double-click the MATLAB Function block to open the MATLAB Function Block Editor, where you write the MATLAB function. You can also define variables, add an input trigger, and create function call outputs by using the Model Explorer or the Symbols pane. For more information, see Create and Define MATLAB Function Block Variables, Manage the Input Trigger of a MATLAB Function Block, and Manage Function Call Outputs of a MATLAB Function Block.
In the Symbols pane, you can declare a block input to be a Simulink parameter instead of a port. The MATLAB Function block also supports inheritance of types and size for inputs, outputs, and parameters. You can specify these properties explicitly. See Define and Modify Variable Data Types, Specify Size of MATLAB Function Block Variables, and Use Data in Multiple MATLAB Function Blocks by Defining Parameter Variables.
When you simulate a model that contains a MATLAB Function block, the software generates binary code or C/C++ MATLAB executable (MEX) code from the block and integrates this code with the model. The MATLAB Function block uses the same infrastructure as MATLAB Coder, which you use to generate C/C++ code from MATLAB code outside of Simulink. Consequentially, the MATLAB Function block code must use MATLAB conventions that are supported for code generation. See Code and Integration Limitations for MATLAB Function Blocks.
To support visualization of data, the MATLAB Function block supports calls to MATLAB functions for simulation only. See Use MATLAB Engine to Execute a Function Call in MATLAB Function Blocks. If you generate code using Simulink Coder, the calls do not appear in the generated code if the function calls do not directly affect the Simulink inputs or outputs.
Examples
Multiply Input Signal by Two
Add a MATLAB Function to your model to modify an input signal.
In the Simulation tab, click Library Browser. Select Simulink > User-Defined Functions. Drag a MATLAB Function block to the Simulink canvas.
Double-click the block to open the MATLAB Function Block Editor. Replace the function body code with the following:
y = 2*u;
Return to the model by clicking the Up to Parent button . Add a Sine Wave block as the input signal and add a Scope block to capture the input and output of the MATLAB Function block.
Run the simulation and open the Scope block to see the effects of the code.
Extended Examples
Run Simulations and Generate Code with Masked Library Subsystems Containing MATLAB Function Blocks
Run simulations and generate code with models using custom MATLAB Function blocks in a library.
Call MATLAB Function Files in MATLAB Function Blocks
Use MATLAB Function blocks to call and execute code written in MATLAB function files.
Radar Tracking Using MATLAB Function Blocks
Create a Kalman filter that estimates the position of an aircraft by using a MATLAB Function block. After estimating the position, the model calls an external MATLAB® function to plot the tracking data.
Spiral Galaxy Formation Simulation Using MATLAB Function Blocks
Use MATLAB Function blocks to simulate and plot galaxy interactions.
Limitations
Although the code for this block attempts to produce exactly the same results as MATLAB, differences might occur due to rounding errors. These numerical differences, which might be a few
eps
initially, can magnify after repeated operations. Reliance on the behavior ofnan
is not recommended. Different C compilers can yield different results for the same computation.Recursive calls are not allowed in MATLAB Function blocks.
Ports
Input
u — Input port
scalar | vector | matrix
Input port that corresponds to the input variables in the MATLAB code of the function. Each input variable has an associated port that uses the name of the variable.
You cannot pass data types supported by MATLAB but not supported by Simulink between the Simulink model and the function in the MATLAB Function block. You can use these data types in the MATLAB Function block.
For more information on fixed-point data type support for this block, see Fixed-Point Data Types with MATLAB Function Block (Fixed-Point Designer) and Data Type Override with MATLAB Function Block (Fixed-Point Designer).
Dependencies
To create input ports, open the block and create input variables in the Symbols pane. See Create and Define MATLAB Function Block Variables.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| Boolean
| string
| fixed point
| enumerated
| bus
Output
y — Output port
scalar | vector | matrix
Output port that corresponds to the output variables in the MATLAB code in the function. Each output variable has an associated port that uses the name of the variable.
Dependencies
To create output ports, open the block and create output variables in the Symbols pane. See Create and Define MATLAB Function Block Variables.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| Boolean
| string
| fixed point
| enumerated
| bus
Parameters
To edit block parameters interactively, use the Property Inspector. From the Simulink Toolstrip, on the Simulation tab, in the Prepare gallery, select Property Inspector.
Note
MATLAB Function blocks also have Subsystem block parameters that you can access by right-clicking the block and clicking Block Parameters (Subsystem). However, updating these block parameters is not recommended.
Update method — Method used for activating block
Inherited
(default) | Discrete
| Continuous
Specify the method for activating the MATLAB Function block as one of these values:
Inherited
— Input from the Simulink model activates the MATLAB Function block.If you define an input trigger, the MATLAB Function block executes in response to a Simulink signal or function-call event on the trigger port. If you do not define an input trigger, the MATLAB Function block implicitly inherits triggers from the model. These implicit events are the discrete or continuous sample times of the signals that provide inputs to the block.
If you define data inputs, the MATLAB Function block samples at the rate of the fastest data input. If you do not define data inputs, the MATLAB Function block samples at the rate defined by the execution behavior of the parent subsystem.
Discrete
— The MATLAB Function block activates by using the rate you specify in the Sample time parameter of the block. The block generates an implicit event at regular time intervals that correspond to the specified rate. Other blocks in the model can have different sample times.Continuous
— The MATLAB Function block activates during major time steps only, and computes outputs and local continuous variables during major and minor time steps. The block can register zero crossings, which allows Simulink models to sample the block whenever state changes occur. The block computes derivatives for local continuous variables.
Programmatic Use
To set the block parameter value programmatically, access the MATLABFunctionConfiguration
or Stateflow.EMChart
object of the block and change the
object property by using dot notation.
If you use the MATLABFunctionConfiguration
object,
specify the property using these options:
Parameter: | UpdateMethod |
Values: | "Inherited" (default) | "Continuous" | "Discrete" |
If you use the Stateflow.EMChart
object, specify the
property using these options:
Parameter: | ChartUpdate |
Values: | "INHERITED" (default) | "CONTINUOUS" | "DISCRETE" |
Sample time — Time interval at which block activates up during simulation
-1
(default) | scalar | vector
Specify the time interval at which the MATLAB Function block activates during simulation. The default value indicates that the block inherits the sample time from Simulink. For more information on specifying sample time, see Specify Sample Time.
Do not use the Sample Time parameter in the Subsystem block parameters. Instead, use the Property Inspector.
Dependencies
To enable this parameter, set Update method to
Discrete
.
Programmatic Use
To set the block parameter value programmatically, access the MATLABFunctionConfiguration
or Stateflow.EMChart
object of the block and change the
object property by using dot notation.
Parameter: | SampleTime |
Values: | "-1" (default) | scalar | vector |
Data Types: | string | char |
Advanced
Saturate on integer overflow — Whether data saturates on integer overflow
on
(default) | off
Specify whether the data in the MATLAB Function block saturates on integer overflow as one of these values:
on
— The block saturates an integer by setting it to the maximum positive or negative value allowed by the word size. This setting matches MATLAB behavior.off
— The block generates a run-time error in simulation mode when a overflow condition occurs. When you use Simulink Coder to generate code, the behavior depends on your C language compiler.
Tips
When this parameter is
on
, MATLAB adds additional checks during simulation to detect integer overflow or underflow. If integer overflow does not occur in the MATLAB Function block code, it is more efficient to disable this option.Code generated by Simulink Coder does not check for integer overflow or underflow and, therefore, may produce unpredictable results when this parameter is
off
. In this situation, simulate your model to test for overflow and underflow before generating code.This parameter setting is relevant only for integer arithmetic. It has no effect on fixed-point or double-precision arithmetic.
Programmatic Use
To set the block parameter value programmatically, access the
MATLABFunctionConfiguration
or Stateflow.EMChart
object of the block and change the
object property by using dot notation.
Parameter: | SaturateOnIntegerOverflow |
Values: | true or
1 (default) | false or 0 |
Data Types: | logical |
Support variable-size arrays — Whether block supports variable-size data
on
(default) | off
Specify whether the MATLAB Function block supports input and output data
that varies in dimension during simulation. When this parameter is
on
, you can define variable-size outputs by
enabling the Variable size property on output
variables. For more information, see Declare Variable-Size MATLAB Function Block Variables and Variable size.
Programmatic Use
To set the block parameter value programmatically, access the
MATLABFunctionConfiguration
or Stateflow.EMChart
object of the block and change the
object property by using dot notation.
Parameter: | SupportVariableSizing |
Values: | true or
1 (default) | false or 0 |
Data Types: | logical |
Allow direct feedthrough — Whether block supports direct feedthrough semantics
on
(default) | off
Specify whether the MATLAB Function block supports direct feedthrough
semantics, so that the output of the block is controlled directly by the
value of an input. When this parameter is off
, the
block outputs rely only on the current state of the block. Using
nondirect feedthrough enables you to use MATLAB Function
blocks in a feedback loop and prevent algebraic loops. For more
information, see Use Nondirect Feedthrough in a MATLAB Function Block.
Dependencies
To disable this parameter, you must set Update method to
Inherited
or
Discrete
.
Programmatic Use
To set the block parameter value programmatically, access the
MATLABFunctionConfiguration
or Stateflow.EMChart
object of the block and change the
object property by using dot notation.
Parameter: | AllowDirectFeedthrough |
Values: | true or
1 (default) | false or 0 |
Data Types: | logical |
Interpret output column vectors as one-dimensional data — Whether block treats output variables with dimension of length 1 as fixed size
off
(default) | on
Since R2021b
Specify whether the MATLAB Function block treats output variables with a dimension of length 1 as fixed size as one of these values:
off
— The 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.on
— 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.
Note
In release R2021b and earlier, MATLAB Function blocks always convert output column vectors to one-dimensional signals.
Programmatic Use
To set the block parameter value programmatically, access the
MATLABFunctionConfiguration
or Stateflow.EMChart
object of the block and change the
object property by using dot notation.
Parameter: | VectorOutputs1D |
Values: | false or
0 (default) | true or 1 |
Data Types: | logical |
Treat dimensions of length 1 as fixed size — Whether variables with at least one dimension of length 1 are fixed size
on
(default) | off
Since R2023a
Specify whether variables with at least one dimension of length 1 are fixed size as one of these values:
on
— Variables that are variable size with a dimension of 1 are fixed size.off
— Variables in the block that have the Variable size property enabled are always variable size.
This parameter only affects output variables that have the Variable size property enabled. See Variable size.
Programmatic Use
To set the block parameter value programmatically, access the
MATLABFunctionConfiguration
or Stateflow.EMChart
object of the block and change the
object property by using dot notation.
Parameter: | TreatDimensionOfLengthOneAsFixedSize |
Values: | true or
1 (default) | false or 0 |
Data Types: | logical |
Fixed-point properties
Treat these inherited Simulink signal types as fi objects — Inherited Simulink signals to treat as fi
objects
Fixed-point
(default) | Fixed-point & Integer
Specify whether to treat inherited fixed-point and integer signals as Fixed-Point Designer™
fi
(Fixed-Point Designer) objects as one of
these values:
Fixed-point
— The MATLAB Function block treats all fixed-point inputs as Fixed-Point Designerfi
objects.Fixed-point & Integer
— The MATLAB Function block treats all fixed-point and integer inputs as Fixed-Point Designerfi
objects.
For more information, see Ways to Construct fi Objects (Fixed-Point Designer).
Programmatic Use
To set the block parameter value programmatically, access the
MATLABFunctionConfiguration
or Stateflow.EMChart
object of the block and change the
object property by using dot notation.
Parameter: | TreatAsFi |
Values: | "Fixed-point" (default) | "Fixed-point & Integer" |
MATLAB function fimath — Default fimath
properties
Same as MATLAB
(default) | Specify Other
Specify the default fimath
(Fixed-Point Designer) object
properties for the MATLAB Function block as one of these
values:
Same as MATLAB
— The block uses the samefimath
object properties as the current defaultfimath
object. The text box is dimmed and displays the current globalfimath
object in read-only form.Specify other
— Specify your ownfimath
object in the text box one of two ways:Constructing the
fimath
object inside the text box.Constructing the
fimath
object in the MATLAB or model workspace and then entering its variable name in the text box. If you use this option and plan to share your model with others, define the variable in the model workspace.
For more information, see fimath Object Construction (Fixed-Point Designer) and Fixed-Point Data Types with MATLAB Function Block (Fixed-Point Designer).
Tips
The
fimath
object of a MATLAB Function block behaves as aglobalfimath
(Fixed-Point Designer) object for the contents of the block. The block associates thefimath
object properties in this parameter with all fixed-point and integer input signals to the MATLAB Function block that you choose to treat asfi
objects. Constructingfi
objects in the MATLAB Function block introduces additional considerations.If no
fimath
object is associated with afi
object when it is constructed, then thefi
constructor uses the defaultfimath
object settings regardless of the properties in MATLAB function fimath. If you perform operations on thefi
object after it is constructed, the object adopts the properties in MATLAB function fimath.If you specify a
fimath
object in thefi
constructor, then thefi
constructor obeys thatfimath
object when quantizing the value. Anyfimath
object settings not specified in thefi
constructor use the specified properties in MATLAB function fimath.
Programmatic Use
To set the block parameter value programmatically, access the
MATLABFunctionConfiguration
or the Stateflow.EMChart
object of the block and change the
associated object property by using dot notation.
If you use the MATLABFunctionConfiguration
object, specify the property using these options:
Parameter: | FimathMode |
Values: | "SameAsMATLAB" (default) | "UserSpecified" |
If you use the Stateflow.EMChart
object, specify
the property using these options:
Parameter: | EmlDefaultFimath |
Values: | "Same as MATLAB
Default" (default) | "Other:UserSpecified" |
Block Characteristics
Tips
You can call functions defined in:
Simulink Function blocks.
Stateflow® functions in charts. To call functions in charts, enable the Export Chart Level Functions and Treat exported functions as globally visible properties.
By default, MATLAB Function blocks do not include the
%#codegen
directive, but check for errors as if it is included. Adding the%#codegen
directive to a MATLAB Function block does not affect error checking. For more information see Compilation Directive %#codegen.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using Simulink® Coder™.
Actual data type or capability support depends on block implementation.
You can generate Halide code if you have Embedded Coder® license. For more information, see Speed Up Generated Code Execution with Halide Code (Embedded Coder).
HDL Code Generation
Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.
HDL Coder™ provides additional configuration options that affect HDL implementation and synthesized logic. Actual data type or capability support depends on block implementation. For best practices of using the MATLAB Function block, see:
Design Guidelines for the MATLAB Function Block (HDL Coder)
Generate Instantiable Code for Functions (HDL Coder)
Optimize MATLAB Loops (HDL Coder)
Pipeline MATLAB Expressions (HDL Coder)
MATLAB Function (Default) | This is the default architecture for MATLAB Function blocks with fixed-point data types. When you use this architecture, you can use speed and area optimizations for blocks that surround the MATLAB Function block. The code inside the MATLAB Function block is not optimized. |
MATLAB Datapath | This is the default architecture for MATLAB Function blocks with floating-point data types. When you use this architecture, the code generator treats the MATLAB Function block like a regular Subsystem block. By enabling this architecture for fixed-point types, you can use speed and area optimizations for blocks inside the MATLAB Function block and across the MATLAB Function block with other Simulink blocks. This capability enables you to specify additional properties for the MATLAB Function block that you would specify for a Subsystem such as ClockRatePipelining and FlattenHierarchy. |
AdaptivePipelining | Automatic pipeline insertion based on the synthesis
tool, target frequency, and multiplier word-lengths. The
default is |
BalanceDelays | Detects introduction of new delays along one path and
inserts matching delays on the other paths. The default is
|
ClockRatePipelining | Insert pipeline registers at a faster clock rate
instead of the slower data rate. The default is
|
ConstMultiplierOptimization | Canonical signed digit (CSD) or factored CSD optimization. The
default is |
ConstrainedOutputPipeline | Number of registers to place at
the outputs by moving existing delays within your design. Distributed
pipelining does not redistribute these registers. The default is
|
DistributedPipelining | Pipeline register distribution,
or register retiming. The default is |
DSPStyle | Synthesis attributes for multiplier mapping. The
default is |
FlattenHierarchy | Remove MATLAB Function block hierarchy
from generated HDL code. The default is
|
InputPipeline | Number of input pipeline stages
to insert in the generated code. Distributed pipelining and constrained
output pipelining can move these registers. The default is
|
InstantiateFunctions | Generate a VHDL® |
LoopOptimization | Unroll, stream, or do not optimize loops. The default
is |
MapPersistentVarsToRAM | Map persistent arrays to RAM. The default is |
OutputPipeline | Number of output pipeline stages
to insert in the generated code. Distributed pipelining and constrained
output pipelining can move these registers. The default is
|
ResetType | Suppress reset logic generation. The default is |
SharingFactor | Number of functionally equivalent resources to map to a single shared resource. The default is 0. See also Resource Sharing (HDL Coder). |
StreamingFactor | Number of parallel data paths, or vectors, that are
time multiplexed to transform into serial, scalar data
paths. The default is 0, which implements fully parallel
data paths. To specify this property, set
Architecture to |
VariablesToPipeline | Warning
Insert a pipeline register at the output of the
specified variable or variables. Specify the list of
variables as a character vector, with spaces separating the
variables. To specify this property, set
Architecture to |
HDL code generation supports half-precision data types for these functions in MATLAB Function block:
all | and, & | any | cast | conj | ctranspose |
end | = | eq | == | ge, >= | gt, > |
half | inf | int8 | int16 | int32 | int64 |
isa | iscolumn | isempty | isequal | isfinite | isfloat |
isinf | isinteger | islogical | isnan | isnumeric | isreal |
isrow | isscalar | isvector | le, <= | length | logical |
lt, < | max | min | minus, - | NaN | ndims |
ne, ~= | not | numel | or, | | plus, + | prod |
reshape | single | size | sqrt | sum | times, .* |
transpose | uint8 | uint16 | uint32 | uint64 | uminus |
uplus | vertconcat | - | - | - | - |
This block supports code generation for complex signals.
See also Complex Data Type Support (HDL Coder).
HDL Coder supports both tunable and non-tunable parameters with the following data types:
Scalar
Vector
Complex
Structure
Enumeration
For details, see Generate DUT Ports for Tunable Parameters (HDL Coder) and Design Guidelines for the MATLAB Function Block (HDL Coder).
To generate HDL code for models that contain Matlab Function blocks:
In the Configuration Parameters dialog box, click Diagnostics, and set the Algebraic loop parameter to
none
orwarning
.Open the block mask for the Matlab Function block and select the Treat as atomic unit and Minimize algebraic loop occurrences parameters.
If the block contains a System object™, block inputs cannot have non-discrete (constant or
Inf
) sample time.HDL Coder does not support a MATLAB Function that contains the same variable as the input and output of the function. For example, this MATLAB code is not supported.
function y = myFun(y) %#codegen y = 3 * y;
The block supports floating-point data types only in the Native Floating Point mode.
For the MATLAB language subset supported for HDL code generation from a MATLAB Function block, see Supported MATLAB Data Types, Operators, and Control Flow Statements (HDL Coder).
PLC Code Generation
Generate Structured Text code using Simulink® PLC Coder™.
UseExternalDefinition | Suppress block definition in generated code. The
default is |
Fixed-Point Conversion
Design and simulate fixed-point systems using Fixed-Point Designer™.
Actual data type or capability support depends on block implementation.
Version History
Introduced in R2011aR2023a: Specify how to treat output variables with dimension of length 1
With the new Treat dimensions of length 1 as fixed size parameter, 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: Output column vectors as two-dimensional or one-dimensional data
You can now output column vectors in MATLAB Function blocks as two-dimensional or one-dimensional data with the Interpret output column vectors as one-dimensional data parameter.
R2021a: Report runtime errors for MATLAB Function blocks in rapid accelerator mode
Report runtime errors for MATLAB Function blocks when simulating in
rapid accelerator mode by setting the Enable memory integrity checks
configuration parameter to Always on
.
R2020a: 64-bit integer type support for MATLAB Function block
MATLAB Function blocks now support 64-bit integer data. The block
implements int64
and uint64
data types as
fixed-point numbers with a word length of 64 bits and a fraction length of 0.
R2019b: String support for MATLAB Function block
Simulink strings are now supported in MATLAB Function blocks.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)