Catalyst.jl

Catalyst.jl is a symbolic modeling package for analysis and high-performance simulation of chemical reaction networks. Catalyst defines symbolic ReactionSystems, which can be created programmatically or easily specified using Catalyst's domain-specific language (DSL). Leveraging ModelingToolkit.jl and Symbolics.jl, Catalyst enables large-scale simulations through auto-vectorization and parallelism. Symbolic ReactionSystems can be used to generate ModelingToolkit-based models, allowing the easy simulation and parameter estimation of mass action ODE models, Chemical Langevin SDE models, stochastic chemical kinetics jump process models, and more. Generated models can be used with solvers throughout the broader Julia and SciML ecosystems, including higher-level SciML packages (e.g. for sensitivity analysis, parameter estimation, machine learning applications, etc).

Breaking changes and new features

NOTE: Version 14 is a breaking release, prompted by the release of ModelingToolkit.jl version 9. This caused several breaking changes in how Catalyst models are represented and interfaced with.

Breaking changes and new functionality are summarized in the HISTORY.md file. Furthermore, a migration guide on how to adapt your workflows to the new v14 update can be found here.

Tutorials and documentation

The latest tutorials and information on using Catalyst are available in the stable documentation. The in-development documentation describes unreleased features in the current master branch.

An overview of the package, its features, and comparative benchmarking (as of version 13) can also be found in its corresponding research paper, Catalyst: Fast and flexible modeling of reaction networks.

Features

Features of Catalyst

• The Catalyst DSL provides a simple and readable format for manually specifying reaction network models using chemical reaction notation.
• Catalyst ReactionSystems provides a symbolic representation of reaction networks, built on ModelingToolkit.jl and Symbolics.jl.
• The Catalyst.jl API provides functionality for building networks programmatically and for composing multiple networks together.
• Leveraging ModelingToolkit, generated models can be converted to symbolic reaction rate equation ODE models, symbolic Chemical Langevin Equation models, and symbolic stochastic chemical kinetics (jump process) models. These can be simulated using any DifferentialEquations.jl ODE/SDE/jump solver, and can be used within EnsembleProblems for carrying out parallelized parameter sweeps and statistical sampling. Plot recipes are available for visualization of all solutions.
• Non-integer (e.g. Float64) stoichiometric coefficients are supported for generating ODE models, and symbolic expressions for stoichiometric coefficients are supported for all system types.
• A network analysis suite permits the computation of linkage classes, deficiencies, reversibility, and other network properties.
• Conservation laws can be detected and utilized to reduce system sizes, and to generate non-singular Jacobians (e.g. during conversion to ODEs, SDEs, and steady state equations).
• Catalyst reaction network models can be coupled with differential and algebraic equations (which are then incorporated during conversion to ODEs, SDEs, and steady state equations).
• Models can be coupled with events that affect the system and its state during simulations.
• By leveraging ModelingToolkit, users have a variety of options for generating optimized system representations to use in solvers. These include construction of dense or sparse Jacobians, multithreading or parallelization of generated derivative functions, automatic classification of reactions into optimized jump types for Gillespie type simulations, automatic construction of dependency graphs for jump systems, and more.
• Symbolics.jl symbolic expressions and Julia Exprs can be obtained for all rate laws and functions determining the deterministic and stochastic terms within resulting ODE, SDE, or jump models.
• Steady states (and their stabilities) can be computed for model ODE representations.

Features of Catalyst composing with other packages

• OrdinaryDiffEq.jl Can be used to numerically solver generated reaction rate equation ODE models.
• StochasticDiffEq.jl can be used to numerically solve generated Chemical Langevin Equation SDE models.
• JumpProcesses.jl can be used to numerically sample generated Stochastic Chemical Kinetics Jump Process models.
• Support for parallelization of all simulations, including parallelization of ODE simulations on GPUs using DiffEqGPU.jl.
• Latexify can be used to generate LaTeX expressions corresponding to generated mathematical models or the underlying set of reactions.
• Graphviz can be used to generate and visualize reaction network graphs (reusing the Graphviz interface created in Catlab.jl).
• Model steady states can be computed through homotopy continuation using HomotopyContinuation.jl (which can find all steady states of systems with multiple ones), by forward ODE simulations using SteadyStateDiffEq.jl, or by numerically solving steady-state nonlinear equations using NonlinearSolve.jl.
• BifurcationKit.jl can be used to compute bifurcation diagrams of model steady states (including finding periodic orbits).
• DynamicalSystems.jl can be used to compute model basins of attraction, Lyapunov spectrums, and other dynamical system properties.
• StructuralIdentifiability.jl can be used to perform structural identifiability analysis.
• Optimization.jl, DiffEqParamEstim.jl, and PEtab.jl can all be used to fit model parameters to data.
• GlobalSensitivity.jl can be used to perform global sensitivity analysis of model behaviors.
• SciMLSensitivity.jl can be used to compute local sensitivities of functions containing forward model simulations.

Features of packages built upon Catalyst

• Catalyst ReactionSystems can be imported from SBML files via SBMLImporter.jl and SBMLToolkit.jl, and from BioNetGen .net files and various stoichiometric matrix network representations using ReactionNetworkImporters.jl.
• MomentClosure.jl allows generation of symbolic ModelingToolkit ODESystems that represent moment closure approximations to moments of the Chemical Master Equation, from reaction networks defined in Catalyst.
• FiniteStateProjection.jl allows the construction and numerical solution of Chemical Master Equation models from reaction networks defined in Catalyst.
• DelaySSAToolkit.jl can augment Catalyst reaction network models with delays, and can simulate the resulting stochastic chemical kinetics with delays models.

