Marine systems simulation
FMU tools

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.

# 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 <--- Folder where the FMU may contain non-executable files needed for operation
└─ binaries <--- Folder where the FMU contains the 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 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.xml' and is used by the FhSim Co-Simulation implementation fhFMUDll 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 uses the zip command to compress the folder into an FMU (zipped archive with .fmu extension). If no zip command is available, the tool exits and asks the user to create the archive (and thus the FMU) manually.

## Program Options

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

Program options                                                                                                                                Description
--add-dir-to-resources Copy a directory/directories to the FMU resource folder to make it available for the FMU
--author-name The author of the FMU, default value "SINTEF"
--autocopy Experimental feature to automatically copy files and folders referenced in the FhSim model attributes as relative paths into FMU resource folder and overwrite references in FMU FhSim model file to point to the bundled files and directories. Default value 'false'
--autocopy-absolute Experimental feature to copy files and folders referenced in model attributes as aboslute paths into the FMU resource and overwrite references in FMU FhSim model file to point to the bundled files and directories. Default value 'false'
--debug Build the FMU from debug binaries, useful for debugging in single threaded mode in Common Simulation Platform. Default value 'false'
--description Description of the FMU, default value "Model exported from FhSim with FhFmuExport"
--guess-input-interface Use constant valued source ports (example: "0,0,1") as input to the FMU. A new ExternalLinkStandard object created for input to the FMU and connected to the previously constant ports. Initial values are preserved. Default value 'false'.
--guess-output-interface Use 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. Note this requries that only port outputs are used in the example output file, no state outputs are allowed. Default value empty/disabled
--help Produce help message
--input-file The FhSim input file defining the model to export as an FMU
--model-name The name of the FMU, default value "fhsimexport"

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

Allowed options:
--help Produce help message
--input-file arg FhSim input file
--model-name arg (=fhsimexport) Model name in FMU
--autocopy arg (=0) Auto copy files and folders referenced
in model attributes as paths into FMU
and overwrite references in FMU fhsim
model file to point to the bundled
files and directories
folder
--debug arg (=0) Build debug-fmu
--author-name arg (=SINTEF) Author name in FMU
--description arg (=Model exported from FhSim with FhFmuExport)
Model description
--guess-input-interface arg (=0) Guess input interface from constant
values in the interconnecitons (keep
initial values)
--guess-output-interface arg FhSim output file to guess additional
FMI output from
Remarks
Currently, our FMU library support running SimObject libraries either with, or without visualization. That is, if you want both, you will need to export two distinct FMUs.

# 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

This should produce a folder awesomeness and – if you have zip CLI tool – 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 yourself. Tip: .fmu is really a .zip.

Note
When referencing LibName in the a config file to be exported, do not use the short form for a library. That is, use LibName="fhsim_base", not LibName="base".

## 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, there is a known issue with conflicting symbols between transitive libraries of the FhSim dynamic library and cosim. To overcome this issue, you can compile cosim with statically linked libcosim, or use proxyfmu instead, 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