OMSimulator¶

Version: v2.1.2

Introduction¶

The OMSimulator project is a FMI-based co-simulation tool that supports ordinary (i.e., non-delayed) and TLM connections. 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 (preliminary) SSP (System Structure and Parameterization) standard. Efficient FMI based simulation is provided for both model-exchange and co-simulation. TLM-based tool connection is provided for a range of applications, e.g., Adams, Simulink, Beast, Dymola, and OpenModelica. Moreover, optional TLM (Transmission Line Modelling) domain-specific connectors are also supported, providing additional numerical stability to 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=<arg>      Export parameters to .csv file (true, [false])
           --algLoopSolver=<arg>           Specifies the alg. loop solver method (fixedpoint, [kinsol]) used for algebraic loops spanning over multiple components.
           --clearAllOptions               Reset all flags to default values
           --CVODEMaxErrTestFails=<int>    Maximum number of error test failures for CVODE
           --CVODEMaxNLSFailures=<int>     Maximum number of nonlinear convergence failures for CVODE
           --CVODEMaxNLSIterations=<int>   Maximum number of nonlinear solver iterations for CVODE
           --CVODEMaxSteps=<int>           Maximum number of steps for CVODE
           --deleteTempFiles=<bool>        Deletes temp files as soon as they are no longer needed ([true], false)
           --directionalDerivatives=<bool>  Specifies whether directional derivatives should be used to calculate the Jacobian for alg. loops or if a numerical approximation should be used instead ([true], false)
           --dumpAlgLoops=<bool>           Dump information for alg loops (true, [false])
           --emitEvents=<bool>             Specifies whether events should be emitted or not ([true], false)
           --fetchAllVars=<arg>            Workaround for certain FMUs that do not update all internal dependencies automatically
           --help [-h]                     Displays the help text
           --ignoreInitialUnknowns=<bool>  Ignore the initial unknowns from the modelDescription.xml (true, [false])
           --inputExtrapolation=<bool>     Enables input extrapolation using derivative information (true, [false])
           --intervals=<int> [-i]          Specifies the number of communication points (arg > 1)
           --logFile=<arg> [-l]            Specifies the logfile (stdout is used if no log file is specified)
           --logLevel=<int>                0 default, 1 debug, 2 debug+trace
           --maxEventIteration=<int>       Specifies the max. number of iterations for handling a single event
           --maxLoopIteration=<int>        Specifies the max. number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
           --mode=<arg> [-m]               Forces a certain FMI mode iff the FMU provides cs and me (cs, [me])
           --numProcs=<int> [-n]           Specifies the max. number of processors to use (0=auto, 1=default)
           --progressBar=<bool>            Shows a progress bar for the simulation progress in the terminal (true, [false])
           --realTime=<bool>               Experimental feature for (soft) real-time co-simulation (true, [false])
           --resultFile=<arg> [-r]         Specifies the name of the output result file
           --skipCSVHeader=<arg>           Skip exporting the scv delimiter in the header ([true], false), 
           --solver=<arg>                  Specifies the integration method (euler, [cvode])
           --solverStats=<bool>            Adds solver stats to the result file, e.g. step size; not supported for all solvers (true, [false])
           --startTime=<double> [-s]       Specifies the start time
           --stepSize=<arg>                Specifies the step size (<step size> or <init step,min step,max step>)
           --stopTime=<double> [-t]        Specifies the stop time
           --stripRoot=<bool>              Removes the root system prefix from all exported signals (true, [false])
           --suppressPath=<bool>           Supresses path information in info messages; especially useful for testing ([true], false)
           --tempDir=<arg>                 Specifies the temp directory
           --timeout=<int>                 Specifies the maximum allowed time in seconds for running a simulation (0 disables)
           --tolerance=<double>            Specifies the relative tolerance
           --version [-v]                  Displays version information
           --wallTime=<bool>               Add wall time information for to the result file (true, [false])
           --workingDir=<arg>              Specifies the working directory
           --zeroNominal=<bool>            Using this flag, FMUs with invalid nominal values will be accepted and the invalid nominal values will be replaced 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);

addConnectorToTLMBus¶

Adds a connector to a TLM bus.

oms_status_enu_t oms_addConnectorToTLMBus(const char* busCref, const char* connectorCref, const char *type);

addExternalModel¶

Adds an external model to a TLM system.

oms_status_enu_t oms_addExternalModel(const char* cref, const char* path, const char* startscript);

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

addTLMBus¶

Adds a TLM bus.

oms_status_enu_t oms_addTLMBus(const char* cref, oms_tlm_domain_t domain, const int dimensions, const oms_tlm_interpolation_t interpolation);

addTLMConnection¶

Connects two TLM connectors.

oms_status_enu_t oms_addTLMConnection(const char* crefA, const char* crefB, double delay, double alpha, double linearimpedance, double angularimpedance);

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

deleteConnectorFromTLMBus¶

Deletes a connector from a given TLM bus.

oms_status_enu_t oms_deleteConnectorFromTLMBus(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.

deleting only the reference file in ".ssd".
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);

