MasterSim User Guide

There is one specific feature of MasterSim that is helpful for using FMUs that write their own output data. To provide a writable, slave-specific output directory to each slave, MasterSim sets the parameter ResultsRootDir (typically with value reference 42) in each slave to this directory. As long as a slave defines such a parameter, the FMU code can rely on getting a valid directory to write its data into. See also section Directory slaves.

This is a straight-forward procedure:

Extremely simple case and, if supported by FMUs, definitely best-practice. In MasterSim only the value assigned to a published parameter needs to be changed (can be done also directly in the project file, e.g. with scripts) and the simulation can be repeated.

This is the most typical case. Here, the input and output variable names and types remain unchanged and also the published parameters remain the same. Yet, the internal behavior of the model changes due to adjustment of internal model behavior, after which the FMU is exported again. Since MasterSim only references FMUs, in such cases the FMU files can simply be replaced and without any further changes the simulator can be started.

In this situation, when a parameter has been configured in MasterSim that no longer exists (or has been renamed), the respective definition must be changed in the project file or be removed in the user interface.

When an imported FMU changes part of its interface (e.g. input or output variables are modified), then this will be shown in the user interface by highlighting invalid connections. If only variable names were changed, you are best of by editing the project file and renaming the variable name there. Otherwise, simply remove the connection and reconnect.

When the variable type changes of an input/output variable, so that an invalid connection is created (or the causality changes), then the user interface may not directly show the invalid connection. However, during initialization, the MasterSimulator command line program will flag that error and abort.

The first task of the simulator is to get all slaves to have consistent initial values. This is already a non-trivial task and not guaranteed to succeed in all cases. The only procedure that can be employed for FMI 1 and FMI 2 slaves is to iteratively get and set output and input variables in all slaves in an iterative manner, until no changes are observed.

The algorithm in MasterSim is:

Note, the initial calculation algorithm is actually a Gauss-Jacobi algorithm, and as such not overly stable or efficient.

MasterSim treats simulation time in seconds.

The simulation time is entered in seconds (or any other supported unit that can be converted to seconds) in the user interface and project file. During the simulation, all time entries (start and end time, and time step sizes and size limits) are first converted to seconds and then used afterwards without any further unit conversion.

For example, if you specify an end time point of 1 h, the master will run until simulation time 3600, which will then be sent as communication interval end time in the last doStep() call.

The overall simulation time interval is passed to the slaves in the setupExperiment() call. If you specify a start time different from 0, the master simulator will start its first communication interval at this time (the slave needs to process the setupExperiment() call correctly and initialize the slave to the start time point).

The end time of the simulation is also passed to the FMU via the setupExperiment() call (the argument stopTimeDefined is always set to fmiTrue by MasterSim).

If the algorithm did not converge within the given iteration limit, the communication step size is reduced by factor 5:

The factor 5 is selected such, that the time step size can be quickly reduced. For example, when a discontinuity is encountered (e.g. triggered through step-wise change of discrete signals) the simulator must reduce the time step very quickly to a small value, to step over the step change.

The step size is then compared with the lower communication step limit (parameter hMin). This is necessary to prevent the simulation to get stuck with extremely low time steps. If the step size would be reduced below the hMin value, the simulation will be aborted with an error message.

In some cases, the interaction between two slaves may prevent any master algorithm to converge (even the Newton algorithm). Still, in these cases the remaining error may be insignificant and the simulation can pass with tiny steps over the problematic time and increase steps afterwards. For such cases, you can specifiy the parameter hFallBackLimit, which must be larger than hMin. If h is reduced to a value below this acceptable communication step size, the master algorithms will return succesfully after all iterations have been done. Thus, the step is treated as converged and the simulation progresses to the next interval.

The publication mentioned above illustrates the behavior of the simulation using these parameters.

If an error test method (ErrorControlMode) is set, a converged step is followed by a local error check. Currently, this error check is based on the step-doubling technique and as such can only be applied if the slaves support FMI 2.0 setting/getting of state functionality.

Basically, the check is done as follows:

The mathematical formulas and calculation details of the error check are documented in publication:

Nicolai, A.: Co-Simulation-Test Case: Predator-Prey (Lotka-Volterra) System (see MasterSim Documentation Webpage).

The error check uses the parameters relTol and absTol to determine an acceptable difference between the full and half-step (or their slopes). Depending on the local error estimate, two options exist:

Basic algorithm:

Gauss-Jacobi is always done without iteration. As shown in the publication (see above), it really doesn’t make sense to use iteration.

Basic algorithm:

Basic algorithm:

Cycles are handled just the same as with Gauss-Seidel.

When opening an example from the welcome page / example page, you are prompted to save the project first in a custom location (examples are distributed in the installation directory, which is usually read-only).

