Functional Mock-up Unit (FMU)
=============================

What is FMI and FMU?
^^^^^^^^^^^^^^^^^^^^

The Functional Mock-up Interface (`FMI <https://fmi-standard.org/>`__)
is a free standard that defines a container and an interface to exchange
dynamic models using a combination of XML files, binaries and C code
zipped into a single file. The generated files for the exchange are
called Functional Mock-up Units (FMU). The binaries are
platform-specific, so a linux user can´t run a FMU which is created on a
windows machine.

There are two versions of the FMI standard. The OMG toolbox uses **FMI
2.0**. Furthermore, there are two simulation types, co-simulation (CS) and
model exchange (ME). Co-simulation has an included solver in the FMU,
model exchange provides the possibility to use solvers in Python. Due to
a lack of implicit solvers in CS, the OMG toolbox uses **ME**.

Create FMU´s
^^^^^^^^^^^^

The best way to create a FMU for the OMG toolbox is to run the
create\_fmu.mos file in the folder "omg_grid" with the terminal. Make sure that
`OpenModelica <https://openmodelica.org/download/download-windows>`__ is
installed and your latest version of your OpenModelica package is in
the same folder as this script.

By running the create\_fmu.mos with the command *omc*, you can create a
FMU of the model *network* in the *Grids* folder.

::

    path\omg_grid> omc create_fmu.mos

Windows users might need to open the terminal out of OpenModelica by clicking 'tools' => 'OpenModelica Command Prompt' to make sure that the command *omc* gets recognized.

Creating FMUs of other models can be generated by changing
*omg_grid.Grids.Network* in the last line of the *create\_fmu.mos* to
*omg_grid.Grids.YourNetworksName*.

::

    OpenModelica.Scripting.loadFile("package.mo"); getErrorString();
    setCommandLineOptions("-d=newInst"); getErrorString();
    setCommandLineOptions("-d=initialization"); getErrorString();
    setCommandLineOptions("--simCodeTarget=Cpp"); getErrorString();
    setCommandLineOptions("-d=-disableDirectionalDerivatives"); getErrorString();
    OpenModelica.Scripting.translateModelFMU(omg_grid.Grids.Network, version="2.0", fmuType = "me"); getErrorString();

The lines in between are setting flags for the FMU-creation. The
target-language is C++ instead of the default C because of a missing
implementation of directional derivatives in C, which are necessary for the solvers in python.

It is possible to create FMUs directly in OpenModelica (File -> Export ->
FMU). Settings for this can be done in Tools -> Options -> Simulation
(Target language and Translation Flags) and Tools -> Options -> FMU for
the Version, type, name and path. This way is not recommended because of
the possibility to miss flags like the initialization. Furthermore,
problems with the providing of directional derivatives occurred during testing.

Merge FMUs
^^^^^^^^^^^

As mentioned above, FMUs only work on the operating system they are
created on. Though, there is a possibility to combine previously
generated FMUs to allow a usage on different platforms.

First, generate FMUs on different platforms from the **same** model.
Then run the Python file *merge*\_fmus.py\. Select the FMUs which
should be combined and choose a target file (does not need to exist
before). The script checks at several points if the FMUs were generated
from the same version of the library (careful: small changes like parameter variation
might not be detected) and if all FMUs contain binaries for different
platforms.

Annotation for Windows: Sometimes, the script throws an error because in
the temp-folder. The script still works and merges
the fmu. The resulting file just needs to be renamed with an ".fmu" at the end and can
directly be used.