Add a training simulator to your Bonsai workspace

The follow content supports the ASSEMBLE phase in the Bonsai user journey

Warning

Any time you run simulators that are managed by Bonsai, your Azure subscription is charged. Test your simulator locally and confirm it works as expected before scaling.

Training simulations are virtual environments that model the behavior of a physical environment and the interactions of objects or agents based in that environment for the sake of training an AI brain. The observable state of a simulator is the data set that represents the virtual environment at a given point in time. Typically, the observable state includes measurements that would be taken by sensors connected to an AI being trained, for example: cameras, temperature gauges, or depth sensors.

The Functional Mockup Interface (FMI) defines the Functional Mockup Unit (FMU) file format. FMI lets you create your model with whatever tool works and export an FMU file to add your training simulation to Bonsai.

Important

Currently, Bonsai does not import FMU files directly. You must package your FMU files in a zip file before uploading.

In programming, a container is an executable software bundle that includes everything needed to run an application including any supporting files or technology used to run a piece of code. To effectively scale the number of simulator instances available for machine teaching, you need to "containerize" your simulator before adding it to Bonsai.

Bonsai supports native Python upload without the need for custom Docker images or the Azure Container Registry.

Before you start

  • Your simulator must be able to export FMU files.
  • Your FMU files must be co-simulation version 2.0 and executable on Windows.
  • You must have a requirements.txt file. Bonsai uses the requirements file to install the correct Python dependencies during upload. If you do not have a requirements file, you can use pip freeze > requirements.txt to create one.
  • You must have a main.py file that connects to Bonsai. If you have not worked with the Bonsai Python SDK before, review one of the available Python samples before continuing.
  • You must use a supported Python version. Bonsai currently supports Python 3.7, 3.8, 3.9, and 3.10 built from the python:<version> image variant.

Step 1: Prepare your simulator

Follow the directions in the Wrapper Model Workflow PDF to integrate and configure the wrapper for your simulator.

To add a FlexSim simulation to your Bonsai workspace, you need to create a zip file by follow the instructions in the FlexSim Getting Started with Bonsai guide.

Causality variables in your FMU file are referenced by the Inkling used to train the brain and used to control your simulation during training. See the simulator keyword for more information about Action, Config, and State types.

Causality variable Description Fields in Bonsai
Parameter Parameter variables are used to configure the initial conditions of simulation episodes. Config type structure
Input Input variables are used to control the FMU simulation. Action type structure
Output Output variables are used to update the brain on the state of the simulation. State type structure

Tip

Syncing your Parameter, Input, and Output variables with your Inkling configuration, action, and state types is sufficient for communicating between your FMU simulator and Bonsai. But you can also provide Bonsai with additional information using built-in FMU variables.

To add your custom simulator you need to package it as a Docker container and add it to Azure Container Register (ACR).

  1. Create a Dockerfile for your simulation code.
  2. Log into your Azure Container Registry (ACR) instance:
    az acr login --name ACR_NAME
    
  3. Build an image from your Dockerfile with a unique name and version tag:
     az acr build             \
       --image IMAGE_NAME:TAG \
       --registry ACR_NAME    \
       --file Dockerfile .
    
  4. Verify the upload succeeded by checking the list of images in your registry:
    az acr repository list --name ACR_NAME --output table
    

Tip

The az acr build command runs the build as a task directly on ACR and can timeout when building a large container. If you find your builds are timing out, use the --timeout flag to increase the timeout limit.

You must create a zip package of your Python project to upload your simulator to Bonsai. The root folder can be named or unnamed, but must include the requirements.txt and main.py file.

For example, both of the following structures will upload successfully when zipped:

MySimProject
|
- requirements.txt
- main.py
- file1.py
- simulator.py

or

- requirements.txt
- main.py
- file1.py
- simulator.py

Follow the directions in the README file to integrate and configure the toolbox for your simulator.

To add a VP Link simulation to your Bonsai environment, you need to create a zip file, sim.zip, that includes the following:

  • vplink_interface.json: a JSON file generated by the VPLinkSim_Bonsai3 tool. The interface file describes all VP Link tags used in your Inkling file for the SimState and SimAction structures.
  • cfg: a directory containing one or more tag file (.tag) and optional snapshot files (**.icf) for your VP Link simulation. Bonsai uses VP Link snapshots to initialize the simulation model at the start of each episode as indicated by the lesson statements in your Inkling code. If you include multiple tag files, the tags in each file should be unique.
  • data: a directory containing any other files your model requires to run. For most users, the data directory will be empty.
  • sces: an empty directory. Bonsai uses this directory to save the VP Link scenarios that get run during a training or assessment episode.

