Add a training simulator to your Bonsai workspace

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.

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.

Important

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.

Before you start

  • You must have the Azure CLI installed.
  • You must have Docker installed on your local machine. The community edition of Docker is available for Windows, Linux, and MacOS.
  • You must have read/write access to Azure Container Registry (ACR). Bonsai provides a default ACR when you provision a workspace under the same resource group as the workspace.

Step 1: Prepare 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 you 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

Screenshot of the VP Link tool UI used to generate an upload package for Bonsai. The bulk of the UI is made up of tag selectors for Action and State. There are two buttons in the bottom right of the UI for building the interface file and creating the zip package for upload.

  1. Download the Bonsai wrapper for Anylogic.
  2. Follow the directions in the Wrapper Model Workflow PDF to integrate and configure the wrapper for your simulator.
  1. Install the Microsoft Project Bonsai Simulink Toolbox
  2. Follow the directions in the README file to integrate and configure the toolbox for your simulator.

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.

Step 2: Add the simulator to your Bonsai workspace

This is the easy part!

  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.

  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.
  5. 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 "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.

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

Alternatively, you can publish an 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

Tip

We recommend the following defaults for most simulators:

  • Cores: 1
  • Memory: 1 GB
  • Operating system: Linux

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.

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.

Once your simulator is uploaded to your Bonsai workspace, 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.