The FhSim FMU (Functional Mock-up Unit) tool makes it possible to export an FhSim model as a stand-alone FMU, see https://fmi-standard.org/. In particular, you can define a set of SimObjects in an FhSim configuration file and export the model, which then bundles necessary libraries and resources in an FMU. Currently, the exported FMU implements FMI 2.0 standard.

FhFmuExport

FhFmuExport is the program that exports an FhSim model file as a stand-alone FMU.

Overview

FhFmuExport is a tool to pack an fhsim model file into an FMU with the required binaries to run the model in an FMU Co-Simulation environment. An FMU is a collection of binaries and resources needed to execute a simulation and communicate over a predefined interface. The folder hierarchy of an FMU is as follows:

.
├─ modelDescription.xml  <--- Definition of the IO interface of the FMU, name and author information
├─ resources             <--- Resource directory with non-executable files needed for operation
└─ binaries              <--- Binary directory with executable files needed for operation
   ├─ win64              <--- Executables for 64 bit Windows platform
   ├─ win32              <--- Executables for 32 bit Windows platform
   ├─ linux32            <--- Executables for 32 bit Linux platform
   └─ linux64            <--- Executables for 64 bit Linux platform

There is no requirement for a complete set of binaries as long as binaries for the platform in use is present. Missing binaries will only influence the ability to exchange FMUs with users of different platforms. This tool only export binaries for the platform it was compiled for. Note that we only actively maintain the 64 bit version of FhSim.

The tool parses the FhSim input file and collects a list of all dynamic libraries used (in the LibName attribute of the Lib elements in the input file). The tool creates the folder structure for the FMU and creates an installation directory for FhSim, which includes the base executables and libraries for simulation and visualization. Only the SimObject libraries being used are copied into the SimObjects library folder.

The tool then collects all SimObjects of type ExternalLinkStandard used for data exchange during simulation. The input ports (input to object, output of FhSim) and output ports (output of object, input to FhSim) are mapped to FMU valuerefs fmiReal. The mapping between the FMU valueref and fhsim ‘'object’:'port'is stored in the file iomapping.xmland is used by the FhSim Co-Simulation implementationfhFMUDll` and is found in the FMU resources folder.

The FhSim model file is stored as model.xml in the FMU resources folder, and the appropriate FMU modelDescription.xml file is written to the FMU folder hierarchy.

Finally, the tool compresses the folder into an FMU (a zipped archive with the .fmu extension). The archive is written in-process with the bundled miniz library, so no external zip program is needed. Pass --no-compression to store the entries uncompressed, which is faster and useful in CI.

Program Options

The table below provides a short description of available command line options for FhFmuExport.

Program option	Short	Default	Description
`--input-file`	`-i`	required	The FhSim input file defining the model to export as an FMU
`--model-name`	`-n`	`fhsimexport`	The name of the FMU
`--author-name`	`-a`	`SINTEF Ocean`	The author of the FMU
`--description`	`-d`	`Model exported from FhSim with FhFMUExport`	Description of the FMU
`--include-license-file`	`-l`	none	Path to a license file to include in the FMU
`--add-dir-to-resources`, `--add-res-dir`	`-p`	none	Copy a directory to the FMU resource folder to make it available for the FMU. May be repeated.
`--autocopy`	`-c`	off	Auto copy files and folders referenced in the FhSim model attributes except those located in `resources`. It rewrites references in the FMU fhsim model file to point to the bundled files and directories.
`--debug`	`-D`	off	Build the FMU from debug binaries, useful for debugging in single threaded mode in Common Simulation Platform.
`--no-compression`	—	off	Store the FMU archive uncompressed. Faster packaging; useful for CI and testing.
`--no-bundled-vis`	—	off	Skip bundling the visualization/Ogre binaries in the FMU. Useful for CI and testing where visualization is disabled.
`--guess-input-interface`	—	off	Use constant valued source ports (example: "0,0,1") as input to the FMU. A new `ExternalLinkStandard` object is created for input to the FMU and connected to the previously constant ports. Initial values are preserved.
`--guess-output-interface`	—	none	Point to a previously generated fhsim output file to make outputs for the FMU. A new `ExternalLinkStandard` object is created for outputs and the ports in the output file are connected to the output. This requires that only port outputs are used in the example output file; no state outputs are allowed.
`--verbosity`	`-v`	off	Print progress detail while exporting. This is not a version flag: `FhFmuExport` has no `--version`.
`--help`	`-h`	—	Display the help menu

