OMSimulator — OpenModelica User's Guide v1.28.0-dev-282-gb926db7519 documentation

# OMSimulator

Version: v3.0.0.post154-g1c85258

## Introduction

The OMSimulator project is a FMI-based co-simulation tool. It supports large-scale simulation and virtual prototyping using models from multiple sources utilizing the FMI standard. It is integrated into OpenModelica but also available stand-alone, i.e., without dependencies to Modelica specific models or technology. OMSimulator provides an industrial-strength open-source FMI-based modelling and simulation tool. Input/output ports of FMUs can be connected, ports can be grouped to buses, FMUs can be parameterized and composed, and composite models can be exported according to the SSP (System Structure and Parameterization) standard. Efficient FMI based simulation is provided for both model exchange and co-simulation. An external API is available for use from other tools and scripting languages such as Python and Lua.

## OMSimulator

OMSimulator is a command line wrapper for the OMSimulatorLib library.

### OMSimulator Flags

A brief description of all command line flags will be displayed using `OMSimulator --help`:

    info:    Usage: OMSimulator [Options] [Lua script] [FMU] [SSP file]
             Options:
               --addParametersToCSV=<bool>      false              Export parameters to a .csv file
               --algLoopSolver=<arg>            "kinsol"           Specifies the loop solver method (fixedpoint, kinsol) used for algebraic loops spanning multiple components.
               --clearAllOptions                                   Reset all flags to their default values
               --CVODEMaxErrTestFails=<int>     100                Maximum number of error test failures for CVODE
               --CVODEMaxNLSFailures=<int>      100                Maximum number of nonlinear convergence failures for CVODE
               --CVODEMaxNLSIterations=<int>    5                  Maximum number of nonlinear solver iterations for CVODE
               --CVODEMaxSteps=<int>            1000               Maximum number of steps for CVODE
               --deleteTempFiles=<bool>         true               Delete temporary files as soon as they are no longer needed
               --directionalDerivatives=<bool>  true               Use directional derivatives to calculate the Jacobian for algebraic loops
               --dumpAlgLoops=<bool>            false              Dump information for algebraic loops
               --emitEvents=<bool>              true               Emit events during simulation
               --help [-h]                                         Display the help text
               --ignoreInitialUnknowns=<bool>   false              Ignore initial unknowns from the modelDescription.xml
               --initialStepSize=<double>       1e-6               Specify the initial step size
               --inputExtrapolation=<bool>      false              Enable input extrapolation using derivative information
               --intervals=<int> [-i]           500                Specify the number of communication points (arg > 1)
               --logFile=<arg> [-l]             ""                 Specify the log file (stdout is used if no log file is specified)
               --logLevel=<int>                 0                  Set the log level (0: default, 1: debug, 2: debug+trace)
               --master=<arg>                   "ma"               Specify the master algorithm (ma)
               --maxEventIteration=<int>        100                Specify the maximum number of iterations for handling a single event
               --maxLoopIteration=<int>         10                 Specify the maximum number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
               --minimumStepSize=<double>       1e-12              Specify the minimum step size
               --mode=<arg> [-m]                "me"               Force a certain FMI mode if the FMU provides both cs and me (cs, me)
               --numProcs=<int> [-n]            1                  Specify the maximum number of processors to use (0=auto, 1=default)
               --progressBar=<bool>             false              Show a progress bar for the simulation progress in the terminal
               --realTime=<bool>                false              Enable experimental feature for (soft) real-time co-simulation
               --resultFile=<arg> [-r]          "<default>"        Specify the name of the output result file
               --skipCSVHeader=<bool>           true               Skip exporting the CSV delimiter in the header
               --solver=<arg>                   "cvode"            Specify the integration method (euler, cvode)
               --solverStats=<bool>             false              Add solver stats to the result file, e.g., step size; not supported for all solvers
               --startTime=<double> [-s]        0                  Specify the start time
               --stepSize=<double>              1e-3               Specify the (maximum) step size
               --stopTime=<double> [-t]         1                  Specify the stop time
               --stripRoot=<bool>               false              Remove the root system prefix from all exported signals
               --suppressPath=<bool>            false              Suppress path information in info messages; especially useful for testing
               --tempDir=<arg>                  "."                Specify the temporary directory
               --timeout=<int>                  0                  Specify the maximum allowed time in seconds for running a simulation (0 disables)
               --tolerance=<double>             1e-4               Specify the relative tolerance
               --version [-v]                                      Display version information
               --wallTime=<bool>                false              Add wall time information to the result file
               --workingDir=<arg>               "."                Specify the working directory
               --zeroNominal=<bool>             false              Accept FMUs with invalid nominal values and replace the invalid nominal values with 1.0

To use flag `logLevel` with option debug (`--logLevel=1`) or debug+trace (`--logLevel=2`) one needs to build OMSimulator with debug configuration enabled. Refer to the OMSimulator README on GitHub for further instructions.

### Examples

    OMSimulator --timeout 180 example.lua

## OMSimulatorLib

This library is the core of OMSimulator and provides a C interface that can easily be utilized to handle co-simulation scenarios.

## C-API

### RunFile

Simulates a single FMU or SSP model.

    oms_status_enu_t oms_RunFile(const char* filename);

### activateVariant

This API provides support to activate a multi-variant modelling from an ssp file [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ] from a ssp file. By default when importing a ssp file the default variant will be "SystemStructure.ssd". The users can be able to switch between other variants by using this API and make changes to that particular variant and simulate them.

    oms_status_enu_t oms_activateVariant(const char* crefA, const char* crefB);

> An example of activating the number of available variants in a ssp file

> oms_newModel("model") oms_addSystem("model.root", "system_wc") oms_addSubModel("model.root.A", "A.fmu") oms_duplicateVariant("model", "varA") // varA will be the current variant oms_duplicateVariant("varA", "varB") // varB will be the current variant oms_activateVariant("varB", "varA") // Reactivate the variant varB to varA oms_activateVariant("varA", "model") // Reactivate the variant varA to model

### addBus

Adds a bus to a given component.

    oms_status_enu_t oms_addBus(const char* cref);

### addConnection

Adds a new connection between connectors A and B. The connectors need to be specified as fully qualified component references, e.g., "model.system.component.signal".

    oms_status_enu_t oms_addConnection(const char* crefA, const char* crefB, bool suppressUnitConversion);

The two arguments crefA and crefB get swapped automatically if necessary. The third argument suppressUnitConversion is optional and the default value is false which allows automatic unit conversion between connections, if set to true then automatic unit conversion will be disabled.

### addConnector

Adds a connector to a given component.

    oms_status_enu_t oms_addConnector(const char* cref, oms_causality_enu_t causality, oms_signal_type_enu_t type);

### addConnectorToBus

Adds a connector to a bus.

    oms_status_enu_t oms_addConnectorToBus(const char* busCref, const char* connectorCref);

### addResources

Adds an external resources to an existing SSP. The external resources should be a ".ssv" or ".ssm" file

    oms_status_enu_t oms_addResources(const char* cref_, const char* path)

### addSignalsToResults

Add all variables that match the given regex to the result file.

    oms_status_enu_t oms_addSignalsToResults(const char* cref, const char* regex);

The second argument, i.e. regex, is considered as a regular expression (C++11). ".*" and "(.)*" can be used to hit all variables.

### addSubModel

Adds a component to a system.

    oms_status_enu_t oms_addSubModel(const char* cref, const char* fmuPath);

### addSystem

Adds a (sub-)system to a model or system.

    oms_status_enu_t oms_addSystem(const char* cref, oms_system_enu_t type);

### compareSimulationResults

This function compares a given signal of two result files within absolute and relative tolerances.

    int oms_compareSimulationResults(const char* filenameA, const char* filenameB, const char* var, double relTol, double absTol);

The following table describes the input values:

Input | Type | Description
--- | --- | ---
filenameA | String | Name of first result file to compare.
filenameB | String | Name of second result file to compare.
var | String | Name of signal to compare.
relTol | Number | Relative tolerance.
absTol | Number | Absolute tolerance.

The following table describes the return values:

Type | Description
--- | ---
Integer | 1 if the signal is considered as equal, 0 otherwise

### copySystem

Copies a system.

    oms_status_enu_t oms_copySystem(const char* source, const char* target);

### delete

Deletes a connector, component, system, or model object.

    oms_status_enu_t oms_delete(const char* cref);

### deleteConnection

Deletes the connection between connectors crefA and crefB.

    oms_status_enu_t oms_deleteConnection(const char* crefA, const char* crefB);

The two arguments crefA and crefB get swapped automatically if necessary.

### deleteConnectorFromBus

Deletes a connector from a given bus.

    oms_status_enu_t oms_deleteConnectorFromBus(const char* busCref, const char* connectorCref);

### deleteResources

Deletes the reference and resource file in a SSP. Deletion of ".ssv" and ".ssm" files are currently supported. The API can be used in two ways.

1. deleting only the reference file in ".ssd".

2. deleting both reference and resource files in ".ssp".

To delete only the reference file in ssd, the user should provide the full qualified cref of the ".ssv" file associated with a system or subsystem or component (e.g) "model.root:root1.ssv".

To delete both the reference and resource file in ssp, it is enough to provide only the model cref of the ".ssv" file (e.g) "model:root1.ssv".

When deleting only the references of a ".ssv" file, if a parameter mapping file ".ssm" is binded to a ".ssv" file then the ".ssm" file will also be deleted. It is not possible to delete the references of ".ssm" seperately as the ssm file is binded to a ssv file.

The filename of the reference or resource file is provided by the users using colon suffix at the end of cref. (e.g) ":root.ssv"

    oms_status_enu_t oms_deleteResources(const char* cref);

### doStep

Simulates a macro step of the given composite model. The step size will be determined by the master algorithm and is limited by the definied minimal and maximal step sizes.

    oms_status_enu_t oms_doStep(const char* cref);

### duplicateVariant

This API provides support to develop a multi-variant modelling in OMSimulator [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ]. When duplicating a variant, the new variant becomes the current variant and all the changes made by the users are applied to the new variants only, and all the ssv and ssm resources associated with the new variant will be given new name based on the variant name provided by the user. This allows the bundling of multiple variants of a system structure definition referencing a similar set of packaged resources as a single SSP. However there must still be one SSD file named SystemStructure.ssd at the root of the ZIP archive which will be considered as default variant.

    oms_status_enu_t oms_duplicateVariant(const char* crefA, const char* crefB);

An example of creating a multi-variant modelling is presented below

    oms_newModel("model")
    oms_addSystem("model.root", "system_wc")
    oms_addSubModel("model.root.A", "A.fmu")
    oms_setReal("model.root.A.param1", "10")
    oms_duplicateVariant("model", "varB")
    oms_addSubModel("varB.root.B" ,"B.fmu")
    oms_setReal("varB.root.A.param2", "20")
    oms_export("varB", "variant.ssp")

The variant.ssp file will have the following structure

    Variant.ssp
        SystemStructure.ssd
        varB.ssd
        resources\
            A.fmu
            B.fmu

### export

Exports a composite model to a SPP file.

    oms_status_enu_t oms_export(const char* cref, const char* filename);

### exportDependencyGraphs

Export the dependency graphs of a given model to dot files.

    oms_status_enu_t oms_exportDependencyGraphs(const char* cref, const char* initialization, const char* event, const char* simulation);

### exportSSMTemplate

Exports all signals that have start values of one or multiple FMUs to a SSM file that are read from modelDescription.xml with a mapping entry. The mapping entry specifies a single mapping between a parameter in the source and a parameter of the system or component being parameterized. The mapping entry contains two attributes namely source and target. The source attribute will be empty and needs to be manually mapped by the users associated with the parameter name defined in the SSV file, the target contains the name of parameter in the system or component to be parameterized. The function can be called for a top level model or a certain FMU component. If called for a top level model, start values of all FMUs are exported to the SSM file. If called for a component, start values of just this FMU are exported to the SSM file.

    oms_status_enu_t oms_exportSSMTemplate(const char* cref, const char* filename)

### exportSSVTemplate

Exports all signals that have start values of one or multiple FMUs to a SSV file that are read from modelDescription.xml. The function can be called for a top level model or a certain FMU component. If called for a top level model, start values of all FMUs are exported to the SSV file. If called for a component, start values of just this FMU are exported to the SSV file.

    oms_status_enu_t oms_exportSSVTemplate(const char* cref, const char* filename)

### exportSnapshot

Lists the SSD representation of a given model, system, or component.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    oms_status_enu_t oms_exportSnapshot(const char* cref, char** contents);

### freeMemory

Free the memory allocated by some other API. Pass the object for which memory is allocated.

    void oms_freeMemory(void* obj);

### getBoolean

Get boolean value of given signal.

    oms_status_enu_t oms_getBoolean(const char* cref, bool* value);

### getBus

Gets the bus object.

    oms_status_enu_t oms_getBus(const char* cref, oms_busconnector_t** busConnector);

### getComponentType

Gets the type of the given component.

    oms_status_enu_t oms_getComponentType(const char* cref, oms_component_enu_t* type);

### getConnections

Get list of all connections from a given component.

    oms_status_enu_t oms_getConnections(const char* cref, oms_connection_t*** connections);

### getConnector

