Skip to main content Link Menu Expand (external link) Document Search Copy Copied
cosim cli on GitHub

Command line interface

cosim is a command line interface (CLI) to libcosim for the cases where a graphical user interface is not available or needed. It facilitates for running co-simulations of systems configured with SSP or OSP system structure configuration. It has three primary use cases:

  • Running simulations from other programs or scripts
  • FMU testing and debugging
  • Users who simply prefer to work from the command line

The CLI is especially suitable when multiple sets of simulation to be executed in parallel. An example for such use case could be in design, where there typically are multiple system variants and parameterization of the system. It can simulate a single FMU and show the model description. Besides being a necessary simulation tool, the CLI also serves as a demonstration for how client applications can make use of the libcosim library. With the CLI, the co-simulation library is used to enable co-simulation from the command-line.

Functional specification

cosim is able to perform the following tasks:

  • Run a simulation, where the system to simulate is specified as an SSP file.
  • Provide information about a model (usually an FMU).
  • Do a “test run” with a single model (FMU).

Detailed specifications are given in the form of “help texts” as follows.

General usage

> cosim help
NAME
  cosim - Command-line co-simulation tool based on libcosim

SYNOPSIS
  cosim <subcommand> <args...> [options...]

DESCRIPTION
  cosim and libcosim are free and open-source software for running distributed co-simulations.

SUBCOMMANDS
  clean-cache         Removes unused data from the program cache
  help                Shows documentation
  inspect             Shows information about a model
  run                 Runs a simulation
  run-single          Runs a simulation with a single subsimulator

OPTIONS
  --help                     Display a help message and exit.
  --log-level arg (=warning) Sets the detail/severity level of diagnostic program output.  Valid
                             argument values, in order of increasing detail (and decreasing
                             severity), are: error, warning, info, debug, trace.
  -v [ --verbose ]           Shorthand for --log-level=info.
  --version                  Display program version information and exit.

Getting information about a model

> cosim inspect --help
NAME
  cosim inspect - Shows information about a model

SYNOPSIS
  cosim inspect <uri_or_path> [options...]

DESCRIPTION
  This command shows information about a model, such as its name, description, author, version, and
  so on.  It also lists information about the model's variables, like their names, types,
  causalities, variabilities, etc.

  The model can be specified with a URI, or, if it's a local FMU, by its path.  Using a path is
  equivalent to using a `file` URI.

PARAMETERS
  uri_or_path           A model URI or FMU path.

OPTIONS
  --help                     Display a help message and exit.
  --log-level arg (=warning) Sets the detail/severity level of diagnostic program output.  Valid
                             argument values, in order of increasing detail (and decreasing
                             severity), are: error, warning, info, debug, trace.
  --no-vars                  Do not print information about variables.
  -v [ --verbose ]           Shorthand for --log-level=info.
  --version                  Display program version information and exit.
> cosim inspect models/relativistic_energy.fmu
name: physics.relativity.energy
author: Albert Einstein
version: 1.0
description: Calculates relativistic energy, E^2 = m^2 c^4 + p^2 c^2
variables:
  - name: mass
    type: real
    causality: parameter
    variability: tunable
  - name: momentum
    type: real
    causality: input
    variability: continuous
  - name: energy
    type: real
    causality: output
    variability: continuous

Running a simulation

> cosim run --help
NAME
  cosim run - Runs a simulation

SYNOPSIS
  cosim run <system_structure_path> [options...]

DESCRIPTION
  This command runs a simulation based on a configuration file that specifies the system structure,
  i.e., which models to include and the connections between them.

  The simulation can be synchronised with real time by using the the '--real-time' option, optionally
  specifying a target real-time factor (RTF).  The RTF is defined as 'elapsed logical time divided by
  elapsed real time in seconds'.  In other words:

  * RTF < 1 means slower than real time
  * RTF = 1 means real time
  * RTF > 1 means faster than real time

  Whether the target RTF can actually be reached depends on the simulation setup, most importantly
  the models being simulated, and the machine(s) on which the simulation is being executed.

  If '--real-time' is not specified, the default is to run as fast as possible, unconstrained by real
  time.

PARAMETERS
  system_structure_path       The path to the system structure definition file/directory.  If this
                              is a file with .xml extension, or a directory that contains a file
                              named OspSystemStructure.xml, it will be interpreted as a OSP system
                              structure definition.  Otherwise, it will be interpreted as an SSP
                              system structure definition.

