Home

Andreas Nicolai

Welcome to the MasterSim Wiki

Webpage: http://mastersim.sourceforge.net/

Project Members:

Detailed Wiki pages

Content

Conceptual Stuff

Design Criteria/Key Features

  • cross-platform: Windows, MacOS, Linux
  • no dependency on externally installed library, all source included in release, especially no dependency on FMI support libraries (exception: standard C++, Qt), so checking out source code and building it should be easy (also packaging for different platforms)
  • complete functionality wrapped in library MasterSim usable by command line tools and GUI applications
  • message handling wrapped to support GUI integration, log file support, no direct printf() or std::cout statements
  • supports FMU debugging: can disable unzipping (persistant dll files), source access allows debugging runtime loading of shared libraries and attaching debuggers
  • high-level C++ code (readible, and better maintainable)
  • includes instrumentation to retrieve counters and timers for benchmarking performance of master algorithms and FMUs
  • code tailored for Master algorithm debugging - all variables in type-specific arrays for easy analysis in debugger

Supported FMU types

  • FMI for CoSimulation version 1
  • FMI for CoSimulation version 2

No asynchronous FMU types supported.

  • on Linux and Mac, MasterSim is typically only built as 64-bit application
  • on Windows, MasterSim can be built as 32-bit application for 32-bit FMUs, and 64-Bit application for 64-Bit FMUs,
  • mixed FMU platform types (32-Bit and 64-Bit) are not supported

Terminology

The following terms are used in the description and naming of classes/variables:

  • FMU - describes the fmu archive including model description and shared libraries
  • slave - describes a simulation model that is instantiated/created from an FMU, there can be several slaves instantiated by a single FMU, unless the capability canBeInstantiatedOnlyOncePerProcess is set to true.
  • master - describes the overall simulation control framework that does all the administrative work
  • master-algorithm - describes the implementation of a mathematical algorithms that advances the coupled simulation in time; may include an iteration scheme
  • error-control - means local truncation error check, used for time step adjustment scheme
  • master time - time of master simulation, starts with 0, unit is not defined (needs to be common agreement between FMUs, typically in seconds)
  • current master time - The time that the master state is at, changes only at end of successful doStep() or restoreState() calls.

Directory Structure of Working Directory

By default, the following directory structure is used. Suppose there is a project file describing the simulation scenario with provided fmus.

 sim_projects/pro1/project.msim
 sim_projects/pro1/fmus/part1.fmu
 sim_projects/pro1/fmus/part2.fmu

when running the master simulator a working directory will be created. By default the file path to this working directory is the project file name without extension.

 sim_projects/pro1/project/             - working directory
 sim_projects/pro1/project/log/         - log and statistic files
 sim_projects/pro1/project/fmus/        - unzipped fmu subdirectories
 sim_projects/pro1/project/fmus/part1   - unzipped part1.fmu
 sim_projects/pro1/project/fmus/part2   - unzipped part2.fmu
 sim_projects/pro1/project/slaves/      - output/working directory for fmu slaves
 sim_projects/pro1/project/results/     - base directory for simulation results

The output directory for slaves is only created by slaves who support a parameter that allows specification of such output directory.

FMU Import

While two library exist for importing FMUs (FMILibrary and FMI++), neither works sufficiently well in this context. FMILibrary has build and linker issues on Linux/MacOS, FMI++ does not support importing FMUs for CoSimulation v.2.

Since the master only needs importing functionality, the most straight-forward way of handling this is creating the importing functionality manually with focus on these tasks:

  • unzipping FMUs (done with the miniunzip library function)
  • reading ModelDescription.xml
  • loading dynamic libraries and importing function pointers (platform specific, for Windows and Mac/Linux)
  • wrapping calls to FMUs so that the master algorithms can work with more convenience interface in addition to the native fmi interface functions

For interfacing with the shared library/DLL of an FMU the function pointers and callback functions are needed. The callback functions are typically independent of the individual FMU or slave and are defined just once for FMI1 and FMI2 within the model manager.

The function pointers are specific to each loaded dynamic library (FMU), as is the ModelDescription. So an FMU is defined in code by these properties:

  • path to the FMU and unzip directory
  • function pointers
  • model description context

This is all stored in the class FMU.

FMU Unzipping / Debugging Features

