sbmlode¶

An SBML model describes a system of ordinary differential equations (ODEs), but it is not written as one: the equations follow from the reactions, rules, events and units of the model. sbmlode derives this system once and writes it

as code which simulates the model: python (numpy and scipy), julia (OrdinaryDiffEq.jl) and R (deSolve), verified against libroadrunner over the SBML test suite;
as documents which describe the model: typst, LaTeX and markdown;
as typed data for an application which lays out the equations itself, such as SBML4Humans, see Typed target.

sbmlode depends on python-libsbml and jinja2 only. It is the ODE export of sbmlutils 0.14 as a package of its own, which sbmlutils re-exports as sbmlutils.converters.ode.

Installation¶

pip install sbmlode               # the export
pip install "sbmlode[simulate]"   # with numpy, pandas and scipy, which the python code runs with

Quick start¶

from sbmlode import OdeSystem

system = OdeSystem.from_sbml("model.xml")

code: str = system.render("python")  # the code or document as a string
system.write("model.jl")  # the format from the suffix of the file
system.write("model.md", standalone=False)  # with the options of the format

The ODE system of the repressilator of Elowitz and Leibler (BIOMD0000000012), as the markdown fragment writes it:

Elowitz2000 - Repressilator¶

Model BIOMD0000000012, SBML Level 2 Version 3, read from BIOMD0000000012_urn.xml, written by sbmlode 0.1.0.

Elowitz2000 - Repressilator

This model describes the deterministic version of the repressilator system.

The authors of this model (see reference) use three transcriptional repressor systems that are not part of any natural biological clock to build an oscillating network that they called the repressilator. The model system was induced in Escherichia coli.

In this system, LacI (variable X is the mRNA, variable PX is the protein) inhibits the tetracycline-resistance transposon tetR (Y, PY describe mRNA and protein). Protein tetR inhibits the gene Cl from phage Lambda (Z, PZ: mRNA, protein),and protein Cl inhibits lacI expression. With the appropriate parameter values this system oscillates.

This model is described in the article:

A synthetic oscillatory network of transcriptional regulators.

Elowitz MB, Leibler S.

Nature. 2000 Jan; 403(6767):335-338

Abstract:

Networks of interacting biomolecules carry out many essential functions in living cells, but the 'design principles' underlying the functioning of such intracellular networks remain poorly understood, despite intensive efforts including quantitative analysis of relatively simple systems. Here we present a complementary approach to this problem: the design and construction of a synthetic network to implement a particular function. We used three transcriptional repressor systems that are not part of any natural biological clock to build an oscillating network, termed the repressilator, in Escherichia coli. The network periodically induces the synthesis of green fluorescent protein as a readout of its state in individual cells. The resulting oscillations, with typical periods of hours, are slower than the cell-division cycle, so the state of the oscillator has to be transmitted from generation to generation. This artificial clock displays noisy behaviour, possibly because of stochastic fluctuations of its components. Such 'rational network design may lead both to the engineering of new cellular behaviours and to an improved understanding of naturally occurring networks.

The model is based upon the equations in Box 1 of the paper; however, these equations as printed are dimensionless, and the correct dimensions have been returned to the equations, and the parameters set to reproduce Figure 1C (left).

The original model was generated by B.E. Shapiro using Cellerator version 1.0 update 2.1127 using Mathematica 4.2 for Mac OS X (June 4, 2002), November 27, 2002 12:15:32, using (PowerMac,PowerPC, Mac OS X,MacOSX,Darwin).

Nicolas Le Novere provided a corrected version generated by SBMLeditor on Sun Aug 20 00:44:05 BST 2006. This removed the EmptySet species. Ran fine on COPASI 4.0 build 18.

Bruce Shapiro revised the model with SBMLeditor on 23 October 2006 20:39 PST. This defines default units and correct reactions. The original Cellerator reactions while being mathematically correct did not accurately reflect the intent of the authors. The original notes were mostly removed because they were mostly incorrect in the revised version. Tested with MathSBML 2.6.0.

Nicolas Le Novere changed the volume to 1 cubic micrometre, to allow for stochastic simulation.

Changed by Lukas Endler to use the average livetime of mRNA instead of its halflife and a corrected value of alpha and alpha0.

Moreover, the equations used in this model were clarified, cf. below.