OPTIONS
  -b [ --begin-time ] arg (=0)     The logical time at which the simulation should start.
  -d [ --duration ] arg (=1)       The duration of the simulation, in logical time.  Excludes
                                   -e/--end-time.
  -e [ --end-time ] arg            The logical end time of the simulation.  Excludes -d/--duration.
  --help                           Display a help message and exit.
  --log-level arg (=warning)       Sets the detail/severity level of diagnostic program output.
                                   Valid argument values, in order of increasing detail (and
                                   decreasing severity), are: error, warning, info, debug, trace.
  --mr-progress [=resolution(=10)] Enables printing of machine-readable progress indicator lines on
                                   the form '@progress n t d'.  Here, n indicates the progress in
                                   1/N-ths of the total time, where N is the resolution given as an
                                   argument to this option.  t is the current logical time and d is
                                   the amount of logical time that has passed since the start of the
                                   simulation.  t and d are floating-point numbers while n is an
                                   integer.
  --output-config arg (=auto)      The path to an XML file that contains configuration settings for
                                   simulation output, or one of the special values 'auto', 'all' and
                                   'none'.  The default is 'auto', which causes the program to look
                                   for a file named 'LogConfig.xml' in the same directory as the
                                   system structure definition file.  If no such file is found, the
                                   effect is the same as for 'all', meaning that the values of all
                                   variables are stored for each time step.  'none' disables file
                                   output altogether.
  --output-dir arg (=.)            The path to a directory for storing simulation results.
  --real-time [=target_rtf(=1)]    Enables real-time-synchronised simulations.  A target RTF may
                                   optionally be specified, with a default value of 1.
  --scenario arg                   The path to a scenario file to run.  By default, no scenario is
                                   run.
  --scenario-start arg (=0)        The logical time at which the scenario will start.  Only used if
                                   --scenario is specified.
  -v [ --verbose ]                 Shorthand for --log-level=info.
  --version                        Display program version information and exit.

Running a single model

> cosim run-single --help
NAME
  cosim run-single - Runs a simulation with a single subsimulator

SYNOPSIS
  cosim run-single <uri_or_path> <initial_value...> [options...]

DESCRIPTION
  This command runs a simulation consisting of a single subsimulator.  This is mainly meant for
  testing and debugging.  The simulator is therefore run directly, without the overhead and extra
  machinery of a full co-simulation.

  The model to simulate can be specified with a URI, or, if it's a local FMU, by its path.  Using a
  path is equivalent to using a 'file' URI.

  Initial variable values may be specified after the model URI/path, by supplying a list of
  name=value pairs as individual command-line arguments.

  The simulation can be synchronised with real time by using the '--real-time' option, optionally
  specifying a target real-time factor (RTF).  The RTF is defined as 'elapsed logical time divided by
  elapsed real time in seconds'.  In other words:

  * RTF < 1 means slower than real time
  * RTF = 1 means real time
  * RTF > 1 means faster than real time

  Whether the target RTF can actually be reached depends on the simulation setup, most importantly
  the models being simulated, and the machine(s) on which the simulation is being executed.

  If '--real-time' is not specified, the default is to run as fast as possible, unconstrained by real
  time.

PARAMETERS
  uri_or_path           A model URI or FMU path.
  initial_value         Initial values for model variables, on the form <name>=<value>.  Allowed
                        values for boolean variables are 'true' or 'false'.

OPTIONS
  -b [ --begin-time ] arg (=0)            The logical time at which the simulation should start.
  -d [ --duration ] arg (=1)              The duration of the simulation, in logical time.  Excludes
                                          -e/--end-time.
  -e [ --end-time ] arg                   The logical end time of the simulation.  Excludes
                                          -d/--duration.
  --help                                  Display a help message and exit.
  --log-level arg (=warning)              Sets the detail/severity level of diagnostic program
                                          output.  Valid argument values, in order of increasing
                                          detail (and decreasing severity), are: error, warning,
                                          info, debug, trace.
  --mr-progress [=resolution(=10)]        Enables printing of machine-readable progress indicator
                                          lines on the form '@progress n t d'.  Here, n indicates
                                          the progress in 1/N-ths of the total time, where N is the
                                          resolution given as an argument to this option.  t is the
                                          current logical time and d is the amount of logical time
                                          that has passed since the start of the simulation.  t and
                                          d are floating-point numbers while n is an integer.
  --output-file arg (=./model-output.csv) The file to which simulation results should be written.
  --real-time [=target_rtf(=1)]           Enables real-time-synchronised simulations.  A target RTF
                                          may optionally be specified, with a default value of 1.
  -s [ --step-size ] arg (=0.01)          The co-simulation step size.
  -v [ --verbose ]                        Shorthand for --log-level=info.
  --version                               Display program version information and exit.

Copyright © 2020 DNV GL AS, Kongsberg Maritime CM AS, SINTEF Ocean AS and NTNU