Python API reference

The supported public Python surface for the biosimulant runtime. Use this section to choose the right interface, then follow the linked reference pages for lifecycle and data-contract details.

Installation

pip install "biosimulant>=0.0.20"

The compatibility ui extra is still accepted but no longer required for Local lab UI:

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

Choose an interface

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()
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.

• BioWorld API
• BioModule API
• HubComposition API

Managed Hub API

Use Client or AsyncClient only when you intentionally want to submit an accessible, versioned Hub Lab as a durable managed run:

from biosimulant import Client
 
with Client() as client:
    result = client.run("owner/lab@1.0.0", inputs={})

Managed execution is separate from BioWorld.run() and requires an API key. See the Developer API for Client, AsyncClient, durable runs, result artifacts, errors, and webhooks.

Architecture

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

API Reference

• BioModule API: Base interface for all composable simulation components.
• BioWorld API: Central orchestrator: lifecycle, events, scheduling.
• WiringBuilder API: Declarative composition: add modules and connect ports.
• BioSignal & Metadata: Message passing between modules.
• HubComposition API: Resolve exact, lockfile-pinned Hub Labs into a local world.
• Supported Python API surface: Exhaustive index of supported root imports.

Schemas

• model.yaml Schema: BioModule manifest format reference.
• lab.yaml Schema: Composed simulation manifest format reference.

Tools & Extensions

• Visualization Contract: Standard format for module visualization output.
• Domain Packs: Pre-built modules for neuroscience and ecology.
• Labs Serve UI: bundled local web UI for runnable labs.