Note: --input-file is the only required option, and it may be given at most once, as may every other option except --add-dir-to-resources.

To print a help message type: FhFmuExport --help and you will get:

./FhFmuExport {OPTIONS}
 
    FMU exporter for FhSim.
 
  OPTIONS:
 
      -h, --help                        Display this help menu
      -i[input-file],
      --input-file=[input-file]         FhSim input file
      -n[model-name],
      --model-name=[model-name]         Model name in FMU
      -c, --autocopy                    Auto copy files and folders referenced
                                        in model attributes except those located
                                        in 'resources'. It will rewrite
                                        references in the FMU fhsim model file
                                        to point to the bundled files and
                                        directories
      -p[add-dir-to-resources...],
      --add-res-dir=[add-dir-to-resources...],
      --add-dir-to-resources=[add-dir-to-resources...]
                                        Paths to be added to fMU resource folder
      -D, --debug                       Build debug-fmu
      --no-compression                  Disable compression for faster FMU
                                        packaging (useful for CI/testing)
      --no-bundled-vis                  Skip bundling visualization/Ogre
                                        binaries in FMU (useful for CI/testing
                                        where vis is disabled)
      -a[author-name],
      --author-name=[author-name]       Author name in FMU
      -d[description],
      --description=[description]       Model description
      -v, --verbosity                   Turn on verbosity?
      --guess-input-interface           Guess input interface from constant
                                        values in the interconnections (keep
                                        initial values)
      --guess-output-interface=[guess-output-interface]
                                        FhSim output file to guess additional
                                        FMI output from
      -l[include-license-file],
      --include-license-file=[include-license-file]
                                        Path to license file to include in FMU
 
    FhSim © 2006-2024 Sintef Ocean - Visit www.fhsim.no for more information

Remarks: If you need an FMU to support running SimObject libraries either with, or without visualization, you need to export from a playpen that contains files for both variants. Note that the fhFMUDll must come from a configuration with visualization. A functional procedure is thus to unzip a playpen with visualization enabled into a non-visualization playpen.

Example usage

Suppose you have created an FhSim configure file awesomeness.xml and want to export an FMU for this model. You have a working FhSim installation (also known as FhSim playpen) located at C:\Users\john\fhsim_awesome\playpen\bin. This installation is FhSim with visualization, where your license.lic file is located in the bin folder. The following commands will create an FMU:

cd C:\Users\john\fhsim_awesome\playpen\bin
FhFmuExport.exe \
    --input-file path\to\awesomeness.xml \
    --model-name awesomeness \
    --author-name "John Doe" \
    --description "John's FhSim awesomeness as FMU" \
    --include-license-file license.lic

This will produce a folder awesomeness and awesomeness.fmu in bin/. Note that if SimObject libraries referenced in awesomeness.xml require additional libraries beyond those required by FhSim, you need to manually package them in the awesomeness folder and compress it into an FMU yourself. Tip: .fmu is really a .zip.

Running an FhSim FMU with cosim

You can use an FMU simulation engine to run your exported FhSim FMU awesomeness. We recommend Open Simulation Platform Software. For instance, you can use cosim to run awesomeness.fmu.

cosim run-single awesomeness.fmu

Warning: When running an FhSim-based FMU with visualization or multiple FhSim FMUs, there may be issues with conflicting symbols between transitive libraries of the FhSim dynamic library and cosim. To overcome this issue, use proxyfmu in the source attribute for each afflicted Simulator, see below.

Running FMU with a system structure definition file

Go ahead an create a OspSystemStructure.xml next to your awesomeness.fmu with the following content:

<OspSystemStructure xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://opensimulationplatform.com/MSMI/OSPSystemStructure" xsi:schemaLocation="http://opensimulationplatform.com/MSMI/OSPSystemStructure ../../../src/cpp/xsd/OspSystemStructure.xsd" version="0.1">
  <StartTime>0.0</StartTime>
  <Simulators>
    <Simulator name="awesome" source="proxyfmu://localhost?file=file:///awesomeness.fmu"/>
  </Simulators>
</OspSystemStructure>

Now, run the simulation scenario for 10 seconds:

cosim run . --duration 10

Table of Contents

FhFmuExport

Overview

Program Options

Example usage

Running an FhSim FMU with cosim