extractFMIKind¶

Extracts the FMI kind of a given FMU from the file system.

oms_status_enu_t oms_extractFMIKind(const char* filename, oms_fmi_kind_enu_t* kind);

faultInjection¶

Defines a new fault injection block.

oms_status_enu_t oms_faultInjection(const char* signal, oms_fault_type_enu_t faultType, double faultValue);

type	Description"
oms_fault_type_bias	y = y.$original + faultValue
oms_fault_type_gain	y = y.$original * faultValue
oms_fault_type_const	y = faultValue

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

getTLMBus¶

Gets the TLM bus objects of the given TLM bus cref.

oms_status_enu_t oms_getTLMBus(const char* cref, oms_tlmbusconnector_t** tlmBusConnector);

getTLMVariableTypes¶

Gets the type of an TLM variable.

oms_status_enu_t oms_getTLMVariableTypes(oms_tlm_domain_t domain, const int dimensions, const oms_tlm_interpolation_t interpolation, char ***types, char ***descriptions);

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* absoluteTolerance, 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.

Referencing only the ".ssv" file.
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=<arg>      Export parameters to .csv file (true, [false])
           --algLoopSolver=<arg>           Specifies the alg. loop solver method (fixedpoint, [kinsol]) used for algebraic loops spanning over multiple components.
           --clearAllOptions               Reset all flags to default values
           --CVODEMaxErrTestFails=<int>    Maximum number of error test failures for CVODE
           --CVODEMaxNLSFailures=<int>     Maximum number of nonlinear convergence failures for CVODE
           --CVODEMaxNLSIterations=<int>   Maximum number of nonlinear solver iterations for CVODE
           --CVODEMaxSteps=<int>           Maximum number of steps for CVODE
           --deleteTempFiles=<bool>        Deletes temp files as soon as they are no longer needed ([true], false)
           --directionalDerivatives=<bool>  Specifies whether directional derivatives should be used to calculate the Jacobian for alg. loops or if a numerical approximation should be used instead ([true], false)
           --dumpAlgLoops=<bool>           Dump information for alg loops (true, [false])
           --emitEvents=<bool>             Specifies whether events should be emitted or not ([true], false)
           --fetchAllVars=<arg>            Workaround for certain FMUs that do not update all internal dependencies automatically
           --help [-h]                     Displays the help text
           --ignoreInitialUnknowns=<bool>  Ignore the initial unknowns from the modelDescription.xml (true, [false])
           --inputExtrapolation=<bool>     Enables input extrapolation using derivative information (true, [false])
           --intervals=<int> [-i]          Specifies the number of communication points (arg > 1)
           --logFile=<arg> [-l]            Specifies the logfile (stdout is used if no log file is specified)
           --logLevel=<int>                0 default, 1 debug, 2 debug+trace
           --maxEventIteration=<int>       Specifies the max. number of iterations for handling a single event
           --maxLoopIteration=<int>        Specifies the max. number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
           --mode=<arg> [-m]               Forces a certain FMI mode iff the FMU provides cs and me (cs, [me])
           --numProcs=<int> [-n]           Specifies the max. number of processors to use (0=auto, 1=default)
           --progressBar=<bool>            Shows a progress bar for the simulation progress in the terminal (true, [false])
           --realTime=<bool>               Experimental feature for (soft) real-time co-simulation (true, [false])
           --resultFile=<arg> [-r]         Specifies the name of the output result file
           --skipCSVHeader=<arg>           Skip exporting the scv delimiter in the header ([true], false), 
           --solver=<arg>                  Specifies the integration method (euler, [cvode])
           --solverStats=<bool>            Adds solver stats to the result file, e.g. step size; not supported for all solvers (true, [false])
           --startTime=<double> [-s]       Specifies the start time
           --stepSize=<arg>                Specifies the step size (<step size> or <init step,min step,max step>)
           --stopTime=<double> [-t]        Specifies the stop time
           --stripRoot=<bool>              Removes the root system prefix from all exported signals (true, [false])
           --suppressPath=<bool>           Supresses path information in info messages; especially useful for testing ([true], false)
           --tempDir=<arg>                 Specifies the temp directory
           --timeout=<int>                 Specifies the maximum allowed time in seconds for running a simulation (0 disables)
           --tolerance=<double>            Specifies the relative tolerance
           --version [-v]                  Displays version information
           --wallTime=<bool>               Add wall time information for to the result file (true, [false])
           --workingDir=<arg>              Specifies the working directory
           --zeroNominal=<bool>            Using this flag, FMUs with invalid nominal values will be accepted and the invalid nominal values will be replaced 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);

setTLMBusGeometry¶

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

setTLMConnectionParameters¶

Simulates a composite model in its own thread.

oms_status_enu_t oms_setTLMConnectionParameters(const char* crefA, const char* crefB, const oms_tlm_connection_parameters_t* parameters);

setTLMPositionAndOrientation¶

Sets initial position and orientation for a TLM 3D interface.

