The FMU Export Assistant

The FMU Export Assistant is a tool that

• prepares the model for export by generating the FMI API functions;

• compiles the C source code of the model into some binary files compatibles with the selected targets;

• generates the XML model description file;

• packs together the description file and the binary files into an FMU file.

It can be accessed in Simulation mode from the Interfaces > FMU export assistant menu command. It opens a dialog box with a three-step assistant. The first step handles the Export settings (see figure below).

Figure 48: First step of the FMU Export Assistant

At the top of the dialog box a drop down list is used to select the FMU type and version. Available combinations are:

• FMI for Co-simulation, version 1.0

• FMI for Co-simulation, version 2.0

• FMI for Co-simulation, version 3.0

• FMI for Model Exchange, version 1.0

• FMI for Model Exchange, version 2.0

Note

The last option (Model Exchange) is only available for explicit systems, that is to say models which yield a system of ordinary differential equations that can be numerically integrated using explicit discretization methods. Systems that have at least one implicit state variable either declared or generated (see figure below) are flagged as implicit and cannot be exported as FMU for Model Exchange.

Figure 49: Implicit state variables reported during the system creation

In that case, the option is grayed-out in the drop down list, and when selected, a message box provides a warning (see figure below).

Figure 50: Warning message about implicit systems when FMI for Model Exchange is selected

In the middle of the FMU Export Assistant dialog box, a radio button list entitled Visibility level: exposed elements allows you to choose which parameters and variables of the model are publicly declared by the FMU. Indeed, it is not always interesting to expose every element (parameters and variables) of a model in the interface of an FMU, except for debugging purposes. Sometimes, only a few parameters and result variables are relevant for the use of the FMU in the import environment. At other times, the FMU is meant to be a "black box" that only has input and output variables connected to its environment, with no way to alter its parameters or access internal variables. Three choices are thus available:

• High: expose all parameters and variables. This means that all parameters and variables of every submodel and supercomponent of the model (including all the global parameters) are declared in the model description file of the FMU;

• Low: expose nothing except input and output variables. Only the input and output variables that are mandatory for connecting the FMU with the signals from the environment are available. All other model parameters and variables are not declared in the model description file of the FMU;

• User-defined: expose only the watch parameters and variables. In this case, the parameters and variables that appear in the watch parameters list and in the watch variables list are declared by the FMU, in addition to the input and output variables that are always required for connecting the FMU with its environment. This is the default setting.

However it has to be noted that if the FMI for Co-simulation type is selected, some of the solver-related parameters (that can be defined in the Run Parameters dialog box) are always declared by the FMU. Indeed, these parameters are needed for setting the behavior of the numerical solver provided within the FMU for Co-simulation. See hereafter for a list of all solver settings declared by the FMU.

Note

For large models containing a large number of components (submodels and supercomponents), exporting all the variables could have an impact on the simulation performance, since the values of all parameters and variables have to be read repeatedly by the import environment during simulation. In that case, exporting only a limited number of interesting and meaningful parameters and variables through the watch lists can significantly enhance performance.

Note

According to the FMI specification, if an FMU for “model exchange” is exported, all its state variables will necessarily be visible in the import tool (whose solver will be used for the integration) as long as the latter supports the display of exposed internal variables of the FMU. This is independent of the visibility level selected. The only way to completely hide these state variables is to choose the "co-simulation" mode, without any option to access the directional derivatives.

The next field of the dialog box is a checkbox titled Provide directional derivatives when applicable. This is only applicable to FMI for Model Exchange or Co-simulation 2.0 or 3.0. This option is ignored with FMI 1.0. When selected, the FMU allows the importing environment to query the value of the directional derivatives of the output variables or of the continuous-time state variable time-derivatives with respect to the input variables or the continuous-time state variables, if any of these variables actually exist in the model. Refer to next section for more details about this feature.

The lower part of the dialog box contains a checkbox titled Embed tables. If the checkbox is selected, all the data files used as parameters by submodels are automatically included in the executable part of the FMU as C declarations. As a consequence, for an FMU which is targeting a native platform like Windows or Linux, the corresponding data are automatically embedded in the binary file of the FMU. For a source-code FMU targeting real-time platforms, the data are part of the source code that is to be compiled by the importing tool of the real-time environment. Thus, these data files do not have to be provided by the importing environment to execute the FMU. This applies to all data table file formats recognized by Simcenter Amesim, such as the 1D, 2D, 3D, 4D, 5D, 6D, 7D, 8D, Multi 1D, Multi M1D and XY tables (see ref. 8 for more details about table formats), provided that the data file is referenced by a text parameter of type input file of a submodel. If the data file is used directly by a submodel without referencing an input file text parameter, the data file is not processed by the FMI export tool, and is therefore not included in the FMU. This means in this case that the data file must be provided at runtime by the importing environment, otherwise the simulation of the FMU may fail because of a missing data file.

