2. OMSimulator¶
OMSimulator is a command line interface for the OMSimulatorLib library. It can be used to simulate Functional Mock-up Units (FMUs) and System Structure and Parameterization (SSP) files, as well as execute dedicated Python simulation scripts using the OMSimulator Python API.
2.1. OMSimulator Flags¶
A brief description of all command line flags can be displayed using
OMSimulator --help:
usage: OMSimulator [-h] [--validate] [--version]
[--addParametersToCSV | --no-addParametersToCSV]
[--algLoopSolver {fixedpoint,kinsol}] [--clearAllOptions]
[--CVODEMaxErrTestFails CVODEMAXERRTESTFAILS]
[--CVODEMaxNLSFailures CVODEMAXNLSFAILURES]
[--CVODEMaxNLSIterations CVODEMAXNLSITERATIONS]
[--CVODEMaxSteps CVODEMAXSTEPS]
[--deleteTempFiles | --no-deleteTempFiles]
[--directionalDerivatives | --no-directionalDerivatives]
[--dumpAlgLoops | --no-dumpAlgLoops]
[--emitEvents | --no-emitEvents]
[--ignoreInitialUnknowns | --no-ignoreInitialUnknowns]
[--initialStepSize INITIALSTEPSIZE]
[--inputExtrapolation | --no-inputExtrapolation]
[--intervals INTERVALS] [--logFile LOGFILE]
[--logLevel LOGLEVEL] [--master MASTER]
[--maxEventIteration MAXEVENTITERATION]
[--maxLoopIteration MAXLOOPITERATION]
[--minimumStepSize MINIMUMSTEPSIZE] [--mode {cs,me}]
[--numProcs NUMPROCS] [--progressBar | --no-progressBar]
[--realTime | --no-realTime] [--resultFile RESULTFILE]
[--skipCSVHeader | --no-skipCSVHeader]
[--solver {euler,cvode}] [--solverStats | --no-solverStats]
[--startTime STARTTIME] [--stepSize STEPSIZE]
[--stopTime STOPTIME] [--stripRoot | --no-stripRoot]
[--suppressPath | --no-suppressPath] [--tempDir TEMPDIR]
[--timeout TIMEOUT] [--tolerance TOLERANCE]
[--wallTime | --no-wallTime] [--workingDir WORKINGDIR]
[--zeroNominal | --no-zeroNominal]
model
Command line entry point for OMSimulator. Allows running a model file
directly, e.g.: OMSimulator test.ssp OMSimulator model.fmu OMSimulator test.py
running a Python driver script without having to write a driver script. All
simulation settings (start/stop time, result file, tolerance, ...) are taken
from the model itself; use --resultFile/--startTime/--stopTime/--tolerance/
--stepSize to override them. For FMUs that export both model exchange and co-
simulation, use --mode to pick which one to run. Pass --stripRoot to drop the
"model.root" prefix from exported signal names. Files are validated against
their schema (FMI for .fmu, SSP for .ssp) before simulation; pass --validate
to only validate the file and skip simulation e.g.: OMSimulator --validate
test.ssp OMSimulator --validate model.fmu
positional arguments:
model Path to a .ssp or .fmu file to simulate
options:
-h, --help show this help message and exit
--validate Only validate the file against its schema; do not
simulate
--version show program's version number and exit
--addParametersToCSV, --no-addParametersToCSV
Export parameters to a .csv file (default: false)
--algLoopSolver {fixedpoint,kinsol}
Specifies the loop solver method used for algebraic
loops spanning multiple components (default: kinsol)
--clearAllOptions Reset all flags to their default values
--CVODEMaxErrTestFails CVODEMAXERRTESTFAILS
Maximum number of error test failures for CVODE
(default: 100)
--CVODEMaxNLSFailures CVODEMAXNLSFAILURES
Maximum number of nonlinear convergence failures for
CVODE (default: 100)
--CVODEMaxNLSIterations CVODEMAXNLSITERATIONS
Maximum number of nonlinear solver iterations for
CVODE (default: 5)
--CVODEMaxSteps CVODEMAXSTEPS
Maximum number of steps for CVODE (default: 1000)
--deleteTempFiles, --no-deleteTempFiles
Delete temporary files as soon as they are no longer
needed (default: true)
--directionalDerivatives, --no-directionalDerivatives
Use directional derivatives to calculate the Jacobian
for algebraic loops (default: true)
--dumpAlgLoops, --no-dumpAlgLoops
Dump information for algebraic loops (default: false)
--emitEvents, --no-emitEvents
Emit events during simulation (default: true)
--ignoreInitialUnknowns, --no-ignoreInitialUnknowns
Ignore initial unknowns from the modelDescription.xml
(default: false)
--initialStepSize INITIALSTEPSIZE
Specify the initial step size (default: 1e-06)
--inputExtrapolation, --no-inputExtrapolation
Enable input extrapolation using derivative
information (default: false)
--intervals INTERVALS
Specify the number of communication points (arg > 1)
(default: 500)
--logFile LOGFILE Specify the log file (default: stdout)
--logLevel LOGLEVEL Set the log level (0: default, 1: debug, 2:
debug+trace) (default: 0)
--master MASTER Specify the master algorithm (ma) (default: ma)
--maxEventIteration MAXEVENTITERATION
Specify the maximum number of iterations for handling
a single event (default: 100)
--maxLoopIteration MAXLOOPITERATION
Specify the maximum number of iterations for solving
algebraic loops between system-level components.
Internal algebraic loops of components are not
affected. (default: 10)
--minimumStepSize MINIMUMSTEPSIZE
Specify the minimum step size (default: 1e-12)
--mode {cs,me} Force 'cs' (co-simulation) or 'me' (model exchange)
for FMUs that export both kinds (.fmu only) (default:
co-simulation)
--numProcs NUMPROCS Specify the maximum number of processors to use
(0=auto, 1=default) (default: 1)
--progressBar, --no-progressBar
Show a progress bar for the simulation progress in the
terminal (default: false)
--realTime, --no-realTime
Enable experimental feature for (soft) real-time co-
simulation (default: false)
--resultFile RESULTFILE
Specify the name of the output result file (default:
the model name plus '_res.mat')
--skipCSVHeader, --no-skipCSVHeader
Skip the CSV delimiter row in the header of .csv
result files (default: true)
--solver {euler,cvode}
Set the ODE solver for model-exchange FMUs (.fmu,
mode=me only) (default: cvode)
--solverStats, --no-solverStats
Add solver stats to the result file, e.g., step size;
not supported for all solvers (default: false)
--startTime STARTTIME
Specify the start time (default: from the model)
--stepSize STEPSIZE Specify the (maximum) step size (.fmu only) (default:
from the model)
--stopTime STOPTIME Specify the stop time (default: from the model)
--stripRoot, --no-stripRoot
Remove the root system prefix from all exported
signals (default: false)
--suppressPath, --no-suppressPath
Suppress path information in info messages; especially
useful for testing (default: true)
--tempDir TEMPDIR Specify the temporary directory (default: the working
directory)
--timeout TIMEOUT Specify the maximum allowed time in seconds for
running a simulation (default: 0 (disabled))
--tolerance TOLERANCE
Specify the relative tolerance (default: from the
model)
--wallTime, --no-wallTime
Add wall time information to the result file (default:
false)
--workingDir WORKINGDIR
Specify the working directory (default: the current
directory)
--zeroNominal, --no-zeroNominal
Accept FMUs with invalid nominal values and replace
the invalid nominal values with 1.0 (default: false)
To use the logLevel flag with option debug (--logLevel=1)
or debug+trace (--logLevel=2), OMSimulator needs to be built with
debug configuration enabled. Refer to the
OMSimulator README on GitHub
for further instructions.
2.2. Examples¶
OMSimulator supports several ways of running simulations.
2.2.1. Running a Python script¶
A dedicated Python script can be passed directly to OMSimulator. The script can use the OMSimulator Python API to create and configure a simulation.
OMSimulator example.py
This is useful when the simulation setup is created programmatically or when a simulation needs additional Python logic.
2.2.2. Running an SSP file¶
An SSP file can be passed directly to OMSimulator. OMSimulator loads the system structure from the SSP file and executes the simulation.
OMSimulator example.ssp
2.2.3. Running an FMU¶
An FMU can also be passed directly to OMSimulator.
OMSimulator example.fmu
This provides a simple way to simulate an FMU without creating an SSP system explicitly.