oms_status_enu_t oms_setTLMPositionAndOrientation(cref, x1, x2, x3, A11, A12, A13, A21, A22, A23, A31, A32, A33);

setTLMSocketData¶

Sets data for TLM socket communication.

oms_status_enu_t oms_setTLMSocketData(const char* cref, const char* address, int managerPort, int monitorPort);

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 absoluteTolerance, 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", absoluteTolerance, relativeTolerance);
oms_setTolerance("model.root", absoluteTolerance, 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)

addConnectorToTLMBus¶

Adds a connector to a TLM bus.

status = oms_addConnectorToTLMBus(busCref, connectorCref, type)

addExternalModel¶

Adds an external model to a TLM system.

status = oms_addExternalModel(cref, path, startscript)

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)

addTLMBus¶

Adds a TLM bus.

status = oms_addTLMBus(cref, domain, dimensions, interpolation)

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

oms_tlm_domain_input
oms_tlm_domain_output
oms_tlm_domain_mechanical
oms_tlm_domain_rotational
oms_tlm_domain_hydraulic
oms_tlm_domain_electric

The fourth argument "interpolation", should be any of the following,

oms_tlm_no_interpolation
oms_tlm_coarse_grained
oms_tlm_fine_grained

addTLMConnection¶

Connects two TLM connectors.

status = oms_addTLMConnection(crefA, crefB, delay, alpha, linearimpedance, angularimpedance)

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)

deleteConnectorFromTLMBus¶

Deletes a connector from a given TLM bus.

status = oms_deleteConnectorFromTLMBus(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.

deleting only the reference file in ".ssd".
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)

faultInjection¶

Defines a new fault injection block.

status = oms_faultInjection(cref, type, value)

type	Description"
oms_fault_type_bias	y = y.$original + faultValue
oms_fault_type_gain	y = y.$original * faultValue
oms_fault_type_const	y = faultValue

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.

absoluteTolerance, 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.

Referencing only the ".ssv" file.
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=<arg>      Export parameters to .csv file (true, [false])
           --algLoopSolver=<arg>           Specifies the alg. loop solver method (fixedpoint, [kinsol]) used for algebraic loops spanning over multiple components.
           --clearAllOptions               Reset all flags to default values
           --CVODEMaxErrTestFails=<int>    Maximum number of error test failures for CVODE
           --CVODEMaxNLSFailures=<int>     Maximum number of nonlinear convergence failures for CVODE
           --CVODEMaxNLSIterations=<int>   Maximum number of nonlinear solver iterations for CVODE
           --CVODEMaxSteps=<int>           Maximum number of steps for CVODE
           --deleteTempFiles=<bool>        Deletes temp files as soon as they are no longer needed ([true], false)
           --directionalDerivatives=<bool>  Specifies whether directional derivatives should be used to calculate the Jacobian for alg. loops or if a numerical approximation should be used instead ([true], false)
           --dumpAlgLoops=<bool>           Dump information for alg loops (true, [false])
           --emitEvents=<bool>             Specifies whether events should be emitted or not ([true], false)
           --fetchAllVars=<arg>            Workaround for certain FMUs that do not update all internal dependencies automatically
           --help [-h]                     Displays the help text
           --ignoreInitialUnknowns=<bool>  Ignore the initial unknowns from the modelDescription.xml (true, [false])
           --inputExtrapolation=<bool>     Enables input extrapolation using derivative information (true, [false])
           --intervals=<int> [-i]          Specifies the number of communication points (arg > 1)
           --logFile=<arg> [-l]            Specifies the logfile (stdout is used if no log file is specified)
           --logLevel=<int>                0 default, 1 debug, 2 debug+trace
           --maxEventIteration=<int>       Specifies the max. number of iterations for handling a single event
           --maxLoopIteration=<int>        Specifies the max. number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
           --mode=<arg> [-m]               Forces a certain FMI mode iff the FMU provides cs and me (cs, [me])
           --numProcs=<int> [-n]           Specifies the max. number of processors to use (0=auto, 1=default)
           --progressBar=<bool>            Shows a progress bar for the simulation progress in the terminal (true, [false])
           --realTime=<bool>               Experimental feature for (soft) real-time co-simulation (true, [false])
           --resultFile=<arg> [-r]         Specifies the name of the output result file
           --skipCSVHeader=<arg>           Skip exporting the scv delimiter in the header ([true], false), 
           --solver=<arg>                  Specifies the integration method (euler, [cvode])
           --solverStats=<bool>            Adds solver stats to the result file, e.g. step size; not supported for all solvers (true, [false])
           --startTime=<double> [-s]       Specifies the start time
           --stepSize=<arg>                Specifies the step size (<step size> or <init step,min step,max step>)
           --stopTime=<double> [-t]        Specifies the stop time
           --stripRoot=<bool>              Removes the root system prefix from all exported signals (true, [false])
           --suppressPath=<bool>           Supresses path information in info messages; especially useful for testing ([true], false)
           --tempDir=<arg>                 Specifies the temp directory
           --timeout=<int>                 Specifies the maximum allowed time in seconds for running a simulation (0 disables)
           --tolerance=<double>            Specifies the relative tolerance
           --version [-v]                  Displays version information
           --wallTime=<bool>               Add wall time information for to the result file (true, [false])
           --workingDir=<arg>              Specifies the working directory
           --zeroNominal=<bool>            Using this flag, FMUs with invalid nominal values will be accepted and the invalid nominal values will be replaced 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)

