SBMLImporter.jl

This is the documentation for SBMLImporter.jl, a Julia importer for ODE models specified in the Systems Biology Markup Language (SBML). This importer supports many SBML features such as events, dynamic compartments size, rate-, assignment-, and algebraic-rules. For a list of supported features, see here. For a list of differences compared to SBMLToolkit.jl, see the README.

To perform parameter estimation for a SBML model, see PEtab.jl.

Tutorial

SBMLImporter is a tool for importing SBML models into a ModelingToolkit.jl ODESystem. This offers several benefits, such as symbolic model pre-processing for efficient simulations. An ODESystem can easily be converted into an ODEProblem and solved using any ODE solver in OrdinaryDiffEq.jl. If the model includes events, callbacks are generated during the import.

Note

The number of arguments returned by SBML_to_ODESystem varies depending on whether the model has events. When importing an SBML model, SBML_to_ODESystem will inform about the number of returned arguments.

Importing a Model Without Events and Without Piecewise Expressions

Importing an SBML model is straightforward. Given the path to a SBML file do:

using SBMLImporter
sys, specie_map, parameter_map = SBML_to_ODESystem(path_SBML)

Here, sys is the ODESystem, specie_map is a mapping for the initial values, and parameter_map is a mapping/values for the model parameters. To simulate the model, create an ODEProblem:

using OrdinaryDiffEq
tspan = (0, 10.0)
prob = ODEProblem(sys, specie_map, tspan, parameter_map, jac=true)
# Solve ODE with Rodas5P solver
sol = solve(prob, Rodas5P())

Setting jac=true mean that the Jacobian of the ODE is computed symbolically, which is recommended for performance. To get the order of the species and parameters in the model do:

using ModelingToolkit
states(sys) # species
parameters(sys)

Importing a Model with Events

When importing a SBML model with events, the events are rewritten to callbacks. There are two types of callbacks, ContinuousCallback and DiscreteCallback. The former use root-finding to identify when the event is triggered, while a DiscreteCallback solves the ODE up to the event time, applies the event, and then proceeds. Since root-finding can be computationally demanding, SBMLImporter rewrites a SBML events into a DiscreteCallback when possible. To keep track of the discrete event times, the importer also returns a function for computing event times given the model parameters:

sys, specie_map, parameter_map, cb, get_tstops = SBML_to_ODESystem(path_SBML)

Here, cb represent the model's events, and get_tstops is a function to compute the event times. To simulate the model, do:

tspan = (0, 10.0)
prob = ODEProblem(sys, specie_map, tspan, parameter_map, jac=true)
# Compute event times
tstops = get_tstops(prob.u0, prob.p)
sol = solve(prob, Rodas5P(), tstops=tstops, callback=callbacks)

Importing a Model with Time-Dependent Piecewise Expressions

In SBML Piecewise expressions correspond to the Julia ifelse function:

ifelse(cond, value_true, value_false)

If cond==true, the statement evaluates to value_true. While ifelse statements can be directly encoded in the model, this may decrease performance as a discontinuity is added. Therefore, SBMLImporter attempts to rewrite ifelse to callbacks (events). Additionally, as ifelse can sometimes be active at time t0, SBMLImporter provides a function to adjust ifelse rewritten callbacks at time zero:

sys, specie_map, parameter_map, cb, get_tstops, ifelse_t0 = SBML_to_ODESystem(path_SBML)

Here, ifelse_t0 is a vector of functions handling piecewise (ifelse) conditions rewritten to events which are active at time zero. To solve the model do:

tspan = (0, 10.0)
prob = ODEProblem(sys, specie_map, tspan, parameter_map, jac=true)
tstops = get_tstops(prob.p, prob.u0)
# Adjust ifelse statements active at time zero
for _f! in ifelse_t0
    _f!(prob.u0, prob.p)
end
sol = solve(prob, Rodas5P(), tstops=tstops, callback=cb)

To not rewrite ifelse to events when creating the ODESystem, set ifelse_to_callback=false when calling SBML_to_ODESystem.

Citation

We will soon publish a paper you can cite if you found SBMLImporter.jl helpful in your work.