Illustrative example

Deterministic ODE simulation of Michaelis-Menten enzyme kinetics

Here we show a simple example where a model is created using the Catalyst DSL, and then simulated as an ordinary differential equation.

# Fetch required packages.
using Catalyst, OrdinaryDiffEq, Plots

# Create model.
model = @reaction_network begin
    kB, S + E --> SE
    kD, SE --> S + E
    kP, SE --> P + E
end

# Create an ODE that can be simulated.
u0 = [:S => 50.0, :E => 10.0, :SE => 0.0, :P => 0.0]
tspan = (0., 200.)
ps = [:kB => 0.01, :kD => 0.1, :kP => 0.1]
ode = ODEProblem(model, u0, tspan, ps)

# Simulate ODE and plot results.
sol = solve(ode)
plot(sol; lw = 5)

Stochastic jump simulations

The same model can be used as input to other types of simulations. E.g. here we instead generate and simulate a stochastic chemical kinetics jump process model for the reaction network. An exact realization of the jump process is sampled using an auto-selected stochastic simulation algorithm (SSA) (which for the small network in the current example ends up being Gillespie's Direct method):

# The initial conditions are now integers as we track exact populations for each species.
using JumpProcesses
u0_integers = [:S => 50, :E => 10, :SE => 0, :P => 0]
jinput = JumpInputs(model, u0_integers, tspan, ps)
jprob = JumpProblem(jinput)
jump_sol = solve(jprob)
plot(jump_sol; lw = 2)

More elaborate example

In the above example, we used basic Catalyst workflows to simulate a simple model. Here we instead show how various Catalyst features can compose to create a much more advanced model. Our model describes how the volume of a cell ($V$) is affected by a growth factor ($G$). The growth factor only promotes growth while in its phosphorylated form ($G^P$). The phosphorylation of $G$ ($G \to G^P$) is promoted by sunlight (modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$), which phosphorylates the growth factor (producing $G^P$). When the cell reaches a critical volume ($V_m$) it undergoes cell division. First, we declare our model:

using Catalyst
cell_model = @reaction_network begin
    @parameters Vₘ g
    @equations begin
        D(V) ~ g*Gᴾ
    end
    @continuous_events begin
        [V ~ Vₘ] => [V ~ V/2]
    end
    kₚ*(sin(t)+1)/V, G --> Gᴾ
    kᵢ/V, Gᴾ --> G
end

We now study the system as a Chemical Langevin Dynamics SDE model, which can be generated as follows

u0 = [:V => 25.0, :G => 50.0, :Gᴾ => 0.0]
tspan = (0.0, 20.0)
ps = [:Vₘ => 50.0, :g => 0.3, :kₚ => 100.0, :kᵢ => 60.0]
sprob = SDEProblem(cell_model, u0, tspan, ps)

This problem encodes the following stochastic differential equation model:

$$\begin{align*} dG(t) &= - \left( \frac{k_p(\sin(t)+1)}{V(t)} G(t) + \frac{k_i}{V(t)} G^P(t) \right) dt - \sqrt{\frac{k_p (\sin(t)+1)}{V(t)} G(t)} \, dW_1(t) + \sqrt{\frac{k_i}{V(t)} G^P(t)} \, dW_2(t) \\\ dG^P(t) &= \left( \frac{k_p(\sin(t)+1)}{V(t)} G(t) - \frac{k_i}{V(t)} G^P(t) \right) dt + \sqrt{\frac{k_p (\sin(t)+1)}{V(t)} G(t)} \, dW_1(t) - \sqrt{\frac{k_i}{V(t)} G^P(t)} \, dW_2(t) \\\ dV(t) &= \left(g \, G^P(t)\right) dt \end{align*}$$

where the $dW_1(t)$ and $dW_2(t)$ terms represent independent Brownian Motions, encoding the noise added by the Chemical Langevin Equation. Finally, we can simulate and plot the results.

using StochasticDiffEq, Plots
sol = solve(sprob, EM(); dt = 0.05)
plot(sol; xguide = "Time (au)", lw = 2)

Some features we used here:

• The cell volume was modeled as a differential equation, which was coupled to the reaction network model.
• The cell divisions were created by incorporating events into the model.
• We designated a specific numeric solver and corresponding solver options.
• The model simulation was plotted using Plots.jl.

Getting help or getting involved

Catalyst developers are active on the Julia Discourse and the Julia Slack channels #sciml-bridged and #sciml-sysbio. For bugs or feature requests, open an issue.

Supporting and citing Catalyst.jl

The software in this ecosystem was developed as part of academic research. If you would like to help support it, please star the repository as such metrics may help us secure funding in the future. If you use Catalyst as part of your research, teaching, or other activities, we would be grateful if you could cite our work:

@article{CatalystPLOSCompBio2023,
 doi = {10.1371/journal.pcbi.1011530},
 author = {Loman, Torkel E. AND Ma, Yingbo AND Ilin, Vasily AND Gowda, Shashi AND Korsbo, Niklas AND Yewale, Nikhil AND Rackauckas, Chris AND Isaacson, Samuel A.},
 journal = {PLOS Computational Biology},
 publisher = {Public Library of Science},
 title = {Catalyst: Fast and flexible modeling of reaction networks},
 year = {2023},
 month = {10},
 volume = {19},
 url = {https://doi.org/10.1371/journal.pcbi.1011530},
 pages = {1-19},
 number = {10},
}