setTLMPositionAndOrientation¶

Sets initial position and orientation for a TLM 3D interface.

status = oms_setTLMPositionAndOrientation(cref, x1, x2, x3, A11, A12, A13, A21, A22, A23, A31, A32, A33)

setTLMSocketData¶

Sets data for TLM socket communication.

status = oms_setTLMSocketData(cref, address, managerPort, monitorPort)

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 tolerance)
status = oms_setTolerance(const char* cref, double absoluteTolerance, 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", absoluteTolerance, relativeTolerance);
oms_setTolerance("model.root", absoluteTolerance, 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)

addConnectorToTLMBus¶

Adds a connector to a TLM bus.

status = oms.addConnectorToTLMBus(busCref, connectorCref, type)

addExternalModel¶

Adds an external model to a TLM system.

status = oms.addExternalModel(cref, path, startscript)

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)

addTLMBus¶

Adds a TLM bus.

status = oms.addTLMBus(cref, domain, dimensions, interpolation)

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

oms.tlm_domain_input
oms.tlm_domain_output
oms.tlm_domain_mechanical
oms.tlm_domain_rotational
oms.tlm_domain_hydraulic
oms.tlm_domain_electric

The fourth argument "interpolation", should be any of the following,

oms.default
oms.coarsegrained
oms.finegrained

addTLMConnection¶

Connects two TLM connectors.

status = oms.addTLMConnection(crefA, crefB, delay, alpha, linearimpedance, angularimpedance)

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)

deleteConnectorFromTLMBus¶

Deletes a connector from a given TLM bus.

status = oms.deleteConnectorFromTLMBus(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.

deleting only the reference file in ".ssd".
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)

faultInjection¶

Defines a new fault injection block.

status = oms.faultInjection(cref, type, value)

type	Description"
oms_fault_type_bias	y = y.$original + faultValue
oms_fault_type_gain	y = y.$original * faultValue
oms_fault_type_const	y = faultValue

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.

absoluteTolerance, 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.

Referencing only the ".ssv" file.
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=<arg>      Export parameters to .csv file (true, [false])
           --algLoopSolver=<arg>           Specifies the alg. loop solver method (fixedpoint, [kinsol]) used for algebraic loops spanning over multiple components.
           --clearAllOptions               Reset all flags to default values
           --CVODEMaxErrTestFails=<int>    Maximum number of error test failures for CVODE
           --CVODEMaxNLSFailures=<int>     Maximum number of nonlinear convergence failures for CVODE
           --CVODEMaxNLSIterations=<int>   Maximum number of nonlinear solver iterations for CVODE
           --CVODEMaxSteps=<int>           Maximum number of steps for CVODE
           --deleteTempFiles=<bool>        Deletes temp files as soon as they are no longer needed ([true], false)
           --directionalDerivatives=<bool>  Specifies whether directional derivatives should be used to calculate the Jacobian for alg. loops or if a numerical approximation should be used instead ([true], false)
           --dumpAlgLoops=<bool>           Dump information for alg loops (true, [false])
           --emitEvents=<bool>             Specifies whether events should be emitted or not ([true], false)
           --fetchAllVars=<arg>            Workaround for certain FMUs that do not update all internal dependencies automatically
           --help [-h]                     Displays the help text
           --ignoreInitialUnknowns=<bool>  Ignore the initial unknowns from the modelDescription.xml (true, [false])
           --inputExtrapolation=<bool>     Enables input extrapolation using derivative information (true, [false])
           --intervals=<int> [-i]          Specifies the number of communication points (arg > 1)
           --logFile=<arg> [-l]            Specifies the logfile (stdout is used if no log file is specified)
           --logLevel=<int>                0 default, 1 debug, 2 debug+trace
           --maxEventIteration=<int>       Specifies the max. number of iterations for handling a single event
           --maxLoopIteration=<int>        Specifies the max. number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
           --mode=<arg> [-m]               Forces a certain FMI mode iff the FMU provides cs and me (cs, [me])
           --numProcs=<int> [-n]           Specifies the max. number of processors to use (0=auto, 1=default)
           --progressBar=<bool>            Shows a progress bar for the simulation progress in the terminal (true, [false])
           --realTime=<bool>               Experimental feature for (soft) real-time co-simulation (true, [false])
           --resultFile=<arg> [-r]         Specifies the name of the output result file
           --skipCSVHeader=<arg>           Skip exporting the scv delimiter in the header ([true], false), 
           --solver=<arg>                  Specifies the integration method (euler, [cvode])
           --solverStats=<bool>            Adds solver stats to the result file, e.g. step size; not supported for all solvers (true, [false])
           --startTime=<double> [-s]       Specifies the start time
           --stepSize=<arg>                Specifies the step size (<step size> or <init step,min step,max step>)
           --stopTime=<double> [-t]        Specifies the stop time
           --stripRoot=<bool>              Removes the root system prefix from all exported signals (true, [false])
           --suppressPath=<bool>           Supresses path information in info messages; especially useful for testing ([true], false)
           --tempDir=<arg>                 Specifies the temp directory
           --timeout=<int>                 Specifies the maximum allowed time in seconds for running a simulation (0 disables)
           --tolerance=<double>            Specifies the relative tolerance
           --version [-v]                  Displays version information
           --wallTime=<bool>               Add wall time information for to the result file (true, [false])
           --workingDir=<arg>              Specifies the working directory
           --zeroNominal=<bool>            Using this flag, FMUs with invalid nominal values will be accepted and the invalid nominal values will be replaced 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 tolerance)