The equations given in box 1 of the original publication are rescaled in three respects (lowercase letters denote the rescaled, uppercase letters the unscaled number of molecules per cell):

the time is rescaled to the average mRNA lifetime, t_ave: τ = t/t_ave

the mRNA concentration is rescaled to the translation efficiency eff: m = M/eff

the protein concentration is rescaled to Km: p = P/Km

α in the equations should be in units of rescaled proteins per promotor and cell, and β is the ratio of the protein to the mRNA decay rates or the ratio of the mRNA to the protein halflife.

In this version of the model α and β are calculated correspondingly to the article, while p and m where just replaced by P/Km resp. M/eff and all equations multiplied by 1/t_ave. Also, to make the equations easier to read, commonly used variables derived from the parameters given in the article by simple rules were introduced.

The parameters given in the article were:

promotor strength (repressed) (tps_repr): 5*10 -4 transcripts/(promotor*s)

promotor strength (full) (tps_active): 0.5 transcripts/(promotor*s)

mRNA half life, τ ½,mRNA: 2 min

protein half life, τ ½,prot: 10 min

K M: 40 monomers/cell

Hill coefficient n: 2

From these the following constants can be derived:

average mRNA lifetime (t_ave): τ ½,mRNA /ln(2) = 2.89 min

mRNA decay rate (kd_mRNA): ln(2)/ τ ½,mRNA = 0.347 min -1

protein decay rate (kd_prot): ln(2)/ τ ½,prot

transcription rate (a_tr): tps_active*60 = 29.97 transcripts/min

transcription rate (repressed) (a0_tr): tps_repr*60 = 0.03 transcripts/min

translation rate (k_tl): eff*kd_mRNA = 6.93 proteins/(mRNA*min)

α : a_tr*eff*τ ½,prot /(ln(2)*K M) = 216.4 proteins/(promotor*cell*Km)

α 0: a0_tr*eff*τ ½,prot /(ln(2)*K M) = 0.2164 proteins/(promotor*cell*Km)

β : k_dp/k_dm = 0.2

Annotation by the Kinetic Simulation Algorithm Ontology (KiSAO):

To reproduce the simulations run published by the authors, the model has to be simulated with any of two different approaches. First, one could use a deterministic method (KISAO_0000035) with continuous variables (KISAO_0000018). One sample algorithm to use is the CVODE solver (KISAO_0000019). Second, one could simulate the system using Gillespie's direct method (KISAO_0000029), which is a stochastic method (KISAO_0000036) supporting adaptive timesteps (KISAO_0000041) and using discrete variables (KISAO_0000016).

This model is hosted on BioModels Database and identified by: BIOMD0000000012.

To cite BioModels Database, please use: BioModels Database: An enhanced, curated and annotated resource for published quantitative kinetic models.

To the extent possible under law, all copyright and related or neighbouring rights to this encoded model have been dedicated to the public domain worldwide. Please refer to CC0 Public Domain Dedication for more information.

Units¶

Time	Substance	Extent	Volume	Area	Length
min	item	item	fl	m²	m

Compartments¶

Symbol	Id	Size	Unit	Constant
\(\mathrm{cell}\)	`cell`	\(1\)	fl	✓

Species¶

Symbol	Id	Name	Compartment	Value	Unit	Properties
\(\mathrm{PX}\)	`PX`	LacI protein	\(\mathrm{cell}\)	\(0\)	item	amount
\(\mathrm{PY}\)	`PY`	TetR protein	\(\mathrm{cell}\)	\(0\)	item	amount
\(\mathrm{PZ}\)	`PZ`	cI protein	\(\mathrm{cell}\)	\(0\)	item	amount
\(X\)	`X`	LacI mRNA	\(\mathrm{cell}\)	\(0\)	item	amount
\(Y\)	`Y`	TetR mRNA	\(\mathrm{cell}\)	\(20\)	item	amount
\(Z\)	`Z`	cI mRNA	\(\mathrm{cell}\)	\(0\)	item	amount

Parameters¶

