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¶

RunFile¶

Simulates a single FMU or SSP model.

# not available

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

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

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¶

[deprecated: setSignalFilter is the recommended API]

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

cancelSimulation_asynchronous¶

Cancels a running asynchronous simulation.

status := oms_cancelSimulation_asynchronous(cref);

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

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.

# not available

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.

# not available

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

getBus¶

Gets the bus object.

# not available

getComponentType¶

Gets the type of the given component.

# not available

getConnections¶

Get list of all connections from a given component.

# not available

getConnector¶

Gets the connector object of the given connector cref.

# not available

getElement¶

Get element information of a given component reference.

# not available

getElements¶

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

# not available

getFMUInfo¶

Returns FMU specific information.

# not available

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

getResultFile¶

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

# not available

getSignalFilter¶

Gets the signal filter of the given model cref.

# not available

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

getTLMBus¶

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

# not available

getTLMVariableTypes¶

Gets the type of an TLM variable.

# not available

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

parseModelName¶

Parses the model name from a given SSD representation.

Memory is allocated for ident. 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.

(ident, status) := oms_parseModelName(contents);

removeSignalsFromResults¶

[deprecated: setSignalFilter is the recommended API]

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

setActivationRatio¶

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

# not yet available

setBoolean¶

Sets the value of a given boolean signal.

status := oms_setBoolean(cref, value);

setBusGeometry¶

# not available

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
           --deleteTempFiles=<bool>        Deletes temp files as soon as they are no longer needed ([true], false)
           --emitEvents=<bool>             Specifies whether events should be emitted or not ([true], false)
           --exportParametersInline=<arg>  Export ParameterBindings inline with .ssd file, 
           --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
           --setInputDerivatives=<bool>    Deprecated; see '--inputExtrapolation'
           --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
           --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

setConnectionGeometry¶

# not available

setConnectorGeometry¶

Set geometry information to a given connector.

# not available

setElementGeometry¶

Set geometry information to a given component.

# not available

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

setLoggingCallback¶

Sets a callback function for the logging system.

# not available

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.

# not available

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.

setSignalFilter¶

This function specifies the signal filter. The signal filter is used to determine which signals will eventually be exported to the result file.

status := oms_setSignalFilter(cref, regex);

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

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

setTLMBusGeometry¶

# not available

setTLMConnectionParameters¶

Simulates a composite model in its own thread.

# not available

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

simulate_asynchronous¶

Simulates a composite model in its own thread.

# not available

simulate_realtime¶

Experimental feature for (soft) real-time simulation.

# not yet available

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