<!-- Source: https://docs.biosimulant.com/runtime -->

# 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](/runtime/quickstart) |
| Understand windows, signals and execution order | [How Biosimulant works](/runtime/concepts) |
| Write a model of your own | [Create a BioModule](/runtime/create-biomodule) |
| Wrap SBML, CellML, NeuroML or ONNX | [Wrap an external simulator](/runtime/wrap-external-simulator) |
| Wire several models together | [Use a BioWorld](/runtime/use-bioworld) |
| Look up a schema or an API | The reference pages in the sidebar |

**Info:**

  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](/overview/surfaces#running-local-or-managed).

## Installation

```bash
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:

```bash
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](https://github.com/Biosimulant/models)

## Local runtime

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

```python
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](/developer-api).

To pin a published lab and run it beside your own modules, see
[Compose Hub labs locally](/hub/compose-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 ──────────────┘
```