Gets the connector object of the given connector cref.

    oms_status_enu_t oms_getConnector(const char* cref, oms_connector_t** connector);

### getDirectionalDerivative

This function computes the directional derivatives of an FMU.

    oms_status_enu_t oms_getDirectionalDerivative(const char* cref, double* value);

### getElement

Get element information of a given component reference.

    oms_status_enu_t oms_getElement(const char* cref, oms_element_t** element);

### getElements

Get list of all sub-components of a given component reference.

    oms_status_enu_t oms_getElements(const char* cref, oms_element_t*** elements);

### getFMUInfo

Returns FMU specific information.

    oms_status_enu_t oms_getFMUInfo(const char* cref, const oms_fmu_info_t** fmuInfo);

### getFixedStepSize

Gets the fixed step size. Can be used for the communication step size of co-simulation systems and also for the integrator step size in model exchange systems.

    oms_status_enu_t oms_getFixedStepSize(const char* cref, double* stepSize);

### getInteger

Get integer value of given signal.

    oms_status_enu_t oms_getInteger(const char* cref, int* value);

### getModelState

Gets the model state of the given model cref.

    oms_status_enu_t oms_getModelState(const char* cref, oms_modelState_enu_t* modelState);

### getReal

Get real value.

    oms_status_enu_t oms_getReal(const char* cref, double* value);

### getResultFile

Gets the result filename and buffer size of the given model cref.

    oms_status_enu_t oms_getResultFile(const char* cref, char** filename, int* bufferSize);

### getSolver

Gets the selected solver method of the given system.

    oms_status_enu_t oms_getSolver(const char* cref, oms_solver_enu_t* solver);

### getStartTime

Get the start time from the model.

    oms_status_enu_t oms_getStartTime(const char* cref, double* startTime);

### getStopTime

Get the stop time from the model.

    oms_status_enu_t oms_getStopTime(const char* cref, double* stopTime);

### getString

Get string value.

Memory is allocated for value. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    oms_status_enu_t oms_getString(const char* cref, char** value);

### getSubModelPath

Returns the path of a given component.

    oms_status_enu_t oms_getSubModelPath(const char* cref, char** path);

### getSystemType

Gets the type of the given system.

    oms_status_enu_t oms_getSystemType(const char* cref, oms_system_enu_t* type);

### getTime

Get the current simulation time from the model.

    oms_status_enu_t oms_getTime(const char* cref, double* time);

### getTolerance

Gets the tolerance of a given system or component.

    oms_status_enu_t oms_getTolerance(const char* cref, double* relativeTolerance);

### getVariableStepSize

Gets the step size parameters.

    oms_status_enu_t oms_getVariableStepSize(const char* cref, double* initialStepSize, double* minimumStepSize, double* maximumStepSize);

### getVersion

Returns the library's version string.

    const char* oms_getVersion();

### importFile

Imports a composite model from a SSP file.

    oms_status_enu_t oms_importFile(const char* filename, char** cref);

### importSnapshot

Loads a snapshot to restore a previous model state. The model must be in virgin model state, which means it must not be instantiated.

    oms_status_enu_t oms_importSnapshot(const char* cref, const char* snapshot, char** newCref);

### initialize

Initializes a composite model.

    oms_status_enu_t oms_initialize(const char* cref);

### instantiate

Instantiates a given composite model.

    oms_status_enu_t oms_instantiate(const char* cref);

### list

Lists the SSD representation of a given model, system, or component.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    oms_status_enu_t oms_list(const char* cref, char** contents);

### listUnconnectedConnectors

Lists all unconnected connectors of a given system.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    oms_status_enu_t oms_listUnconnectedConnectors(const char* cref, char** contents);

### listVariants

This API shows the number of variants available [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ] from a ssp file.

    oms_status_enu_t oms_listVariants(const char* cref);

An example for finding the number of available variants in a ssp file

    oms_newModel("model")
    oms_addSystem("model.root", "system_wc")
    oms_addSubModel("model.root.A", "A.fmu")
    oms_duplicateVariant("model", "varA")
    oms_duplicateVariant("varA", "varB")

    oms_listVariants("varB")

The API will list the available variants like below

    <oms:Variants>
      <oms:variant name="model" />
      <oms:variant name="varB" />
      <oms:variant name="varA" />
    </oms:Variants>

### loadSnapshot

Loads a snapshot to restore a previous model state. The model must be in virgin model state, which means it must not be instantiated.

    oms_status_enu_t oms_loadSnapshot(const char* cref, const char* snapshot, char** newCref);

### newModel

Creates a new and yet empty composite model.

    oms_status_enu_t oms_newModel(const char* cref);

### newResources

Adds a new empty resources to the SSP. The resource file is a ".ssv" file where the parameter values set by the users using "oms_setReal()", "oms_setInteger()" and "oms_setReal()" are writtern to the file. Currently only ".ssv" files can be created.

The filename of the resource file is provided by the users using colon suffix at the end of cref. (e.g) ":root.ssv"

    oms_status_enu_t oms_newResources(const char* cref)

### referenceResources

Switches the references of ".ssv" and ".ssm" in a SSP file. Referencing of ".ssv" and ".ssm" files are currently supported. The API can be used in two ways.

1. Referencing only the ".ssv" file.

2. Referencing both the ".ssv" along with the ".ssm" file.

This API should be used in combination with "oms_deleteResources".To switch with a new reference, the old reference must be deleted first using "oms_deleteResources" and then reference with new resources.

When deleting only the references of a ".ssv" file, if a parameter mapping file ".ssm" is binded to a ".ssv" file, then the reference of ".ssm" file will also be deleted. It is not possible to delete the references of ".ssm" seperately as the ssm file is binded to a ssv file. Hence it is not possible to switch the reference of ".ssm" file alone. So inorder to switch the reference of ".ssm" file, the users need to bind the reference of ".ssm" file along with the ".ssv".

The filename of the reference or resource file is provided by the users using colon suffix at the end of cref (e.g) ":root.ssv", and the ".ssm" file is optional and is provided by the user as the second argument to the API.

    oms_status_enu_t oms_referenceResources(const char* cref, const char* ssmFile);

### removeSignalsFromResults

Removes all variables that match the given regex to the result file.

    oms_status_enu_t oms_removeSignalsFromResults(const char* cref, const char* regex);

The second argument, i.e. regex, is considered as a regular expression (C++11). ".*" and "(.)*" can be used to hit all variables.

### rename

Renames a model, system, or component.

    oms_status_enu_t oms_rename(const char* cref, const char* newCref);

### replaceSubModel

Replaces an existing fmu component, with a new component provided by the user, When replacing the fmu checks are made in all ssp concepts like in ssd, ssv and ssm, so that connections and parameter settings are not lost. It is possible that the namings of inputs and parameters match, but the start values might have been changed, in such cases new start values will be applied in ssd, ssv and ssm. In case if the Types of inputs and outputs and parameters differed, then the variables are updated according to the new changes and the connections will be removed with warning messages to user. In case when replacing a fmu, if the fmu contains parameter mapping associated with the ssv file, then only the ssm file entries are updated and the start values in the ssv files will not be changed.

    oms_status_enu_t oms_replaceSubModel(const char* cref, const char* fmuPath);

> It is possible to import an partially developed fmu (i.e contains only modeldescription.xml without any binaries) in OMSimulator, and later can be replaced with a fully develped fmu. An example to use the API, oms_addSubModel("model.root.A", "../resources/replaceA.fmu") oms_export("model", "test.ssp") oms_import("test.ssp") oms_replaceSubModel("model.root.A", "../resources/replaceA_extended.fmu")

### reset

Reset the composite model after a simulation run.

The FMUs go into the same state as after instantiation.

    oms_status_enu_t oms_reset(const char* cref);

### setActivationRatio

Experimental feature for setting the activation ratio of FMUs for experimenting with multi-rate master algorithms.

    oms_status_enu_t experimental_setActivationRatio(const char* cref, int k);

### setBoolean

Sets the value of a given boolean signal.

    oms_status_enu_t oms_setBoolean(const char* cref, bool value);

### setBusGeometry

    oms_status_enu_t oms_setBusGeometry(const char* bus, const ssd_connector_geometry_t* geometry);

### setCommandLineOption

Sets special flags.

    oms_status_enu_t oms_setCommandLineOption(const char* cmd);

Available flags:

    info:    Usage: OMSimulator [Options] [Lua script] [FMU] [SSP file]
             Options:
               --addParametersToCSV=<bool>      false              Export parameters to a .csv file
               --algLoopSolver=<arg>            "kinsol"           Specifies the loop solver method (fixedpoint, kinsol) used for algebraic loops spanning multiple components.
               --clearAllOptions                                   Reset all flags to their default values
               --CVODEMaxErrTestFails=<int>     100                Maximum number of error test failures for CVODE
               --CVODEMaxNLSFailures=<int>      100                Maximum number of nonlinear convergence failures for CVODE
               --CVODEMaxNLSIterations=<int>    5                  Maximum number of nonlinear solver iterations for CVODE
               --CVODEMaxSteps=<int>            1000               Maximum number of steps for CVODE
               --deleteTempFiles=<bool>         true               Delete temporary files as soon as they are no longer needed
               --directionalDerivatives=<bool>  true               Use directional derivatives to calculate the Jacobian for algebraic loops
               --dumpAlgLoops=<bool>            false              Dump information for algebraic loops
               --emitEvents=<bool>              true               Emit events during simulation
               --help [-h]                                         Display the help text
               --ignoreInitialUnknowns=<bool>   false              Ignore initial unknowns from the modelDescription.xml
               --initialStepSize=<double>       1e-6               Specify the initial step size
               --inputExtrapolation=<bool>      false              Enable input extrapolation using derivative information
               --intervals=<int> [-i]           500                Specify the number of communication points (arg > 1)
               --logFile=<arg> [-l]             ""                 Specify the log file (stdout is used if no log file is specified)
               --logLevel=<int>                 0                  Set the log level (0: default, 1: debug, 2: debug+trace)
               --master=<arg>                   "ma"               Specify the master algorithm (ma)
               --maxEventIteration=<int>        100                Specify the maximum number of iterations for handling a single event
               --maxLoopIteration=<int>         10                 Specify the maximum number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
               --minimumStepSize=<double>       1e-12              Specify the minimum step size
               --mode=<arg> [-m]                "me"               Force a certain FMI mode if the FMU provides both cs and me (cs, me)
               --numProcs=<int> [-n]            1                  Specify the maximum number of processors to use (0=auto, 1=default)
               --progressBar=<bool>             false              Show a progress bar for the simulation progress in the terminal
               --realTime=<bool>                false              Enable experimental feature for (soft) real-time co-simulation
               --resultFile=<arg> [-r]          "<default>"        Specify the name of the output result file
               --skipCSVHeader=<bool>           true               Skip exporting the CSV delimiter in the header
               --solver=<arg>                   "cvode"            Specify the integration method (euler, cvode)
               --solverStats=<bool>             false              Add solver stats to the result file, e.g., step size; not supported for all solvers
               --startTime=<double> [-s]        0                  Specify the start time
               --stepSize=<double>              1e-3               Specify the (maximum) step size
               --stopTime=<double> [-t]         1                  Specify the stop time
               --stripRoot=<bool>               false              Remove the root system prefix from all exported signals
               --suppressPath=<bool>            false              Suppress path information in info messages; especially useful for testing
               --tempDir=<arg>                  "."                Specify the temporary directory
               --timeout=<int>                  0                  Specify the maximum allowed time in seconds for running a simulation (0 disables)
               --tolerance=<double>             1e-4               Specify the relative tolerance
               --version [-v]                                      Display version information
               --wallTime=<bool>                false              Add wall time information to the result file
               --workingDir=<arg>               "."                Specify the working directory
               --zeroNominal=<bool>             false              Accept FMUs with invalid nominal values and replace the invalid nominal values with 1.0

### setConnectionGeometry

    oms_status_enu_t oms_setConnectionGeometry(const char* crefA, const char* crefB, const ssd_connection_geometry_t* geometry);

### setConnectorGeometry

Set geometry information to a given connector.

    oms_status_enu_t oms_setConnectorGeometry(const char* cref, const ssd_connector_geometry_t* geometry);

### setElementGeometry

Set geometry information to a given component.

    oms_status_enu_t oms_setElementGeometry(const char* cref, const ssd_element_geometry_t* geometry);

### setFixedStepSize

Sets the fixed step size. Can be used for the communication step size of co-simulation systems and also for the integrator step size in model exchange systems.

    oms_status_enu_t oms_setFixedStepSize(const char* cref, double stepSize);

### setInteger

Sets the value of a given integer signal.

    oms_status_enu_t oms_setInteger(const char* cref, int value);

### setLogFile

Redirects logging output to file or std streams. The warning/error counters are reset.

filename="" to redirect to std streams and proper filename to redirect to file.

    oms_status_enu_t oms_setLogFile(const char* filename);

### setLoggingCallback

Sets a callback function for the logging system.

    void oms_setLoggingCallback(void (*cb)(oms_message_type_enu_t type, const char* message));

### setLoggingInterval

Set the logging interval of the simulation.

    oms_status_enu_t oms_setLoggingInterval(const char* cref, double loggingInterval);

### setLoggingLevel

Enables/Disables debug logging (logDebug and logTrace).

