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, doses are given at times, 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 Simulation is a simulation with its changes before the initialization and at times, e.g. the doses of a dosing protocol, a Scan runs a simulation over dimensions of values, simulations and models, serially or in a pool of processes, 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 ScanResult objects, labeled N-dimensional arrays with units, so the statistics 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, exchanging a fit as a PEtab problem, and analysing the sensitivity of a model to its parameters.

Features

Core

  • Models - SBML models are loaded into roadrunner with their units, parameter changes and selections; the source of a model is a file or the SBML itself.
  • Simulations - Simulation and Change, changes of parameters and initial conditions before the initialization and at times, for dosing protocols and perturbations, with the semantics of PEtab v2.
  • 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.

Sensitivity and uncertainty

  • Parameter scans - Scan and Dimension run a simulation over dimensions of values, simulations and models, serially or in a pool of processes; the result is a ScanResult with the changed values as coordinates.
  • Sampling and uncertainty - distributions and designs of the sampler (random, Latin hypercube, Sobol, FAST, Morris, local, populations and designs of a fit) as dimensions of a scan, and the bands and distributions of the uncertainty of the outputs.
  • Observables - formulas, non-compartmental PK analyses and custom functions of a run, computed on the simulations of a scan.
  • Sensitivity analysis - local sensitivities and the global Morris, Sobol and FAST methods of SALib, computed on the result of a scan with a design of the sampler, with classification and plots.

Parameter optimization

  • Parameter fitting - FitParameter, FitMapping and OptimizationProblem with local and global optimizers, the metrics and the reports of a fit.
  • Identifiability - the profile likelihood and the Fisher information of the fitted parameters.
  • PEtab - a fit is written as a PEtab v2 problem and a PEtab v2 problem is read as a fit.
  • PEtab SciML - hybrid problems of a model and neural networks.

Test suites

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

Quickstart

A model is simulated with a Simulation, the result is a ScanResult:

from sbmlsim.resources import REPRESSILATOR_SBML
from sbmlsim.simulation import Change, Simulation
from sbmlsim.simulator import Simulator

simulator = Simulator()
simulation = Simulation(end=200, changes=[Change(100, {"X": 10})], steps=200)
res = simulator.run(REPRESSILATOR_SBML, simulation)
print(res["X"])

Continue with Installation and the 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 (Version 0.9.4) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.23324383

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.