4. OMSimulatorLua¶
This is a shared library that provides a Lua interface for the OMSimulatorLib library.
4.1. 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")
4.2. Lua Scripting Commands¶
4.2.1. 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
4.2.3. 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.
4.2.4. 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
4.2.5. addConnectorToBus¶
Adds a connector to a bus.
status = oms_addConnectorToBus(busCref, connectorCref)
4.2.6. addConnectorToTLMBus¶
Adds a connector to a TLM bus.
status = oms_addConnectorToTLMBus(busCref, connectorCref, type)
4.2.7. addExternalModel¶
Adds an external model to a TLM system.
status = oms_addExternalModel(cref, path, startscript)
4.2.8. 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")
4.2.9. 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.
4.2.12. 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
4.2.13. addTLMConnection¶
Connects two TLM connectors.
status = oms_addTLMConnection(crefA, crefB, delay, alpha, linearimpedance, angularimpedance)
4.2.14. 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 |
4.2.17. 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.
4.2.18. deleteConnectorFromBus¶
Deletes a connector from a given bus.
status = oms_deleteConnectorFromBus(busCref, connectorCref)
4.2.19. deleteConnectorFromTLMBus¶
Deletes a connector from a given TLM bus.
status = oms_deleteConnectorFromTLMBus(busCref, connectorCref)
4.2.20. 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")
4.2.21. 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 presente 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
4.2.23. exportDependencyGraphs¶
Export the dependency graphs of a given model to dot files.
status = oms_exportDependencyGraphs(cref, initialization, event, simulation)
4.2.24. 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)
4.2.25. 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)
4.2.26. 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)
4.2.27. 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 |
4.2.28. 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.
4.2.30. getDirectionalDerivative¶
This function computes the directional derivatives of an FMU.
value, status = oms_getDirectionalDerivative(cref)
4.2.31. 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)
4.2.33. getModelState¶
Gets the model state of the given model cref.
modelState, status = oms_getModelState(cref)
4.2.35. getSolver¶
Gets the selected solver method of the given system.
solver, status = oms_getSolver(cref)
4.2.38. 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)
4.2.41. getTolerance¶
Gets the tolerance of a given system or component.
absoluteTolerance, relativeTolerance, status = oms_getTolerance(cref)
4.2.42. getVariableStepSize¶
Gets the step size parameters.
initialStepSize, minimumStepSize, maximumStepSize, status = oms_getVariableStepSize(cref)
4.2.44. importFile¶
Imports a composite model from a SSP file.
cref, status = oms_importFile(filename)
4.2.45. 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)
4.2.48. 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)
4.2.49. 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)
4.2.50. 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>
4.2.51. 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)
4.2.53. 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")
4.2.54. 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")
4.2.55. 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.
4.2.57. 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”)
4.2.58. reset¶
Reset the composite model after a simulation run.
The FMUs go into the same state as after instantiation.
status = oms_reset(cref)
4.2.59. setActivationRatio¶
Experimental feature for setting the activation ratio of FMUs for experimenting with multi-rate master algorithms.
status = experimental_setActivationRatio(cref, k)
4.2.61. 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)
--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
4.2.62. 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)
4.2.64. 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)
4.2.65. setLoggingInterval¶
Set the logging interval of the simulation.
status = oms_setLoggingInterval(cref, loggingInterval)
4.2.66. setLoggingLevel¶
Enables/Disables debug logging (logDebug and logTrace).
0 default, 1 default+debug, 2 default+debug+trace
oms_setLoggingLevel(logLevel)
4.2.67. setMaxLogFileSize¶
Sets maximum log file size in MB. If the file exceeds this limit, the logging will continue on stdout.
oms_setMaxLogFileSize(size)
4.2.68. 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.
4.2.69. 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)
4.2.70. 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.
4.2.71. 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) |
4.2.72. setStartTime¶
Set the start time of the simulation.
status = oms_setStartTime(cref, startTime)
4.2.75. 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)
4.2.76. setTLMSocketData¶
Sets data for TLM socket communication.
status = oms_setTLMSocketData(cref, address, managerPort, monitorPort)
4.2.78. 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.
4.2.80. setVariableStepSize¶
Sets the step size parameters for methods with stepsize control.
status = oms_getVariableStepSize(cref, initialStepSize, minimumStepSize, maximumStepSize)
4.2.81. setWorkingDirectory¶
Set a new working directory.
status = oms_setWorkingDirectory(newWorkingDir)
4.2.83. simulate_realtime¶
Experimental feature for (soft) real-time simulation.
status = experimental_simulate_realtime(ident)
4.2.84. stepUntil¶
Simulates a composite model until a given time value.
status = oms_stepUntil(cref, stopTime)