0 default, 1 default+debug, 2 default+debug+trace

    void oms_setLoggingLevel(int logLevel);

### setMaxLogFileSize

Sets maximum log file size in MB. If the file exceeds this limit, the logging will continue on stdout.

    void oms_setMaxLogFileSize(const unsigned long size);

### setReal

Sets the value of a given real signal.

    oms_status_enu_t oms_setReal(const char* cref, double value);

This function can be called in different model states:

- Before instantiation: setReal can be used to set start values or to define initial unknowns (e.g. parameters, states). The values are not immediately applied to the simulation unit, since it isn't actually instantiated.

- After instantiation and before initialization: Same as before instantiation, but the values are applied immediately to the simulation unit.

- After initialization: Can be used to force external inputs, which might cause discrete changes of continuous signals.

### setRealInputDerivative

Sets the first order derivative of a real input signal.

This can only be used for CS-FMU real input signals.

    oms_status_enu_t oms_setRealInputDerivative(const char* cref, double value);

### setResultFile

Set the result file of the simulation.

    oms_status_enu_t oms_setResultFile(const char* cref, const char* filename, int bufferSize);

The creation of a result file is omitted if the filename is an empty string.

### setSolver

Sets the solver method for the given system.

    oms_status_enu_t oms_setSolver(const char* cref, oms_solver_enu_t solver);

### setStartTime

Set the start time of the simulation.

    oms_status_enu_t oms_setStartTime(const char* cref, double startTime);

### setStopTime

Set the stop time of the simulation.

    oms_status_enu_t oms_setStopTime(const char* cref, double stopTime);

### setString

Sets the value of a given string signal.

    oms_status_enu_t oms_setString(const char* cref, const char* value);

### setTempDirectory

Set new temp directory.

    oms_status_enu_t oms_setTempDirectory(const char* newTempDir);

### setTolerance

Sets the tolerance for a given model or system.

    oms_status_enu_t oms_setTolerance(const char* cref, double relativeTolerance);

Default values are 1e-4 for both relative and absolute tolerances.

A tolerance specified for a model is automatically applied to its root system, i.e. both calls do exactly the same:

    oms_setTolerance("model", relativeTolerance);
    oms_setTolerance("model.root", relativeTolerance);

Component, e.g. FMUs, pick up the tolerances from there system. That means it is not possible to define different tolerances for FMUs in the same system right now.

In a strongly coupled system (oms_system_sc), the relative tolerance is used for CVODE and the absolute tolerance is used to solve algebraic loops.

In a weakly coupled system (oms_system_wc), both the relative and absolute tolerances are used for the adaptive step master algorithms and the absolute tolerance is used to solve algebraic loops.

### setUnit

Sets the unit of a given signal.

    oms_status_enu_t oms_setUnit(const char* cref, const char* value);

### setVariableStepSize

Sets the step size parameters for methods with stepsize control.

    oms_status_enu_t oms_getVariableStepSize(const char* cref, double* initialStepSize, double* minimumStepSize, double* maximumStepSize);

### setWorkingDirectory

Set a new working directory.

    oms_status_enu_t oms_setWorkingDirectory(const char* newWorkingDir);

### simulate

Simulates a composite model.

    oms_status_enu_t oms_simulate(const char* cref);

### simulate_realtime

Experimental feature for (soft) real-time simulation.

    oms_status_enu_t experimental_simulate_realtime(const char* ident);

### stepUntil

Simulates a composite model until a given time value.

    oms_status_enu_t oms_stepUntil(const char* cref, double stopTime);

### terminate

Terminates a given composite model.

    oms_status_enu_t oms_terminate(const char* cref);

## OMSimulatorLua

This is a shared library that provides a Lua interface for the OMSimulatorLib library.

### Examples

    oms_setTempDirectory("./temp/")
    oms_newModel("model")
    oms_addSystem("model.root", oms_system_sc)

    -- instantiate FMUs
    oms_addSubModel("model.root.system1", "FMUs/System1.fmu")
    oms_addSubModel("model.root.system2", "FMUs/System2.fmu")

    -- add connections
    oms_addConnection("model.root.system1.y", "model.root.system2.u")
    oms_addConnection("model.root.system2.y", "model.root.system1.u")

    -- simulation settings
    oms_setResultFile("model", "results.mat")
    oms_setStopTime("model", 0.1)
    oms_setFixedStepSize("model.root", 1e-4)

    oms_instantiate("model")
    oms_setReal("model.root.system1.x_start", 2.5)

    oms_initialize("model")
    oms_simulate("model")
    oms_terminate("model")
    oms_delete("model")

#### Lua Scripting Commands

### activateVariant

This API provides support to activate a multi-variant modelling from an ssp file [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ] from a ssp file. By default when importing a ssp file the default variant will be "SystemStructure.ssd". The users can be able to switch between other variants by using this API and make changes to that particular variant and simulate them.

    status = oms_activateVariant(crefA, crefB)

> An example of activating the number of available variants in a ssp file

> oms_newModel("model") oms_addSystem("model.root", "system_wc") oms_addSubModel("model.root.A", "A.fmu") oms_duplicateVariant("model", "varA") // varA will be the current variant oms_duplicateVariant("varA", "varB") // varB will be the current variant oms_activateVariant("varB", "varA") // Reactivate the variant varB to varA oms_activateVariant("varA", "model") // Reactivate the variant varA to model

### addBus

Adds a bus to a given component.

    status = oms_addBus(cref)

### addConnection

Adds a new connection between connectors A and B. The connectors need to be specified as fully qualified component references, e.g., "model.system.component.signal".

    status = oms_addConnection(crefA, crefB, suppressUnitConversion)

The two arguments crefA and crefB get swapped automatically if necessary. The third argument suppressUnitConversion is optional and the default value is false which allows automatic unit conversion between connections, if set to true then automatic unit conversion will be disabled.

### addConnector

Adds a connector to a given component.

    status = oms_addConnector(cref, causality, type)

    The second argument "causality", should be any of the following,

    oms_causality_input
    oms_causality_output
    oms_causality_parameter
    oms_causality_bidir
    oms_causality_undefined

    The third argument "type", should be any of the following,

    oms_signal_type_real
    oms_signal_type_integer
    oms_signal_type_boolean
    oms_signal_type_string
    oms_signal_type_enum
    oms_signal_type_bus

### addConnectorToBus

Adds a connector to a bus.

    status = oms_addConnectorToBus(busCref, connectorCref)

### addResources

Adds an external resources to an existing SSP. The external resources should be a ".ssv" or ".ssm" file

    status = oms_addResources(cref, path)

    -- Example
    oms_importFile("addExternalResources1.ssp")
    -- add list of external resources from filesystem to ssp
    oms_addResources("addExternalResources", "../../resources/externalRoot.ssv")
    oms_addResources("addExternalResources:externalSystem.ssv", "../../resources/externalSystem1.ssv")
    oms_addResources("addExternalResources", "../../resources/externalGain.ssv")
    -- export the ssp with new resources
    oms_export("addExternalResources", "addExternalResources1.ssp")

### addSignalsToResults

Add all variables that match the given regex to the result file.

    status = oms_addSignalsToResults(cref, regex)

The second argument, i.e. regex, is considered as a regular expression (C++11). ".*" and "(.)*" can be used to hit all variables.

### addSubModel

Adds a component to a system.

    status = oms_addSubModel(cref, fmuPath)

### addSystem

Adds a (sub-)system to a model or system.

    status = oms_addSystem(cref, type)

### compareSimulationResults

This function compares a given signal of two result files within absolute and relative tolerances.

    oms_compareSimulationResults(filenameA, filenameB, var, relTol, absTol)

The following table describes the input values:

Input | Type | Description
--- | --- | ---
filenameA | String | Name of first result file to compare.
filenameB | String | Name of second result file to compare.
var | String | Name of signal to compare.
relTol | Number | Relative tolerance.
absTol | Number | Absolute tolerance.

The following table describes the return values:

Type | Description
--- | ---
Integer | 1 if the signal is considered as equal, 0 otherwise

### copySystem

Copies a system.

    status = oms_copySystem(source, target)

### delete

Deletes a connector, component, system, or model object.

    status = oms_delete(cref)

### deleteConnection

Deletes the connection between connectors crefA and crefB.

    status = oms_deleteConnection(crefA, crefB)

The two arguments crefA and crefB get swapped automatically if necessary.

### deleteConnectorFromBus

Deletes a connector from a given bus.

    status = oms_deleteConnectorFromBus(busCref, connectorCref)

### deleteResources

Deletes the reference and resource file in a SSP. Deletion of ".ssv" and ".ssm" files are currently supported. The API can be used in two ways.

1. deleting only the reference file in ".ssd".

2. deleting both reference and resource files in ".ssp".

To delete only the reference file in ssd, the user should provide the full qualified cref of the ".ssv" file associated with a system or subsystem or component (e.g) "model.root:root1.ssv".

To delete both the reference and resource file in ssp, it is enough to provide only the model cref of the ".ssv" file (e.g) "model:root1.ssv".

When deleting only the references of a ".ssv" file, if a parameter mapping file ".ssm" is binded to a ".ssv" file then the ".ssm" file will also be deleted. It is not possible to delete the references of ".ssm" seperately as the ssm file is binded to a ssv file.

The filename of the reference or resource file is provided by the users using colon suffix at the end of cref. (e.g) ":root.ssv"

    status = oms_deleteResources(cref)

    -- Example
    oms_importFile("deleteResources1.ssp")
    -- delete only the references in ".ssd" file
    oms_deleteResources("deleteResources.root:root.ssv")
    -- delete both references and resources
    oms_deleteResources("deleteResources:root.ssv")
    oms_export("deleteResources1.ssp")

### duplicateVariant

This API provides support to develop a multi-variant modelling in OMSimulator [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ]. When duplicating a variant, the new variant becomes the current variant and all the changes made by the users are applied to the new variants only, and all the ssv and ssm resources associated with the new variant will be given new name based on the variant name provided by the user. This allows the bundling of multiple variants of a system structure definition referencing a similar set of packaged resources as a single SSP. However there must still be one SSD file named SystemStructure.ssd at the root of the ZIP archive which will be considered as default variant.

    status = oms_duplicateVariant(crefA, crefB)

An example of creating a multi-variant modelling is presented below

    oms_newModel("model")
    oms_addSystem("model.root", "system_wc")
    oms_addSubModel("model.root.A", "A.fmu")
    oms_setReal("model.root.A.param1", "10")
    oms_duplicateVariant("model", "varB")
    oms_addSubModel("varB.root.B" ,"B.fmu")
    oms_setReal("varB.root.A.param2", "20")
    oms_export("varB", "variant.ssp")

The variant.ssp file will have the following structure

    Variant.ssp
        SystemStructure.ssd
        varB.ssd
        resources\
            A.fmu
            B.fmu

### export

Exports a composite model to a SPP file.

    status = oms_export(cref, filename)

### exportDependencyGraphs

Export the dependency graphs of a given model to dot files.

    status = oms_exportDependencyGraphs(cref, initialization, event, simulation)

### exportSSMTemplate

Exports all signals that have start values of one or multiple FMUs to a SSM file that are read from modelDescription.xml with a mapping entry. The mapping entry specifies a single mapping between a parameter in the source and a parameter of the system or component being parameterized. The mapping entry contains two attributes namely source and target. The source attribute will be empty and needs to be manually mapped by the users associated with the parameter name defined in the SSV file, the target contains the name of parameter in the system or component to be parameterized. The function can be called for a top level model or a certain FMU component. If called for a top level model, start values of all FMUs are exported to the SSM file. If called for a component, start values of just this FMU are exported to the SSM file.

    status = oms_exportSSMTemplate(cref, filename)

### exportSSVTemplate

Exports all signals that have start values of one or multiple FMUs to a SSV file that are read from modelDescription.xml. The function can be called for a top level model or a certain FMU component. If called for a top level model, start values of all FMUs are exported to the SSV file. If called for a component, start values of just this FMU are exported to the SSV file.

    status = oms_exportSSVTemplate(cref, filename)

### exportSnapshot

Lists the SSD representation of a given model, system, or component.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    contents, status = oms_exportSnapshot(cref)

### freeMemory

Free the memory allocated by some other API. Pass the object for which memory is allocated.

This function is neither needed nor available from the Lua interface.

### getBoolean

Get boolean value of given signal.

    value, status = oms_getBoolean(cref)

### getDirectionalDerivative

This function computes the directional derivatives of an FMU.

    value, status = oms_getDirectionalDerivative(cref)

### getFixedStepSize

Gets the fixed step size. Can be used for the communication step size of co-simulation systems and also for the integrator step size in model exchange systems.

    stepSize, status = oms_setFixedStepSize(cref)

### getInteger

Get integer value of given signal.

    value, status = oms_getInteger(cref)

### getModelState

Gets the model state of the given model cref.

    modelState, status = oms_getModelState(cref)

### getReal

Get real value.

    value, status = oms_getReal(cref)

### getSolver

Gets the selected solver method of the given system.

    solver, status = oms_getSolver(cref)

### getStartTime

Get the start time from the model.

    startTime, status = oms_getStartTime(cref)

### getStopTime

Get the stop time from the model.

    stopTime, status = oms_getStopTime(cref)

### getString

Get string value.

