FhSim - time domain simulation  2.0.1
FhSim API overview

Documentation overview

Information about specific topics:

Introduction

FhSim is a software tool and an API for describing and simulating real world systems. The systems are formulated as ordinary differential equations, and FhSim uses for time-domain integration for the simulation. The integration can be performed by several integration routines. FhSim offers 3D visualization based on the open source rendering engine Ogre3D. An user will typically build a system from several predefined SimObjects, which are submodels typically modelling a physical system or some characteristics of such a system. The term SimObject is a simplification of "Simulation Object". These SimObjects can be used to compose different systems. Each SimObject is defined through both internal models and external properties, such as input ports, output ports and parameters. Each SimObject also contains its own visualization, making this visualization valid regardless of the rest of the system.

The composition of the system to simulate, as well as controlling how the simulation is to be performed, is defined through XML input files or specialized applications.

FhSim is built especially to satisfy the following conditions:

  • Fast simulations.
  • Possibility to embed in other applications.
  • The ability to debug development using visualization of the system.
  • Relatively few and complex SimObjects
  • The need for SimObjects to query other SimObjects, as well as having access to shared resources (useful e.g. for shared environments).
  • Separate development and usage of submodels. This means that users only needs to know the interface of the SimObjects, and also that SimObjects based on confidential code can be used by others without disclosing the code.
  • Accumulation of project results and knowledge through SimObject libraries.

Implementation

The FhSim API is written in C++. It is possible to write SimObjects in other languages, as long as it is possible to compile these into shared libraries or call them from the C language. The model development is, however, in practice usually done in C++, as existing methods make this the simplest choice.

The open source rendering engine Ogre3D is used for the visualization. Ogre3D is built into FhSim, and should not be installed by users of the FhSim libraries. More information about Ogre3D can be found at http://www.ogre3d.org. For the basic usage of FhSim only a basic understanding of Ogre3D is needed.

To fulfill the goals of being embeddable and fast, while giving the opportunity to use visualization either as a mean for simpler model development or for presentation of results, the API is compiled in two versions. One with, and one without visualization. The structure without visualization is shown in the figure below.

dot_FhSimOverview.png
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.

dot_FhVisOverview.png
Overview of the FhSim API if compiled with visualization

Components

Referring to the two figures above, the following are the key components of the FhSim API:

CFhSim
CFhSim wraps a system to integrate, the integrator, and the integrator settings. The system is specified through input files. The results are returned either as a text file or as the answer to a function call.
CModelStructure
CModelStructure is responsible for representing a collection of SimObjects as one larger model for the CFhIntegrator. It maintains an overview of the SimObjects, their ports and their states, and applies the interconnections as defined in the construct input file. It acts as a single model which the integrator calls, and it implements all the necessary methods for the class CModel.
CFhIntegrator
The integrator is responsible for keeping track of the states of the total model, and to advance these states by getting the calculations of the derivatives from the CModelStructure. It also handles aspects such as reading and writing initial conditions from/to file and gets its parameters from the input file parser, CParse.
CSimObject
In the source code, submodels translates to classes derived from the CSimObject class. This class contains all functionality common to all SimObjects, while functionality specific for each submodel is implemented in classes inheriting this CSimObject. Typically this includes defining its interface, in terms of input ports, output ports and parameters, as well as its state variables. A SimObject should also provide methods for calculating the derivatives of its states and for setting its output ports. Each SimObject needs to know nothing about other SimObjects, as all input are provided for by CModelStructure.
File I/O
FhSim handles different file types in different ways. The main input file is in XML format, and is read by CParse, which uses the library TinyXML for this purpose. CParse contains functions to read the input file and write its content to the appropriate structures. These structures are then provided where they are needed. While FhSim is running, the writing of log messages to screen and file is performed by CPrintDuringExec. This is done according to separate loglevels for screen and logfile. CPrintDuringExec is also able to write the results of the simulation to file. This method writes states and/or output from the specified SimObjects at the specified times to the specified file. The points in time for which this is to be done is found based on the settings in the main input file, specifically by the property TOutput.

The most important classes of fhSim are briefly explained in fhsimclasses

Implementation overview

Complex systems are modeled as a set of objects with input ports, output ports and parameters. These objects are referred to as SimObjects, short for simulation objects. Each SimObject implements its own differential equations. Several SimObjects are connected through their input and output ports. The connections between the different SimObjects are defined through input files and/or xml strings.

The FhSim API is written in C++. The SimObjects are usually also written in C++ and compiled into a shared library (dll on windows). It is possible to write SimObjects in other languages, as long as it is possible to compile these into shared libraries or call them from the C language. The model development is, however, in practice usually done in C++, as existing methods make this the simplest choice.

To fulfill the goals of being embeddable and fast, while giving the opportunity to use visualization either as a mean for simpler model development or for presentation of results, the API is compiled in two versions. One with, and one without visualization.