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.
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.