Biosimulant runtime

The Biosimulant runtime is the open-source Python package the rest of the platform is built on. Studio, the Developer API and the agent Gateway run the same labs on it. What changes between them is how you sign in and where the compute happens, not what executes.

MIT licensed, runs offline, no account needed. You do not have to install it to use Biosimulant — reach for it when you want to author models, run them on your own machine, or put either in your own CI.

Where to start

If you want to…	Go to
Run your first simulation in Python	Runtime quickstart
Understand windows, signals and execution order	How Biosimulant works
Write a model of your own	Create a BioModule
Wrap SBML, CellML, NeuroML or ONNX	Wrap an external simulator
Wire several models together	Use a BioWorld
Look up a schema or an API	The reference pages in the sidebar

Running a lab locally is free and puts results on your machine. It does not produce a managed Run or an Evidence Passport. See Running: local or managed.

Installation

pip install "biosimulant>=0.0.26"

ExecutionPolicy, ExecutionContext, and the execute() hook need 0.0.26 or later. The local lab UI ships with the default install. The old ui extra was removed in 0.0.15.

To install from a Git ref instead of PyPI:

pip install "biosimulant @ git+https://github.com/Biosimulant/biosimulant.git@<ref>"
biosimulant labs serve ./my-lab

For curated model packs, see the companion repo: github.com/Biosimulant/models

Local runtime

Use the open-source runtime to build and run simulations on your machine or in your own CI:

from biosimulant import BioWorld
from biosimulant.hub import HubComposition
 
world = BioWorld(communication_step=0.1)
composition = HubComposition(world, lab_root="./lab")

BioWorld and BioModule are the core local composition interface. HubComposition explicitly resolves exact, lockfile-pinned Hub Labs into that same local world; it never turns a Python import into a network request.

Client and AsyncClient are separate. They submit a versioned Hub Lab as a managed run and need an API key. See the Developer API.

To pin a published lab and run it beside your own modules, see Compose Hub labs locally.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                       BioWorld                               │
│           (Orchestrator + Event Queue)                       │
│                                                              │
│  Events: STARTED → STEP* → FINISHED                          │
└─────────────────────────────┬───────────────────────────────┘
                              │
         ┌────────────────────┼────────────────────┐
         │                    │                    │
         ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   BioModule     │  │   BioModule     │  │   BioModule     │
│  (Neuron Pop)   │  │  (Monitor)      │  │  (Metabolism)   │
│                 │  │                 │  │                 │
│ in: current     │  │ in: spikes      │  │ in: params      │
│ out: spikes     │──│                 │  │ out: species    │
└─────────────────┘  └─────────────────┘  └─────────────────┘
         │                                         │
         └─────────────── BioSignals ──────────────┘

How Biosimulant works