FMI Import

This section provides a short description of FMI standard and description of FMU Import component used for importing FMU files.

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 FMI standard defines two concepts:
  • FMI for Model Exchange - The intention is that a modeling environment can generate a C code representation of a dynamic system model that can be utilized by other modeling and simulation environments. Models are described by differential, algebraic and discrete equations with time-, state- and step-events. If the C code describes a continuous system, this system is solved with the integrators of the environment where it is used.
  • FMI for Co-Simulation - The intention is to provide an interface standard for coupling of simulation tools in a co-simulation environment. The data exchange between subsystems is restricted to discrete communication points. In the time between two communication points, the subsystems are solved independently from each other by their individual solver. Master algorithms control the data exchange between subsystems and the synchronization of all simulation solvers (Slaves). Simple Master algorithms, as well as more sophisticated ones are both supported. [fmi-standard-org]

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. []

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).

Figure 1: Co-simulation with the generated code

Figure 2: Co-simulation with tool coupling

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.

Figure 3: Data flow at communication points

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.

Figure 4: FMI Master algorithm

The algorithm explanation is as follows:
  • Initialize Slave – in this step the fmi2Instantiate function is called that allocates all the necessary resources for the Slave model
  • Initialize Parameters – fmi2SetReal, fmi2SetInteger and fmi2SetBoolean functions are called to initialize all the constant inputs and parameter values.
  • Setup Experiment – fmi2SetupExperiment function is called. The start time is defined as 0 and stop time is not defined.
  • Enter initialization mode – fmi2EnterInitializationMode function is called.
  • Exit initialization mode – fmi2ExitInitializationMode function is called.
  • Set inputs – this step is called during the simulation and it initializes the Slaves inputs and tunable parameters by calling the fmi2SetReal, fmi2SetInteger and fmi2SetBoolean functions.
  • Do step – fmi2DoStep function is called which triggers the Slave to do one simulation step. Defined simulation step is equal to the execution rate defined in the schematic model.
  • Read outputs - fmi2GetReal, fmi2GetInteger and fmi2GetBoolean functions are called to obtain the Slave output values.
  • Terminate experiment – fmi2Terminate function is called that terminates the experiment.
  • Free Slave – fmi2FreeInstance function is called to free all the resources allocated in Initialize Slave step.

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

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.

Figure 5: Successfully parsed FMU file

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.

Four variable types are supported:
  • Inputs – these are the input values for the FMU Slave. If Model control check-box is checked, an input terminal will be created on the component that allows the user to connect the desired signal to this variable. By default, all Inputs are selected to be Model controlled. In this case, the Start value will be ignored and the value of the connected signal will be used. If the Model control is unchecked, the terminal will not be connected and the Start value will be used as the variable value. The Start value can be changed if the Model control is unchecked.
  • Outputs – these are the outputs of the FMU Slave. Output terminal is created for each Output variable and it cannot be selected or deselected.
  • Parameters – these are the parameters defined in the FMU Slave. Similar to Inputs, parameters can be constant or can be changed during simulation. If Model control is checked, the input terminal will be created on the component to connect the desired signal. By default, all parameters are treated as constants. The Start value can be changed if desired.
  • Locals – these are local variables of the FMU Slave. The FMI define Locals as variables that can be read but their value cannot be used anywhere else in the simulation. Practically, this means that these values can be read, but they do not create any terminals on the component. If Enable plotting option is checked, a Probe component will be created inside the FMU Import component that will allow for that variable to be monitored in SCADA or read using API functions.
The Table parameters are explained below:
Table 2. Parameter description
Property name Description
Name Variable name. Also specifies the terminal name.
Dimension Dimension of the variable. FMI version 2 supports only scalars so this value will always be 1. Vector values will be unwrapped in the FMU file and each element will be mapped as scalar. For example if ‘res’ is an output vector variable, three output variables will be present instead ‘res[0]’, ‘res[1]’, …
Start value Initial value for the Inputs and Parameters. If the variable is not Model controlled, this value can be changed.
Data type Data type as specified in FMU file. All data types are supported (Real, Integer, Boolean, Enumeration and String) but only Real, Integer and Boolean variables can be controlled externally through a signal from the model. In other words, only these three variables can crate terminals on the component.
Min Minimal allowed variable value.
Max Maximal allowed variable value.
Unit Variable unit as defined in FMU. The value of this property will not alter the variable value in any way. If a unit is nonstandard (ex. mi/h), the conversion to km/h or m/s must be added by the user.
Enable plotting Used for Locals. If checked, the variable can be observed in SCADA or read using API functions.
Model control Used for Inputs, Parameters. If checked, an input terminal is created on the component to allow the user to connect the desired signal from the model.

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.

Figure 6: Induction Machine Open Loop Control example

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).

Figure 7: Control modeled in Simulink

The Simulink model is then exported as an FMU file and imported in the Typhoon HIL tool-chain. The tool used to export the FMU file is FMI Kit. Instructions on how to use this tool is presented in the section Exporting FMU file from MATLAB Simulink model.

Exporting FMU file from MATLAB Simulink model

FMU Import functionality is tested using FMU files exported with FMI Kit 2.7 tool from MATLAB 2017b.

In order to use FMI Kit tool to export FMI Simulink models, some additional tools must be also installed. These tools are MATLAB Support for MinGW and CMake. All the necessary files can be downloaded following these links:

Installing the necessary tools

  1. Add MATLAB Support for MinGW:
    1. Download MATLAB Support for MinGW from the link above. The downloaded file has the extension .mlpkginstall. This file can be installed directly through MATLAB.
    2. Open MATLAB, navigate to the downloaded file inside the MATLAB file explorer and install it.

  2. Download FMI Kit tool:
    1. Download FMI Kit tool from the link above.
    2. Extract the archive on the desired location (ex. C:\FMI Kit\).
  3. Install CMake:
    1. Inside the FMI Kit folder, there is a script that automatically downloads CMake. The is called grtfmi_install_cmake.m and it is located in grtfmi folder (ex. C:\FMI Kit\grtfmi\ grtfmi_install_cmake.m).
    2. Open the script in MATLAB nad run it.
    3. After the script finishes, CMake will be present in the root directory.

Using FMI Kit

  1. Initialize FMI Kit:
    1. Open MATLAB
    2. Add the FMI Kit to path by executing the command: addpath('C:\FMI Kit\')

    3. Initialize FMI Kit library by typing the command: FMIKit.initialize()

  2. Exporting the FMI Simulink model:
    1. Open the model in Simulink and change the Model Configuration Parameters

    2. Change the Solver to Fixed-step and define the Fixed-step size

    3. In Code Generation, change the System target file to gtrfmi.tlc using the Browse button. At the bottom, specify the Select objective to be either Debugging or Execution efficiency

    4. Under FMI options, make sure to check Include sources in FMU. Without the source files, the model cannot be compiled to work on HIL device

    5. Under CMake options, select MinGW Makefiles for CMake generator, and for CMake command put the path to cmake executable (ex. C:\FMI Kit\cmake…\bin\cmake.exe)

    6. Press OK
    7. Build the model using the Ctrl+B command
    8. If the build is successful, the <model_name>.fmu file should be generated in the current folder. Import this file in Typhoon HIL FMI Import component

Known limitations

  • FMU Import is tested with files exported using FMI Kit 2.7 from MATLAB 2017b
  • Although using multiple FMU Import components is supported, exported FMU files using FMI Kit 2.7 are not adequate for this use. Files exported with this FMI Kit version do not use unique functions and redefinition breaks the model compilation. The FMU files can be manually changed to patch this.
  • Although Co-simulation for tool coupling is permitted for Virtual HIL, this option is not tested since FMI Kit 2.7 does not support this.