Memory is allocated for value. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    value, status = oms_getString(cref)

### getSystemType

Gets the type of the given system.

    type, status = oms_getSystemType(cref)

### getTime

Get the current simulation time from the model.

    time, status = oms_getTime(cref)

### getTolerance

Gets the tolerance of a given system or component.

    relativeTolerance, status = oms_getTolerance(cref)

### getVariableStepSize

Gets the step size parameters.

    initialStepSize, minimumStepSize, maximumStepSize, status = oms_getVariableStepSize(cref)

### getVersion

Returns the library's version string.

    version = oms_getVersion()

### importFile

Imports a composite model from a SSP file.

    cref, status = oms_importFile(filename)

### importSnapshot

Loads a snapshot to restore a previous model state. The model must be in virgin model state, which means it must not be instantiated.

    newCref, status = oms_importSnapshot(cref, snapshot)

### initialize

Initializes a composite model.

    status = oms_initialize(cref)

### instantiate

Instantiates a given composite model.

    status = oms_instantiate(cref)

### list

Lists the SSD representation of a given model, system, or component.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    contents, status = oms_list(cref)

### listUnconnectedConnectors

Lists all unconnected connectors of a given system.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    contents, status = oms_listUnconnectedConnectors(cref)

### listVariants

This API shows the number of variants available [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ] from a ssp file.

    status = oms_listVariants(cref)

An example for finding the number of available variants in a ssp file

    oms_newModel("model")
    oms_addSystem("model.root", "system_wc")
    oms_addSubModel("model.root.A", "A.fmu")
    oms_duplicateVariant("model", "varA")
    oms_duplicateVariant("varA", "varB")

    oms_listVariants("varB")

The API will list the available variants like below

    <oms:Variants>
      <oms:variant name="model" />
      <oms:variant name="varB" />
      <oms:variant name="varA" />
    </oms:Variants>

### loadSnapshot

Loads a snapshot to restore a previous model state. The model must be in virgin model state, which means it must not be instantiated.

    newCref, status = oms_loadSnapshot(cref, snapshot)

### newModel

Creates a new and yet empty composite model.

    status = oms_newModel(cref)

### newResources

Adds a new empty resources to the SSP. The resource file is a ".ssv" file where the parameter values set by the users using "oms_setReal()", "oms_setInteger()" and "oms_setReal()" are writtern to the file. Currently only ".ssv" files can be created.

The filename of the resource file is provided by the users using colon suffix at the end of cref. (e.g) ":root.ssv"

    status = oms_newResources(cref)

    -- Example
    oms_newModel("newResources")

    oms_addSystem("newResources.root", oms_system_wc)
    oms_addConnector("newResources.root.Input1", oms_causality_input, oms_signal_type_real)
    oms_addConnector("newResources.root.Input2", oms_causality_input, oms_signal_type_real)

    -- add Top level new resources, the filename is provided using the colon suffix ":root.ssv"
    oms_newResources("newResources.root:root.ssv")
    oms_setReal("newResources.root.Input1", 10)
    -- export the ssp with new resources
    oms_export("newResources", "newResources.ssp")

### referenceResources

Switches the references of ".ssv" and ".ssm" in a SSP file. Referencing of ".ssv" and ".ssm" files are currently supported. The API can be used in two ways.

1. Referencing only the ".ssv" file.

2. Referencing both the ".ssv" along with the ".ssm" file.

This API should be used in combination with "oms_deleteResources".To switch with a new reference, the old reference must be deleted first using "oms_deleteResources" and then reference with new resources.

When deleting only the references of a ".ssv" file, if a parameter mapping file ".ssm" is binded to a ".ssv" file, then the reference of ".ssm" file will also be deleted. It is not possible to delete the references of ".ssm" seperately as the ssm file is binded to a ssv file. Hence it is not possible to switch the reference of ".ssm" file alone. So inorder to switch the reference of ".ssm" file, the users need to bind the reference of ".ssm" file along with the ".ssv".

The filename of the reference or resource file is provided by the users using colon suffix at the end of cref (e.g) ":root.ssv", and the ".ssm" file is optional and is provided by the user as the second argument to the API.

    status = oms_referenceResources(cref, ssmFile)

    -- Example
    oms_importFile("referenceResources1.ssp")
    -- delete only the references in ".ssd" file
    oms_deleteResources("referenceResources1.root:root.ssv")
    -- usage-1 switch with new references, only ssv file
    oms_referenceResources("referenceResources1.root:Config1.ssv")
    -- usage-2 switch with new references, both ssv and ssm file
    oms_referenceResources("referenceResources1.root:Config1.ssv", "Config1.ssm")
    oms_export("referenceResources1.ssp")

### removeSignalsFromResults

Removes all variables that match the given regex to the result file.

    status = oms_removeSignalsFromResults(cref, regex)

The second argument, i.e. regex, is considered as a regular expression (C++11). ".*" and "(.)*" can be used to hit all variables.

### rename

Renames a model, system, or component.

    status = oms_rename(cref, newCref)

### replaceSubModel

Replaces an existing fmu component, with a new component provided by the user, When replacing the fmu checks are made in all ssp concepts like in ssd, ssv and ssm, so that connections and parameter settings are not lost. It is possible that the namings of inputs and parameters match, but the start values might have been changed, in such cases new start values will be applied in ssd, ssv and ssm. In case if the Types of inputs and outputs and parameters differed, then the variables are updated according to the new changes and the connections will be removed with warning messages to user. In case when replacing a fmu, if the fmu contains parameter mapping associated with the ssv file, then only the ssm file entries are updated and the start values in the ssv files will not be changed.

    status = oms_replaceSubModel(cref, fmuPath)

> It is possible to import an partially developed fmu (i.e contains only modeldescription.xml without any binaries) in OMSimulator, and later can be replaced with a fully develped fmu. An example to use the API, oms_addSubModel("model.root.A", "../resources/replaceA.fmu") oms_export("model", "test.ssp") oms_import("test.ssp") oms_replaceSubModel("model.root.A", "../resources/replaceA_extended.fmu")

### reset

Reset the composite model after a simulation run.

The FMUs go into the same state as after instantiation.

    status = oms_reset(cref)

### setActivationRatio

Experimental feature for setting the activation ratio of FMUs for experimenting with multi-rate master algorithms.

    status = experimental_setActivationRatio(cref, k)

### setBoolean

Sets the value of a given boolean signal.

    status = oms_setBoolean(cref, value)

### setCommandLineOption

Sets special flags.

    status = oms_setCommandLineOption(cmd)

Available flags:

    info:    Usage: OMSimulator [Options] [Lua script] [FMU] [SSP file]
             Options:
               --addParametersToCSV=<bool>      false              Export parameters to a .csv file
               --algLoopSolver=<arg>            "kinsol"           Specifies the loop solver method (fixedpoint, kinsol) used for algebraic loops spanning multiple components.
               --clearAllOptions                                   Reset all flags to their default values
               --CVODEMaxErrTestFails=<int>     100                Maximum number of error test failures for CVODE
               --CVODEMaxNLSFailures=<int>      100                Maximum number of nonlinear convergence failures for CVODE
               --CVODEMaxNLSIterations=<int>    5                  Maximum number of nonlinear solver iterations for CVODE
               --CVODEMaxSteps=<int>            1000               Maximum number of steps for CVODE
               --deleteTempFiles=<bool>         true               Delete temporary files as soon as they are no longer needed
               --directionalDerivatives=<bool>  true               Use directional derivatives to calculate the Jacobian for algebraic loops
               --dumpAlgLoops=<bool>            false              Dump information for algebraic loops
               --emitEvents=<bool>              true               Emit events during simulation
               --help [-h]                                         Display the help text
               --ignoreInitialUnknowns=<bool>   false              Ignore initial unknowns from the modelDescription.xml
               --initialStepSize=<double>       1e-6               Specify the initial step size
               --inputExtrapolation=<bool>      false              Enable input extrapolation using derivative information
               --intervals=<int> [-i]           500                Specify the number of communication points (arg > 1)
               --logFile=<arg> [-l]             ""                 Specify the log file (stdout is used if no log file is specified)
               --logLevel=<int>                 0                  Set the log level (0: default, 1: debug, 2: debug+trace)
               --master=<arg>                   "ma"               Specify the master algorithm (ma)
               --maxEventIteration=<int>        100                Specify the maximum number of iterations for handling a single event
               --maxLoopIteration=<int>         10                 Specify the maximum number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
               --minimumStepSize=<double>       1e-12              Specify the minimum step size
               --mode=<arg> [-m]                "me"               Force a certain FMI mode if the FMU provides both cs and me (cs, me)
               --numProcs=<int> [-n]            1                  Specify the maximum number of processors to use (0=auto, 1=default)
               --progressBar=<bool>             false              Show a progress bar for the simulation progress in the terminal
               --realTime=<bool>                false              Enable experimental feature for (soft) real-time co-simulation
               --resultFile=<arg> [-r]          "<default>"        Specify the name of the output result file
               --skipCSVHeader=<bool>           true               Skip exporting the CSV delimiter in the header
               --solver=<arg>                   "cvode"            Specify the integration method (euler, cvode)
               --solverStats=<bool>             false              Add solver stats to the result file, e.g., step size; not supported for all solvers
               --startTime=<double> [-s]        0                  Specify the start time
               --stepSize=<double>              1e-3               Specify the (maximum) step size
               --stopTime=<double> [-t]         1                  Specify the stop time
               --stripRoot=<bool>               false              Remove the root system prefix from all exported signals
               --suppressPath=<bool>            false              Suppress path information in info messages; especially useful for testing
               --tempDir=<arg>                  "."                Specify the temporary directory
               --timeout=<int>                  0                  Specify the maximum allowed time in seconds for running a simulation (0 disables)
               --tolerance=<double>             1e-4               Specify the relative tolerance
               --version [-v]                                      Display version information
               --wallTime=<bool>                false              Add wall time information to the result file
               --workingDir=<arg>               "."                Specify the working directory
               --zeroNominal=<bool>             false              Accept FMUs with invalid nominal values and replace the invalid nominal values with 1.0

### setFixedStepSize

Sets the fixed step size. Can be used for the communication step size of co-simulation systems and also for the integrator step size in model exchange systems.

    status = oms_setFixedStepSize(cref, stepSize)

### setInteger

Sets the value of a given integer signal.

    status = oms_setInteger(cref, value)

### setLogFile

Redirects logging output to file or std streams. The warning/error counters are reset.

filename="" to redirect to std streams and proper filename to redirect to file.

    status = oms_setLogFile(filename)

### setLoggingInterval

Set the logging interval of the simulation.

    status = oms_setLoggingInterval(cref, loggingInterval)

### setLoggingLevel

Enables/Disables debug logging (logDebug and logTrace).

0 default, 1 default+debug, 2 default+debug+trace

    oms_setLoggingLevel(logLevel)

### setMaxLogFileSize

Sets maximum log file size in MB. If the file exceeds this limit, the logging will continue on stdout.

    oms_setMaxLogFileSize(size)

### setReal

Sets the value of a given real signal.

    status = oms_setReal(cref, value)

This function can be called in different model states:

- Before instantiation: setReal can be used to set start values or to define initial unknowns (e.g. parameters, states). The values are not immediately applied to the simulation unit, since it isn't actually instantiated.

- After instantiation and before initialization: Same as before instantiation, but the values are applied immediately to the simulation unit.

- After initialization: Can be used to force external inputs, which might cause discrete changes of continuous signals.

### setRealInputDerivative

Sets the first order derivative of a real input signal.

This can only be used for CS-FMU real input signals.

    status = oms_setRealInputDerivative(cref, value)

### setResultFile

Set the result file of the simulation.

    status = oms_setResultFile(cref, filename)
    status = oms_setResultFile(cref, filename, bufferSize)

The creation of a result file is omitted if the filename is an empty string.

### setSolver

Sets the solver method for the given system.

    status = oms_setSolver(cref, solver)

solver | Type | Description
--- | --- | ---
oms_solver_sc_explicit_euler | sc-system | Explicit euler with fixed step size
oms_solver_sc_cvode | sc-system | CVODE with adaptive stepsize
oms_solver_wc_ma | wc-system | default master algorithm with fixed step size
oms_solver_wc_mav | wc-system | master algorithm with adaptive stepsize
oms_solver_wc_mav2 | wc-system | master algorithm with adaptive stepsize (double-step)

### setStartTime

Set the start time of the simulation.

    status = oms_setStartTime(cref, startTime)

### setStopTime

Set the stop time of the simulation.

    status = oms_setStopTime(cref, stopTime)

### setString

Sets the value of a given string signal.

    status = oms_setString(cref, value)

### setTempDirectory

Set new temp directory.

    status = oms_setTempDirectory(newTempDir)

### setTolerance

Sets the tolerance for a given model or system.

    status = oms_setTolerance(const char* cref, double relativeTolerance)

Default values are 1e-4 for both relative and absolute tolerances.

A tolerance specified for a model is automatically applied to its root system, i.e. both calls do exactly the same:

    oms_setTolerance("model", relativeTolerance);
    oms_setTolerance("model.root", relativeTolerance);

Component, e.g. FMUs, pick up the tolerances from there system. That means it is not possible to define different tolerances for FMUs in the same system right now.

