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¶
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);
The two arguments crefA and crefB get swapped automatically if necessary.
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);
addSignalsToResults¶
[deprecated: setSignalFilter is the recommended API]
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);
cancelSimulation_asynchronous¶
Cancels a running asynchronous simulation.
oms_status_enu_t oms_cancelSimulation_asynchronous(const char* cref);
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);
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);
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);
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);
getSignalFilter¶
Gets the signal filter of the given model cref.
oms_status_enu_t oms_getSignalFilter(const char* cref, char** regex);
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);
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);
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);
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);
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);
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);
newModel¶
Creates a new and yet empty composite model.
oms_status_enu_t oms_newModel(const char* 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.
oms_status_enu_t oms_parseModelName(const char* contents, char** cref);
removeSignalsFromResults¶
[deprecated: setSignalFilter is the recommended API]
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);
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
--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¶
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.
setSignalFilter¶
This function specifies the signal filter. The signal filter is used to determine which signals will eventually be exported to the result file.
oms_status_enu_t oms_setSignalFilter(const char* cref, const char* 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.
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);
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.
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_asynchronous¶
Simulates a composite model in its own thread.
oms_status_enu_t oms_simulate_asynchronous(const char* cref, void (*cb)(const char* cref, double time, oms_status_enu_t status));
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);