Software overview

Table of Contents

• What ships with FhSim
• Visualization is a compile-time choice
• How it works internally

What ships with FhSim

The FhSim core codebase consists of several components and tools which support different ways of use. These components and tools are specified in the main code base for FhSim and include the following:

• The FhSim executables can run simulations with and without visualisation. The corresponding executables are FhSim and FhVis; either can additionally pace the simulation to real time (see Real-time pacing).
• FMU tools makes it possible to export a FhSim model as a stand-alone FMU.
• Running FhSim from your own software covers the three routes for driving a simulation from code you write yourself: loading the shared library, exporting an FMU, or shelling out to the standalone executable.
• The FhSim API can be used for creating new simulation models and seamlessly integrate FhSim with your own software.
• Plugable model libraries, based on the SimObject interface.

Visualization is a compile-time choice

To fulfil the goals of being embeddable and fast, while still allowing visualization either as an aid during model development or for presenting results, the API is compiled in two configurations: one with visualization and one without. The structure without visualization is shown below.

Overview of the FhSim API if compiled without visualization

If the API is compiled with visualization capabilities, the only change is that additional methods are called. In practice, this is done by checking for the preprocessor definition FH_VISUALIZATION. If this is defined, the visualization methods are used, if not they are omitted. The next figure shows the additional components that are added if compiled with visualization, and which of the original components that are affected.

Overview of the FhSim API if compiled with visualization

This is why an installation gives you either FhSim or FhVis (or both) rather than a single executable with a switch — see Installation and setup.

How it works internally

You do not need this section to run simulations or to write scenario XML; it is background for readers who want to know what the figures above are showing. Referring to those figures, these are the key components of the FhSim API:

Component	Responsibility
FhSim	Wraps the system to integrate, the integrator, and the integrator settings. The system is specified through input files; results are returned either as a text file or as the answer to a function call.
ModelStructure	Represents a collection of SimObjects as one larger model for the integrator. It tracks the SimObjects, their ports and their states, applies the interconnections from the input file, and acts as the single model the integrator calls.
FhIntegrator	Keeps track of the states of the total model and advances them, obtaining state derivatives from ModelStructure. It also reads and writes initial conditions from/to file, and takes its parameters from the input file parser.
SimObject	The base class all submodels derive from. It carries the functionality common to every SimObject, while each submodel adds its own interface (input ports, output ports, parameters), its state variables, its state derivatives and its output-port values. A SimObject needs to know nothing about other SimObjects — all its inputs are supplied by ModelStructure.
Parse	Reads the XML input file (via libxml2, behind a thin C++ wrapper) and writes its content into the structures that need it.
PrintDuringExec	Writes log messages to screen and to the log file, at separate log levels for each.
Observers	Simulation results are written by observers, not by the logger: FileOutputObserver writes the CSV, and other observers stream, render or plug in custom handling. They are declared in the <OBSERVERS> section of the input file.

For the file formats these components consume and produce, see The FhSim input file and OBSERVERS section.