In a strongly coupled system (oms_system_sc), the relative tolerance is used for CVODE and the absolute tolerance is used to solve algebraic loops.

In a weakly coupled system (oms_system_wc), both the relative and absolute tolerances are used for the adaptive step master algorithms and the absolute tolerance is used to solve algebraic loops.

### setUnit

Sets the unit of a given signal.

    status = oms_setUnit(cref, value)

### setVariableStepSize

Sets the step size parameters for methods with stepsize control.

    status = oms_getVariableStepSize(cref, initialStepSize, minimumStepSize, maximumStepSize)

### setWorkingDirectory

Set a new working directory.

    status = oms_setWorkingDirectory(newWorkingDir)

### simulate

Simulates a composite model.

    status = oms_simulate(cref)

### simulate_realtime

Experimental feature for (soft) real-time simulation.

    status = experimental_simulate_realtime(ident)

### stepUntil

Simulates a composite model until a given time value.

    status = oms_stepUntil(cref, stopTime)

### terminate

Terminates a given composite model.

    status = oms_terminate(cref)

## OMSimulatorPython

This is a shared library that provides a Python interface for the OMSimulatorLib library.

Installation using `pip` is recommended:

    > pip3 install OMSimulator --upgrade

### Examples

    from OMSimulator import OMSimulator

    oms = OMSimulator()
    oms.setTempDirectory("./temp/")
    oms.newModel("model")
    oms.addSystem("model.root", oms.system_sc)

    # instantiate FMUs
    oms.addSubModel("model.root.system1", "FMUs/System1.fmu")
    oms.addSubModel("model.root.system2", "FMUs/System2.fmu")

    # add connections
    oms.addConnection("model.root.system1.y", "model.root.system2.u")
    oms.addConnection("model.root.system2.y", "model.root.system1.u")

    # simulation settings
    oms.setResultFile("model", "results.mat")
    oms.setStopTime("model", 0.1)
    oms.setFixedStepSize("model.root", 1e-4)

    oms.instantiate("model")
    oms.setReal("model.root.system1.x_start", 2.5)

    oms.initialize("model")
    oms.simulate("model")
    oms.terminate("model")
    oms.delete("model")

The python package also provides a more object oriented API. The following example is equivalent to the previous one:

    import OMSimulator as oms

    oms.setTempDirectory('./temp/')
    model = oms.newModel("model")
    root = model.addSystem('root', oms.Types.System.SC)

    # instantiate FMUs
    root.addSubModel('system1', 'FMUs/System1.fmu')
    root.addSubModel('system2', 'FMUs/System2.fmu')

    # add connections
    root.addConnection('system1.y', 'system2.u')
    root.addConnection('system2.y', 'system1.u')

    # simulation settings
    model.resultFile = 'results.mat'
    model.stopTime = 0.1
    model.fixedStepSize = 1e-4

    model.instantiate()
    model.setReal('root.system1.x_start', 2.5)
    #or system.setReal('system1.x_start', 2.5)

    model.initialize()
    model.simulate()
    model.terminate()
    model.delete()

### Python Scripting Commands

### activateVariant

This API provides support to activate a multi-variant modelling from an ssp file [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ] from a ssp file. By default when importing a ssp file the default variant will be "SystemStructure.ssd". The users can be able to switch between other variants by using this API and make changes to that particular variant and simulate them.

    status = oms.activateVariant(crefA, crefB)

> An example of activating the number of available variants in a ssp file

> oms_newModel("model") oms_addSystem("model.root", "system_wc") oms_addSubModel("model.root.A", "A.fmu") oms_duplicateVariant("model", "varA") // varA will be the current variant oms_duplicateVariant("varA", "varB") // varB will be the current variant oms_activateVariant("varB", "varA") // Reactivate the variant varB to varA oms_activateVariant("varA", "model") // Reactivate the variant varA to model

### addBus

Adds a bus to a given component.

    status = oms.addBus(cref)

### addConnection

Adds a new connection between connectors A and B. The connectors need to be specified as fully qualified component references, e.g., "model.system.component.signal".

    status = oms.addConnection(crefA, crefB, suppressUnitConversion)

The two arguments crefA and crefB get swapped automatically if necessary. The third argument suppressUnitConversion is optional and the default value is false which allows automatic unit conversion between connections, if set to true then automatic unit conversion will be disabled.

### addConnector

Adds a connector to a given component.

    status = oms.addConnector(cref, causality, type)

    The second argument "causality", should be any of the following,

    oms.input
    oms.output
    oms.parameter
    oms.bidir
    oms.undefined

    The third argument "type", should be any of the following,

    oms.signal_type_real
    oms.signal_type_integer
    oms.signal_type_boolean
    oms.signal_type_string
    oms.signal_type_enum
    oms.signal_type_bus

### addConnectorToBus

Adds a connector to a bus.

    status = oms.addConnectorToBus(busCref, connectorCref)

### addResources

Adds an external resources to an existing SSP. The external resources should be a ".ssv" or ".ssm" file

    status = oms.addResources(cref, path)

    ## Example
    from OMSimulator import OMSimulator
    oms = OMSimulator()
    oms.importFile("addExternalResources1.ssp")
    ## add list of external resources from filesystem to ssp
    oms.addResources("addExternalResources", "../../resources/externalRoot.ssv")
    oms.addResources("addExternalResources:externalSystem.ssv", "../../resources/externalSystem1.ssv")
    oms.addResources("addExternalResources", "../../resources/externalGain.ssv")
    ## export the ssp with new resources
    oms_export("addExternalResources", "addExternalResources1.ssp")

### addSignalsToResults

Add all variables that match the given regex to the result file.

    status = oms.addSignalsToResults(cref, regex)

The second argument, i.e. regex, is considered as a regular expression (C++11). ".*" and "(.)*" can be used to hit all variables.

### addSubModel

Adds a component to a system.

    status = oms.addSubModel(cref, fmuPath)

### addSystem

Adds a (sub-)system to a model or system.

    status = oms.addSystem(cref, type)

### compareSimulationResults

This function compares a given signal of two result files within absolute and relative tolerances.

    oms.compareSimulationResults(filenameA, filenameB, var, relTol, absTol)

The following table describes the input values:

Input | Type | Description
--- | --- | ---
filenameA | String | Name of first result file to compare.
filenameB | String | Name of second result file to compare.
var | String | Name of signal to compare.
relTol | Number | Relative tolerance.
absTol | Number | Absolute tolerance.

The following table describes the return values:

Type | Description
--- | ---
Integer | 1 if the signal is considered as equal, 0 otherwise

### copySystem

Copies a system.

    status = oms.copySystem(source, target)

### delete

Deletes a connector, component, system, or model object.

    status = oms.delete(cref)

### deleteConnection

Deletes the connection between connectors crefA and crefB.

    status = oms.deleteConnection(crefA, crefB)

The two arguments crefA and crefB get swapped automatically if necessary.

### deleteConnectorFromBus

Deletes a connector from a given bus.

    status = oms.deleteConnectorFromBus(busCref, connectorCref)

### deleteResources

Deletes the reference and resource file in a SSP. Deletion of ".ssv" and ".ssm" files are currently supported. The API can be used in two ways.

1. deleting only the reference file in ".ssd".

2. deleting both reference and resource files in ".ssp".

To delete only the reference file in ssd, the user should provide the full qualified cref of the ".ssv" file associated with a system or subsystem or component (e.g) "model.root:root1.ssv".

To delete both the reference and resource file in ssp, it is enough to provide only the model cref of the ".ssv" file (e.g) "model:root1.ssv".

When deleting only the references of a ".ssv" file, if a parameter mapping file ".ssm" is binded to a ".ssv" file then the ".ssm" file will also be deleted. It is not possible to delete the references of ".ssm" seperately as the ssm file is binded to a ssv file.

The filename of the reference or resource file is provided by the users using colon suffix at the end of cref. (e.g) ":root.ssv"

    status = oms.deleteResources(cref))

    ## Example
    from OMSimulator import OMSimulator
    oms = OMSimulator()
    oms.importFile("deleteResources1.ssp")
    ## delete only the references in ".ssd" file
    oms.deleteResources("deleteResources.root:root.ssv")
    ## delete both references and resources
    oms.deleteResources("deleteResources:root.ssv")
    oms.export("deleteResources1.ssp")

### doStep

Simulates a macro step of the given composite model. The step size will be determined by the master algorithm and is limited by the definied minimal and maximal step sizes.

    status = oms.doStep(cref)

### duplicateVariant

This API provides support to develop a multi-variant modelling in OMSimulator [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ]. When duplicating a variant, the new variant becomes the current variant and all the changes made by the users are applied to the new variants only, and all the ssv and ssm resources associated with the new variant will be given new name based on the variant name provided by the user. This allows the bundling of multiple variants of a system structure definition referencing a similar set of packaged resources as a single SSP. However there must still be one SSD file named SystemStructure.ssd at the root of the ZIP archive which will be considered as default variant.

    status = oms.duplicateVariant(crefA, crefB)

An example of creating a multi-variant modelling is presented below

    oms_newModel("model")
    oms_addSystem("model.root", "system_wc")
    oms_addSubModel("model.root.A", "A.fmu")
    oms_setReal("model.root.A.param1", "10")
    oms_duplicateVariant("model", "varB")
    oms_addSubModel("varB.root.B" ,"B.fmu")
    oms_setReal("varB.root.A.param2", "20")
    oms_export("varB", "variant.ssp")

The variant.ssp file will have the following structure

    Variant.ssp
        SystemStructure.ssd
        varB.ssd
        resources\
            A.fmu
            B.fmu

### export

Exports a composite model to a SPP file.

    status = oms.export(cref, filename)

### exportDependencyGraphs

Export the dependency graphs of a given model to dot files.

    status = oms.exportDependencyGraphs(cref, initialization, event, simulation)

### exportSSMTemplate

Exports all signals that have start values of one or multiple FMUs to a SSM file that are read from modelDescription.xml with a mapping entry. The mapping entry specifies a single mapping between a parameter in the source and a parameter of the system or component being parameterized. The mapping entry contains two attributes namely source and target. The source attribute will be empty and needs to be manually mapped by the users associated with the parameter name defined in the SSV file, the target contains the name of parameter in the system or component to be parameterized. The function can be called for a top level model or a certain FMU component. If called for a top level model, start values of all FMUs are exported to the SSM file. If called for a component, start values of just this FMU are exported to the SSM file.

    status = oms.exportSSMTemplate(cref, filename)

### exportSSVTemplate

Exports all signals that have start values of one or multiple FMUs to a SSV file that are read from modelDescription.xml. The function can be called for a top level model or a certain FMU component. If called for a top level model, start values of all FMUs are exported to the SSV file. If called for a component, start values of just this FMU are exported to the SSV file.

    status = oms.exportSSVTemplate(cref, filename)

### exportSnapshot

Lists the SSD representation of a given model, system, or component.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    contents, status = oms.exportSnapshot(cref)

### freeMemory

Free the memory allocated by some other API. Pass the object for which memory is allocated.

    oms.freeMemory(obj)

### getBoolean

Get boolean value of given signal.

    value, status = oms.getBoolean(cref)

### getDirectionalDerivative

This function computes the directional derivatives of an FMU.

    value, status = oms.getDirectionalDerivative(cref)

### getFixedStepSize

Gets the fixed step size. Can be used for the communication step size of co-simulation systems and also for the integrator step size in model exchange systems.

    stepSize, status = oms.getFixedStepSize(cref)

### getInteger

Get integer value of given signal.

    value, status = oms.getInteger(cref)

### getReal

Get real value.

    value, status = oms.getReal(cref)

### getResultFile

Gets the result filename and buffer size of the given model cref.

    filename, bufferSize, status = oms.getResultFile(cref)

### getSolver

Gets the selected solver method of the given system.

    solver, status = oms.getSolver(cref)

### getStartTime

Get the start time from the model.

    startTime, status = oms.getStartTime(cref)

### getStopTime

Get the stop time from the model.

    stopTime, status = oms.getStopTime(cref)

### getString

Get string value.

Memory is allocated for value. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    value, status = oms.getString(cref)

### getSubModelPath

Returns the path of a given component.

    path, status = oms.getSubModelPath(cref)

### getSystemType

Gets the type of the given system.

    type, status = oms.getSystemType(cref)

### getTime

Get the current simulation time from the model.

    time, status = oms.getTime(cref)

### getTolerance

Gets the tolerance of a given system or component.

    relativeTolerance, status = oms.getTolerance(cref)

### getVariableStepSize

Gets the step size parameters.

    initialStepSize, minimumStepSize, maximumStepSize, status = oms.getVariableStepSize(cref)

### getVersion

Returns the library's version string.

    oms = OMSimulator()
    oms.getVersion()

### importFile

Imports a composite model from a SSP file.

    cref, status = oms.importFile(filename)

### importSnapshot

Loads a snapshot to restore a previous model state. The model must be in virgin model state, which means it must not be instantiated.

    newCref, status = oms.importSnapshot(cref, snapshot)

### initialize

Initializes a composite model.

    status = oms.initialize(cref)

### instantiate

Instantiates a given composite model.

    status = oms.instantiate(cref)

### list

Lists the SSD representation of a given model, system, or component.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    contents, status = oms.list(cref)