Default behavior for the master simulator would be to unzip all referenced FMU files. However, for debugging purposes it may be meaningful to skip the unzipping part and tell the master to use already unzipped FMUs. In this case, the master shall try to read the modelDescription.xml file in the location where it would reside after unzipping.

This functionality is triggered by the command line argument skip-unzip see command line arguments. This is particularly useful if you want to try out different options in the modelDescription.xml file without extracting/compressing the FMU archive always.

FMU unzip path

By default, FMUs will be unzipped in a path relative to the working directory with the path name uniquely generated from FMU file name and in case of ambiguity an additional counter. Basically, for each FMU to unzip, a path is generated. If another FMU with same filename (but maybe different relative/absolute path) has been extracted before, the FMU path get's formed with mask

<working-dir>/fmus/<filename-without-fmu-extension>_<counter>

where the counter is increased until a unique file path has been found.

The user may want to override this by specifying an unzip directory for one ore more FMUs. This should best be done in the master project file as optional meta-data. Error checking has to be done to prevent a user from overriding a path of other FMUs.

FMU Slave Working Directories

Each instance of an FMU is called a simulation slave. From a single FMU-archive several instances can be created. Therefore, the working directory for a simulation slave is different than the extraction/unzip directory of an FMU file.

Within the master, the file path to each slave's working directory is generated from the unique simulation slave name, defined in the master file.

Since slave names must be unique, the corresponding file paths will be unique as well.

<working-dir>/slaves/<slave-name>

The names of the slaves must follow the rules that apply for generating file names. The generated directory name is passed to each slave via parameter, which requires the FMU to support such an output file path parameter.

Outputs and Logging

Time unit handling

Master time (and time send to FMUs) is not fixed to any scientific unit. Therefore, any output by the master referring to time points will just use this anonymous time stamp. However, for practical reasons, it is difficult to interpret an error occurring at time t=1284382.21.

Inside the master code, all time output is formatted in a time-distance-format function that can be configured to use anonymous time stamps or interpret master time as time offset in seconds. Further, it can be used to configure a reference time that gets added to the master time (offset) in order to get meaningful local time stamps.

The unit used by the master (and agreed on by all slaves used in the same scenario) can be specified by a project file parameter. Then, prior to outputs the master time is being converted from this given unit to seconds before any output happens.

Log file support

Log file name is 'screenlog.txt'. The log file is located within the working directory (see directory structure above).

Output Files

Output files are written based on type. Files are only generated when outputs of this type are generated.

  • boolean.d6o
  • integer.d6o
  • strings.csv

Real value outputs are sorted according to units of exchange variables. File names are composed with following naming convention:

  • real_<unit>.d6o

d6o are DataIO containers. See http://nbn-resolving.de/urn:nbn:de:bsz:14-qucosa-70337 for details on this format.

string.csv is a plain csv file with the string outputs.

Output Handling

The output function is called by the master whenever a step was completed successfully. The decision, whether outputs shall be written or not depends on two alternative strategies:

  • a schedules output time interval has passed
  • the differences between computed values and interpolated values differ too much so that the last interval is written.

The second algorithm can be done individually for each output quantity, resulting in output files with different time points (but best accuracy). The idea is that when analyzing output data, typically plots are generated with polygons through data points which implies linear interpolation on all points between output data samples. However, when three data samples are aligned such, that the middle one lies close enough to the interpolated value, this output can be skipped.

Algorithm looks like that:

  • keep current and last data samples to write (tp_1, v_1), (tp_2, v_2)
  • obtain new output (tp_3, v_3)
  • compute interpolated value at tp_2 using v_1 and v_3 --> v_2intp
  • compare old with new interpolated value:

    abs((v_2- v_2intp)/(max(v_2, v_2intp)+eps)) > threshold

  • If threshold is exceeded, store tp_2,v_2 into file, move values 2 -> 1.

  • move sample 3 -> sample 2

Simulation Statistics

Solver statistics
------------------------------------------------------------------------------
Wall clock time                            =   16.878 ms
------------------------------------------------------------------------------
Output writing                             =    4.825 ms
Master-Algorithm                           =    5.876 ms          10
Convergence failures                       =                       0
Error test time and failure count          =    0.882 ms           0
------------------------------------------------------------------------------
Part1                               doStep =    0.999 ms          66
                                  getState =    0.111 ms          30
                                  setState =    0.157 ms          46
