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