### listUnconnectedConnectors

Lists all unconnected connectors of a given system.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    contents, status = oms.listUnconnectedConnectors(cref)

### listVariants

This API shows the number of variants available [(e.g). SystemStructure.ssd, VarA.ssd, VarB.ssd ] from a ssp file.

    status = oms.listVariants(cref)

An example for finding the number of available variants in a ssp file

    oms_newModel("model")
    oms_addSystem("model.root", "system_wc")
    oms_addSubModel("model.root.A", "A.fmu")
    oms_duplicateVariant("model", "varA")
    oms_duplicateVariant("varA", "varB")

    oms_listVariants("varB")

The API will list the available variants like below

    <oms:Variants>
      <oms:variant name="model" />
      <oms:variant name="varB" />
      <oms:variant name="varA" />
    </oms:Variants>

### loadSnapshot

Loads a snapshot to restore a previous model state. The model must be in virgin model state, which means it must not be instantiated.

    newCref, status = oms.loadSnapshot(cref, snapshot)

### newModel

Creates a new and yet empty composite model.

    status = oms.newModel(cref)

### newResources

Adds a new empty resources to the SSP. The resource file is a ".ssv" file where the parameter values set by the users using "oms_setReal()", "oms_setInteger()" and "oms_setReal()" are writtern to the file. Currently only ".ssv" files can be created.

The filename of the resource file is provided by the users using colon suffix at the end of cref. (e.g) ":root.ssv"

    status = oms.newResources(cref)

    ## Example
    from OMSimulator import OMSimulator
    oms = OMSimulator()
    oms.newModel("newResources")

    oms.addSystem("newResources.root", oms_system_wc)
    oms.addConnector("newResources.root.Input1", oms.input, oms_signal_type_real)
    oms.addConnector("newResources.root.Input2", oms.input, oms_signal_type_real)

    ## add Top level resources, the filename is provided using the colon suffix ":root.ssv"
    oms.newResources("newResources.root:root.ssv")
    oms.setReal("newResources.root.Input1", 10)
    ## export the ssp with new resources
    oms.export("newResources", "newResources.ssp")

### referenceResources

Switches the references of ".ssv" and ".ssm" in a SSP file. Referencing of ".ssv" and ".ssm" files are currently supported. The API can be used in two ways.

1. Referencing only the ".ssv" file.

2. Referencing both the ".ssv" along with the ".ssm" file.

This API should be used in combination with "oms_deleteResources".To switch with a new reference, the old reference must be deleted first using "oms_deleteResources" and then reference with new resources.

When deleting only the references of a ".ssv" file, if a parameter mapping file ".ssm" is binded to a ".ssv" file, then the reference of ".ssm" file will also be deleted. It is not possible to delete the references of ".ssm" seperately as the ssm file is binded to a ssv file. Hence it is not possible to switch the reference of ".ssm" file alone. So inorder to switch the reference of ".ssm" file, the users need to bind the reference of ".ssm" file along with the ".ssv".

The filename of the reference or resource file is provided by the users using colon suffix at the end of cref (e.g) ":root.ssv", and the ".ssm" file is optional and is provided by the user as the second argument to the API.

    status = oms.referenceResources(cref, ssmFile)

    ## Example
    from OMSimulator import OMSimulator
    oms = OMSimulator()
    oms.importFile("referenceResources1.ssp")
    ## delete only the references in ".ssd" file
    oms.deleteResources("referenceResources1.root:root.ssv")
    ## usage-1 switch with new references, only ssv file
    oms.referenceResources("referenceResources1.root:Config1.ssv")
    ## usage-2 switch with new references, both ssv and ssm file
    oms.referenceResources("referenceResources1.root:Config1.ssv", "Config1.ssm")

### removeSignalsFromResults

Removes all variables that match the given regex to the result file.

    status = oms.removeSignalsFromResults(cref, regex)

The second argument, i.e. regex, is considered as a regular expression (C++11). ".*" and "(.)*" can be used to hit all variables.

### rename

Renames a model, system, or component.

    status = oms.rename(cref, newCref)

### replaceSubModel

Replaces an existing fmu component, with a new component provided by the user, When replacing the fmu checks are made in all ssp concepts like in ssd, ssv and ssm, so that connections and parameter settings are not lost. It is possible that the namings of inputs and parameters match, but the start values might have been changed, in such cases new start values will be applied in ssd, ssv and ssm. In case if the Types of inputs and outputs and parameters differed, then the variables are updated according to the new changes and the connections will be removed with warning messages to user. In case when replacing a fmu, if the fmu contains parameter mapping associated with the ssv file, then only the ssm file entries are updated and the start values in the ssv files will not be changed.

    status = oms.replaceSubModel(cref, fmuPath)

> It is possible to import an partially developed fmu (i.e contains only modeldescription.xml without any binaries) in OMSimulator, and later can be replaced with a fully develped fmu. An example to use the API, oms_addSubModel("model.root.A", "../resources/replaceA.fmu") oms_export("model", "test.ssp") oms_import("test.ssp") oms_replaceSubModel("model.root.A", "../resources/replaceA_extended.fmu")

### reset

Reset the composite model after a simulation run.

The FMUs go into the same state as after instantiation.

    status = oms.reset(cref)

### setBoolean

Sets the value of a given boolean signal.

    status = oms.setBoolean(cref, value)

### setCommandLineOption

Sets special flags.

    status = oms.setCommandLineOption(cmd)

Available flags:

    info:    Usage: OMSimulator [Options] [Lua script] [FMU] [SSP file]
             Options:
               --addParametersToCSV=<bool>      false              Export parameters to a .csv file
               --algLoopSolver=<arg>            "kinsol"           Specifies the loop solver method (fixedpoint, kinsol) used for algebraic loops spanning multiple components.
               --clearAllOptions                                   Reset all flags to their default values
               --CVODEMaxErrTestFails=<int>     100                Maximum number of error test failures for CVODE
               --CVODEMaxNLSFailures=<int>      100                Maximum number of nonlinear convergence failures for CVODE
               --CVODEMaxNLSIterations=<int>    5                  Maximum number of nonlinear solver iterations for CVODE
               --CVODEMaxSteps=<int>            1000               Maximum number of steps for CVODE
               --deleteTempFiles=<bool>         true               Delete temporary files as soon as they are no longer needed
               --directionalDerivatives=<bool>  true               Use directional derivatives to calculate the Jacobian for algebraic loops
               --dumpAlgLoops=<bool>            false              Dump information for algebraic loops
               --emitEvents=<bool>              true               Emit events during simulation
               --help [-h]                                         Display the help text
               --ignoreInitialUnknowns=<bool>   false              Ignore initial unknowns from the modelDescription.xml
               --initialStepSize=<double>       1e-6               Specify the initial step size
               --inputExtrapolation=<bool>      false              Enable input extrapolation using derivative information
               --intervals=<int> [-i]           500                Specify the number of communication points (arg > 1)
               --logFile=<arg> [-l]             ""                 Specify the log file (stdout is used if no log file is specified)
               --logLevel=<int>                 0                  Set the log level (0: default, 1: debug, 2: debug+trace)
               --master=<arg>                   "ma"               Specify the master algorithm (ma)
               --maxEventIteration=<int>        100                Specify the maximum number of iterations for handling a single event
               --maxLoopIteration=<int>         10                 Specify the maximum number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
               --minimumStepSize=<double>       1e-12              Specify the minimum step size
               --mode=<arg> [-m]                "me"               Force a certain FMI mode if the FMU provides both cs and me (cs, me)
               --numProcs=<int> [-n]            1                  Specify the maximum number of processors to use (0=auto, 1=default)
               --progressBar=<bool>             false              Show a progress bar for the simulation progress in the terminal
               --realTime=<bool>                false              Enable experimental feature for (soft) real-time co-simulation
               --resultFile=<arg> [-r]          "<default>"        Specify the name of the output result file
               --skipCSVHeader=<bool>           true               Skip exporting the CSV delimiter in the header
               --solver=<arg>                   "cvode"            Specify the integration method (euler, cvode)
               --solverStats=<bool>             false              Add solver stats to the result file, e.g., step size; not supported for all solvers
               --startTime=<double> [-s]        0                  Specify the start time
               --stepSize=<double>              1e-3               Specify the (maximum) step size
               --stopTime=<double> [-t]         1                  Specify the stop time
               --stripRoot=<bool>               false              Remove the root system prefix from all exported signals
               --suppressPath=<bool>            false              Suppress path information in info messages; especially useful for testing
               --tempDir=<arg>                  "."                Specify the temporary directory
               --timeout=<int>                  0                  Specify the maximum allowed time in seconds for running a simulation (0 disables)
               --tolerance=<double>             1e-4               Specify the relative tolerance
               --version [-v]                                      Display version information
               --wallTime=<bool>                false              Add wall time information to the result file
               --workingDir=<arg>               "."                Specify the working directory
               --zeroNominal=<bool>             false              Accept FMUs with invalid nominal values and replace the invalid nominal values with 1.0

### setFixedStepSize

Sets the fixed step size. Can be used for the communication step size of co-simulation systems and also for the integrator step size in model exchange systems.

    status = oms.setFixedStepSize(cref, stepSize)

### setInteger

Sets the value of a given integer signal.

    status = oms.setInteger(cref, value)

### setLogFile

Redirects logging output to file or std streams. The warning/error counters are reset.

filename="" to redirect to std streams and proper filename to redirect to file.

    status = oms.setLogFile(filename)

### setLoggingInterval

Set the logging interval of the simulation.

    status = oms.setLoggingInterval(cref, loggingInterval)

### setLoggingLevel

Enables/Disables debug logging (logDebug and logTrace).

0 default, 1 default+debug, 2 default+debug+trace

    oms.setLoggingLevel(logLevel)

### setMaxLogFileSize

Sets maximum log file size in MB. If the file exceeds this limit, the logging will continue on stdout.

    oms.setMaxLogFileSize(size)

### setReal

Sets the value of a given real signal.

    status = oms.setReal(cref, value)

This function can be called in different model states:

- Before instantiation: setReal can be used to set start values or to define initial unknowns (e.g. parameters, states). The values are not immediately applied to the simulation unit, since it isn't actually instantiated.

- After instantiation and before initialization: Same as before instantiation, but the values are applied immediately to the simulation unit.

- After initialization: Can be used to force external inputs, which might cause discrete changes of continuous signals.

### setRealInputDerivative

Sets the first order derivative of a real input signal.

This can only be used for CS-FMU real input signals.

    status = oms.setRealInputDerivative(cref, value)

### setResultFile

Set the result file of the simulation.

    status = oms.setResultFile(cref, filename)
    status = oms.setResultFile(cref, filename, bufferSize)

The creation of a result file is omitted if the filename is an empty string.

### setSolver

Sets the solver method for the given system.

    status = oms.setSolver(cref, solver)

solver | Type | Description
--- | --- | ---
oms.solver_sc_explicit_euler | sc-system | Explicit euler with fixed step size
oms.solver_sc_cvode | sc-system | CVODE with adaptive stepsize
oms.solver_wc_ma | wc-system | default master algorithm with fixed step size
oms.solver_wc_mav | wc-system | master algorithm with adaptive stepsize
oms.solver_wc_mav2 | wc-system | master algorithm with adaptive stepsize (double-step)

### setStartTime

Set the start time of the simulation.

    status = oms.setStartTime(cref, startTime)

### setStopTime

Set the stop time of the simulation.

    status = oms.setStopTime(cref, stopTime)

### setString

Sets the value of a given string signal.

    status = oms.setString(cref, value)

### setTempDirectory

Set new temp directory.

    status = oms.setTempDirectory(newTempDir)

### setTolerance

Sets the tolerance for a given model or system.

    status = oms.setTolerance(const char* cref,  double relativeTolerance)

Default values are 1e-4 for both relative and absolute tolerances.

A tolerance specified for a model is automatically applied to its root system, i.e. both calls do exactly the same:

    oms_setTolerance("model", relativeTolerance);
    oms_setTolerance("model.root", relativeTolerance);

Component, e.g. FMUs, pick up the tolerances from there system. That means it is not possible to define different tolerances for FMUs in the same system right now.

In a strongly coupled system (oms_system_sc), the relative tolerance is used for CVODE and the absolute tolerance is used to solve algebraic loops.

In a weakly coupled system (oms_system_wc), both the relative and absolute tolerances are used for the adaptive step master algorithms and the absolute tolerance is used to solve algebraic loops.

### setUnit

Sets the unit of a given signal.

    status = oms.setUnit(cref, value)

### setVariableStepSize

Sets the step size parameters for methods with stepsize control.

    status = oms.getVariableStepSize(cref, initialStepSize, minimumStepSize, maximumStepSize)

### setWorkingDirectory

Set a new working directory.

    status = oms.setWorkingDirectory(newWorkingDir)

### simulate

Simulates a composite model.

    status = oms.simulate(cref)

### stepUntil

Simulates a composite model until a given time value.

    status = oms.stepUntil(cref, stopTime)

### terminate

Terminates a given composite model.

    status = oms.terminate(cref)

This example uses a simple Modelica model and FMI-based batch simulation to approximate the value of pi.

