8. OpenModelicaScripting¶
This is a shared library that provides a OpenModelica Scripting interface for the OMSimulatorLib library.
8.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();
8.2. OpenModelica Scripting Commands¶
8.3. addBus¶
Adds a bus to a given component.
status := oms_addBus(cref);
8.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.
8.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"
8.6. addConnectorToBus¶
Adds a connector to a bus.
status := oms_addConnectorToBus(busCref, connectorCref);
8.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.
8.8. addSubModel¶
Adds a component to a system.
status := oms_addSubModel(cref, fmuPath);
8.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"
8.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 |
8.11. copySystem¶
Copies a system.
status := oms_copySystem(source, target);
8.12. delete¶
Deletes a connector, component, system, or model object.
status := oms_delete(cref);
8.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.
8.14. deleteConnectorFromBus¶
Deletes a connector from a given bus.
status := oms_deleteConnectorFromBus(busCref, connectorCref);
8.15. export¶
Exports a composite model to a SPP file.
status := oms_export(cref, filename);
8.16. exportDependencyGraphs¶
Export the dependency graphs of a given model to dot files.
status := oms_exportDependencyGraphs(cref, initialization, event, simulation);
8.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);
8.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
8.19. getBoolean¶
Get boolean value of given signal.
(value, status) := oms_getBoolean(cref);
8.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_setFixedStepSize(cref);
8.21. getInteger¶
Get integer value of given signal.
(value, status) := oms_getInteger(cref);
8.22. getModelState¶
Gets the model state of the given model cref.
(modelState, status) := oms_getModelState(cref);
8.23. getReal¶
Get real value.
(value, status) := oms_getReal(cref);
8.24. getSolver¶
Gets the selected solver method of the given system.
(solver, status) := oms_getSolver(cref);
8.25. getStartTime¶
Get the start time from the model.
(startTime, status) := oms_getStartTime(cref);
8.26. getStopTime¶
Get the stop time from the model.
(stopTime, status) := oms_getStopTime(cref);
8.27. getSubModelPath¶
Returns the path of a given component.
(path, status) := oms_getSubModelPath(cref);
8.28. getSystemType¶
Gets the type of the given system.
(type, status) := oms_getSystemType(cref);
8.29. getTime¶
Get the current simulation time from the model.
(time, status) := oms_getTime(cref);
8.30. getTolerance¶
Gets the tolerance of a given system or component.
(relativeTolerance, status) := oms_getTolerance(cref);
8.31. getVariableStepSize¶
Gets the step size parameters.
(initialStepSize, minimumStepSize, maximumStepSize, status) := oms_getVariableStepSize(cref);
8.32. getVersion¶
Returns the library’s version string.
version := oms_getVersion();
8.33. importFile¶
Imports a composite model from a SSP file.
(cref, status) := oms_importFile(filename);
8.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);
8.35. initialize¶
Initializes a composite model.
status := oms_initialize(cref);
8.36. instantiate¶
Instantiates a given composite model.
status := oms_instantiate(cref);
8.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);
8.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);
8.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);
8.40. newModel¶
Creates a new and yet empty composite model.
status := oms_newModel(cref);
8.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.
8.42. rename¶
Renames a model, system, or component.
status := oms_rename(cref, newCref);
8.43. reset¶
Reset the composite model after a simulation run.
The FMUs go into the same state as after instantiation.
status := oms_reset(cref);
8.44. setBoolean¶
Sets the value of a given boolean signal.
status := oms_setBoolean(cref, value);
8.45. setCommandLineOption¶
Sets special flags.
status := oms_setCommandLineOption(cmd);
Available flags:
info: Usage: OMSimulator [Options] [Lua script] [FMU] [SSP file]
Options:
--addParametersToCSV=<bool> false Export parameters to a .csv file
--algLoopSolver=<arg> "kinsol" Specifies the loop solver method (fixedpoint, kinsol) used for algebraic loops spanning multiple components.
--clearAllOptions Reset all flags to their default values
--CVODEMaxErrTestFails=<int> 100 Maximum number of error test failures for CVODE
--CVODEMaxNLSFailures=<int> 100 Maximum number of nonlinear convergence failures for CVODE
--CVODEMaxNLSIterations=<int> 5 Maximum number of nonlinear solver iterations for CVODE
--CVODEMaxSteps=<int> 1000 Maximum number of steps for CVODE
--deleteTempFiles=<bool> true Delete temporary files as soon as they are no longer needed
--directionalDerivatives=<bool> true Use directional derivatives to calculate the Jacobian for algebraic loops
--dumpAlgLoops=<bool> false Dump information for algebraic loops
--emitEvents=<bool> true Emit events during simulation
--help [-h] Display the help text
--ignoreInitialUnknowns=<bool> false Ignore initial unknowns from the modelDescription.xml
--initialStepSize=<double> 1e-6 Specify the initial step size
--inputExtrapolation=<bool> false Enable input extrapolation using derivative information
--intervals=<int> [-i] 500 Specify the number of communication points (arg > 1)
--logFile=<arg> [-l] "" Specify the log file (stdout is used if no log file is specified)
--logLevel=<int> 0 Set the log level (0: default, 1: debug, 2: debug+trace)
--master=<arg> "ma" Specify the master algorithm (ma)
--maxEventIteration=<int> 100 Specify the maximum number of iterations for handling a single event
--maxLoopIteration=<int> 10 Specify the maximum number of iterations for solving algebraic loops between system-level components. Internal algebraic loops of components are not affected.
--minimumStepSize=<double> 1e-12 Specify the minimum step size
--mode=<arg> [-m] "me" Force a certain FMI mode if the FMU provides both cs and me (cs, me)
--numProcs=<int> [-n] 1 Specify the maximum number of processors to use (0=auto, 1=default)
--progressBar=<bool> false Show a progress bar for the simulation progress in the terminal
--realTime=<bool> false Enable experimental feature for (soft) real-time co-simulation
--resultFile=<arg> [-r] "<default>" Specify the name of the output result file
--skipCSVHeader=<bool> true Skip exporting the CSV delimiter in the header
--solver=<arg> "cvode" Specify the integration method (euler, cvode)
--solverStats=<bool> false Add solver stats to the result file, e.g., step size; not supported for all solvers
--startTime=<double> [-s] 0 Specify the start time
--stepSize=<double> 1e-3 Specify the (maximum) step size
--stopTime=<double> [-t] 1 Specify the stop time
--stripRoot=<bool> false Remove the root system prefix from all exported signals
--suppressPath=<bool> false Suppress path information in info messages; especially useful for testing
--tempDir=<arg> "." Specify the temporary directory
--timeout=<int> 0 Specify the maximum allowed time in seconds for running a simulation (0 disables)
--tolerance=<double> 1e-4 Specify the relative tolerance
--version [-v] Display version information
--wallTime=<bool> false Add wall time information to the result file
--workingDir=<arg> "." Specify the working directory
--zeroNominal=<bool> false Accept FMUs with invalid nominal values and replace the invalid nominal values with 1.0
8.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);
8.47. setInteger¶
Sets the value of a given integer signal.
status := oms_setInteger(cref, value);
8.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);
8.49. setLoggingInterval¶
Set the logging interval of the simulation.
status := oms_setLoggingInterval(cref, loggingInterval);
8.50. setLoggingLevel¶
Enables/Disables debug logging (logDebug and logTrace).
0 default, 1 default+debug, 2 default+debug+trace
oms_setLoggingLevel(logLevel);
8.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.
8.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);
8.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.
8.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"
8.55. setStartTime¶
Set the start time of the simulation.
status := oms_setStartTime(cref, startTime);
8.56. setStopTime¶
Set the stop time of the simulation.
status := oms_setStopTime(cref, stopTime);
8.57. setTempDirectory¶
Set new temp directory.
status := oms_setTempDirectory(newTempDir);
8.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.
8.59. setVariableStepSize¶
Sets the step size parameters for methods with stepsize control.
status := oms_getVariableStepSize(cref, initialStepSize, minimumStepSize, maximumStepSize);
8.60. setWorkingDirectory¶
Set a new working directory.
status := oms_setWorkingDirectory(newWorkingDir);
8.61. simulate¶
Simulates a composite model.
status := oms_simulate(cref);
8.62. stepUntil¶
Simulates a composite model until a given time value.
status := oms_stepUntil(cref, stopTime);
8.63. terminate¶
Terminates a given composite model.
status := oms_terminate(cref);