Simer - Simulation Runner
Synopsis
Containerised simulation run-time.
# Run a simulation.
$ simer path/to/simulation -stepsize 0.0005 -endtime 0.04
Simulation Setup
Structure
The structure of a simulation is flexible and can be arranged based on individual
project needs. All paths used within a simulation configuration should be
relative to the root of the simulation folder (i.e. the simulation path).
The simer
tool will search for YAML files contained within the simulation path and
automatically configure, and then run, the contained simulation.
The following example simulation layout is generated by the SDP Builder.
Example Simulation Structure
path/to/simulation <-- simulation path
└── data
└── simulation.yaml <-- Simulation definition
└── model
└── input <-- Model 'input'
└── data
└── model.yaml <-- Model definition
signalgroup.yaml <-- Signal definitions
input.csv <-- Data used by the model
└── lib/libcsv.so <-- Model library
└── linear <-- Model 'linear'
└── data/signalgroup.yaml <-- Signal definitions
└── lib/libfmimcl.so <-- FMIMCL library (FMU loader)
lib/fmu3linear.so <-- FMU library
Simulation Stacks
A simulation can be further structured by using several Stack definitions in the simulation.yaml file. This enables parts of the simulation to be partitioned according to either structural, deployment or operational constraints. Simer can then be used to run the appropriate stacks (i.e. those that will use a Linux/Container runtime) while the remaining stacks are run in their appropriate ‘remote’ systems.
32-Bit Models
The Simer runtime supports two 32-bit Linux architectures:
- linux-x86 - model runtime flag
x32
, compiler flags:-mx32
- linux-i386 - model runtime flag
i386
, compiler flags:-m32
Models which should run with either of these architectures can be configured
in a stack via either the runtime.x32
or runtime.i386
property of the
model. Simer will then select the correct ModelC runtime to run these models.
Note: Simulation stacks configured with either a
stacked
orsequential
runtime are run by Simer in a single ModelC instance. Therefore all models in such a simulation stack must have the same runtime properties.
Example Linux-x86 Stack
simulation.yaml
---
kind: Stack
metadata:
name: simulation
spec:
models:
- name: x32_model_instance
uid: 45
model:
name: X32_Model
runtime:
x32: true
channels:
- name: signal_channel
alias: signal
Example Linux-i386 Stack with ‘stacked’ Runtime
simulation.yaml
---
kind: Stack
metadata:
name: simulation
runtime:
stacked: true
spec:
models:
- name: foo
uid: 1
model:
name: I386_Model_Foo
runtime:
i386: true
channels:
- name: signal_channel
alias: signal
- name: bar
uid: 2
model:
name: I386_Model_Bar
runtime:
i386: true
channels:
- name: signal_channel
alias: signal
Remote Models
Simulations which contain remote models, such as gateway models running in
foreign simulation environments, or Windows based models, can be
configured in a separate stack(s).
When the simulation is run by the simer
tool, only a selected list of
stacks/models can be started.
The remaining stacks and/or gateway models are then started in their own
environment, and once started they can connect to the simulation running in the
simer
tool.
Hint: Models which need to be run with an older version of the
simer
tool can be defined in their own stack and run independently (i.e. using an older version of Simer).
Example Remote Stack with Gateway Model
simulation.yaml
---
kind: Stack
metadata:
name: linux
spec:
models:
- name: simbus
model:
name: simbus
channels:
- name: signal_channel
expectedModelCount: 2
- name: model_instance
uid: 1
model:
name: Model
channels:
- name: signal_channel
alias: signal
---
kind: Stack
metadata:
name: remote
spec:
connection:
transport:
redispubsub:
uri: redis://somehost:6379
timeout: 60
models:
- name: gateway_instance
uid: 2
model:
name: GatewayModel
channels:
- name: signal_channel
alias: signal
# Start the simulation (excluding Remote models).
$ simer path/to/simulation -stack linux -endtime 0.1
# Now start the Remote models ...
Stacked Models
Several models may be run stacked into a single ModelC runtime instance by setting
the runtime:stacked
property of their stack to true
. The simer
tool
will start all models in that stack in a single instance of the ModelC runtime.
Example Stacked Simulation with Loopback/Local SimBus
simulation.yaml
---
kind: Stack
metadata:
name: simulation
spec:
connection:
transport:
loopback:
uri: loopback
runtime:
stacked: true
models:
- name: simbus
model:
name: simbus
channels:
- name: signal_channel
expectedModelCount: 2
- name: foo
uid: 1
model:
name: Foo_Model
channels:
- name: signal_channel
alias: signal
- name: bar
uid: 2
model:
name: Bar_Model
channels:
- name: signal_channel
alias: signal
Environment & Files
Environment variables may be specified in either the runtime:env
property
of a stack or model, or with the -env
CLI option of the simer
tool.
Environment variables set by the -env
CLI option of the simer
tool can be
set for all models in the simulation, or targeted to a specific model.
# Set the SimBus transport to `redis` for all models in the simulation.
$ simer path/to/simulation -env SIMBUS_TRANSPORT=redis
# Set the log level for the 'simbus' model _only_.
$ simer path/to/simulation -env simbus:SIMBUS_LOGLEVEL=2
Environment variables are passed by the simer
tool to the ModelC runtime in
the order that they are defined: stack environment variables first, and then
model environment variables, and lastly those specified via the -env
flag(s).
Values set later will overwrite those set earlier.
Additional Files may be specified in the runtime:files
property of a model.
The path of each listed file should be relative to the simulation path or
an absolute path.
Example Stack with Environment & Files Specified
simulation.yaml
---
kind: Stack
metadata:
name: simulation
spec:
runtime:
env:
SIMBUS_LOGLEVEL: 4
models:
- name: simbus
model:
name: simbus
channels:
- name: data_channel
expectedModelCount: 2
- name: counter_A
uid: 1
model:
name: Counter
runtime:
env:
COUNTER_NAME: counter_A
COUNTER_VALUE: 100
files:
- data/signalgroup.yaml
channels:
- name: data_channel
alias: data
- name: counter_B
uid: 2
model:
name: Counter
runtime:
env:
SIMBUS_LOGLEVEL: 3
COUNTER_NAME: counter_B
COUNTER_VALUE: 200
files:
- data/signalgroup.yaml
channels:
- name: data_channel
alias: data
In this example the SIMBUS_LOGLEVEL is set to 4
for all models with the
exception of the ‘counter_B’ model where this value is overridden and set to 3
.
Both models are configured to reference the same file data/signalgroup.yaml
.
This file will be located relative to the simulation path.
Simer Tool
Setup
Simer is a containerised simulation run-time which can be operated using a number of techniques. The container is suitable for use in automated workflows.
Container images are available and released with each new version of the ModelC project.
# Latest Simer Container:
$ docker pull ghcr.io/boschglobal/dse-simer:latest
# Specific versions of the Simer Container
$ docker pull ghcr.io/boschglobal/dse-simer:2.0.7
$ docker pull ghcr.io/boschglobal/dse-simer:2.0
Shell Function
# Define a shell function (or add to .profile file).
$ export SIMER_IMAGE=ghcr.io/boschglobal/dse-simer:latest
$ simer() { ( if test -d "$1"; then cd "$1" && shift; fi && \
docker run -it --user $(id -u):$(id -g) --rm \
-v $(pwd):/sim \
-p 2159:2159 -p 6379:6379 \
$SIMER_IMAGE "$@"; ) }
# Run the simulation.
$ simer path/to/simulation -endtime 0.04
Alias File / Function
function simer() {
( if test -d "$1"; then cd "$1" && shift; fi && \
docker run -it --user $(id -u):$(id -g) --rm \
-v $(pwd):/sim \
-p 2159:2159 -p 6379:6379 \
$SIMER_IMAGE "$@"; \
)
}
export -f simer
# Run the simulation.
$ simer path/to/simulation -endtime 0.04
Makefile
SIMER_IMAGE ?= ghcr.io/boschglobal/dse-simer:latest
SIM_PATH := path/to/simulation
SIM_ENDTIME := 0.04
.PHONY: simer
simer:
docker run -it --user $$(id -u):$$(id -g) --rm \
-v $$(pwd)/$(SIM_PATH):/sim \
$(SIMER_IMAGE) -endtime $(SIM_ENDTIME)
# Run the simulation.
$ make simer
GitHub Workflow Action
jobs:
simulation:
runs-on: ubuntu-latest
steps:
- name: Simer
uses: boschglobal/dse.sdp/actions/simer
with:
path: path/to/simulation
endtime: '0.04'
Options
$ simer -h
SIMER (SIMulation runnER)
Containerised simulation run-time.
Part of the Dynamic Simulation Environment Core Platform.
repo: https://github.com/boschglobal/dse.modelc
doc: https://boschglobal.github.io/dse.doc/docs/user/simer
Examples:
simer -endtime 0.1
simer -stack minimal_stack -endtime 0.1 -logger 2
simer -stepsize 0.0005 -endtime 0.005 -transport redis -uri redis://redis:6379
simer -tmux -endtime 0.02
simer -gdb simbus -tmux -endtime 0.004 -logger 2 -timeout 5
Flags:
-endtime *flag.float64Value
simulation end time (0.002)
-env *simer.listFlag
environment modifier, in format '-env MODEL:NAME=VAL'
-gdb *flag.stringValue
run this model instance via GDB, use CSL in format '-gdb simbus,model'
-gdbserver *flag.stringValue
attach this model instance to GDB server
-logger *flag.intValue
log level (select between 0..4) (3)
-modelcI386 *flag.stringValue
path to ModelC i386 executable (/usr/local/bin/modelc32_i386)
-modelcX32 *flag.stringValue
path to ModelC x32 executable (/usr/local/bin/modelc32_x86)
-stack *flag.stringValue
run the named simulation stack(s)
-stepsize *flag.float64Value
simulation step size (0.0005)
-timeout *flag.float64Value
timeout (60)
-tmux *flag.boolValue
run simulation with TMUX user interface (false)
-transport *flag.stringValue
SimBus transport (redispubsub)
-uri *flag.stringValue
SimBus connection URI (redis://localhost:6379)
-valgrind *flag.stringValue
run this model instance via Valgrind, use CSL in format '-valgrind simbus,model'
Tmux Interface
$ simer path/to/simulation -endtime 0.04 -tmux
The terminal multiplexer tmux is a technical CLI interface which makes it easy to observe the output of simulations which are comprised of several models. When using the tmux interface each Model is represented in its own terminal window, and it is possible to switch between terminal windows using tmux keyboard shortcuts. Some of these shortcuts are listed below.
Tmux Keyboard Shortcuts
- Ctrl+b c
- Create new window.
- Ctrl+b p
- Select previous window.
- Ctrl+b n
- Select next window.
- Ctrl+b 0..9
- Switch between tmux windows.
- Ctrl+b w
- List windows.
- Ctrl+b [
- Enter copy mode. Use VI keys to move cursor around the window (q to quit copy mode).
- Ctrl+b PgUp
- Enter copy mode and scroll up. Use VI keys to move cursor around the window (q to quit copy mode).
In copy mode use:
- Spacebar
- Start selection.
- Esc
- Clear selection.
- Enter
- Copy selection.
- /
- Search forwards.
- ?
- Search backwards.
Finally, use:
- Ctrl+b d
- Detach from the tmux session (and exit the simulation!).
GDB Debug
GDB
Models (and the SimBus) running in the simer
tool can be interactively debugged
using GDB. This method of debugging requires the use of the Tmux interface.
# Start the simulation with the SimBus running under GDB.
$ simer path/to/simulation -tmux -gdb model_inst -endtime 0.04 -timeout 5
# Start the simulation with a model and the SimBus running under GDB.
$ simer path/to/simulation -tmux -gdb simbus,model_inst -endtime 0.04 -timeout 5
GDB Server (remote)
Models running in a simulation can be debugged with GDB by indicating which model
is being debugged via the option -gdbserver
, and then connecting a GDB instance to
that model running “remotely” in the Simer simulation.
# Start the simulation and indicate the Model being debugged.
$ simer path/to/simulation -endtime 0.04 -tmux -gdbserver gdb_inst
# Start GDB (in a second terminal), and connect to the simulation.
$ gdb dse/modelc/build/_out/bin/modelc
(gdb) set solib-search-path path/to/simulation/lib
(gdb) target remote localhost:2159
(gdb) continue
(gdb) bt
Definitions
- Channel
- Represents a grouping of signals which are exchanged between models.
- GDB
- A tool for debugging software and investigating bugs (typically segmentation faults).
- Model (Definition)
- The definition of a model, specifying the location of libraries (for all supported os/arch combinations) as well as possible channel configurations.
- Model (distribution/binary)
- A packaged version of a model (including binaries and related artifacts).
- Model Instance
- An instance of a particular Model. Will include runtime properties.
- ModelC
- An implementation of a Model Runtime (i.e. Importer).
- Redis
- A data service used by ModelC instances to communicate with a SimBus. Redis is packaged in the Simer Container and started automatically (disabled by setting hidden parameter
-redis
to""
). - Remote Model
- A model configured in a simulation but which runs on a remote system.
- Signal Group
- A set, or subset, of signals which belong to a channel.
- SimBus (Simulation Bus)
- An implementation of a data exchange mechanism for scalar and binary signals.
- Simulation
- The structural arrangement of several Models, which, when connected via a Simulation Bus, form a simulation. Typically defined in a file
simulation.yaml
. - Simulation Package (simulation path/folder)
- This folder contains all configuration, models and artifacts necessary to run a simulation.
- Stack
- Defines a list of models which should be run as a part of a simulation. Simulations may be defined by one or more stacks.
- Stacked Models
- A list/collection of models which are stacked into a single ModelC runtime instance.
- Valgrind
- A tool used to detect memory leaks. Run with valgrind as a part of a model QA strategy (i.e. as a part of E2E tests).
- x32
- The linux x32 ABI architecture specifier, for models which must run as 32bit processes.
- i386
- The linux i386 ABI architecture specifier, for models which must run as 32bit processes.