ode2sbml 0.1.1

Convert Python ODE systems to SBML (Level 3 Version 2) and PEtab bundles

ode2sbml

Convert Python ODE systems to SBML (Level 3 Version 2) and PEtab bundles.

ode2sbml is a Python package that converts ordinary differential equation (ODE) systems written in Python into valid SBML Level 3 Version 2 files and optionally PEtab bundles for parameter estimation.

---

Installation

pip install ode2sbml

Or install from source:

git clone https://github.com/bibymaths/ode2sbml.git
cd ode2sbml
pip install -e .

Dependencies (installed automatically):

• python-libsbml >= 5.20
• sympy >= 1.12
• sbmlmath >= 0.3
• petab >= 0.4
• click >= 8.0
• rich >= 13.0
• numpy >= 1.24
• pydantic >= 2.0

---

Quick Start

Convention A — scipy-style function

from ode2sbml import from_function, to_sbml

def lotka_volterra(t, y, p):
    x, y_val = y
    alpha, beta, delta, gamma = p
    dx = alpha * x - beta * x * y_val
    dy = -gamma * y_val + delta * x * y_val
    return [dx, dy]

model = from_function(
    func=lotka_volterra,
    state_vars=["x", "y"],
    param_names=["alpha", "beta", "delta", "gamma"],
    initial_conditions={"x": 10.0, "y": 5.0},
    parameter_values={"alpha": 1.1, "beta": 0.4, "delta": 0.1, "gamma": 0.4},
    model_id="lotka_volterra",
    model_name="Lotka-Volterra",
)

to_sbml(model, "lotka_volterra.xml")

Convention B — dict-of-formulas

from ode2sbml import from_dict, to_sbml

model_spec = {
    "species": {"S": 990.0, "I": 10.0, "R": 0.0},
    "parameters": {"beta": 0.3, "gamma": 0.1},
    "odes": {
        "S": "-beta*S*I",
        "I": "beta*S*I - gamma*I",
        "R": "gamma*I",
    },
    "compartments": {"host": 1.0},
}

model = from_dict(model_spec, model_id="sir", model_name="SIR Epidemic Model")
to_sbml(model, "sir_model.xml")

Convention C — SymPy symbolic system

import sympy as sp
from ode2sbml import from_sympy, to_sbml

x, y, z = sp.symbols("x y z")
sigma, rho, b = sp.symbols("sigma rho b")

odes = {
    x: sigma * (y - x),
    y: x * (rho - z) - y,
    z: x * y - b * z,
}
params = {sigma: 10.0, rho: 28.0, b: 8.0 / 3.0}
inits = {x: 0.0, y: 1.0, z: 0.0}

model = from_sympy(odes=odes, params=params, inits=inits,
                   model_id="lorenz", model_name="Lorenz System")
to_sbml(model, "lorenz.xml")

---

PEtab Export

from ode2sbml import from_dict, to_petab

model = from_dict(model_spec, model_id="sir", model_name="SIR")
yaml_path = to_petab(model, outdir="petab_bundle/", observables={
    "obs_I": {"formula": "I", "noise_formula": "0.1 * I"},
})
print(f"PEtab bundle written. Manifest: {yaml_path}")

---

CLI

# Convert a Python model file to SBML
ode2sbml convert model.py --output model.xml --format sbml

# Convert to PEtab bundle
ode2sbml convert model.py --output ./bundle/ --format petab

# Validate an SBML file
ode2sbml validate model.xml

---

Supported SBML Features

Feature	Supported
SBML Level 3 Version 2	✅
Compartments	✅
Species (state variables)	✅
Parameters	✅
Rate rules (ODEs)	✅
Assignment rules	✅
Events (with triggers)	✅
Unit definitions	✅
Model notes	✅
MathML via sbmlmath	✅
libsbml consistency check	✅
PEtab bundle export	✅
JSON serialization (IR)	✅
Reactions / stoichiometry	❌ (use RateRules)
Spatial SBML	❌

---

API Reference

Parsers

• from_function(func, state_vars, param_names, initial_conditions, parameter_values, ...) — Convention A
• from_dict(model_dict, ...) — Convention B
• from_sympy(odes, params, inits, ...) — Convention C

Exporters

• to_sbml(model, filepath) — Write SBML Level 3 Version 2 XML
• to_petab(model, outdir, observables, ...) — Write PEtab bundle

Validators

• validate_sbml_file(filepath) — Validate from file
• validate_sbml_string(xml_str) — Validate from string
• validate_sbml_doc(doc) — Validate libsbml document

IR Classes

• ODEModel, Compartment, Species, Parameter, RateRule, AssignmentRule, EventTrigger

---

References

• Hucka M. et al. (2003). The systems biology markup language (SBML). Bioinformatics.
• Schmiester L. et al. (2021). PEtab. PLOS Computational Biology.
• Müller W. et al. (2021). yaml2sbml. JOSS.
• Watanabe L. et al. (2019). SBMLtoODEpy. JOSS.
• SBML Level 3 Version 2 Specification
• libsbml Python API
• sbmlmath documentation
• PEtab documentation

---

License

MIT — see LICENSE.