Symbol	Id	Name	Value	Constant
\(\beta\)	`beta`	beta
\(\alpha_{0}\)	`alpha0`	alpha0
\(\alpha\)	`alpha`	alpha
\(\mathrm{eff}\)	`eff`	translation efficiency	\(20\)	✓
\(n\)	`n`	n	\(2\)	✓
\(\mathrm{KM}\)	`KM`	KM	\(40\)	✓
\(\tau_{\mathrm{mRNA}}\)	`tau_mRNA`	mRNA half life	\(2\)	✓
\(\tau_{\mathrm{prot}}\)	`tau_prot`	protein half life	\(10\)	✓
\(t_{\mathrm{ave}}\)	`t_ave`	average mRNA life time
\(\mathrm{kd}_{\mathrm{mRNA}}\)	`kd_mRNA`	kd_mRNA
\(\mathrm{kd}_{\mathrm{prot}}\)	`kd_prot`	kd_prot
\(k_{\mathrm{tl}}\)	`k_tl`	k_tl
\(a_{\mathrm{tr}}\)	`a_tr`	a_tr
\(\mathrm{ps}_{\mathrm{a}}\)	`ps_a`	tps_active	\(0.5\)	✓
\(\mathrm{ps}_{0}\)	`ps_0`	tps_repr	\(0.0005\)	✓
\(\mathrm{a0}_{\mathrm{tr}}\)	`a0_tr`	a0_tr

Initial assignments and assignment rules¶

The assignment rules hold at every time \(t\):

\[ \begin{aligned} t_{\mathrm{ave}} &= \frac{\tau_{\mathrm{mRNA}}}{\ln\mathopen{}\left(2\right)} \\[1ex] \beta &= \frac{\tau_{\mathrm{mRNA}}}{\tau_{\mathrm{prot}}} \\[1ex] k_{\mathrm{tl}} &= \frac{\mathrm{eff}}{t_{\mathrm{ave}}} \\[1ex] a_{\mathrm{tr}} &= \mathopen{}\left(\mathrm{ps}_{\mathrm{a}} - \mathrm{ps}_{0}\right) \cdot 60 \\[1ex] \mathrm{a0}_{\mathrm{tr}} &= \mathrm{ps}_{0} \cdot 60 \\[1ex] \mathrm{kd}_{\mathrm{prot}} &= \frac{\ln\mathopen{}\left(2\right)}{\tau_{\mathrm{prot}}} \\[1ex] \mathrm{kd}_{\mathrm{mRNA}} &= \frac{\ln\mathopen{}\left(2\right)}{\tau_{\mathrm{mRNA}}} \\[1ex] \alpha &= \frac{a_{\mathrm{tr}} \cdot \mathrm{eff} \cdot \tau_{\mathrm{prot}}}{\ln\mathopen{}\left(2\right) \cdot \mathrm{KM}} \\[1ex] \alpha_{0} &= \frac{\mathrm{a0}_{\mathrm{tr}} \cdot \mathrm{eff} \cdot \tau_{\mathrm{prot}}}{\ln\mathopen{}\left(2\right) \cdot \mathrm{KM}} \end{aligned} \]

Reactions¶

Rate	Id	Name	Equation	Modifiers
\(v_{\mathrm{Reaction1}}\)	`Reaction1`	degradation of LacI transcripts	\(X \longrightarrow \varnothing\)
\(v_{\mathrm{Reaction2}}\)	`Reaction2`	degradation of TetR transcripts	\(Y \longrightarrow \varnothing\)
\(v_{\mathrm{Reaction3}}\)	`Reaction3`	degradation of CI transcripts	\(Z \longrightarrow \varnothing\)
\(v_{\mathrm{Reaction4}}\)	`Reaction4`	translation of LacI	\(\varnothing \longrightarrow \mathrm{PX}\)	\(X\)
\(v_{\mathrm{Reaction5}}\)	`Reaction5`	translation of TetR	\(\varnothing \longrightarrow \mathrm{PY}\)	\(Y\)
\(v_{\mathrm{Reaction6}}\)	`Reaction6`	translation of CI	\(\varnothing \longrightarrow \mathrm{PZ}\)	\(Z\)
\(v_{\mathrm{Reaction7}}\)	`Reaction7`	degradation of LacI	\(\mathrm{PX} \longrightarrow \varnothing\)
\(v_{\mathrm{Reaction8}}\)	`Reaction8`	degradation of TetR	\(\mathrm{PY} \longrightarrow \varnothing\)
\(v_{\mathrm{Reaction9}}\)	`Reaction9`	degradation of CI	\(\mathrm{PZ} \longrightarrow \varnothing\)
\(v_{\mathrm{Reaction10}}\)	`Reaction10`	transcription of LacI	\(\varnothing \longrightarrow X\)	\(\mathrm{PZ}\)
\(v_{\mathrm{Reaction11}}\)	`Reaction11`	transcription of TetR	\(\varnothing \longrightarrow Y\)	\(\mathrm{PX}\)
\(v_{\mathrm{Reaction12}}\)	`Reaction12`	transcription of CI	\(\varnothing \longrightarrow Z\)	\(\mathrm{PY}\)

