An FMU description consists of several files. An FMU implementation may be distributed in source code and/or in binary format. All relevant files are stored in a ZIP file with a pre-defined structure. The implementation must either implement all the functions of FMI for Model Exchange or all the functions of FMI for Co-Simulation or both. Specifically it is required that all functions specified for Model Exchange and/or Co-Simulation are present, even if they are only needed for capabilities that the FMU does not support. The behavior of those functions is unspecified, so while calling environments can rely on the functions being present, they cannot rely on any particular behavior for functions only needed for capabilities the FMU does not support. The extension of the ZIP file must be ".fmu", for example, "HybridVehicle.fmu". The compression method used for the ZIP file must be "deflate" [(most free tools, such as zlib, offer only the common compression method "deflate")].
Every FMU is distributed with its own ZIP file. This ZIP file has the following structure:
// Structure of ZIP file of an FMU
modelDescription.xml // description of FMU (required file)
model.png // image file of FMU icon (optional)
documentation // directory containing the documentation (optional)
index.html // entry point of the documentation
<other documentation files>
sources // directory containing the C sources (optional)
// all needed C sources and C header files to compile and link the FMU
// with exception of: fmi3PlatformTypes.h, fmi3FunctionTypes.h and fmi3Functions.h
// The files to be compiled (but not the files included from these files)
// have to be reported in the XML file under the structure
// <ModelExchange><SourceFiles> ... and <CoSimulation><SourceFiles>
binaries // directory containing the binaries (optional)
x86_64-windows // binaries for Windows on Intel 64-bit
<modelIdentifier>.dll // shared library of the FMI implementation
<other DLLs> // the DLL can include other DLLs
x86_64-windows-msvc140mt // static libraries for 64-bit Windows generated with
<modelIdentifier>.lib // Visual Studio 2015 with /MT flag
i686-linux // binaries for Linux on Intel 32-bit
<modelIdentifier>.so // shared library of the FMI implementation
aarch32-linux // binaries for Linux on ARM 32-bit
<modelIdentifier>.so // shared library of the FMI implementation
x86_64-darwin // binaries for macOS
<modelIdentifier>.dylib // shared library of the FMI implementation
resources // resources needed by the FMU (optional)
// data in FMU specific files which will be read during initialization;
// also more folders can be added under resources (tool/model specific).
// In order for the FMU to access these resource files, the resource directory
// must be available in unzipped form and the absolute path to this directory
// must be reported via argument "fmuResourceLocation" via fmi3Instantiate.
An FMU has to implement all common functions (according to tables in [state-machine-model-exchange] and [state-machine-co-simulation]). ModelExchange FMUs have to provide additionally the respective Model Exchange function, CoSimulation FMUs the Co-Simulation functions.
The FMU must be distributed with at least one implementation, in other words, either sources or one of the binaries for a particular machine.
It is also possible to provide the sources and binaries for different target machines together in one ZIP file.
The names of the binary directories are standardized by the "platform tuple".
Further names can be introduced by vendors.
Dynamic link libraries must include all referenced resources that are not available on a standard target machine [for example, DLLs on Windows machines must be built with option "MT" to include the run-time environment of VisualStudio in the DLL, and not use the option "MD" where this is not the case].
When compiling a shared object on Linux, RPATH="$ORIGIN" has to be set when generating the shared object in order that shared objects used from it, can be dynamically loaded.
The binaries must be placed in the respective <platformTuple> directory with the general format <arch>-<sys>{-<abi>{<abi_ver>}{<abi_sub>}}.
- Architecture
<arch> -
Name Description aarch32
ARM 32-bit Architecture
aarch64
ARM 64-bit Architecture
i386
Intel 3rd generation x86 32-bit
i586
Intel 5th generation x86 32-bit w/o SSE
i686
Intel 6th generation x86 32-bit with SSE2
x86_64
Intel/AMD x86 64-bit
- Operating system
<sys> -
Name Description darwin
Darwin (macOS, iOS, watchOS, tvOS, audioOS)
linux
Linux
windows
Microsoft Windows
- Application Binary Interface (ABI)
<abi> -
Name Description elf
ELF file format
gnu
GNU
android
Android
macho
Mach object file format
msvc
Microsoft Visual C
- ABI version
<abi_ver> -
Name Description 80
Visual Studio 2005 (MSVC++ 8.0)
90
Visual Studio 2008 (MSVC++ 9.0)
100
Visual Studio 2010 (MSVC++ 10.0)
110
Visual Studio 2012 (MSVC++ 11.0)
120
Visual Studio 2013 (MSVC++ 12.0)
140
Visual Studio 2015 (MSVC++ 14.0)
141
Visual Studio 2017 (MSVC++ 15.0)
- Sub-ABI
<abi_sub> -
Name Description md
Visual Studio with /MD
mt
Visual Studio with /MT
mdd
Visual Studio with /MDd
mtd
Visual Studio with /MTd
Typical scenarios are to provide binaries only for one machine type (for example, on the machine where the target simulator is running and for which licenses of run-time libraries are available) or to provide only sources (for example, for translation and download for a particular micro-processor). If run-time libraries cannot be shipped due to licensing, special handling is needed, for example, by providing the run-time libraries at appropriate places by the receiver.
FMI provides the means for two kinds of implementation: needsExecutionTool = "true" and needsExecutionTool = "false".
In the first case a tool specific wrapper DLL/SharedObject has to be provided as the binary, in the second a compiled or source code version of the model with its solver is stored (see [CoSimulation] for details).
In an FMU both a version for ModelExchange and for CoSimulation might be present.
If in both cases the executable part is provided as a shared library, then two different or only one library can be provided.
The library names are defined in the modelIdentifier attribute of elements fmiModelDescription.ModelExchange and fmiModelDescription.CoSimulation:
[Example for different libraries:
binaries
x86_64-windows
MyModel_ModelExchange.dll // ModelExchange.modelIdentifier =
// "MyModel_ModelExchange"
MyModel_CoSimulation.dll // CoSimulation.modelIdentifier =
// "MyModel_CoSimulation"
]
The usual distribution of an FMU will be with DLLs/SharedObjects because then further automatic processing [(for example, importing into another tool)] is possible.
If run-time libraries are needed by the FMU that have to be present on the target machine, then automatic processing is likely impossible.
The requirements and the expected processing should be documented in the documentation directory in this case.
A source-based distribution might require manual interaction in order that it can be utilized.
The intention is to support platforms that are not known in advance (such as HIL-platforms or micro-controllers).
Typically, in such a case the complete source code in ANSI-C is provided (for example, one C source file that includes all other needed C files with the #include directive).
All C source file names that need to be defined in a compiler directive have to be defined in the XML file under structure <ModelExchange><SourceFiles> and <CoSimulation><SourceFiles>.
These files may include other files.
#include directive with "" should be used for header-filers distributed in the FMU instead of using <…>.
If default options of the compiler are sufficient, it might then be possible to automatically process such source code FMUs.
An exporting tool should give documentation on how to build an executable, either via a documentation file and/or via a template makefile for a particular platform, from which a user can construct the makefile for his/her target platform.
This documentation should be stored in the documentation directory, possibly with a link to the template makefile (stored in the sources directory).
[As template makefile, CMake (http://www.cmake.org), a cross- platform, open-source build system might be used.]
In directory resources, additional data can be provided in FMU specific formats, typically for tables and maps used in the FMU.
This data must be read into the model at the latest during initialization (that is, before fmi3ExitInitializationMode is called).
The actual file names in the ZIP file to access the data files can either be hard-coded in the generated FMU functions, or the file names can be provided as string parameters via the fmi3SetString function.
[Note that the absolute file name of the resource directory is provided by the initialization functions].
In the case of a co-simulation implementation of needsExecutionTool = "true" type, the resources directory can contain the model file in the tool specific file format.
[Note that the header files fmi3PlatformTypes.h and fmi3FunctionTypes.h/fmi3Functions.h are not included in the FMU due to the following reasons:
fmi3PlatformTypes.h makes no sense in the sources directory, because if sources are provided, then the target simulator defines this header file and not the FMU.
This header file is not included in the binaries directory, because it is implicitly defined by the platform directory (for example, i686-windows for a 32-bit machine or x86_64-linux for a 64-bit machine).
fmi3FunctionTypes.h / fmi3Functions.h are not needed in the sources directory, because they are implicitly defined by attribute fmiVersion in file modelDescription.xml.
Furthermore, in order that the C compiler can check for consistent function arguments, the header file from the target simulator should be used when compiling the C sources.
It would therefore be counter-productive (unsafe) if this header file was present.
These header files are not included in the binaries directory, since they are already utilized to build the target simulator executable.
The version number of the header file used to construct the FMU can be deduced via attribute fmiVersion in file modelDescription.xml or via function call fmi3GetVersion.]