Part2                               doStep =    0.961 ms          66
                                  getState =    0.095 ms          30
                                  setState =    0.144 ms          46
------------------------------------------------------------------------------

Explanation:
Wall clock time lists the total simulation time spend after initialization (unzipping and loading of shared libraries is excluded).

Output writing and Master-Algorithm are the major two components of the master algorithm, so they should sum up close to the total wall clock time.

Error test time and failure count shows the time spend in error testing routine (Richardson-Variant) and the counter for error test failures.

The third column contains counters. The counter for Master-Algorithm is the number of times the master algorithm takes a step, so it's the total step count. Re-tries and iterations within the master algorithm are not counted here.

The last section of the statistics lists timings and counters for individual FMU slaves and the most relevant functions.

Data Types

In simulations with mixed FMUs (v1 and v2) data types should match. Also, the default type-headers are the same for both versions.

Intendet platform for this master is Desktop systems (32bit/64bit), therefore all data types seen by the master algorithms are mapped to:

  • fmi2Boolean (bool in scalar interface functions)
  • int
  • double
  • std::string

External Libraries

The MasterSim library and the simulator projects depend on the following external/third-party libraries:

MasterSimulator and MasterSimulatorUI

  • IBK library (from IBK, TU Dresden, Germany)
  • DataIO library (from IBK, TU Dresden, Germany)
  • TiCPP library (adapted version provided by IBK, TU Dresden, Germany)
  • minizip and zlib for unzipping FMUs

only MasterSimulatorUI

  • Qt 4/5 Qt Webpage, Qt 4 is used for compatibility to older MacOSX versions and older Linux versions. However, the code may be compiled also with Qt 5.

The release-versions of the libraries (with the exception of Qt) are located in the sub-directory 'third-party'.

Connection Graph and Variable Mapping

Variables can be uniquely identified by

 <slave-name>.<variable-name>

and a graph may be defined by:

 A.x1         B.u1
 A.d1         C.du1
 B.x1         C.u1
 B.x2         A.u2
 C.x1         A.u1

First colum are output variables, second column are connected input variables. x are of type real, d of type integer.

Each slave holds for each data type a vector of output values (bool, int, real/double, string).
The master also holds for each data type a vector of connection variables.

A mapping of variables from local slave storage to global vector and from global vector to input is done with a mapping table for each data type individually:

Output mapping - Type Real

Slave VariableName global index local index
A x1 0 0
B x1 1 0
B x2 2 1
C x1 3 0

The transfer from local to global data storage is then a simple algorithm:

loop connectedVariableIndexes:
    copy(localArray[localIndex], globalArray[globalIndex])

In case of slave B the array connectedVariableIndexes will be {0, 1}.

Input mapping - Type Real

For input variables a similar mapping exists. Each slave does not have an input variable cache, instead
variables are set individually (see also Newton algorithm and Jacobian generation via DQ algorithm).

Slave VariableName global index local value reference
B u1 0 55
C u1 1 348432
A u2 2 122
A u1 3 321

Input and output mappings are combined into a single table RealVariableMappings.

Note: An output of a slave may be directly connected to any of its own input variables, for example:

fmu1.var2   fmu1.var15

Custom Features

ResultsRootDir parameter

Whenever an FMU has a string parameter with name ResultsRootDir defined, the parameter is set automatically to the file location described above, unless user has specified the parameter manually.

Simulation time reference time/date

Whenever and FMU has a string parameter with name ReferenceTimeStamp defined, the master sets the reference time/date automatically and consistently among FMUs.

TODO: Determine and fix format for time stamp

Scientific Publications

Schierz T., Arnold M., and Clauß C.; Co-simulation with communication step size control in an fmi-compatible master algorithm, In 9th International Modelica Conveference 2012, Modelica Association, 2012

This publication discusses the local error estimation technique and time step adjustment algorithm implemented in MasterSim.


The wiki uses Markdown syntax.


Related

Wiki: BuildingAndDevelopment
Wiki: CommandLineArguments
Wiki: License
Wiki: MasterSimProjectFileFormat
Wiki: MathAlgorithms
Wiki: TestSuite

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks