Skip to content

sbmlsim: SBML simulation made easy

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

sbmlsim is a collection of python utilities for the simulation of models in the Systems Biology Markup Language (SBML), built on libroadrunner. The source code is available from https://github.com/matthiaskoenig/sbmlsim.

Background

SBML is the exchange format for computational models in systems biology (Keating et al. 2020) and libroadrunner is a fast simulator for it (Welsh et al. 2023). Simulating a model is a few lines with roadrunner; a simulation experiment is more: the model comes with changes of parameters and initial conditions, timecourses are concatenated into dosing protocols, parameters are scanned over ranges, the results are compared to experimental data in the units of the model, plotted and reported, and all of that has to be reproducible.

sbmlsim is the layer above the simulator which describes these experiments. A Timecourse is a period of a simulation with its changes, a TimecourseSim concatenates them, a ScanSim runs a simulation over the dimensions of parameter changes, and a SimulationExperiment collects models, datasets, simulations, tasks, data and figures into one python object which is executed and reported by an ExperimentRunner. Results are XResult objects, labeled N-dimensional arrays with units, so the mean over a scan dimension or the conversion to the units of a dataset is one call.

Around this core the package collects the tasks which come with simulation experiments: fitting parameters to data, analysing the sensitivity of a model to its parameters, and executing experiments described in SED-ML from COMBINE archives.

Features

  • Models — SBML models are loaded into roadrunner with their units, parameter changes and selections; species can be clamped and model sources can be files, URNs or URLs.
  • Timecourse simulations — Timecourse and TimecourseSim, concatenated periods with changes of parameters and initial conditions, for dosing protocols and perturbations.
  • Parameter scans — ScanSim runs a simulation over the dimensions of parameter changes, the result is an N-dimensional XResult.
  • Units — the units of the model are read from the SBML and all changes and results carry pint quantities, so values are converted instead of assumed.
  • Simulation experiments — SimulationExperiment and ExperimentRunner, the reproducible description of an experiment with models, datasets, simulations, tasks, data and figures.
  • Data — Data references simulation results and experimental datasets, with functions computed from them.
  • Plots and reports — figures described independent of the backend and rendered with matplotlib, HTML and markdown reports of experiments.
  • Parameter fitting — FitParameter, FitMapping and OptimizationProblem with local and global optimizers, analysis of the results and PEtab archives.
  • Sensitivity analysis — local sensitivities by finite differences and the global Morris, Sobol and FAST methods of SALib, with classification and plots.
  • SED-ML and COMBINE archives — execution of simulation experiments in the Simulation Experiment Description Markup Language, from files and COMBINE archives.

The standards and methods behind the package are cited in References.

Quickstart

A model is simulated with a TimecourseSim, the result is an XResult:

from sbmlsim.resources import REPRESSILATOR_SBML
from sbmlsim.simulation import Timecourse, TimecourseSim
from sbmlsim.simulator import SimulatorSerial

simulator = SimulatorSerial(model=REPRESSILATOR_SBML)
simulation = TimecourseSim(
    [
        Timecourse(start=0, end=100, steps=100),
        Timecourse(start=0, end=100, steps=100, changes={"X": 10}),
    ]
)
xres = simulator.run_timecourse(simulation)
print(xres["X"])

Continue with Installation and the timecourse simulation guide.

How to cite

DOI

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

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

License

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.