Digital Twin Assembly

Digital Twin Assembly (dtasm) is a binary interface (ABI) for executable numerical simulators compiled into WebAssembly modules. Such simulators implement methods for dynamically stepping forward in discrete time steps, where in each step, the simulator takes values for its declared input variables, performs the time step calculation, and emits values for its declared output variables at the end of the time step. dtasm is based on WebAssembly, WASI and FlatBuffers. See here for a specification of the ABI. An in-depth description of dtasm with a discussion of advantages and drawbacks has been presented at the Modelica 2021 conference.

Contents

This repository contains various implementations of dtasm runtimes and modules for demonstration purposes. It is not meant as a finished product or reference implementation of the dtasm interface, but rather as a starting point for compiling and running numerical simulators as WebAssembly modules.

The main components of this repository are:

• dtasmtime - A Rust library implementing a runtime for dtasm modules based on Wasmtime. An example command-line program using this library for loading and executing dtasm modules can be found in runtime/examples/dtasmtime_rs.
• dtasmtime-c-api - C API for dtasmtime, allowing the library to be called from C/C++, as well as other languages with C interop capabilities. An example command-line program in C that uses this library can be found in runtime/examples/dtasmtime_c.
• dtasm3 - A lightweight C++ runtime for dtasm modules based on wasm3. Due to efficiency and low footprint of wasm3, this runtime is a good fit for smaller hardware or an MCU (Raspberry Pi, ESP32). An example for using this runtime can be found in runtime/examples/dtasm3_main.
• dpend_cpp - Exemplary dtasm module implementing a double pendulum simulator (based on example code by M. Wheatland.
• dpend_rs - Same double pendulum simulator written in Rust.
• add_rs - Simple test module adding (or concatenating, anding) two inputs of each type.

Getting started - Dev Containers

The easiest way to obtain all necessary dependencies for building and running the code in this repo is using Visual Studio Code with the Dev Containers extension (this will also need an installation of Docker). Clone the repo including submodules (git clone --recurse-submodules ...), then open the repo folder in VS Code. It will prompt you to open inside a Dev Container, select 'Reopen in Dev Container' (if it does not prompt, select 'View' -> 'Command Palette' -> 'Dev Containers: Rebuild and Reopen in Container'). Initial building of the Dev Container and downloading of toolchains will take quite some time, wait until the process is finished and then proceed with build.

Getting Started - Manual

The following prerequisites are needed:

• Linux or Windows OS on x86_64 or aarch64 platform (except for dtasm3 which also supports many smaller platforms, see here)
• Rust, cargo and wasm32-wasi target for the active Rust toolchain (if using rustup, this can be installed by running rustup target add wasm32-wasi)
• C/C++ compiler (e.g. gcc/g++)
• GNU make
• cmake
• WASI SDK (version >= 12) installed into the default location at /opt/wasi-sdk
• xxd tool (e.g. sudo apt install xxd).

Once the prerequisites are installed, be sure to clone the repo including submodules (git clone --recurse-submodules ...), then proceed with the build section.

Build

A top-level Makefile is provided for convenience to build the components. Running

make deps

will first build the FlatBuffers compiler flatc, then create all needed FlatBuffer stubs and buffers required by the components. Running

make

builds dtasmtime, the Rust command-line example and the Rust double pendulum module. You can execute the module by running make run-rs afterwards.

The same can be done for the C/C++ API and double pendulum simulator by running make cpp followed by make run-c. Finally, some examples using dtasm3 can be run with make run-dtasm3.

License

This project is released under the MIT License.