To create your zip bundle:

  1. Run the VPLinkSim_Bonsai3 executable.
  2. Use the Add tags to State button to select the relevant tags for your simulator states.
  3. Use the Add tags to Button button to select the relevant tags for your simulator actions.
  4. Push the Build Bonsai Interface button to create your vplink_interface.json file.
  5. Push the Create Bonsai Loadable button to create your sim.zip file for upload.

VP Link tool

creating the zip package for upload.

Step 2: Add the simulator to your Bonsai workspace

This is the easy part!

Note

We recommend the following defaults for most simulators:

  • Cores: 1
  • Memory: 1 GB
  1. Click + Add sim next to the Simulators list in the Bonsai UI.
  2. Select "AnyLogic" from the list of simulator types.
  3. Select your AnyLogic file for upload.
  4. Provide a display name for your simulator package for Simulator package display name.
  5. If you have multiple managed simulator offers installed, select the appropriate offer for Managed offer.
  6. Click the Create simulator button to add your simulator package to the Simulators list.

Tip

AnyLogic will automatically bundle your simulator into a single package that includes all the required files. In the exported model folder, you can safely delete the chromium folder to save on drive space.

AnyLogic sim upload

Screenshot of the AnyLogic simulator upload dialog box.

  1. Click + Add sim next to the Simulators list in the Bonsai UI.
  2. Select "FlexSim" from the list of simulator types.
  3. Select your FlexSim file for upload.
  4. Provide a display name for your simulator package for Simulator package display name.
  5. If you have multiple managed simulator offers installed, select the appropriate offer for Managed offer.
  6. Click the Create simulator button to add your simulator package to the Simulators list.

FlexSim sim upload

Screenshot of the FlexSim simulator upload dialog box.

  1. Click + Add sim next to the Simulators list in the Bonsai UI.
  2. Select FMU from the list of simulator types.
  3. Select, or drag and drop, your FMU zip package.
  4. Provide a display name for your simulator package.
  5. Click the Create simulator button to add your simulator package to the Simulators list.

FMU sim upload

Screenshot of the FMU simulator upload dialog box.

You can upload custom simulators through the Bonsai UI or the CLI.

You can publish the ACR image as a simulator package using the Bonsai CLI. For example:

bonsai simulator package container create -n clientmoabdemo:latest \
   -u bonsaisimdev.azurecr.io/clientmoabdemo:latest \
   --i 500 \
   --min-instance-count 50 \
   --max-instance-count 500 \
   -r 0.25 \
   -m 0.5 \
   --auto-scale True \
   -p Linux
  1. Click + Add sim next to the Simulators list in the Bonsai UI.
  2. Select "Python" from the list of simulator types.
  3. Select your zip file for upload.
  4. Provide a display name for your simulator package.
  5. Click the Create simulator button to add your simulator package to the Simulators list.

Python sim upload

Screenshot of the Python simulator upload dialog box.

  1. Click + Add sim next to the Simulators list in the Bonsai UI.
  2. Select "Simulink" from the list of simulator types.
  3. Select your Simulink file for upload.
  4. Provide a display name for your simulator package.
  5. Click the Create simulator button to add your simulator package to the Simulators list.

Simulink sim upload

Screenshot of the Simulink simulator upload dialog box.

  1. Click + Add sim next to the Simulators list in the Bonsai UI.
  2. Select "VP Link" from the list of simulator types.
  3. Select your VP Link zip file (sim.zip) for upload.
  4. Provide a display name for your simulator package.
  5. Click the Create simulator button to add your simulator package to the Simulators list.

VP Link sim upload

Screenshot of the VP Link simulator upload dialog box.

Tip

When you upload a new simulator you can automatically generate Inkling code for SimState and SimAction structures. The generated code includes comments for each member of the SimState and SimAction that indicate allowable values and value ranges. Select a simulator and click the Create brain button to create a new brain with Inkling code matching your simulator structures.

Step 3: Scale the simulator

Important

Azure quotas are credit limits, not capacity guarantees. As a result, Azure limits the number of container instances you can spin up based on your subscription. Azure subscriptions typically limit resource use across a given time period (scoped hourly) or across the entire subscription. If you have large-scale capacity needs, you should contact Azure support or increase your Azure quota.

After you upload your simulator to Bonsai, you can assign it to your training session using Inkling or the UI. Bonsai will automatically spin up multiple instances of the simulator to train at scale.

  1. Select the Teach tab to open your Inkling file.
  2. Find the simulator clause in Inkling.
  3. Assign the simulator package name to be the display name you set previously:
    source simulator (Action: Action, Config: SimConfig): State {
      package "example-sim"
    }
    
  4. Click the Train button to begin training.