status = oms.setTolerance(const char* cref, double absoluteTolerance, 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", absoluteTolerance, relativeTolerance);
oms_setTolerance("model.root", absoluteTolerance, 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.¶

import math
import matplotlib.pyplot as plt
import OMSimulator as oms

# redirect logging to file and limit the file size to 65MB
oms.setLogFile('pi.log', 65)

model = oms.newModel('pi')
root = model.addSystem('root', oms.Types.System.SC)
root.addSubModel('circle', 'Circle.fmu')

model.resultFile = '' # no result file
model.instantiate()

results = list()
inside = 0

MIN = 100
MAX = 1000000
for i in range(0, MAX+1):
  if i > 0:
    model.reset()
  model.setInteger('root.circle.globalSeed', i)
  model.initialize()
  if model.getBoolean("root.circle.inside"):
    inside = inside + 1
  if i >= MIN:
    results.append(4.0*inside/i)
model.terminate()
model.delete()

plt.plot([MIN, MAX], [math.pi, math.pi], 'r--', range(MIN, MAX+1), results)
plt.xscale('log')
plt.ylabel('Approximation of pi')
plt.savefig('pi.png')

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

_images/pi.png — Figure 59 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);

addConnectorToTLMBus¶

Adds a connector to a TLM bus.

status := oms_addConnectorToTLMBus(busCref, connectorCref, type);

addExternalModel¶

Adds an external model to a TLM system.

status := oms_addExternalModel(cref, path, startscript);

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_tlm"
"OpenModelica.Scripting.oms_system.oms_system_sc"
"OpenModelica.Scripting.oms_system.oms_system_wc"

addTLMBus¶

Adds a TLM bus.

status := oms_addTLMBus(cref, domain, dimensions, interpolation);

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

"OpenModelica.Scripting.oms_tlm_domain.oms_tlm_domain_input"
"OpenModelica.Scripting.oms_tlm_domain.oms_tlm_domain_output"
"OpenModelica.Scripting.oms_tlm_domain.oms_tlm_domain_mechanical"
"OpenModelica.Scripting.oms_tlm_domain.oms_tlm_domain_rotational"
"OpenModelica.Scripting.oms_tlm_domain.oms_tlm_domain_hydraulic"
"OpenModelica.Scripting.oms_tlm_domain.oms_tlm_domain_electric"

The fourth argument "interpolation", should be any of the following,

"OpenModelica.Scripting.oms_tlm_interpolation.oms_tlm_no_interpolation"
"OpenModelica.Scripting.oms_tlm_interpolation.oms_tlm_coarse_grained"
"OpenModelica.Scripting.oms_tlm_interpolation.oms_tlm_fine_grained"

addTLMConnection¶

Connects two TLM connectors.

status := oms_addTLMConnection(crefA, crefB, delay, alpha, linearimpedance, angularimpedance);

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

deleteConnectorFromTLMBus¶

Deletes a connector from a given TLM bus.

status := oms_deleteConnectorFromTLMBus(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);

extractFMIKind¶

Extracts the FMI kind of a given FMU from the file system.

(kind,status) := oms_extractFMIKind(filename);

faultInjection¶

Defines a new fault injection block.

status := oms_faultInjection(cref, type, value);
The second argument type, can be any of the following described below

"OpenModelica.Scripting.oms_fault_type.oms_fault_type_bias"
"OpenModelica.Scripting.oms_fault_type.oms_fault_type_gain"
"OpenModelica.Scripting.oms_fault_type.oms_fault_type_const"

type	Description"
oms_fault_type_bias	y = y.$original + faultValue
oms_fault_type_gain	y = y.$original * faultValue
oms_fault_type_const	y = faultValue

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.

(absoluteTolerance, 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=<arg>      Export parameters to .csv file (true, [false])
           --algLoopSolver=<arg>           Specifies the alg. loop solver method (fixedpoint, [kinsol]) used for algebraic loops spanning over multiple components.
           --clearAllOptions               Reset all flags to default values
           --CVODEMaxErrTestFails=<int>    Maximum number of error test failures for CVODE
           --CVODEMaxNLSFailures=<int>     Maximum number of nonlinear convergence failures for CVODE
           --CVODEMaxNLSIterations=<int>   Maximum number of nonlinear solver iterations for CVODE
           --CVODEMaxSteps=<int>           Maximum number of steps for CVODE
           --deleteTempFiles=<bool>        Deletes temp files as soon as they are no longer needed ([true], false)
           --directionalDerivatives=<bool>  Specifies whether directional derivatives should be used to calculate the Jacobian for alg. loops or if a numerical approximation should be used instead ([true], false)
           --dumpAlgLoops=<bool>           Dump information for alg loops (true, [false])
           --emitEvents=<bool>             Specifies whether events should be emitted or not ([true], false)
           --fetchAllVars=<arg>            Workaround for certain FMUs that do not update all internal dependencies automatically
           --help [-h]                     Displays the help text
           --ignoreInitialUnknowns=<bool>  Ignore the initial unknowns from the modelDescription.xml (true, [false])
           --inputExtrapolation=<bool>     Enables input extrapolation using derivative information (true, [false])
           --intervals=<int> [-i]          Specifies the number of communication points (arg > 1)
           --logFile=<arg> [-l]            Specifies the logfile (stdout is used if no log file is specified)
           --logLevel=<int>                0 default, 1 debug, 2 debug+trace
           --maxEventIteration=<int>       Specifies the max. number of iterations for handling a single event
           --maxLoopIteration=<int>        Specifies the max. number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
           --mode=<arg> [-m]               Forces a certain FMI mode iff the FMU provides cs and me (cs, [me])
           --numProcs=<int> [-n]           Specifies the max. number of processors to use (0=auto, 1=default)
           --progressBar=<bool>            Shows a progress bar for the simulation progress in the terminal (true, [false])
           --realTime=<bool>               Experimental feature for (soft) real-time co-simulation (true, [false])
           --resultFile=<arg> [-r]         Specifies the name of the output result file
           --skipCSVHeader=<arg>           Skip exporting the scv delimiter in the header ([true], false), 
           --solver=<arg>                  Specifies the integration method (euler, [cvode])
           --solverStats=<bool>            Adds solver stats to the result file, e.g. step size; not supported for all solvers (true, [false])
           --startTime=<double> [-s]       Specifies the start time
           --stepSize=<arg>                Specifies the step size (<step size> or <init step,min step,max step>)
           --stopTime=<double> [-t]        Specifies the stop time
           --stripRoot=<bool>              Removes the root system prefix from all exported signals (true, [false])
           --suppressPath=<bool>           Supresses path information in info messages; especially useful for testing ([true], false)
           --tempDir=<arg>                 Specifies the temp directory
           --timeout=<int>                 Specifies the maximum allowed time in seconds for running a simulation (0 disables)
           --tolerance=<double>            Specifies the relative tolerance
           --version [-v]                  Displays version information
           --wallTime=<bool>               Add wall time information for to the result file (true, [false])
           --workingDir=<arg>              Specifies the working directory
           --zeroNominal=<bool>            Using this flag, FMUs with invalid nominal values will be accepted and the invalid nominal values will be replaced 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_assc"
"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);

setTLMPositionAndOrientation¶

Sets initial position and orientation for a TLM 3D interface.

status := oms_setTLMPositionAndOrientation(cref, x1, x2, x3, A11, A12, A13, A21, A22, A23, A31, A32, A33);

setTLMSocketData¶

Sets data for TLM socket communication.

status := oms_setTLMSocketData(cref, address, managerPort, monitorPort);

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 tolerance);
status := oms_setTolerance(const char* cref, double absoluteTolerance, 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", absoluteTolerance, relativeTolerance);
oms_setTolerance("model.root", absoluteTolerance, 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 has an optional dependency to OpenModelica in order to utilize the graphical modelling editor OMEdit. This feature requires to install the full OpenModelica tool suite, which includes OMSimulator. The independent stand-alone version doesn't provide any graphical modelling editor.

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.

_images/omedit_01.png — Figure 60 OMEdit MainWindow and Browsers.¶

New SSP Model¶

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

_images/omedit_02.png — Figure 61 OMEdit: New SSP Model¶

That will open a dialog to enter the names of the model and the root system and to choose the root systems type.

There are three types available:

TLM - Transmission Line Modeling System
Weakly Coupled - Connected Co-Simulation FMUs System
Strongly Coupled - Connected Model-Exchange FMUs System

_images/omedit_03.png — Figure 62 OMEdit: New SSP Model Dialog¶

_images/omedit_04.png — Figure 63 OMEdit: Newly created empty root system of SSP model¶

Add System¶

When a new model is created a root system is always generated. If you need to have another system in your root system you can add it with SSP->Add System.

For example only a weakly coupled system (Co-Simulation) can integrate strongly coupled system (Model Exchange). Therefore, the weakly coupled system must be selected from the Libraries Browser and the respective menu item can be selected:

_images/omedit_05.png — Figure 64 OMEdit: Add System¶

That will pop-up a dialog to enter the names of the new system.

_images/omedit_06.png — Figure 65 OMEdit: Add System Dialog¶

Add SubModel¶

A sub-model is typically an FMU, but it also can be result file. In order to import a sub-model, the respective system must be selected and the action can be selected from the menu bar:

_images/omedit_07.png — Figure 66 OMEdit: Add SubModel¶

The file browser will open to select an FMU (.fmu) or result file (.csv) as a subsmodel. Then a dialog opens to choose the name of the new sub-model.

_images/omedit_08.png — Figure 67 OMEdit: Add SubModel Dialog¶

_images/omedit_09.png — Figure 68 OMEdit: Root system with added FMU.¶

Simulate¶

Select the simulate button (symbol with green arrow) or select Simulation->Simulate from the menu in OMEdit to simulate the SSP model.

Dual Mass Oscillator Example¶

The dual mass oscillator example from our testsuite is a simple example one can recreate using components from the Modelica Standard Library. After splitting the model into two models and exporting each as an Model-Exchange and Co-Simulation FMU.

_images/DualMassOscillator.png — Figure 69 Dual mass oscillator Modelica model (diagramm view) and FMUs¶

_images/omedit_10.png — Figure 70 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>

TLM Systems¶

TLM systems are only allowed on top-level. SSD annotations are used to specify the system type inside the ssd:SimulationInformation tag, as shown in the example below. Attributes ip, managerport and monitorport defines the socket communication, used both to exchange data with external tools and with internal simulation threads.

<?xml version="1.0"?>
<ssd:System name="tlm">
  <ssd:SimulationInformation>
   <ssd:Annotations>
      <ssd:Annotation type="org.openmodelica">
        <oms:TlmMaster ip="127.0.1.1" managerport="11111" monitorport="11121"/>
      </ssd:Annotation>
   </ssd:Annotations>
  </ssd:SimulationInformation>
  <ssd:Elements>
    <ssd:System name="weaklycoupled">
      <ssd:SimulationInformation>
        <ssd:FixedStepMaster description="oms-ma" stepSize="1e-1" />
      </ssd:SimulationInformation>
    </ssd:System>
  </ssd:Elements>
</ssd:System>

TLM Connections¶

TLM connections are implemented without regular SSD connections. TLM connections are only allowed in TLM systems. TLM connectors are only allowed in weakly coupled or strongly coupled systems. Both connectors and connections are implemented as SSD annotations in the System tag.

The example below shows a TLM system containing two weakly coupled systems, wc1 and wc2. System wc1 contains two TLM connectors, one of type 1D signal and one of type 1D mechanical. System wc2 contains only a 1D signal type connector. The two 1D signal connectors are connected to each other in the TLM top-level system.

<?xml version="1.0"?>
<ssd:System name="tlm">
  <ssd:Elements>
    <ssd:System name="wc2">
      <ssd:Connectors>
        <ssd:Connector name="y" kind="input" type="Real" />
      </ssd:Connectors>
      <ssd:Annotations>
        <ssd:Annotation type="org.openmodelica">
          <oms:Bus name="bus2" type="tlm" domain="signal"
                   dimension="1" interpolation="none">
            <oms:Signals>
              <oms:Signal name="y" tlmType="value" />
            </oms:Signals>
          </oms:Bus>
        </ssd:Annotation>
      </ssd:Annotations>
    </ssd:System>
    <ssd:System name="wc1">
      <ssd:Connectors>
        <ssd:Connector name="y" kind="output" type="Real" />
        <ssd:Connector name="x" kind="output" type="Real" />
        <ssd:Connector name="v" kind="output" type="Real" />
        <ssd:Connector name="f" kind="input" type="Real" />
      </ssd:Connectors>
      <ssd:Annotations>
        <ssd:Annotation type="org.openmodelica">
          <oms:Bus name="bus1" type="tlm" domain="signal"
                   dimension="1" interpolation="none">
            <oms:Signals>
              <oms:Signal name="y" tlmType="value" />
            </oms:Signals>
          </oms:Bus>
          <oms:Bus name="bus2" type="tlm" domain="mechanical"
                   dimension="1" interpolation="none">
            <oms:Signals>
              <oms:Signal name="x" tlmType="state" />
              <oms:Signal name="v" tlmType="flow" />
              <oms:Signal name="f" tlmType="effort" />
            </oms:Signals>
          </oms:Bus>
        </ssd:Annotation>
      </ssd:Annotations>
    </ssd:System>
  </ssd:Elements>
  <ssd:Annotations>
    <ssd:Annotation type="org.openmodelica">
      <oms:Connections>
        <oms:Connection startElement="wc1" startConnector="bus1"
                        endElement="wc2" endConnector="bus2"
                        delay="0.001000" alpha="0.300000"
                        linearimpedance="100.000000"
                        angularimpedance="0.000000" />
      </oms:Connections>
    </ssd:Annotation>
  </ssd:Annotations>
</ssd:System>

Depending on the type of TLM bus connector (dimension, domain and interpolation), connectors need to be assigned to different tlm variable types. Below is the complete list of supported TLM bus types and their respective connectors.

1D signal

tlmType	causality
`"value"`	input/output

1D physical (no interpolation)

tlmType	causality
`"state"`	output
`"flow"`	output
`"effort"`	input

1D physical (coarse-grained interpolation)

tlmType	causality
`"state"`	output
`"flow"`	output
`"wave"`	input
`"impedance"`	input

1D physical (fine-grained interpolation)

tlmType	causality
`"state"`	output
`"flow"`	output
`"wave1"`	input
`"wave2"`	input
`"wave3"`	input
`"wave4"`	input
`"wave5"`	input
`"wave6"`	input
`"wave7"`	input
`"wave8"`	input
`"wave9"`	input
`"wave10"`	input
`"time1"`	input
`"time2"`	input
`"time3"`	input
`"time4"`	input
`"time5"`	input
`"time6"`	input
`"time7"`	input
`"time8"`	input
`"time9"`	input
`"time10"`	input
`"impedance"`	input

3D physical (no interpolation)

tlmType	causality
`"state1"`	output
`"state2"`	output
`"state3"`	output
`"A11"`	output
`"A12"`	output
`"A13"`	output
`"A21"`	output
`"A22"`	output
`"A23"`	output
`"A31"`	output
`"A32"`	output
`"A33"`	output
`"flow1"`	output
`"flow2"`	output
`"flow3"`	output
`"flow4"`	output
`"flow5"`	output
`"flow6"`	output
`"effort1"`	input
`"effort2"`	input
`"effort3"`	input
`"effort4"`	input
`"effort5"`	input
`"effort6"`	input

3D physical (coarse-grained interpolation)

tlmType	causality
`"state1"`	output
`"state2"`	output
`"state3"`	output
`"A11"`	output
`"A12"`	output
`"A13"`	output
`"A21"`	output
`"A22"`	output
`"A23"`	output
`"A31"`	output
`"A32"`	output
`"A33"`	output
`"flow1"`	output
`"flow2"`	output
`"flow3"`	output
`"flow4"`	output
`"flow5"`	output
`"flow6"`	output
`"wave1"`	input
`"wave2"`	input
`"wave3"`	input
`"wave4"`	input
`"wave5"`	input
`"wave6"`	input
`"linearimpedance"`	input
`"angularimpedance"`	input

3D physical (fine-grained interpolation)

tlmType	causality
`"state1"`	output
`"state2"`	output
`"state3"`	output
`"A11"`	output
`"A12"`	output
`"A13"`	output
`"A21"`	output
`"A22"`	output
`"A23"`	output
`"A31"`	output
`"A32"`	output
`"A33"`	output
`"flow1"`	output
`"flow2"`	output
`"flow3"`	output
`"flow4"`	output
`"flow5"`	output
`"flow6"`	output
`"wave1_1"`	input
`"wave1_2"`	input
`"wave1_3"`	input
`"wave1_4"`	input
`"wave1_5"`	input
`"wave1_6"`	input
`"wave2_1"`	input
`"wave2_2"`	input
`"wave2_3"`	input
`"wave2_4"`	input
`"wave2_5"`	input
`"wave2_6"`	input
`"wave3_1"`	input
`"wave3_2"`	input
`"wave3_3"`	input
`"wave3_4"`	input
`"wave3_5"`	input
`"wave3_6"`	input
`"wave4_1"`	input
`"wave4_2"`	input
`"wave4_3"`	input
`"wave4_4"`	input
`"wave4_5"`	input
`"wave4_6"`	input
`"wave5_1"`	input
`"wave5_2"`	input
`"wave5_3"`	input
`"wave5_4"`	input
`"wave5_5"`	input
`"wave5_6"`	input
`"wave6_1"`	input
`"wave6_2"`	input
`"wave6_3"`	input
`"wave6_4"`	input
`"wave6_5"`	input
`"wave6_6"`	input
`"wave7_1"`	input
`"wave7_2"`	input
`"wave7_3"`	input
`"wave7_4"`	input
`"wave7_5"`	input
`"wave7_6"`	input
`"wave8_1"`	input
`"wave8_2"`	input
`"wave8_3"`	input
`"wave8_4"`	input
`"wave8_5"`	input
`"wave8_6"`	input
`"wave9_1"`	input
`"wave9_2"`	input
`"wave9_3"`	input
`"wave9_4"`	input
`"wave9_5"`	input
`"wave9_6"`	input
`"wave10_1"`	input
`"wave10_2"`	input
`"wave10_3"`	input
`"wave10_4"`	input
`"wave10_5"`	input
`"wave10_6"`	input
`"time1"`	input
`"time2"`	input
`"time3"`	input
`"time4"`	input
`"time5"`	input
`"time6"`	input
`"time7"`	input
`"time8"`	input
`"time9"`	input
`"time10"`	input
`"linearimpedance"`	input
`"angularimpedance"`	input