Skip to content

sbmlsim: SBML simulation made easy

GitHub Actions CI/CD Status Documentation Version Python Versions MIT License DOI

sbmlsim is a python library for simulating models in the Systems Biology Markup Language (SBML), the exchange format for models in systems biology (Keating et al. 2020). It runs on the fast simulator libroadrunner (Welsh et al. 2023), or on COPASI (Hoops et al. 2006) or AMICI (Fröhlich et al. 2021) as a second and a third engine, see Engines, and adds what a simulation study needs around it: doses and other changes at given times, values with units, parameter scans, comparisons with experimental data, figures and reports, parameter fitting, and sensitivity and uncertainty analysis. The source code is on GitHub.

New to sbmlsim?

Install the package with pip install sbmlsim, then work through the Tutorial. It takes one drug model from a first simulation to a parameter fit and an uncertainty analysis, one small step at a time.

A first simulation

sbmlsim ships a whole body model of midazolam, a sedative which the liver turns into 1-hydroxymidazolam. This simulation gives a 7.5 mg tablet every 8 hours and follows both substances in the blood for a day:

import matplotlib.pyplot as plt

from sbmlsim import Q
from sbmlsim.plot import label_axes
from sbmlsim.resources import MIDAZOLAM_SBML
from sbmlsim.simulation import Change, Simulation
from sbmlsim.simulator import Simulator

simulator = Simulator()
simulation = Simulation(
    time_unit="hr",
    end=24,
    changes=[Change([0, 8, 16], {"PODOSE_mid": Q(7.5, "mg")})],
)
res = simulator.run(MIDAZOLAM_SBML, simulation)

fig, ax = plt.subplots(figsize=(8, 3.5))
for sid, name in [("[Cve_mid]", "midazolam"), ("[Cve_mid1oh]", "1-hydroxymidazolam")]:
    ax.plot(res.q["time"].to("hr"), res.q[sid].to("nM"), label=name)
label_axes(ax, "time", "venous blood")
ax.legend(loc="center left", bbox_to_anchor=(1, 0.5))

Output figure

The times are in hours and sbmlsim converts them into the minutes of the model. res is a ScanResult with every variable of the model at the time points the integrator chose. res.q[...] gives a variable as a quantity, its values with their unit, so .to("nM") converts the concentrations from the mmol/l of the model. Quantities plot directly with matplotlib, and label_axes writes the units of the axes into their labels. The Tutorial starts from here and goes step by step through the features with a model of another drug.

Features

Core:

  • Models: load SBML models, inspect them and set default changes.
  • Simulations: timecourses with changes before the start and at given times, e.g. repeated doses.
  • Observables: values computed from every simulation, such as a peak concentration or a pharmacokinetic analysis.
  • Units: give values in the units you have; sbmlsim converts them into the units of the model.
  • Simulation experiments: models, data, simulations and figures of one study in one reproducible python class.
  • Data: simulation results and experimental datasets, side by side in matching units.
  • Plots and reports: figures as images or interactive HTML pages, and reports of experiments.

Sensitivity and uncertainty:

  • Parameter scans: run a simulation over ranges of values, in parallel if you like.
  • Sampling: draw parameters from distributions, e.g. a virtual population.
  • Uncertainty: propagate uncertain inputs and test statements about the predictions.
  • Sensitivity analysis: local sensitivities and the global Sobol, FAST and Morris methods.

Parameter optimization:

  • Parameter fitting: fit parameters to data with local and global optimizers, with reports.
  • Identifiability: profile likelihoods and the Fisher information of fitted parameters.
  • PEtab: write a fit as a PEtab v2 problem and read PEtab v2 problems.
  • PEtab SciML: hybrid models of SBML and neural networks.

Test suites show how sbmlsim does on the SBML Test Suite, the PEtab Test Suite, the PEtab Benchmark Problems and the PEtab SciML Test Suite. The standards and methods behind the package are cited in References.

How to cite

DOI

If you use sbmlsim please cite the archived software on Zenodo:

König, M. (2026). sbmlsim: SBML simulation made easy (Version 0.16.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.23944505

License

  • Source Code: MIT
  • Documentation: CC BY-SA 4.0
  • Citation style: the bundled src/sbmlsim/resources/references.csl of the reports is the IEEE style of the Citation Style Language project under CC BY-SA 3.0, adapted to print the version note of a software.

Funding

Matthias König is supported by the German Research Foundation (DFG) within the Research Unit Programme FOR 5151 "QuaLiPerF (Quantifying Liver Perfusion-Function Relationship in Complex Resection - A Systems Medicine Approach)" by grant number 436883643 and by grant number 465194077 (Priority Programme SPP 2311, Subproject SimLivA).

Matthias König was supported by the Federal Ministry of Education and Research (BMBF, Germany) within the research network Systems Medicine of the Liver (LiSyM, grant number 031L0054). Matthias König has received funding from the EOSCsecretariat.eu which has received funding from the European Union's Horizon Programme call H2020-INFRAEOSC-05-2018-2019, grant Agreement number 831644.