---
name: biosimulant-sbml
title: Biosimulant SBML Labs
description: Create and polish SBML-backed Biosimulant labs using TelluriumSBMLBioModule while preserving SBML source fidelity.
version: 2026.05.23
tags: [biosimulant, sbml, tellurium, biomodels, source-faithful]
audience: Claude Code, Cursor, Continue, Aider
recommended: false
---

# Biosimulant SBML Labs

Use this skill for SBML-backed Biosimulant labs.

Biosimulant wraps the source SBML model in a `BioModule`, wires it through `lab.yaml`, emits runtime signals, and uses
visualisation modules plus README evidence for publication.

## Runtime Standard

Use `biosimulant.contrib.sbml.TelluriumSBMLBioModule` for kept SBML simulator models. The bundled SBML/XML file is the
scientific source of truth, and open-source Tellurium/RoadRunner execution should run that SBML directly.

Do not manually reimplement SBML equations, parameters, units, reactions, species, or initial values.

## Wrapper Shape

```python
from biosimulant.contrib.sbml import TelluriumSBMLBioModule


class ExampleModel(TelluriumSBMLBioModule):
    _SBML_ID = "BIOMD0000000000"
    _TITLE = "Example SBML Model"
    _TIME_UNIT = "model_time"
    _OBSERVABLE_STRATEGY = "species"
    _OBSERVABLES = ["S1", "S2"]
    _SPECIES_LABELS = {"S1": "Substrate", "S2": "Product"}
    _PARAMETER_INPUTS = {
        "stimulus_strength": ("stimulus", 1.0, "dimensionless", "External stimulus parameter.")
    }
    _HEADLINE_OUTPUTS = {
        "substrate": ("S1", "native SBML value", "Substrate. Maps to SBML species `S1`.")
    }
```

Preserve the stable class alias referenced by `models/core/model.yaml`.

Example public mapping:

```yaml
io:
  inputs:
    - name: initial_substrate_concentration
      maps_to: core.initial_substrate_concentration
      description: Initial value for SBML species `S1`; does not alter reaction laws.
  outputs:
    - name: product_concentration
      maps_to: core.product
      description: Product species trajectory. Maps to SBML species `S2`.
```

## Inputs And Outputs

Expose public inputs only when they map to real SBML parameters, boundary species, initial conditions, or documented
stimulus/protocol controls.

Expose outputs as:

- `state`
- `summary`
- `species_labels`
- selected source-backed species or observables

Use friendly names and keep raw SBML symbols in `maps_to`, descriptions, labels maps, and README mappings.

## Scientific Validation

Confirm:

- SBML artifact exists
- upstream BioModels/source metadata is traceable
- Tellurium loads the model
- simulation succeeds
- outputs are finite and non-empty
- headline outputs map to real SBML symbols
- public inputs change real source-backed parameters or initial conditions

Do not call a lab scientifically accurate if it only validates file structure.

## Visuals

Good SBML visuals include:

- species trajectories
- final species ranking
- source/runtime evidence table
- Q/A table answering the lab-specific biological question
- steady-state evidence when outputs are flat

Use desktop schemas: bar `data.items`, timeseries `data.series[*].points`, scatter `data.points`.

## Orphan Rules

Orphan SBML labs when:

- the source artifact is missing
- the SBML cannot load
- simulation fails and cannot be fixed by packaging/runtime changes
- public labels would require invented biology
- the lab is out of scope or scientifically misleading