A Modelica model is used to calculate two uniform distributed pseudo-random numbers between 0 and 1 based on a seed value and evaluates if the resulting coordinate is inside the unit circle or not.

    model Circle
      parameter Integer globalSeed = 30020 "global seed to initialize random number generator";
      parameter Integer localSeed = 614657 "local seed to initialize random number generator";
      Real x;
      Real y;
      Boolean inside = x*x + y*y < 1.0;
    protected
      Integer state128[4];
    algorithm
      when initial() then
        state128 := Modelica.Math.Random.Generators.Xorshift128plus.initialState(localSeed, globalSeed);
        (x, state128) := Modelica.Math.Random.Generators.Xorshift128plus.random(state128);
        (y, state128) := Modelica.Math.Random.Generators.Xorshift128plus.random(state128);
      end when;
      annotation(uses(Modelica(version="4.0.0")));
    end Circle;

The model is then exported using the FMI interface and the generated FMU can then be used to run a million simulations in just a few seconds.

Listing 4 Batch simulation of the simple Cirlce model with different seed values. All OMSimulator-related comands are highlighted for convenience.

     1import math
     2import matplotlib.pyplot as plt
     3import OMSimulator as oms
     4
     5# redirect logging to file and limit the file size to 65MB
     6oms.setLogFile('pi.log', 65)
     7
     8model = oms.newModel('pi')
     9root = model.addSystem('root', oms.Types.System.SC)
    10root.addSubModel('circle', 'Circle.fmu')
    11
    12model.resultFile = '' # no result file
    13model.instantiate()
    14
    15results = list()
    16inside = 0
    17
    18MIN = 100
    19MAX = 1000000
    20for i in range(0, MAX+1):
    21  if i > 0:
    22    model.reset()
    23  model.setInteger('root.circle.globalSeed', i)
    24  model.initialize()
    25  if model.getBoolean("root.circle.inside"):
    26    inside = inside + 1
    27  if i >= MIN:
    28    results.append(4.0*inside/i)
    29model.terminate()
    30model.delete()
    31
    32plt.plot([MIN, MAX], [math.pi, math.pi], 'r--', range(MIN, MAX+1), results)
    33plt.xscale('log')
    34plt.ylabel('Approximation of pi')
    35plt.savefig('pi.png')

The following figure shows the approximation of pi in relation to the number of samples.

Figure 43 Results of the above batch simulation which approximates the value of pi

## OpenModelicaScripting

This is a shared library that provides a OpenModelica Scripting interface for the OMSimulatorLib library.

### Examples

    loadOMSimulator();
    oms_setTempDirectory("./temp/");
    oms_newModel("model");
    oms_addSystem("model.root", OpenModelica.Scripting.oms_system.oms_system_sc);

    // instantiate FMUs
    oms_addSubModel("model.root.system1", "FMUs/System1.fmu");
    oms_addSubModel("model.root.system2", "FMUs/System2.fmu");

    // add connections
    oms_addConnection("model.root.system1.y", "model.root.system2.u");
    oms_addConnection("model.root.system2.y", "model.root.system1.u");

    // simulation settings
    oms_setResultFile("model", "results.mat");
    oms_setStopTime("model", 0.1);
    oms_setFixedStepSize("model.root", 1e-4);

    oms_instantiate("model");
    oms_setReal("model.root.system1.x_start", 2.5);

    oms_initialize("model");
    oms_simulate("model");
    oms_terminate("model");
    oms_delete("model");
    unloadOMSimulator();

### OpenModelica Scripting Commands

### addBus

Adds a bus to a given component.

    status := oms_addBus(cref);

### addConnection

Adds a new connection between connectors A and B. The connectors need to be specified as fully qualified component references, e.g., "model.system.component.signal".

    status := oms_addConnection(crefA, crefB, suppressUnitConversion);

The two arguments crefA and crefB get swapped automatically if necessary. The third argument suppressUnitConversion is optional and the default value is false which allows automatic unit conversion between connections, if set to true then automatic unit conversion will be disabled.

### addConnector

Adds a connector to a given component.

    status := oms_addConnector(cref, causality, type);

    The second argument "causality", should be any of the following,

    "OpenModelica.Scripting.oms_causality.oms_causality_input"
    "OpenModelica.Scripting.oms_causality.oms_causality_output"
    "OpenModelica.Scripting.oms_causality.oms_causality_parameter"
    "OpenModelica.Scripting.oms_causality.oms_causality_bidir"
    "OpenModelica.Scripting.oms_causality.oms_causality_undefined"

    The third argument type, should be any of the following,

    "OpenModelica.Scripting.oms_signal_type.oms_signal_type_real"
    "OpenModelica.Scripting.oms_signal_type.oms_signal_type_integer"
    "OpenModelica.Scripting.oms_signal_type.oms_signal_type_boolean"
    "OpenModelica.Scripting.oms_signal_type.oms_signal_type_string"
    "OpenModelica.Scripting.oms_signal_type.oms_signal_type_enum"
    "OpenModelica.Scripting.oms_signal_type.oms_signal_type_bus"

### addConnectorToBus

Adds a connector to a bus.

    status := oms_addConnectorToBus(busCref, connectorCref);

### addSignalsToResults

Add all variables that match the given regex to the result file.

    status := oms_addSignalsToResults(cref, regex);

The second argument, i.e. regex, is considered as a regular expression (C++11). ".*" and "(.)*" can be used to hit all variables.

### addSubModel

Adds a component to a system.

    status := oms_addSubModel(cref, fmuPath);

### addSystem

Adds a (sub-)system to a model or system.

    status := oms_addSystem(cref, type);

    The second argument type, should be any of the following,

    "OpenModelica.Scripting.oms_system.oms_system_none"
    "OpenModelica.Scripting.oms_system.oms_system_wc"
    "OpenModelica.Scripting.oms_system.oms_system_sc"

### compareSimulationResults

This function compares a given signal of two result files within absolute and relative tolerances.

    status := oms_compareSimulationResults(filenameA, filenameB, var, relTol, absTol);

The following table describes the input values:

Input | Type | Description
--- | --- | ---
filenameA | String | Name of first result file to compare.
filenameB | String | Name of second result file to compare.
var | String | Name of signal to compare.
relTol | Number | Relative tolerance.
absTol | Number | Absolute tolerance.

The following table describes the return values:

Type | Description
--- | ---
Integer | 1 if the signal is considered as equal, 0 otherwise

### copySystem

Copies a system.

    status := oms_copySystem(source, target);

### delete

Deletes a connector, component, system, or model object.

    status := oms_delete(cref);

### deleteConnection

Deletes the connection between connectors crefA and crefB.

    status := oms_deleteConnection(crefA, crefB);

The two arguments crefA and crefB get swapped automatically if necessary.

### deleteConnectorFromBus

Deletes a connector from a given bus.

    status := oms_deleteConnectorFromBus(busCref, connectorCref);

### export

Exports a composite model to a SPP file.

    status := oms_export(cref, filename);

### exportDependencyGraphs

Export the dependency graphs of a given model to dot files.

    status := oms_exportDependencyGraphs(cref, initialization, event, simulation);

### exportSnapshot

Lists the SSD representation of a given model, system, or component.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    (contents, status) := oms_exportSnapshot(cref);

### freeMemory

Free the memory allocated by some other API. Pass the object for which memory is allocated.

This function is not needed for OpenModelicaScripting Interface

### getBoolean

Get boolean value of given signal.

    (value, status) := oms_getBoolean(cref);

### getFixedStepSize

Gets the fixed step size. Can be used for the communication step size of co-simulation systems and also for the integrator step size in model exchange systems.

    (stepSize, status) := oms_setFixedStepSize(cref);

### getInteger

Get integer value of given signal.

    (value, status) := oms_getInteger(cref);

### getModelState

Gets the model state of the given model cref.

    (modelState, status) := oms_getModelState(cref);

### getReal

Get real value.

    (value, status) := oms_getReal(cref);

### getSolver

Gets the selected solver method of the given system.

    (solver, status) := oms_getSolver(cref);

### getStartTime

Get the start time from the model.

    (startTime, status) := oms_getStartTime(cref);

### getStopTime

Get the stop time from the model.

    (stopTime, status) := oms_getStopTime(cref);

### getSubModelPath

Returns the path of a given component.

    (path, status) := oms_getSubModelPath(cref);

### getSystemType

Gets the type of the given system.

    (type, status) := oms_getSystemType(cref);

### getTime

Get the current simulation time from the model.

    (time, status) := oms_getTime(cref);

### getTolerance

Gets the tolerance of a given system or component.

    (relativeTolerance, status) := oms_getTolerance(cref);

### getVariableStepSize

Gets the step size parameters.

    (initialStepSize, minimumStepSize, maximumStepSize, status) := oms_getVariableStepSize(cref);

### getVersion

Returns the library's version string.

    version := oms_getVersion();

### importFile

Imports a composite model from a SSP file.

    (cref, status) := oms_importFile(filename);

### importSnapshot

Loads a snapshot to restore a previous model state. The model must be in virgin model state, which means it must not be instantiated.

    status := oms_importSnapshot(cref, snapshot);

### initialize

Initializes a composite model.

    status := oms_initialize(cref);

### instantiate

Instantiates a given composite model.

    status := oms_instantiate(cref);

### list

Lists the SSD representation of a given model, system, or component.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    (contents, status) := oms_list(cref);

### listUnconnectedConnectors

Lists all unconnected connectors of a given system.

Memory is allocated for contents. The caller is responsible to free it using the C-API. The Lua and Python bindings take care of the memory and the caller doesn't need to call free.

    (contents, status) := oms_listUnconnectedConnectors(cref);

### loadSnapshot

Loads a snapshot to restore a previous model state. The model must be in virgin model state, which means it must not be instantiated.

    status := oms_loadSnapshot(cref, snapshot);

### newModel

Creates a new and yet empty composite model.

    status := oms_newModel(cref);

### removeSignalsFromResults

Removes all variables that match the given regex to the result file.

    status := oms_removeSignalsFromResults(cref, regex);

The second argument, i.e. regex, is considered as a regular expression (C++11). ".*" and "(.)*" can be used to hit all variables.

### rename

Renames a model, system, or component.

    status := oms_rename(cref, newCref);

### reset

Reset the composite model after a simulation run.

The FMUs go into the same state as after instantiation.

    status := oms_reset(cref);

### setBoolean

Sets the value of a given boolean signal.

    status := oms_setBoolean(cref, value);

### setCommandLineOption

Sets special flags.

    status := oms_setCommandLineOption(cmd);

Available flags:

    info:    Usage: OMSimulator [Options] [Lua script] [FMU] [SSP file]
             Options:
               --addParametersToCSV=<bool>      false              Export parameters to a .csv file
               --algLoopSolver=<arg>            "kinsol"           Specifies the loop solver method (fixedpoint, kinsol) used for algebraic loops spanning multiple components.
               --clearAllOptions                                   Reset all flags to their default values
               --CVODEMaxErrTestFails=<int>     100                Maximum number of error test failures for CVODE
               --CVODEMaxNLSFailures=<int>      100                Maximum number of nonlinear convergence failures for CVODE
               --CVODEMaxNLSIterations=<int>    5                  Maximum number of nonlinear solver iterations for CVODE
               --CVODEMaxSteps=<int>            1000               Maximum number of steps for CVODE
               --deleteTempFiles=<bool>         true               Delete temporary files as soon as they are no longer needed
               --directionalDerivatives=<bool>  true               Use directional derivatives to calculate the Jacobian for algebraic loops
               --dumpAlgLoops=<bool>            false              Dump information for algebraic loops
               --emitEvents=<bool>              true               Emit events during simulation
               --help [-h]                                         Display the help text
               --ignoreInitialUnknowns=<bool>   false              Ignore initial unknowns from the modelDescription.xml
               --initialStepSize=<double>       1e-6               Specify the initial step size
               --inputExtrapolation=<bool>      false              Enable input extrapolation using derivative information
               --intervals=<int> [-i]           500                Specify the number of communication points (arg > 1)
               --logFile=<arg> [-l]             ""                 Specify the log file (stdout is used if no log file is specified)
               --logLevel=<int>                 0                  Set the log level (0: default, 1: debug, 2: debug+trace)
               --master=<arg>                   "ma"               Specify the master algorithm (ma)
               --maxEventIteration=<int>        100                Specify the maximum number of iterations for handling a single event
               --maxLoopIteration=<int>         10                 Specify the maximum number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
               --minimumStepSize=<double>       1e-12              Specify the minimum step size
               --mode=<arg> [-m]                "me"               Force a certain FMI mode if the FMU provides both cs and me (cs, me)
               --numProcs=<int> [-n]            1                  Specify the maximum number of processors to use (0=auto, 1=default)
               --progressBar=<bool>             false              Show a progress bar for the simulation progress in the terminal
               --realTime=<bool>                false              Enable experimental feature for (soft) real-time co-simulation
               --resultFile=<arg> [-r]          "<default>"        Specify the name of the output result file
               --skipCSVHeader=<bool>           true               Skip exporting the CSV delimiter in the header
               --solver=<arg>                   "cvode"            Specify the integration method (euler, cvode)
               --solverStats=<bool>             false              Add solver stats to the result file, e.g., step size; not supported for all solvers
               --startTime=<double> [-s]        0                  Specify the start time
               --stepSize=<double>              1e-3               Specify the (maximum) step size
               --stopTime=<double> [-t]         1                  Specify the stop time
               --stripRoot=<bool>               false              Remove the root system prefix from all exported signals
               --suppressPath=<bool>            false              Suppress path information in info messages; especially useful for testing
               --tempDir=<arg>                  "."                Specify the temporary directory
               --timeout=<int>                  0                  Specify the maximum allowed time in seconds for running a simulation (0 disables)
               --tolerance=<double>             1e-4               Specify the relative tolerance
               --version [-v]                                      Display version information
               --wallTime=<bool>                false              Add wall time information to the result file
               --workingDir=<arg>               "."                Specify the working directory
               --zeroNominal=<bool>             false              Accept FMUs with invalid nominal values and replace the invalid nominal values with 1.0

