4. Creating an FMU¶
This chapter describes how to create a Functional Mockup Unit. It assumes you have followed the Installation and Configuration instructions, and that you have created the Simulator model description file as well as the Python script required to interface the Simulator following the Best Practice guidelines.
4.1. Command-line use¶
To create an FMU, open a command-line window (see Notation). The standard invocation of the SimulatorToFMU tool is:
> python <scriptDir>SimulatorToFMU.py -s <python-scripts-path>
where scriptDir
is the path to the scripts directory of SimulatorToFMU.
This is the parser
subdirectory of the installation directory.
See Installation and Configuration for details.
An example of invoking SimulatorToFMU.py
on Windows is
# Windows:
> python parser\SimulatorToFMU.py -s parser\utilities\simulator_wrapper.py,d:\calc.py
Following requirements must be met when using SimulatorToFMU
- All file paths can be absolute or relative.
- If any file path contains spaces, then it must be surrounded with double quotes.
SimulatorToFMU.py
supports the following command-line switches:
Options | Purpose |
---|---|
-s | Paths to python scripts required to run the Simulator.
The main Python script must be an extension of the
simulator_wrapper.py script which is provided in
parser/utilities/simulator_wrapper.py . The name of the main
Python script must be of the form "modelname" + "_wrapper.py" . |
-c | Path to the Simulator model or configuration file. |
-i | Path to the XML input file with the inputs/outputs of the FMU.
Default is parser/utilities/SimulatorModelDescription.xml |
-v | FMI version. Options are 1.0 and 2.0 . Default is 2.0 |
-a | FMI API version. Options are cs (co-simulation) and me
(model exchange). Default is me . |
-t | Modelica compiler. Options are dymola (Dymola), jmodelica
(JModelica), and openmodelica (OpenModelica).
Default is dymola . |
-pt | Path to the Modelica executable compiler. |
The main functions of SimulatorToFMU are
- reading, validating, and parsing the Simulator XML input file. This includes removing and replacing invalid characters in variable names such as
*+-
with_
,- writing Modelica code with valid inputs and outputs names,
- invoking a Modelica compiler to compile the Modelica code as an FMU for model exchange or co-simulation
1.0
or2.0
.
The next section discusses requirements of some of the arguments of SimulatorToFMU.
4.1.1. Simulation model or configuration file¶
An FMU exported by SimulatorToFMU needs in certain cases a configuration file to run. There are two ways of providing the configuration file to the FMU:
- The path to the configuration file is passed as the comamnd line argument
"-c"
of SimulatorToFMU.py. In this situation, the configuration file is copied in the resources folder of the FMU.- The path to the configuration is set by the master algorithm before initializing the FMU.
Note
The name of the configuration variable is _configurationFileName
.
This name is reserved and should not be used for FMU input and output names.
Depending on the tool used to export the FMU, following requirements/restrictions apply:
4.1.1.1. Dymola¶
- If the path to the configuration file is provided, then Dymola copies the file to its resources folder and uses the configuration file at runtime. In this case, the path to the configuration file can’t be set and changed by the master algorithm.
- If the configuration file is not provided, then the path to the configuration file must be set by the master algorithm prior to initializing the FMU.
4.1.1.2. JModelica¶
If the path to the configuration file is provided, then JModelica will not copy it to the resources folder of the FMU. Instead, the path to the configuration is hard-coded in the FMU. As a further restriction, the path to the configuration file can’t be set and changed by the master algorithm.
These are known limitations in JModelica 2.0. The workaround is to make sure that the path of the configuration file is the same on the machine where the FMU will be run.
If the configuration file is not provided, then SimulatorToFMU will issue a warning.
4.1.1.3. OpenModelica¶
If the path to a configuration file is provided, then OpenModelica will not copy it to the resources folder of the FMU. Instead, the path to the configuration is hard-coded in the FMU. However, the path to the configuration file can be set and changed by the master algorithm.
This is a known limitation in OpenModelica 1.11.0. The workaround is to either make sure that the path of the configuration file is the same on the machine where the FMU will be run, or set the path of the configuration file when running the FMU.
If the configuration file is not provided, then the path to the configuration file must be set by master algorithm prior to initializing the FMU.
4.1.2. Reserved variable names¶
Following variables names are not allowed to be used as FMU input, output, or parameter names.
_configurationFileName
: Variable name used to set the path to the Simulator model or configuration file._saveToFile
: Variable used to set the flag for storing simulation results (1 for storing, 0 else).time
: Internal FMU simulation time.
If any of these variables is used for an FMU input, output, or parameter name, SimulatorToFMU will exit with an error.
4.2. Outputs of SimulatorToFMU¶
The main outputs from running SimulatorToFMU.py
consist of an FMU named
after the modelName
specified in the input file, a zip
file called "modelname"
+ ".scripts.zip"
, and a zip
file called "modelname"
+ ".binaries.zip"
. That is, if the modelName
is called Simulator
, then the outputs of SimulatorToFMU
will be Simulator.fmu
, Simulator.scripts.zip
, and Simulator.binaries.zip
.
The FMU and the zip file are written to the current working directory, that is, in the directory from which you entered the command.
"modelname"
+ ".scripts.zip"
contains the Python scripts that are needed to
interface with the Simulator. The unzipped folder must be added
to the PYTHONPATH
of the target machine where the FMU will be used.
"modelname"
+ ".binaries.zip"
contains subdirectories
with binaries files that are needed to interface with the Simulator.
Subdirectories with binaries to be supported by the FMU must be added
to the system PATH
on Windows or the LD_LIBRARY_PATH
on Linux.
That is, if the FMU is exported for Windows 32 bit,
then the subdirectory "win32"
must be added to the system PATH
of
the target machine where the FMU is run.
Any secondary output from running the SimulatorToFMU tools can be deleted safely.
Note that the FMU itself is a zip file.
This means you can open and inspect its contents.
To do so, it may help to change the “.fmu
” extension to “.zip
”.
Note
- FMUs exported using OpenModelica 1.11.0 needs significantly longer compilation/simulation time compared to the tested versions of Dymola and JModelica.
- FMUs exported using Dymola 2018 needs a Dymola runtime license to run.
A Dymola runtime license is not be needed if the FMU is exported with
a version of Dymola which has the
Binary Model Export
license.