search

SciML / Catalyst.jl

Chemical reaction network and systems biology interface for scientific machine learning (SciML). High performance, GPU-parallelized, and O(1) solvers in open source software.
https://docs.sciml.ai/Catalyst/stable/
Other
463 stars 78 forks source link
biology chemical-reactions differential-equations dsl gillespie-algorithm julia ode rate-laws reaction-network scientific-machine-learning sciml sde simulation systems-biology systems-biology-simulation

readme

Catalyst.jl

Latest Release (for users) API Latest Release (for users) Master (for developers) API Master (for developers

Build Status codecov.io Coverage Status

ColPrac: Contributor's Guide on Collaborative Practices for Community Packages SciML Code Style Citation

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

Features of Catalyst composing with other packages

Features of packages built upon Catalyst

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)

ODE simulation

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)

Jump simulation

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)

Elaborate SDE simulation

Some features we used here:

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},
}