The rates of the reactions are:

\[ \begin{aligned} v_{\mathrm{Reaction1}} &= \mathrm{kd}_{\mathrm{mRNA}} \cdot X \\[1ex] v_{\mathrm{Reaction2}} &= \mathrm{kd}_{\mathrm{mRNA}} \cdot Y \\[1ex] v_{\mathrm{Reaction3}} &= \mathrm{kd}_{\mathrm{mRNA}} \cdot Z \\[1ex] v_{\mathrm{Reaction4}} &= k_{\mathrm{tl}} \cdot X \\[1ex] v_{\mathrm{Reaction5}} &= k_{\mathrm{tl}} \cdot Y \\[1ex] v_{\mathrm{Reaction6}} &= k_{\mathrm{tl}} \cdot Z \\[1ex] v_{\mathrm{Reaction7}} &= \mathrm{kd}_{\mathrm{prot}} \cdot \mathrm{PX} \\[1ex] v_{\mathrm{Reaction8}} &= \mathrm{kd}_{\mathrm{prot}} \cdot \mathrm{PY} \\[1ex] v_{\mathrm{Reaction9}} &= \mathrm{kd}_{\mathrm{prot}} \cdot \mathrm{PZ} \\[1ex] v_{\mathrm{Reaction10}} &= \mathrm{a0}_{\mathrm{tr}} + \frac{a_{\mathrm{tr}} \cdot \mathrm{KM}^{n}}{\mathrm{KM}^{n} + \mathrm{PZ}^{n}} \\[1ex] v_{\mathrm{Reaction11}} &= \mathrm{a0}_{\mathrm{tr}} + \frac{a_{\mathrm{tr}} \cdot \mathrm{KM}^{n}}{\mathrm{KM}^{n} + \mathrm{PX}^{n}} \\[1ex] v_{\mathrm{Reaction12}} &= \mathrm{a0}_{\mathrm{tr}} + \frac{a_{\mathrm{tr}} \cdot \mathrm{KM}^{n}}{\mathrm{KM}^{n} + \mathrm{PY}^{n}} \end{aligned} \]

ODE system¶

The states change in time with the rates of the reactions:

\[ \begin{aligned} \frac{\mathrm{d} \,\mathrm{PX}}{\mathrm{d} t} &= v_{\mathrm{Reaction4}} - v_{\mathrm{Reaction7}} \\[1ex] \frac{\mathrm{d} \,\mathrm{PY}}{\mathrm{d} t} &= v_{\mathrm{Reaction5}} - v_{\mathrm{Reaction8}} \\[1ex] \frac{\mathrm{d} \,\mathrm{PZ}}{\mathrm{d} t} &= v_{\mathrm{Reaction6}} - v_{\mathrm{Reaction9}} \\[1ex] \frac{\mathrm{d} X}{\mathrm{d} t} &= -v_{\mathrm{Reaction1}} + v_{\mathrm{Reaction10}} \\[1ex] \frac{\mathrm{d} Y}{\mathrm{d} t} &= -v_{\mathrm{Reaction2}} + v_{\mathrm{Reaction11}} \\[1ex] \frac{\mathrm{d} Z}{\mathrm{d} t} &= -v_{\mathrm{Reaction3}} + v_{\mathrm{Reaction12}} \end{aligned} \]

The Guide describes the formats, their options, the supported SBML and the verification, the API reference the classes and functions.

How to cite¶

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

König, M. (2026). sbmlode: ordinary differential equations of SBML models (Version 0.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.23179200

@software{koenig_sbmlode,
  author    = {König, Matthias},
  title     = {sbmlode: ordinary differential equations of SBML models},
  year      = {2026},
  month     = oct,
  version   = {0.1.0},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.23179200},
  url       = {https://doi.org/10.5281/zenodo.23179200},
}

License¶

sbmlode is open source under the MIT license. Please open an issue for a question or a problem.