Here’s a list of useful program-wide shortcuts:

In the lower left part of the view you may edit project comments (if nothing is selected in the network view), slave properties (if a slave is selected, see also Slave properties/parameter values), or connection properties (if a connection is selected).

New slaves are added by selecting fmu or csv or tsv files. MasterSim automatically uses the basename of the selected file as ID name for the slave. If already such an ID name exists, MasterSim appends a number to the basename. In any case, slave ID names must be unique within the project.

Below the table with imported slaves is a list of parameters published by the FMU. The list is specific to the currently selected slave. A simulator slave can be selected in the slave table or by clicking on a block in the network view.

Parameters can be edited by double-clicking on the value cell and entering a value. Clearing the content of the cell will reset the parameter to its default value.

The network view (9) shows a simple schematic of all FMU slaves and their connections. This network view is optional and not really needed for the simulation. Still, a visual representation of the simulation scenario is important for communication.

The network shows blocks (matching the simulators/slaves) and on each of the blocks one or more sockets. Sockets indicate input/output variables of each simulation slave. Blocks are shown in different colors, indicating the individual block states.

The block editor allows you to define the basic, rectangular shape of your FMU and to layout your sockets. The block editor is opened either directly after an FMU has been imported, or when double-clicking on a block in the network view.

This feature is very helpful if FMUs are coupled, where output and input variables of two slaves have the same name. This is particularly helpful, if you have to connect many input and output variables between two slaves. If you create one FMU such, that variable names match the other side, you can use the following procedure:

A connection is created, when:

If you want to do unit conversion or other transformations (sign inversion, scaling) between output variables and input variables, you can double-click on the third column in table (6), to open a dialog for editing transformation factors and offsets. See section Connection graph for a detailed description.

If no working directory is given, the directory path is generated from the project file path with extension removed. For example:

In the section Structure and content of the working directory the content of the working directory is explained.

MasterSimulator writes progress information/warning and error messages to the console window, and to the file <working-dir>/logs/screenlog.txt. The amount of text to be written and the detail level is controlled through the --verbosity-level parameter, which determines the amount of debug information generated by the master.

Verbosity level of 0 disables pretty much all output, verbosity level 1 is the default with normal progress message output. Use higher verbosity levels for debugging purposes or to narrow down the source of an error.

By default, the console window (on Windows) stays open at the end of the simulation unless the -x command line flag is passed.

This directory contains three files:

The format of the progress.txt is fairly simple:

The file has three columns, separated by a Tab character. The file is written and updated during the simulation run and can be used by other tools to pick up the overall progress and generate progress diagrams (speed/percentage etc.)

The meaning of the different values in the summary.txt are explained in section.

Inside this directory, the imported FMUs are extracted, each in a subdirectory with basename of the FMU (part1.fmu → part1).

When a MasterSim project references several FMUs with same base name, which are for example in different subdirectories, then it will adjust the extraction path name. Example:

Basically, each fmu file is only extracted once.

Often, non-trivial simulation slaves write their own output files, instead of pushing all output data via FMI output variables to the master. In cases, where PDEs are solved and many thousands of variables are generated, this may actually not be possible.

Since a slave FMU may be instantiated several times, hard-coding output paths inside the FMU is generally a bad idea (though still current practice). Also, writing outputs into the current working directory is not too smart either, since the working directory would have to be changed by the master between calls to FMUs, and this is best avoided.

Unfortunately, the FMU standard does not provide an option, to officially set such a result directory. MasterSim handles this by setting the slave-specific directory path in a string parameter named ResultsRootDir, if the FMU declares such a parameter. If there is no value set in the project file for this parameter, then MasterSim will set the path generated for the slave in the working directory. The FMU can rely on the path being created by MasterSim and being writable. Of course, as with any parameter, you can set manually a value for this parameter.

MasterSim creates two result files within the results subdirectory.

and depending on whether synonymous variables are defined in the ModelDescription (see below), the file synonymous_variables.txt.

String output files are only generated when outputs of this type are generated. CSV files use tab chars as separators. First column is always the time point, the column header indicates the time unit.

Example values.csv file:

The file format corresponds to that of the csv-files used as FileReader-slaves, see section CSV FileReader Slaves, with:

The FMI variable names are prefixed with the corresponding slave name. The units are given in brackets and for unitless integer and boolean data types, the unit [-] is used.

MasterSim contains internal profiling functions that monitor the evaluation times of various parts of the software. Also, execution counts for different critical functions are shown.

The statistics is printed on the console window (for verbosity level > 0) and in the log file screenlog.txt in the following format:

Also, the same statistics information is printed into the summary.txt log file, in a more machine-friendly format (with timings always in seconds):