Note

A limited number of submodels may implicitly (i.e. by means of enumeration parameters) use tables – such as fluid or thermal properties – that are provided in the Simcenter Amesim distribution. FMUs need to access these tables as well. Therefore, if the target machine does not have Simcenter Amesim installed, these submodels need to be set – before the export – to their “user defined” modes in order to point to copies of these tables instead. These copies can then be embedded as described previously. Alternatively, a directory structure containing these tables (e.g. $AME\libhydr\data), similar to the “original” Simcenter Amesim directory structure, can be reproduced on the target machine, with an AME environment variable set accordingly.

After clicking the Next> button, and when an unrecognized file format is detected by the export tool, a dialog box asks for the actual type of the file (see figure below).

Figure 51: The File type not recognized dialog box

By selecting the appropriate file type in the drop down list, it is possible that the data file will be recognized by the export tool, and thus embedded in the executable part of the FMU. Otherwise, the data file must be provided at runtime by the importing environment. A second checkbox titled FMU for real-time is available if the FMU type selected is Co-simulation. It is aimed at generating a source-code FMU for one of the supported real-time platforms. It should be left unchecked if you want to generate a binary FMU for one of the native platforms of Simcenter Amesim, e.g. Windows or Linux. Since real-time targets only accept FMU for Co-simulation that makes use of a fixed step size integrator, it is not possible to generate an FMU if the variable step size solver is currently enabled for simulating the model. Indeed, after clicking the Next> button, and if a fixed step size solver is not enabled, a message box warns you about it, and proposes to open the Simcenter Amesim Run Parameters dialog box to switch on the fixed step size integrator (see figure below).

Figure 52: Warning message about fixed step size integrator not selected

The last field at the bottom of the dialog box is called Output directory. It is the path to the directory where the FMU is to be created. This path can be typed in directly in the field, or selected using the directory browser that can be opened using the … button on the right of the field. The Next> button calls the second step of the assistant. This step handles platform selection and it enables you to choose combinations of architecture and compiler for building the binary files to include in the FMU. Two cases are available:

• The FMU for real-time checkbox is not selected. A binary FMU is desired for the native platform, i.e. the platform on which Simcenter Amesim is currently running, either Windows or Linux. The dialog box proposes the options shown in the figures below. By selecting the corresponding checkboxes, and depending on the availability of the compilers, it is possible to create binary executables for a 64-bit architecture. No check is done on the availability of the compilers. Only the GNU GCC compiler provided with Simcenter Amesim is guaranteed to be available on the Windows platform:

Figure 53: Second step of the FMU Export Assistant, showing the architecture and compiler options for the native Windows platform

Figure 54: Second step of the FMU Export Assistant, showing the architecture and compiler options for the native Linux platform

Note

If you are using the Visual Studio or Intel oneAPI compiler, you must make sure the execution environment of the exported FMU has the corresponding redistributable libraries installed.

• The FMU for real-time checkbox is selected. A source-code FMU for a real-time platform is desired. The dialog box displays a drop down list, as shown in the figure below. Any combination of FMI for Co-simulation version and of real-time target can be selected at this time. Refer to the user manual of the real-time target to check for the versions of FMI supported by the importing environment.

Figure 55: Second step of the FMU Export Assistant, showing the real-time target selection list (Linux)

Figure 56: Second step of the FMU Export Assistant, showing the real-time target selection list (Windows)

The bottom of the dialog box displays a field for entering additional settings. The Generate log file checkbox, if enabled, creates a file called interf.log that contains all the messages reported by the Export tool during the system compilation and FMU generation. The content of this file corresponds to the content of the Details tab that is displayed at the last step of the assistant. When the Generate> button is clicked, the assistant enters its last step, which concerns FMU generation. Two tabs are displayed, the first one called Messages, and the second one called Details. The Messages tab displays a summary of the export activity: preparation of the model, C code compilation (in the case of a binary FMU), and FMU generation (see figure below).

Figure 57: Last step of the FMU Export Assistant, showing the Messages tab

When the FMU is actually generated, a message FMU generation succeeded is visible. In the Details tab, all the details about the export process are given, and especially the C code compilation in the case of a binary FMU (see figure below).

Figure 58: The last step of the FMU Export Assistant,  showing the Details tab

If the Generate log file checkbox is enabled at the second step of the assistant, the content of this tab is completely written in the interf.log file which is stored in the same directory as the Simcenter Amesim model. The Close button terminates the assistant. The FMU is available in the output directory specified during first step.