Export Simulink Models to Functional Mock-up Units - MATLAB & Simulink (original) (raw)
Export Models
Export Simulink® models to functional mockup unit (FMU) that supports co-simulation and model exchange modes for FMI version 2.0 and 3.0. To check that the exported block is still a valid Simulink model, you can also direct the software to import the FMU back to a Simulink model as part of the export process.
Requirements include:
- Simulink Compiler™
- FMU Builder for Simulink Support Package
- A writable folder into which to place the exported FMU.
Exported models can have:
- Input and output data types
double
,int32
,boolean
,Enum
, andstring
for FMI 2.0 - Input and output data types
single
,double
,int8
,uint8
,int16
,uint16
,int32
,uint32
,int64
,uint64
,boolean
,Enum
andstring
for FMI 3.0 - Matrices
- Bus Signals
- Tunable parameters which can be model arguments, base workspace, or data dictionary variables.
- Unit and description.
Enum
type in Simulink is int32
based. In FMI 2.0 enumerations are int32
based and in FMI 3.0 enumerations areint64
based.
When you export a model as a standalone FMU, certain metadata from Simulink is also exported with the FMU. The metadata includes:
- Model description
- Signal unit
- Parameter unit
- Signal description
- Parameter description
Standalone FMU
Simulink models can be exported to:
- Co-simulation FMU compatible with FMI version 2.0 and 3.0. For an example, seeExport Simulink Model to Standalone FMU.
- Model exchange FMU compatible with FMI version 2.0 and 3.0. For an example, seeGenerate Model Exchange FMU from Simulink Model.
Exporting simulink model to standalone FMU with Simulink Compiler has the same compiler requirements as Simulink Compiler. For more information see, https://www.mathworks.com/support/requirements/supported-compilers.html
The generated FMU package for FMI 2.0 contains the following files:
modelDescription.xml
model.png (optional)
binaries\win64\modelname.dll
, orbinaries\linux64\modelname.so
, orbinaries\darwin64\modelname.dylib
The generated FMU package for FMI 3.0 contains the following files:
modelDescription.xml
terminalsAndIcons\icon.png (optional)
binaries\x86_64-windows\modelname.dll
, orbinaries\x86_64-linux\modelname.so
, orbinaries\x86_64-darwin\modelname.dylib
sources\buildDescription.xml
You might experience an expected time delay in the exported FMU for co-Simulation mode. You can use co-simulation FMU 3.0 with event mode to reduce this delay. For more information, see Eliminate Single Step Delay in Co-Simulation FMU Using Event Mode.
FMU Variables
FMU modelDescription.xml
file contains interfacing variables converted from Simulink model:
- Variables with
causality=’input’
: converted from root Inport block - Variables with
causality=’output’
: converted from root Outport block - Variables with
causality=’parameter’
: converted from referenced Runtime Tunable Parameters - Variables with
causality=’local’
: converted from internal variables - Independent variable
‘time’
<Clock>
variables withintervalDecimal
andshiftDecimal
specifying constant period clock rate and offset, assigned to root Inport or Outport blocks.
To generate FMU input and output, define root Inport and Outport blocks in Simulink model. The name of the generated variable is converted from root Inport or Outport block name, by removing special and blank characters and avoiding duplicates. If input/output signal carries unit information, it is exported as Unit
attribute of the FMU variable. If the input/output block has a non-empty description information under Block Properties > General, it is exported as Description
attribute of the FMU variable.
The following input and output data types are supported for FMI 2.0:
double
(Real in FMI)int32
(Integer in FMI)boolean
(Boolean in FMI)string
(String in FMI)Enum
(Enumeration in FMI)
The following input and output data types are supported for FMI 3.0:
single
(Float32 in FMI)double
(Float64 in FMI)int8
(Int8 in FMI)uint8
(UInt8 in FMI)int16
(Int16 in FMI)uint16
(UInt16 in FMI)int32
(Int32 in FMI)uint32
(UInt32 in FMI)int64
(Int64 in FMI)uint64
(UInt64 in FMI)boolean
(Boolean in FMI)string
(String in FMI)Enum
(Enumeration in FMI)
Enum
type in Simulink is int32
based. In FMI 2.0 enumerations areint32
based and in FMI 3.0 enumerations are int64
based.
If model root Inport or Outport block is a non-virtual bus, individual bus elements will be expanded to variables using structured naming convention (‘.’)
. If model root Inport or Outport block is array or matrix, individual scalar elements will be expanded to variables using array naming convention (‘[]’)
.
To export referenced variables as FMU parameter, you can:
- Define a base workspace variable or data dictionary.
- Define a Simulink Parameter object.
Ensure that the variable and the parameter object is directly references by tunable parameters of Simulink blocks. In FMU Export dialog box, open Parameters tab to configure each parameter. You can:
- Unselect Exported option to hide a parameter.
- Modify Exported Name so the parameter is displayed with a different name on FMU interface. Do not use special characters and duplicate names.
- Set
Unit
andDescription
of FMU parameter variable by clicking on parameter name, and directly modifying the parameter object.
If the FMU parameter isSimulink.Parameter
, click the hyperlink to modify theUnit
andDescription
of the variable.
If FMU parameter is a regular MATLAB® variable, clicking the hyperlink opens model explorer. You can convert MATLAB variable to aSimulink.Parameter
so that it can carryUnit
andDescription
.Unit
andDescription
of FMU parameter variable cannot be updated directly in FMU Export dialog box. You can configureUnit
andDescription
through model explorer, double-clickingSimulink.Parameter
in base workspace, etc.
The following parameter data types are supported for FMI 2.0:
double
(Real in FMI)int32
(Integer in FMI)boolean
or logical (Boolean in FMI)string
(String in FMI)Enum
(Enumeration in FMI)
The following parameter data types are supported for FMI 3.0:
single
(Float32 in FMI)double
(Float64 in FMI)int8
(Int8 in FMI)uint8
(UInt8 in FMI)int16
(Int16 in FMI)uint16
(UInt16 in FMI)int32
(Int32 in FMI)uint32
(UInt32 in FMI)int64
(Int64 in FMI)uint64
(UInt64 in FMI)boolean
(Boolean in FMI)string
(String in FMI)Enum
(Enumeration in FMI)
Enum
type in Simulink is int32
based. In FMI 2.0 enumerations are int32
based and in FMI 3.0 enumerations areint64
based.
If referenced parameter is a struct
, individualstruct
members will be expanded to variables using structured naming convention (‘.’)
. If referenced parameter is array or matrix, individual scalar elements will be expanded to variables using array naming convention(‘[]’)
.
When a Simulink model with model reference block is exported to FMU, you can also export base workspace variables, model arguments and instance parameters that are promoted from the sub model.
On the Simulink toolstrip, under Save, select Export Model to Standalone FMU to view options for exporting an FMU with internal variables. For more information on exporting a model as FMU with internal variables, seeConfigure Model to Export as FMU with Internal Variables.
FMU Solver
Models with fixed-step and variable-step solvers are supported for export to a standalone co-simulation FMU that is compatible with FMI 2.0 or FMI 3.0 standards. It is recommended to set a fixed fundamental sample time (Solver >Solver details > Fixed-step size) before exporting a model with fixed-step solver. For simulating a variable-step FMU in your system, you need to have an installation of MATLAB or MATLAB runtime. If you are using MATLAB runtime, its version should be the same as the MATLAB version in which the variable-step FMU was created. When simulating the standalone FMU in another environment, communication step-size must be an integral multiple of the fundamental sample time.
FMU Dynamic Library
A generated FMU contains a dynamic library build for the current platform. The defaultfmi2TypesPlatform
or fmi3TypesPlatform
value is used.
All required and optional fmi2
or fmi3
functions defined by FMI standard can be invoked. However, the following functions have no operation and return fmi2OK
or fmi3OK
immediately:
- Model-Exchange functions
- Functions accessing or serializing
FMUstate
- Functions setting or getting input or output derivatives
- Functions querying
fmi2DoStep
orfmi3DoStep
status, or cancelingfmi2DoStep
orfmi3DoStep
- Function computing directional derivatives of variables
Generate FMU with Clocks
Export your model with fixed-step solver as a standalone cosimulation FMU, compatible with FMI 3.0 standards and containing constant periodic clocks.
To generate FMU with constant periodic clocks from a model, in the block dialog box of the model root inport and outport blocks, set the Sample time parameter with a desired sample rate and offset. Unique discrete periodic sample rates specified in Simulink are registered as constant periodic clocks within the FMU.
During the export, set the ConstantPeriodicClock
argument of theexportToFMU
function to on
.
exportToFMU('model','FMIVersion','3.0', ... 'FMUType','CS','ConstantPeriodicClock','on');
You can also select the Export constant periodic clock check box on the FMU Export dialog box to export an FMU with clocks.
The modelDescription.xml
file will contain<Clock>
elements within ModelVariables
that defines the clock variable for each of the exported clock. It is added as attribute of the input or output element. For an example of exporting model as FMU with clocks, see Export Model as FMU with Constant Periodic Clocks.
Save Source Code with FMU Export
Export a Simulink model to FMU along with C or C++ source code. To do so, first set the desired target language for your model. Use the set_param
function withTargetLang
argument or the Language field in theCode Generation configuration pane of the Configuration Parameters dialog box of the model to set the desired target language for the source code as C or C++.
set_param('mdlName','TargetLang','C++');
To generate the FMU, check Save Source Code in theExport Model to FMU Co-Simulation window or use the commandexportToFMU('mdlName', 'FMIVersion', '2.0', 'FMUType', 'CS', 'SaveSourceCodeToFMU','on')
to export the model to FMU with C or C++ source code. You can set the SaveSourceCodeToFMU
argument asoff
if you do not need access to the source files.
Note
You need Simulink Coder™ license to package the FMU with C or C++ source code and access the source files.
If the Simulink model contains model references with custom data types or fixed-point functions, exporting FMU with source code may cause an error due to duplicate header files in the _sharedutils
folder. Follow instructions on Generate Shared Utility Code to set the Code Generation >Interface > Shared Code Placement parameter to 'Shared Location
' and regenerate the FMU.
You can export a Simulink model with a FMU Import blocks as nested standalone FMU. When exporting a nested FMU, Simulink packs all dependent inner FMUs into the resources/ folder of the nested FMU. When the nested FMU is instantiated in a simulation environment, all inner FMUs will share the same callback functions provided by the environment, for example, logger and memory allocation functions.
Generate Multi-Instantiable FMU
During export you can specify if you need the FMU to be compatible for multi-instantiation. You can export Simulink models with fixed-step solvers as multi-instantiable FMU compatible with FMI 2.0 and 3.0 standards. Doing so enables you to import and reuse multiple instances of the FMU or use it within the For Each Subsystem block in Simulink.
To generate a multi-instantiable FMU, set the supportMultiInstance
argument of the exportToFMU
function as on
during export.
exportToFMU('model','FMIVersion','3.0', ... 'FMUType','CS','SupportMultiInstance','on');
You can also select the Support multiple instantiation per process check-box in the Advanced tab of the FMU Export dialog box to export the model as a multi-instantiable FMU.
The canBeInstantiatedOnlyOncePerProcess
flag inmodelDescription.xml
is set to false
when you configure an FMU for compatibility with multi-instantiation.
Export Model as FMU with States
You can export a Simulink model with a fixed-step solver as an FMU that containsFMUState
and is compatible with FMI 2.0 and 3.0 standards. This enhances the simulation control of the FMU in Simulink. It enables the FMU to be used with model operating point to capture simulation state, perform backward simulation stepping, use fast restart for iterative simulation, and solve algebraic loops involving the FMU. For more information, see Capture Simulation State, Fast Restart, and Step Through Model Containing FMU.
To generate an FMU with FMUState
, set theEnableFMUState
argument of the exportToFMU
function option as on
during export.
exportToFMU('model','FMIVersion','3.0', ... 'FMUType','CS','EnableFMUState','on');
You can also select the Enable FMUState capability check-box in the Advanced tab of the FMU Export dialog box to export the model as a FMU with FMUState
.
The canGetAndSetFMUState
andcanSerializeFMUState
flags in themodelDescription.xml
are set to true
for an FMU when it supports FMU states.
Specify Additional Files
While exporting a Simulink to a standalone FMU, you can specify additional files to be included in the generated FMU, such as resource, DLL etc. The target locations for these files can be:
<fmuroot>/binaries/<arch>/
– dependent DLLs<fmuroot>/resources/
– data files, lookup tables, etc<fmuroot>/documentation/
– user provide their own help content
For an example on specifying additional files while exporting a Simulink model, see Export Simulink Model to Standalone FMU with User Specified Files and Archived Project with Harness Model.
Export Protected Model
You can export a Simulink model that is protected to FMI 2.0. For an example on exporting protected models, see Export Simulink Model with Protected Model and FMU Import Block to Standalone FMU.
Limitations
You cannot generate FMU from a Simulink model, due to these limitations:
- Non-zero simulation start time is not supported.
Specify Additional Targets
You can generate a standalone cosimulation Functional Mockup Unit (FMU) that is compatible with FMI 2.0 and 3.0 standards with Linux® binary on Windows® platform. For more information, see Export Model as FMU with Linux Binary on Windows.
Tips to Mitigate Numerical Accuracy of Cosimulation FMU
- One-step delay behavior of co-simulation FMU: At every communication point of a cosimulation FMU, both input and output signals are synchronized between the FMU and Simulink. This means changing input at time
T(i)
will not affect the output signal value at the same time point. The earliest time it affects output is the next communication pointT(i+1)
. This is applicable for cosimulation FMUs compatible with FMI 1.0, 2.0, and 3.0 standards. You can eliminate this one-step delay for a cosimulation FMU compatible with FMI 3.0 standard by using the event mode. For an example, see Eliminate Single Step Delay in Co-Simulation FMU Using Event Mode. - Selection of local solver step size before exporting FMU: In Simulink, local solver step size should be a factor of any discrete rate in the model. The communication step size of the cosimulation FMU should be an integral multiple of the base sample rate of the model in which it is imported. When exporting to FMU, it is recommended to choose a local solver step size that is much smaller than potential communication step size when this FMU is used. For example, when exporting a system with one integrator, if the communication step size equals to local step size, the input signal will take few communication steps to be propagated to the output. If the local solver step size is much smaller, it would improve the numerical accuracy of the cosimulation FMU.
- Selection of communication step size for co-simulation FMU: If a Simulink model has a periodic sample rate on root Inport/Outport, when exporting to FMU it places logical constraints on the range of communication step size that the FMU can accept when being simulated in an FMU importing tool:
- If the discrete rate input/output signal represents a signal which is continuous by nature (e.g. a physical quantity as in physical modeling domain) but unfortunately has to be sampled due to the co-simulation boundary: when importing the FMU into new environment, the communication step size may be arbitrary, as long as it is an integer multiple of fundamental step size of local solver.
- If the discrete rate input/output signal represents a signal that is discrete-sampled by nature (e.g. a clocked signal as in controller/logic design): when importing the FMU into new environment, the communication step size should be a factor of this rate, and shall not exceed the rate itself to avoid accidental down-sampling.
- "Variability" attribute for I/O signals on FMU: In Simulink, the sample rate of a signal (continuous, discrete) and its datatype (
double
,int32
, etc.) are independent of each other. This poses an issue when exporting to FMU, because FMI does not allow variable "variability" attribute to be "continuous" unless the datatype is double (fmiReal
). In the generated FMU, the signal "variability" attribute cannot represent the rate information of original Inport/Outport modeled in Simulink environment. - Input interface limitation: You must not connect continuous derivative blocks or any blocks that is continuous in nature with continuous time root Inport. After exporting to cosimulation FMU, the cosimulation scheme forces the root Inport to be discrete and generate zero-order-hold signal. This confuses continuous blocks and will produce wrong answer. To avoid this behavior, use discrete derivative blocks and discrete rate signals instead.
- Numeric compensation in Simulink: To improve the numeric accuracy of the imported cosimulation FMU in Simulink, consider using the numeric compensation feature of Simulink. For more information, see Numerical Compensation.
Export a Simulink Model
Use the Export Dialog Box
Export the vdp
example using the Simulink toolstrip: Simulation > Save >Standalone FMU.
- Open the model vdp.
- In the Simulink Editor, navigate to Simulation >Save > Standalone FMU.
- In Simulink Editor, select Save > Export to > FMU Co-Simulation.
- The export dialog box opens without compiling the model. This allows for faster export when using the default options. You can manually run compilation of the model using the Refresh option in the dialog box to view and customize the export of inputs, outputs, parameters and internal variables.
- Set the desired FMU Type and FMI Version.
- Specify the desired path and name for the FMU.
- Click Create
By default, Simulink creates the FMU and a harness model with its dependencies stored in aMAT
file. It then packs them into archived project (.mlproj
). You can change the behavior by settingContents option to .
Use the Programmatic Interface
- Export the
vdp
example to an FMU using the defaultexportToFMU
function. This command creates the FMU filemodelName.fmu
. By default, the command also creates a Simulink modelmodelName_fmu.slx
, that contains an FMU Co-Simulation block with the original model. Create this model if you want to check the integrity of the exported FMU.
openExample('simulink_general/VanDerPolOscillatorExample');
load_system('vdp')
set_param('vdp', 'SolverType', 'Variable-step')
exportToFMU('vdp', 'FMIVersion', '2.0', 'FMUType', 'CS') - Export the
vdp
example to an FMU using theexportToFMU
function, but do not create a Simulink model. This command creates the FMU filemodelName.fmu
.
openExample('simulink_general/VanDerPolOscillatorExample');
load_system('vdp')
set_param('vdp', 'SolverType', 'Fixed-step')
exportToFMU('vdp', 'FMIVersion', '3.0', 'FMUType', 'CS', ...
'CreateModelAfterGeneratingFMU','off') - Export the
vdp
example to an FMU using theexportToFMU
function. Create a model for the FMU and use an image of the original model as the block icon. This command creates the FMU file,modelName.fmu
and a Simulink model with an FMU Co-Simulation block whose block icon is the original model.
openExample('simulink_general/VanDerPolOscillatorExample');
exportToFMU('vdp', 'FMIVersion', '2.0', 'FMUType', 'CS', ...
'AddIcon','snapshot')
Examples for Different Workflows
The examples below illustrate how to use FMU export for all different scenarios:
- Export Simulink Model to Standalone FMU
- Export Standalone FMU with External C++ Code
- Export Simulink Model with Protected Model and FMU Import Block to Standalone FMU
- Export Simulink Model to Standalone FMU with User Specified Files and Archived Project with Harness Model
- Export Simulink Model to Standalone FMU with Source Code
See Also
exportToFMU | configureForDeployment | Simulink.SimulationInput | mcc | sim