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

# Reference

Reference pages for the `biosimulant` Python runtime and its [CLI](/references/cli).
Use this page to pick the right interface, then follow the links for lifecycle
and data-contract details.

**Info:**

  Looking for step-by-step instructions? See the [How-To Guides](/how-to).

## 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/biosim.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).

## 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 ──────────────┘
```