# 5. OpenModelicaScripting

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

## 5.1. 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();

## 5.2. OpenModelica Scripting Commands

## 5.3. addBus

Adds a bus to a given component.

    status := oms_addBus(cref);

## 5.4. 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.

## 5.5. 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"

## 5.6. addConnectorToBus

Adds a connector to a bus.

    status := oms_addConnectorToBus(busCref, connectorCref);

## 5.7. 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.

## 5.8. addSubModel

Adds a component to a system.

    status := oms_addSubModel(cref, fmuPath);

## 5.9. addSystem

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

    status := oms_addSystem(cref, type);

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

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

## 5.10. 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

## 5.11. copySystem

Copies a system.

    status := oms_copySystem(source, target);

## 5.12. delete

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

    status := oms_delete(cref);

## 5.13. 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.

## 5.14. deleteConnectorFromBus

Deletes a connector from a given bus.

    status := oms_deleteConnectorFromBus(busCref, connectorCref);

## 5.15. export

Exports a composite model to a SPP file.

    status := oms_export(cref, filename);

## 5.16. exportDependencyGraphs

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

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

## 5.17. 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);

## 5.18. 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

## 5.19. getBoolean

Get boolean value of given signal.

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

## 5.20. 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);

## 5.21. getInteger

Get integer value of given signal.

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

## 5.22. getModelState

Gets the model state of the given model cref.

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

## 5.23. getReal

Get real value.

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

## 5.24. getSolver

Gets the selected solver method of the given system.

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

## 5.25. getStartTime

Get the start time from the model.

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

## 5.26. getStopTime

Get the stop time from the model.

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

## 5.27. getSubModelPath

Returns the path of a given component.

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

## 5.28. getSystemType

Gets the type of the given system.

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

## 5.29. getTime

Get the current simulation time from the model.

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

## 5.30. getTolerance

Gets the tolerance of a given system or component.

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

## 5.31. getVariableStepSize

Gets the step size parameters.

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

## 5.32. getVersion

Returns the library’s version string.

    version := oms_getVersion();

## 5.33. importFile

Imports a composite model from a SSP file.

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

## 5.34. 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);

## 5.35. initialize

Initializes a composite model.

    status := oms_initialize(cref);

## 5.36. instantiate

Instantiates a given composite model.

    status := oms_instantiate(cref);

## 5.37. 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);

## 5.38. 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);

## 5.39. 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);

## 5.40. newModel

Creates a new and yet empty composite model.

    status := oms_newModel(cref);

## 5.41. 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.

## 5.42. rename

Renames a model, system, or component.

    status := oms_rename(cref, newCref);

## 5.43. reset

Reset the composite model after a simulation run.

The FMUs go into the same state as after instantiation.

    status := oms_reset(cref);

## 5.44. setBoolean

Sets the value of a given boolean signal.

    status := oms_setBoolean(cref, value);

## 5.45. setCommandLineOption

Sets special flags.

    status := oms_setCommandLineOption(cmd);

## 5.46. 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);

## 5.47. setInteger

Sets the value of a given integer signal.

    status := oms_setInteger(cref, value);

## 5.48. 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);

## 5.49. setLoggingInterval

Set the logging interval of the simulation.

    status := oms_setLoggingInterval(cref, loggingInterval);

## 5.50. setLoggingLevel

Enables/Disables debug logging (logDebug and logTrace).

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

    oms_setLoggingLevel(logLevel);

## 5.51. 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.

## 5.52. 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);

## 5.53. 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.

## 5.54. setSolver

Sets the solver method for the given system.

    status := oms_setSolver(cref, solver);

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

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

## 5.55. setStartTime

Set the start time of the simulation.

    status := oms_setStartTime(cref, startTime);

## 5.56. setStopTime

Set the stop time of the simulation.

    status := oms_setStopTime(cref, stopTime);

## 5.57. setTempDirectory

Set new temp directory.

    status := oms_setTempDirectory(newTempDir);

## 5.58. setTolerance

Sets the tolerance for a given model or system.

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

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

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

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

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

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

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

## 5.59. setVariableStepSize

Sets the step size parameters for methods with stepsize control.

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

## 5.60. setWorkingDirectory

Set a new working directory.

    status := oms_setWorkingDirectory(newWorkingDir);

## 5.61. simulate

Simulates a composite model.

    status := oms_simulate(cref);

## 5.62. stepUntil

Simulates a composite model until a given time value.

    status := oms_stepUntil(cref, stopTime);

## 5.63. terminate

Terminates a given composite model.

    status := oms_terminate(cref);