Builder - Simulation Development Platform

Synopsis

Containerised simulation builder with DSL (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 called DSE Lang. This DSL is used to describe the construction of a simulation and its constituent channels, models and workflows.

@startuml

@startebnf dse-lang-syntax

title DSE Lang Syntax

(* Simulation Structural Elements *)

simulation = "simulation", [ "arch=", ARCH ], [ "stepsize=", STEP_SIZE ], [ "endtime=", END_TIME ];
channel = { "channel", CHANNEL_NAME, { "network", NETWORK_NAME, MIMEtype}- }-;
uses = {USES_NAME, URI, [ VERSION ], [ "path=", PATH ], [ "user=", USER ], [ "token=", TOKEN ]}-;
var = { "var", VAR_NAME, VALUE}-;
stack = "stack", STACK_NAME, [ "stacked=", ( "false" | "true" ) ], [ "sequential=", ( "false" | "true" ) ], [ "arch=", ARCH ];

(* Model Construction Elements *)

model =
    "model", MODEL_NAME,
    (
        MODEL, [ "external=", ( "false" | "true" ) ]
      | "external=", ( "false" | "true" )
    ),
    [ "arch=", ARCH ],
    [ "uid=", UID ];
channel = { "channel", CHANNEL_NAME, CHANNEL_ALIAS }-;
envar = { "envar", ENVAR_NAME, VALUE }-;
file = { "file", MODEL_FILE, FILE_SOURCE }-;


workflow = 
    "workflow", NAME, [ "uses ", USES_NAME ],
    {[ "var", VAR_NAME, (VALUE | "uses", USES_NAME | "var", VAR_NAME)]}-;
@endebnf

@enduml

Channel (Model)

channel CHANNEL_NAME CHANNEL_ALIAS

• CHANNEL_NAME: the name of a simulation channel.
• CHANNEL_ALIAS: the alias used by the model for this channel.

Channel (Simulation)

channel CHANNEL_NAME
[network NETWORK_NAME MIME_TYPE] ...

• CHANNEL_NAME: the name of a simulation/model channel.
• NETWORK_NAME: the name of the network.
• MIME_TYPE: the network’s protocol, format, and attributes.

Envar

envar ENVAR_NAME VAR_VALUE

• ENVAR_NAME: the name of a environment variable.
• VAR_VALUE: the variable value.

File

file MODEL_FILE FILE_SOURCE

• MODEL_FILE: the name by which the model refers to the file.
• FILE_SOURCE: the actual path of the file.

Model

model MODEL_INST_NAME MODEL_NAME [external=EXTERNAL] [arch=ARCH] [uid=UID]
[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.
• EXTERNAL: the boolean flag indicating that the model is external, either a complete external model or one linked with workflows.
• ARCH: the architecture of this model.
• UID: the unique id of the 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.

Simulation

simulation [arch=ARCH] [stepsize=STEP_SIZE] [endtime=END_TIME]
[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
• STEP_SIZE: the time increment for each simulation step (default : 0.0005).
• END_TIME: the total simulation duration (default : 0.005).

Stack

stack STACK_NAME [stacked=STACKED] [sequential=SEQUENTIAL] [arch=ARCH]

• STACK_NAME: the name of the stack.
• STACKED: the boolean flag that indicates if the models in a stack should be layered.
• SEQUENTIAL: the boolean flag for stacks that ensures models are executed one after another, in a defined order.
• ARCH: the architecture of this stack and the models it contains.

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.

Var

var VAR_NAME VAR_VALUE

• VAR_NAME: the name of a variable.
• VAR_VALUE: the variable value.

Workflow

Workflow WORKFLOW_NAME [uses USES_NAME]
[var VAR_NAME VAR_VALUE] ...
[var VAR_NAME uses USES_NAME] ...

• WORKFLOW_NAME: the name of the workflow.
• USES_NAME (workflow level): the name of a dependency that this workflow imports.
• VAR_NAME: the name of a variable used by this workflow.
• VAR_VALUE: the variable value.
• USES_NAME (variable level): 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 (in the form: {{ .SPECIAL_VAR }}). 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

Info: The following shell function passes credentials to the Build Container which are used to fetch artifacts and repository metadata. Adjust as necessary for your environment (the -e parameters of the docker command).

# 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"); fi && docker run -it --user $(id -u):$(id -g) --rm -e AR_USER -e AR_TOKEN -e GHE_USER -e GHE_TOKEN -e GHE_PAT -v $(pwd):/workdir $BUILDER_IMAGE "$@"; ) }

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

# And then use Task to complete the simulation (according to the build plan).
export TASK_X_REMOTE_TASKFILES=1
$ task -y -v
ls -R out/sim

Authentication

Any uses items in your DSE Script which require authentication credentials need to be defined in your environment and passed to the builder container. For example the following DSE Script uses a private GitHub repository and Artifactory instance:

simulation arch=linux-amd64
channel signal

uses
fsil.runnable https://{{.GHE_TOKEN}}@github.boschdevcloud.com/fsil/fsil.runnable v1.1.2 user={{.AR_USER}} token={{.AR_TOKEN}}

and needs the following authentication setup:

# Define authentication tokens.
export AR_USER=foo
export AR_TOKEN=foo_token
export GHE_TOKEN=goo_token

# Specify the shell function.
$ builder() { ( if test -f "$1"; then cd $(dirname "$1"); fi && docker run -it --user $(id -u):$(id -g) --rm -e AR_USER -e AR_TOKEN -e GHE_TOKEN -v $(pwd):/workdir $BUILDER_IMAGE "$@"; ) }