### setFixedStepSize

Sets the fixed step size. Can be used for the communication step size of co-simulation systems and also for the integrator step size in model exchange systems.

    status := oms_setFixedStepSize(cref, stepSize);

### setInteger

Sets the value of a given integer signal.

    status := oms_setInteger(cref, value);

### setLogFile

Redirects logging output to file or std streams. The warning/error counters are reset.

filename="" to redirect to std streams and proper filename to redirect to file.

    status := oms_setLogFile(filename);

### setLoggingInterval

Set the logging interval of the simulation.

    status := oms_setLoggingInterval(cref, loggingInterval);

### setLoggingLevel

Enables/Disables debug logging (logDebug and logTrace).

0 default, 1 default+debug, 2 default+debug+trace

    oms_setLoggingLevel(logLevel);

### setReal

Sets the value of a given real signal.

    status := oms_setReal(cref, value);

This function can be called in different model states:

- Before instantiation: setReal can be used to set start values or to define initial unknowns (e.g. parameters, states). The values are not immediately applied to the simulation unit, since it isn't actually instantiated.

- After instantiation and before initialization: Same as before instantiation, but the values are applied immediately to the simulation unit.

- After initialization: Can be used to force external inputs, which might cause discrete changes of continuous signals.

### setRealInputDerivative

Sets the first order derivative of a real input signal.

This can only be used for CS-FMU real input signals.

    status := oms_setRealInputDerivative(cref, value);

### setResultFile

Set the result file of the simulation.

    status := oms_setResultFile(cref, filename);
    status := oms_setResultFile(cref, filename, bufferSize);

The creation of a result file is omitted if the filename is an empty string.

### setSolver

Sets the solver method for the given system.

    status := oms_setSolver(cref, solver);

    The second argument "solver" should be any of the following,

    "OpenModelica.Scripting.oms_solver.oms_solver_none"
    "OpenModelica.Scripting.oms_solver.oms_solver_sc_min"
    "OpenModelica.Scripting.oms_solver.oms_solver_sc_explicit_euler"
    "OpenModelica.Scripting.oms_solver.oms_solver_sc_cvode"
    "OpenModelica.Scripting.oms_solver.oms_solver_sc_max"
    "OpenModelica.Scripting.oms_solver.oms_solver_wc_min"
    "OpenModelica.Scripting.oms_solver.oms_solver_wc_ma"
    "OpenModelica.Scripting.oms_solver.oms_solver_wc_mav"
    "OpenModelica.Scripting.oms_solver.oms_solver_wc_mav2"
    "OpenModelica.Scripting.oms_solver.oms_solver_wc_max"

### setStartTime

Set the start time of the simulation.

    status := oms_setStartTime(cref, startTime);

### setStopTime

Set the stop time of the simulation.

    status := oms_setStopTime(cref, stopTime);

### setTempDirectory

Set new temp directory.

    status := oms_setTempDirectory(newTempDir);

### setTolerance

Sets the tolerance for a given model or system.

    status := oms_setTolerance(const char* cref, double relativeTolerance);

Default values are 1e-4 for both relative and absolute tolerances.

A tolerance specified for a model is automatically applied to its root system, i.e. both calls do exactly the same:

    oms_setTolerance("model", relativeTolerance);
    oms_setTolerance("model.root", relativeTolerance);

Component, e.g. FMUs, pick up the tolerances from there system. That means it is not possible to define different tolerances for FMUs in the same system right now.

In a strongly coupled system (oms_system_sc), the relative tolerance is used for CVODE and the absolute tolerance is used to solve algebraic loops.

In a weakly coupled system (oms_system_wc), both the relative and absolute tolerances are used for the adaptive step master algorithms and the absolute tolerance is used to solve algebraic loops.

### setVariableStepSize

Sets the step size parameters for methods with stepsize control.

    status := oms_getVariableStepSize(cref, initialStepSize, minimumStepSize, maximumStepSize);

### setWorkingDirectory

Set a new working directory.

    status := oms_setWorkingDirectory(newWorkingDir);

### simulate

Simulates a composite model.

    status := oms_simulate(cref);

### stepUntil

Simulates a composite model until a given time value.

    status := oms_stepUntil(cref, stopTime);

### terminate

Terminates a given composite model.

    status := oms_terminate(cref);

## Graphical Modelling

OMSimulator provides a graphical modelling environment through OMEdit, the OpenModelica Connection Editor. This feature requires a full OpenModelica installation that includes OMSimulator.

Composite models are imported and exported in the System Structure Description (SSD) format, which is part of the System Structure and Parameterization (SSP) standard.

See also FMI documentation and SSP documentation.

### Architecture

OMEdit communicates with OMSimulator through a Python-based ZMQ server:

- OMSimulatorGuiServer.py — handles all GUI-driven requests (model management, element queries, solver settings, connections, etc.)

- OMSimulatorSimulationServer.py — handles simulation execution and result streaming

The GUI server is started automatically when the first SSP model is opened or created. A notification in the Messages Browser confirms the server is running, including the script path and ZMQ endpoint.

### New SSP Model

A new and empty SSP model can be created from `File -> New -> SSP` menu item.

Figure 44 OMEdit: New SSP Model

A dialog opens to enter the model name and the name of the root system.

Figure 45 OMEdit: New SSP Model Dialog

Figure 46 OMEdit: Newly created empty root system of SSP model

### Open SSP Model

An existing SSP file (`.ssp`) can be opened from `File -> Open Model/Library`. If a model with the same name is already loaded, an error is reported and the file is not loaded again.

### Add System and Sub-Systems

A root system is always created together with the model. Additional subsystems can be added inside the root system via `SSP -> Add System`.

Figure 47 OMEdit: Add System

A dialog opens to enter the name of the new system.

Figure 48 OMEdit: Add System Dialog

### Add SubModel

A sub-model is typically an FMU, but it can also be a result file (CSV). To add a sub-model, select the target system in the Libraries Browser and choose `SSP -> Add SubModel`.

Figure 49 OMEdit: Add SubModel

A file browser opens to select an FMU (`.fmu`) or result file (`.csv`). A dialog then opens to set the name for the new sub-model.

Figure 50 OMEdit: Add SubModel Dialog

Figure 51 OMEdit: Root system with added FMU.

### Replace SubModel

An existing sub-model can be replaced with a different FMU by right-clicking on the component in the diagram view and selecting `Replace SubModel` from the context menu.

Figure 52 OMEdit: Replace SubModel Dialog.

A file browser opens to select the new FMU. The replacement is performed in two steps:

1. Dry run (`dryRun=true`) — OMEdit first performs a dry run without making any changes to the model. It checks for interface differences between the old and new FMU, such as added, removed, or modified connectors and parameters. If any changes are detected, they are reported in the Messages Browser and a warning dialog is shown. The model remains unchanged at this stage, allowing the user to review the impact before deciding to proceed.

2. Replacement (`dryRun=false`) — If the user confirms, the replacement is carried out and all detected interface changes are applied to the model. Existing connections to removed or renamed connectors are dropped, and new connectors are available for connecting.

Figure 53 OMEdit: Replace SubModel context menu.

### Simulation Setup

Select `Simulation -> Simulation Setup` to configure simulation parameters before running. The dialog has two tabs: General and Solver Settings.

The General tab covers start time, stop time, and result file settings.

Figure 54 OMEdit: Simulation Setup — Solver Settings tab with a solver configuration.

The Solver Settings tab is divided into two parts:

Solver Configurations

This table lists the named solver configurations available in the model. Each configuration has a name and a method. Click Add to create a new solver configuration — a new row appears in the table with a default method of `oms-ma`. The method can be changed using the combo box in the Method column.

Figure 55 OMEdit: Simulation Setup — Solver Settings tab with a solver configuration.

To fine-tune a solver's numerical parameters, select the row and click Edit. This opens the Solver Settings dialog:

Figure 56 OMEdit: Solver Settings dialog.

The available fields depend on the solver method:

- Fixed-step solvers (`oms-ma`, `euler`) — Fixed Step Size is editable; Initial Step Size, Minimum Step Size, and Maximum Step Size are disabled.

- Variable-step solvers (`oms-mav`, `oms-mav-2`, `cvode`) — Initial Step Size, Minimum Step Size, Maximum Step Size, and Relative Tolerance are editable; Fixed Step Size is disabled.

Click Remove to delete the selected solver configuration.

Component Assignments

This table lists all FMU components in the model. Each component can be assigned one of the named solver configurations using the combo box in the Solver column. The available solvers are filtered by the FMI kind of each component:

- Co-Simulation FMUs — only co-simulation masters are selectable (`oms-ma`, `oms-mav`, `oms-mav-2`).

- Model-Exchange FMUs — only ODE integrators are selectable (`cvode`, `euler`).

- me+cs FMUs — all solvers are available.

Figure 57 OMEdit: Solver Assignments in Components

Incompatible solvers are shown as disabled in the combo box with a tooltip explaining why. If no solver is assigned, `(none)` is used and the system default applies.

### Simulate

Select the simulate button (green arrow) or `Simulation -> Simulate` to run the SSP model. Results are streamed back in real time via the simulation server.

### Dual Mass Oscillator Example

The dual mass oscillator example from the test suite demonstrates a typical SSP workflow. The model is split into two sub-models, each exported as an FMU, and then connected in an SSP.

Figure 58 Dual mass oscillator Modelica model (diagram view) and FMUs

Figure 59 OMEdit: Simulate Dual Mass Oscillator SSP model

## SSP Support

Composite models are imported and exported in the System Structure Description (SSD) format, which is part of the System Structure and Parameterization (SSP) standard.

### Bus Connections

Bus connections are saved as annotations to the SSD file. Bus connectors are only allowed in weakly coupled and strongly coupled systems. Bus connections can exist in any system type. Bus connectors are used to hide SSD connectors and bus connections are used to hide existing SSD connections in the graphical user interface. It is not required that all connectors referenced in a bus are connected. One bus may be connected to multiple other buses, and also to SSD connectors.

The example below contains a root system with two subsystems, `WC1` and `WC2`. Bus connector `WC1.bus1` is connected to `WC2.bus2`. Bus connector `WC2.bus2` is also connected to SSD connector `WC1.C3`.

    <?xml version="1.0" encoding="UTF-8"?>
    <ssd:SystemStructureDescription name="Test" version="Draft20180219">
      <ssd:System name="Root">
        <ssd:Elements>
          <ssd:System name="WC2">
            <ssd:Connectors>
              <ssd:Connector name="C1" kind="input" type="Real"/>
              <ssd:Connector name="C2" kind="output" type="Real"/>
            </ssd:Connectors>
            <ssd:Annotations>
              <ssc:Annotation type="org.openmodelica">
                <oms:Bus name="bus2">
                  <oms:Signals>
                    <oms:Signal name="C1"/>
                    <oms:Signal name="C2"/>
                  </oms:Signals>
                </oms:Bus>
              </ssc:Annotation>
            </ssd:Annotations>
          </ssd:System>
          <ssd:System name="WC1">
            <ssd:Connectors>
              <ssd:Connector name="C1" kind="output" type="Real"/>
              <ssd:Connector name="C2" kind="input" type="Real"/>
              <ssd:Connector name="C3" kind="input" type="Real"/>
            </ssd:Connectors>
            <ssd:Annotations>
              <ssc:Annotation type="org.openmodelica">
                <oms:Bus name="bus1">
                  <oms:Signals>
                    <oms:Signal name="C1"/>
                    <oms:Signal name="C2"/>
                  </oms:Signals>
                </oms:Bus>
              </ssc:Annotation>
            </ssd:Annotations>
          </ssd:System>
        </ssd:Elements>
        <ssd:Connections>
          <ssd:Connection startElement="WC2" startConnector="C1"
                          endElement="WC1" endConnector="C1"/>
          <ssd:Connection startElement="WC2" startConnector="C2"
                          endElement="WC1" endConnector="C2"/>
          <ssd:Connection startElement="WC2" startConnector="C2"
                          endElement="WC1" endConnector="C3"/>
        </ssd:Connections>
        <ssd:Annotations>
          <ssc:Annotation type="org.openmodelica">
            <oms:Connections>
              <oms:Connection startElement="WC1" startConnector="bus1"
                              endElement="WC2" endConnector="bus2"/>
              <oms:Connection startElement="WC2" startConnector="bus2"
                              endElement="WC1" endConnector="C3"/>
            </oms:Connections>
          </ssc:Annotation>
        </ssd:Annotations>
      </ssd:System>
    </ssd:SystemStructureDescription>