Builder - Simulation Development Platform

Tags:

Synopsis

Containerised simulation builder and supporting DSE Language (DSE Lang).

Describe a Simulation

simulation arch=linux-amd64
channel network

uses
dse.fmi https://github.com/boschglobal/dse.fmi v1.1.32

model fmu_CAN dse.fmi.network_model
    channel network network_channel

workflow generate-model
    var NETWORK_SIGNAL can_bus
    var MIME_TYPE "application/x-automotive-bus;interface=stream;type=frame;bus=can;schema=fbs;bus_id=1;node_id=2;interface_id=3"
    var MEASUREMENT measurement.txt
    var OUT_DIR {{.PATH}}/data

workflow generate-fmimodelc
    var FMU_NAME example
    var SIGNAL_GROUPS network

Use the Builder Tool

# Build a simulation.
$ cd examples/runnable
$ builder runnable.dse
$ task -y

Run the Simulation

# Run a simulation.
$ simer out/sim -stepsize 0.0005 -endtime 0.10

DSE Lang

Simulations using the Simulation Development Platform (SDP) are written in a custom DSL language: colloquially called ‘DSE Lang’. This language is used to describe the construction of a simulation and its constituent channels, models and workflows.

Simulation

simulation [arch=ARCH]
[channel CHANNEL_NAME] ...
  • ARCH: the architecture of the overall simulation. Select from supported platforms, including:
    • linux-amd64
    • linux-x86
    • linux-i386
    • windows-x64
    • windows-x86
  • CHANNEL_NAME: the name of a simulation channel. Repeat for each channel of the simulation.

Uses

uses
[USES_NAME URI [VERSION] [path=PATH] [user=USER] [token=TOKEN]] ...
  • USES_NAME: the name of the uses item.
  • URI: a URI for the uses item. May be a URL or file.
  • VERSION: the version of the uses item.
  • PATH: a sub-path of the uses item (incase the item should be extracted from a ZIP archive).
  • USER: authentication user needed for retrieving the _uses_item.
  • TOKEN: authentication token (or password) needed for retrieving the _uses_item.

Stack

stack STACK_NAME [arch=ARCH]
  • STACK_NAME: the name of the stack.
  • ARCH: the architecture of this stack and the models it contains.

Model

model MODEL_INST_NAME MODEL_NAME [arch=ARCH]
[channel CHANNEL_NAME CHANNEL_ALIAS] ...
  • MODEL_INST_NAME: the name of the model (used within the simulation).
  • MODEL_NAME: the name of the model as referenced by a uses item.
  • ARCH: the architecture of this model.
  • CHANNEL_NAME: the name of a simulation channel to be mapped to this model.
  • CHANNEL_ALIAS: the model alias for the channel being mapped.

Workflow

Workflow WORKFLOW_NAME
[var VAR_NAME VAR_VALUE] ...
[var VAR_NAME uses USES_NAME] ...
  • WORKFLOW_NAME: the name of the workflow.
  • VAR_NAME: the name of a variable used by this workflow.
  • VAR_VALUE: the variable value.
  • USES_NAME: sets the variable value to the path of this uses item.

Special Variables

DSE Lang uses a templating mechanism to introduce special variables to a DSE Script. Those variables are used to influence how a simulation is constructed. Additionally, the templating mechanism can be used to introduce environment variables to a DSE Script (useful for authentication).

{{.ENV_VAR}} : Expands to the named ENV_VAR.

{{.MODEL}}
When used within the context of a model expands to the models name (i.e. MODEL_INST_NAME).
{{.OUTDIR}}
The output directory of the SDP toolchains (typically out). Contains the simulation folder.
{{.PATH}}
When used within the context of a model expands to the models path within the simulation filesystem (set to SIMDIR/MODEL_INST_NAME).
{{.SIMDIR}}
The simulation folder (typically sim).

Builder Tool

Info: The Builder Tool is already setup and configured in both GitHub Codespaces and Dev Containers environments.

Setup

The SDP Builder is a containerized tool which can be configured and used in a Linux environment. The following container images are available.

# Latest Builder Container:
$ docker pull ghcr.io/boschglobal/dse-builder:latest

# Specific versions of the Builder Container
$ docker pull ghcr.io/boschglobal/dse-builder:1.0.4
$ docker pull ghcr.io/boschglobal/dse-builder:1.0

Shell Function

TODO: This section needs to be updated.

# Define a shell function (or add to .profile file).
$ export BUILDER_IMAGE=ghcr.io/boschglobal/dse-builder:latest
$ builder() { ( if test -f "$1"; then cd $dirname("$1") && shift; fi && docker run -it --rm -v $(pwd):/workdir $BUILDER_IMAGE "$@"; ) }

# Build the simulation.
$ builder examples/runnable/runnable.dse

Authentication

TODO: This section needs to be updated.