The remaining lines show timings and counters for each slave individually. This lines show the time taken in the function calls to doStep(), getState() and setState() for this slave and the respective call count. The state-related functions are only used by iterative master algorithms, when the FMUs support FMI 2.0 features. Mind, these functions are called both by the master algoritm and by the error test (if enabled).

Output writing and Master-Algorithm are the major two components of the MasterSimulator program, so there times should sum up close to the total wall clock time.

The third column in the screenlog-statistics contains counters. The counter for Master-Algorithm is the number of times the master algorithm takes a step, so that’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.

The following settings are mostly needed for use with cross-check procedure.

Depending on the selected options, certain capabilities must be supported by the FMUs, see section Master Algorithms.

Instead of an FMU, you can also reference a data file (extension tsv or csv). In this case, MasterSim will instantiate FileReader slaves and the data in the file is treated like an FMU that provides only output, but has no input and no parameters.

MasterSim actually supports two flavours of csv files. In both variants, numbers are always written in english number notation. The file parser first attempts to use the tab-separated value flavour by splitting the first two lines at the tab characters. If this yields more than two columns and the same nummber of columns in both lines (the header and first data line), a tab-separated csv/tsv flavour is assumed. Otherwise, the Excel-type quoted-csv flavour is assumed.

The time points can be spaced at arbitrary intervals. MasterSim currently expects simulations to run in seconds as base time unit. That means, internally, variables are exchanged matching a simulation time in seconds. When an input file defines a different unit for time, MasterSim converts these times into seconds.

The following time units are recognized by MasterSim:

Variables without given units, i.e. the […​] is missing in the column captions, are assigned an unknown/undefined unit -.

During simulation, when the FileReader slave is asked to provide a value for a variable, the following rules apply.

You can set parameters of FMUs (or more specifically of the individual FMU slaves/instances) by using the parameter keyword.

Definition syntax:

For boolean parameters you have to specify true (case-sensitive!) for true, or any other value (for example false) for false.

For integer values you specify simply the value as number.

Values for Real parameters are expected in the unit defined for the respective parameter in the modelDescription.xml file. Unit conversion is not supported here.

For string parameters, everything after the variable name is taken as string (until end of line). Example:

Whitespaces can be included, but backspaces need to be encoded as \\. Line breaks have to be encoded with \n, as in the following example:

Will set the string:

platform is (currently) one of: linux64, win32,win64 and darwin64

Each test suite has a set of subdirectories:

Within a test suite different similar test cases with modified parameters or adjusted solver settings can be stored. Test cases are grouped in test suites mostly when they use the same FMUs or other input files.

For each test case a MasterSim project file exists with the extension msim. The script that runs the test cases processes all msim files found in the subdirectory structure below the current platform.

For a test case to pass the check, a set of reference results must be present, stored in a subdirectory with name

For example:

These directories are basically renamed working directories after a simulation run, where everything except summary.txt and values.csv has been removed.

The tests are run automatically after building with the build scripts. Otherwise run the appropriate script:

From within a test directory, call the script update_reference_results.py with the directory suffix as argument.

For example, from within:

call:

which will update all reference results in this directory. If you want to process/update the reference results of several test suites, execute the following script from one directory up, for example from data/tests/linux64:

A convenient way to get simple, very specific test FMUs is the use of the FMI Code Generator tool. Its a python tool with graphical interface where FMU variables and properties can be defined. With that information, the code generator creates a source code directory with template code and related build scripts - such that it is very easy to handcraft own FMUs. See documentation/tutorial on the github page.

Requires a suitable license. Exporting FMUs from SimX is very easy, but limited to the Windows platform.

OpenModelica can export FMUs as well. Here are the steps to generate such an FMU.

The MasterSim library and the simulator projects depend on the following external/third-party libraries (except for Qt, all are included in the source code repository, so it is not necessary to install these libraries separately):

MasterSimulator and MasterSimulatorUI

only MasterSimulatorUI

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

Development with Qt Creator is encouraged and project files are provided. Individual project files are in subdirectories

Executables are placed in

To get all fmi2 functions

MasterSimulator can be built in Qt Creator in debug mode. By default the qmake projects will create shared libraries for all dependent libraries like IBK, BlockMod, TiCPP etc.

Slaves can also be built to link against their dependency as shared libraries. This happens, for example, when typical IBK-based projects are also built in debug mode.

Now, since MasterSim and FMU slaves are developed seperately, it is likely that the version of common libraries like IBK, BlockMod, IBKMK etc. differ. This then becomes a problem!

When developing MasterSim it is best to compile all FMUs to link statically against their dependencies:

Assuming you develop the shared FMU library with Qt Creator, you can follow this procedure:

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:

Variables can be uniquely identified by

and a graph may be defined by:

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

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

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).

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: