/Bodylight.js-FMU-Compiler

Scripts and simple web service to compile FMU to Web Assembly embedded as Javascript object. It contains Docker container for sample instantiation.

Primary LanguageCGNU General Public License v3.0GPL-3.0

Bodylight.js FMU Compiler

stability-beta

This repository contains scripts and configuration facilitating compilation of FMU file (with source codes in C of compiled Modelica model and solver) to Javascript with embedded WebAssembly. Such compiled javascript allows to access model simulation via FMI API v 2.0 as specified in FMI standard.

  • FMU co-simulation mode with source codes and CVODE solver generated by Dymola is fully supported.
  • FMU co-simulation mode with source codes and Euler solver generated by OpenModelica is supported.
  • FMU co-simulation mode with source codes and CVODE solver generated by OpenModelica is being solved as issue #4

This repository also contains basic HTML and Python script as CGI script to support compilation on Linux platform with (EMSDK, GlibC,...).

To use Bodylight.js-FMU-Compiler, choose one of these options:

  1. compiler in virtual machine - Vagrant tool and VirtualBox is needed - see Bodylight-Virtualmachine
  2. compiler in local environment - needs to install EMSDK,GLIBC and PYTHON3 manually
  3. compiler in docker - needs docker to be installed in environment. This configuration is not maintained.

You may follow our tutorial at https://bodylight.physiome.cz/Bodylight-docs/tutorial/

1. Compiler in Virtual Machine

(Recommended) Install Bodylight-VirtualMachine using vagrant tool and VirtualBox. Instruction at https://github.com/creative-connections/Bodylight-VirtualMachine The compiler web service is available at http://localhost:8080/compiler

2. Compiler in Local Environmnet

(on your own risk) Be sure that EMSDK, GLIBC 2.18, Python 3 and CMake are installed e.g.

Bodylight.js-FMU-Compiler contains index.html and save-file.py to support compilation via simple web interface. Make the root of Bodylight.js-FMU-Compiler accessible for Apache web server, and the simple web form can be used. E.g.

Alias "/compiler" "/home/vagrant/Bodylight.js-FMU-Compiler/"
<Directory "/home/vagrant/Bodylight.js-FMU-Compiler">
  Options +ExecCGI
  AddHandler cgi-script .py
  Header set Access-Control-Allow-Origin "*"
  Require all granted
  Options +Indexes +FollowSymLinks +IncludesNOEXEC
  IndexOptions FancyIndexing HTMLTable NameWidth=*
  AllowOverride All
</Directory>

Allow access to input and output subdirectories of Bodylight.js-FMU-Compiler.

chmod ugo+rwx input output

3. Compiler in Docker Container

This is not recommended now as it is not maintained due to lack of contributors. This option uses docker container with all required software to run this compiler in any platform, uses older emsdk image.

Windows instructions

  1. Install docker

  2. Download this repository and open PowerShell in the top directory

If you decide to clone this repository, take care to disable automatic line ending conversion in git.

  1. Build the docker image
docker build -t bodylight.js.fmu.compiler .

This builds the Dockerfile as bodylight.js.fmu.compiler.

Usage

Put a name.fmu file into the input directory and run the following command in PowerShell inside the directory. Taking care to replace name.fmu at the end of the command with the name of your .fmu file.

docker run --rm --mount "type=bind,source=$(Get-Location)\input,target=/input" --mount "type=bind,source=$(Get-Location)\output,target=/output" bodylight.js.fmu.compiler:latest bash worker.sh name.fmu

After the compilation finishes, input/name.fmu is deleted and the resulting name.js file is copied to output. Along with the compilation log name.log.

Linux instructions

  1. Install docker

  2. Clone this repository and cd inside

  3. Build the docker image

docker build -t bodylight.js.fmu.compiler "$(pwd)"

This builds the Dockerfile as bodylight.js.fmu.compiler. You might need to run this command with root privileges.

Automatic compilation

Starting the compiler

docker run -d \
  --name bodylight.js.fmu.compiler \
  --mount type=bind,source="$(pwd)"/input,target=/input \
  --mount type=bind,source="$(pwd)"/output,target=/output \
  --rm bodylight.js.fmu.compiler:latest bash worker.sh

This starts the docker container and binds the input and output directories.

Stopping the compiler

docker stop bodylight.js.fmu.compiler

Usage

Put name.fmu files into the input directory. After the compilation finishes, input/name.fmu is deleted and the resulting name.js file is copied to output. Along with the compilation log name.log.

Files are processed sequentially in alphabetical order.

In case of error, only the compilation log will be present in the output directory.

Manual compilation

Put a name.fmu file into the input directory and run the following command inside the directory. Taking care to replace name.fmu at the end of the command with the name of your .fmu file.

docker run \
  --mount type=bind,source="$(pwd)"/input,target=/input \
  --mount type=bind,source="$(pwd)"/output,target=/output \
  --rm bodylight.js.fmu.compiler:latest bash worker.sh name.fmu

After the compilation finishes, input/name.fmu is deleted and the resulting name.js file is copied to output. Along with the compilation log name.log.

Examples

The following models were converted to web-based simulators using FMU compiler.

  • Simple Circulation - model published as part of Physiolibrary
    • Kulhánek T, Tribula M, Kofránek J, Mateják M: Simple models of the cardiovascular system for educational and research purposes. MEFANET Journal 2014; 2(2); ISSN:1805-9171. Available at WWW: http://mj.mefanet.cz/mj-04140914.
  • Nefron Simulation - model and Bodylight.js technology published as
    • ŠILAR, Jan, David POLÁK, Arnošt MLÁDEK, Filip JEŽEK, Theodore W KURTZ, Stephen E DICARLO, Jan ŽIVNÝ a Jiri KOFRANEK. Development of In-Browser Simulators for Medical Education: Introduction of a Novel Software Toolchain. Journal of Medical Internet Research [online]. 2019, 21(7) [cit. 2019-11-25]. DOI: 10.2196/14160. ISSN 1438-8871. Dostupné z: https://www.jmir.org/2019/7/e14160
  • Bodlight Scenarios - simulators using web components. Section of hemodynamics, blood-gases, iron metabolism and virtual body preparing for publication
  • Buddy - experimental simulator of most complex model of physiology Physiomodel

The simple and medium size models compile into Javascript with size 0.5 MB - 2 MB. The embedded WebAssembly is supported by 4 major web browsers (Firefox,Chrome,Ms Edge,Safari). The simulation is nearly native speed (1.5x or 2x slower). One drawback can be memory limit on some mobile devices, which may prevent to run some of the most complex model (see Buddy above) there.