FMI Import

About FMI standard

The Functional Mock-up Interface (FMI) 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 called an FMU (Functional Mock-up unit). In other words, FMI provides rules on how to export a model from one simulation tool and import it in other and how to interface that model.

The difference between the two kinds consist of how the importing tool makes the FMU step forward in time.

Models that represent physical quantities such as temperature or velocity are generally described by differential equations. The way that the quantities change with time depend on the value of the quantities themselves (the state), and what external influence they are subjected to (the inputs).

Let’s take the following example: A very simple mathematical model for how the temperature of a house evolves can be written as:

dThouse/dt = k1*(Tout-Thouse) k2*BoilerPower k3

Here, the rate of change of the quantity (dThouse/dt) depends on the state (Thouse) and the inputs (Tout and BoilerPower). k1, k2, and k3 are parameters that do not change with time. To compute how the temperature in the house changes with time, the differential equation needs to be hooked up to a numerical solver.

When you simulate a Co-simulation FMU, the numerical solver is embedded and supplied by the exporting tool. The importing tool will set the inputs, tell the FMU to step forward a given time, and then read the outputs.

When you simulate a Model Exchange FMU, the numerical solver is supplied by the importing tool. The FMU provides functions to set the state and inputs, and to compute the state derivatives (i.e., the left hand side of the equation). The solver in the importing tool will determine what time steps to use, and how to compute the state at the next time step. [modelon.com]

FMI for Co-simulation

In Typhoon HIL tool-chain only FMI for Co-simulation is supported and it will be explained here.

FMI for Co-Simulation is designed both for coupling with subsystem models, which have been exported by their simulators together with its solvers as runnable code (Figure 1), and for coupling of simulation tools (simulator coupling, tool coupling (Figure 2).

The exported FMUs behave as Slaves whereas tools that import them behave as Masters. The masters are responsible for all the data exchange and time synchronization. Also, the data exchange between the Slaves is handled via the master only. There is no direct communication between the slaves.

The data exchange between the Master and Slave is restricted to discrete communication points. This is best explained with the most common master algorithm. This algorithm stops the simulation at each communication point, collects the outputs from all Slaves, calculates the Slave inputs, distributes these inputs to the Slaves and continues the (co-)simulation with the next communication step, with fixed communication step size.

The data flow at each communication point can be illustrated with the block diagram below.

FMI support in Typhoon HIL tool-chain

As already mentioned above, the Typhoon HIL tool-chain supports only FMI for Co-simulation. Also, only FMI version 2 is supported and only the import of FMU files is supported. This is enabled using FMU Import component from the library (Signal Processing -> Extras -> FMU Import).

Both HIL and Virtual HIL device support the FMU import functionality. If HIL device is used, source code files must be included in the FMU file. If Virtual HIL is used, both source code and win64 library can be used. If both are specified, the source code will be used.

Also, if HIL device is used, Co-simulation must be standalone. This means that tool coupling is not possible and the model solver must be included in the FMU. This is not the limitation for Virtual HIL, but the asynchronous execution will not work correctly. In other words, Do Step function must not return the status “Pending” because the Master algorithm is not designed to support this.

The Master algorithm is presented on the block diagram below.

It is important to note that return values, of any function call, are not checked and the Master expects the OK status as a return value.

FMU Import

The FMI Slave functionality is defined using the FMU Import component from the Schematic library.

The component image, dialog window and properties are presented below.

Table 1. FMU Import component

Component icon	Component dialog	Properties
FMU Import		Import FMU file Path type Execution rate Additional definitions

The Choose file button on components dialog window allows you to browse to desired FMU file.

If the FMU file is parsed correctly, the table will be updated from the variables extracted from the file. General info field will also be filled with the information from FMU file. The example of dialog window, once the FMU file is imported is illustrated below.

The Path type property lets you select the save format of the FMU file path. The absolute path will store the full system path to the FMU file, whereas relative path will save the path relative to the model directory. The relative path can be selected only if the model is saved first.

As mentioned in the About FMI standard section, the FMU is essentially a collection of binary files and C code zipped in a single archive. This means that a C compiler is called in order to compile the code into an executable running on a HIL device. Most of the time, FMUs do not require any additional definitions to be passed to the compiler, but in a case where it is required, the Additional definitions property serves this purpose. For example, the code may contain the NO_MULTITHREADED_SUPPORT definition that handles code execution for a platform that support multi-threading. Since HIL devices do not support multi-threading, this definition must be included in the Additional definitions as shown in Additional definitions property.

If there are more than one definition, they are separated using a single space.

One definition that is included by default is FMI2_FUNCTION_PREFIX. This definition assures that all the FMU functions have appropriate prefixes and there is no need to manually declare them.

Additional resources

The FMU standard defines that the resources folder can exist in the FMU archive. If any additional resources are required for the simulation to work properly, these resources are stored in this folder. Usually, these are some empirical data, parameters, tables, or even additional DLLs.

The Signal Processing code running on the HIL device is executed as a bare-metal application and this means that file system calls are not supported on the HIL device. In addition this means that the resources folder is of no use since the HIL device cannot open any file to extract data; this folder will simply be ignored. Please consider this when implementing an FMU on a HIL device, as this may greatly alter simulation results.

When running a simulation using VHIL, the resources folder will be used and the simulation will run as normal.

Usage example

The use of the FMU Import component will be illustrated on the Induction Machine Open Loop Control example model (examples\models\power electronics\indm_open_loop_control\ indm_open_loop_control.tse).

The example model is presented on the picture below.

Open loop control is designed using Signal Processing components and it is located on the bottom of the schematic. There are two inputs and one output of this control. The inputs are Frequency and Modulation index and the output is the reference signal for 3 phase rectifier. The same control is created in MATLAB Simulink (below).

The Simulink model is then exported as an FMU file and imported in the Typhoon HIL toolchain. Instructions on how to export FMU files from MATLAB Simulink is explained in Exporting FMU files from MATLAB Simulink.

Exporting FMU files from MATLAB Simulink

From the 2021a version, MATLAB enables its users to export a Simulink model to an FMU archive.