GitHub

Catalyst.jl for Reaction Network Modeling

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

Features

Features of Catalyst

Features of Catalyst composing with other packages

Features of packages built upon Catalyst

How to read this documentation

The Catalyst documentation is separated into sections describing Catalyst's various features. Where appropriate, some sections will also give advice on best practices for various modeling workflows, and provide links with further reading. Each section also contains a set of relevant example workflows. Finally, the API section contains a list of all functions exported by Catalyst (as well as descriptions of them and their inputs and outputs).

New users are recommended to start with either the Introduction to Catalyst and Julia for New Julia users or Introduction to Catalyst sections (depending on whether they are familiar with Julia programming or not). This should be enough to carry out many basic Catalyst workflows.

This documentation contains code which is dynamically run whenever it is built. If you copy the code and run it in your Julia environment it should work. The exact Julia environment that is used in this documentation can be found here.

For most code blocks in this documentation, the output of the last line of code is printed at the of the block, e.g.

1 + 2
3

and

@reaction_network begin
    (p,d), 0 <--> X
end

\[ \begin{align*} \varnothing &\xrightleftharpoons[d]{p} \mathrm{X} \end{align*} \]

However, in some situations (e.g. when output is extensive, or irrelevant to what is currently being described) we have disabled this, e.g. like here:

1 + 2

and here:

@reaction_network begin
    (p,d), 0 <--> X
end

Installation

Catalyst is an officially registered Julia package, which can be installed through the Julia package manager:

using Pkg
Pkg.add("Catalyst")

Many Catalyst features require the installation of additional packages. E.g. for ODE-solving and simulation plotting

Pkg.add("OrdinaryDiffEqDefault")
Pkg.add("Plots")

is also needed.

It is strongly recommended to install and use Catalyst in its own environment with the minimal set of needed packages. For example, to install Catalyst and Plots in a new environment named catalyst_project (saved in the current directory) one can say

Pkg.activate("catalyst_project")
Pkg.add("Catalyst")
Pkg.add("Plots")

If one would rather just create a temporary environment that is not saved when exiting Julia you can say

Pkg.activate(; temp = true)
Pkg.add("Catalyst")
Pkg.add("Plots")

After installation, we suggest running 

Pkg.status("Catalyst")

to confirm that the latest version of Catalyst was installed (and not an older version). If you have installed into a new environment this should always be the case. However, if you installed into an existing environment, such as the default Julia global environment, the presence of incompatible versions of other pre-installed packages could lead to older versions of Catalyst being installed. In this case we again recommend creating a new environment and installing Catalyst there to obtain the latest version.

A more thorough guide for setting up Catalyst and installing Julia packages can be found here.

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, OrdinaryDiffEqDefault, 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)
Example block output

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.

# Create and simulate a jump process (here using Gillespie's direct algorithm).
# 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)
Example block output

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, which is modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$. 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

\[ \begin{align*} \mathrm{G} &\xrightleftharpoons[\frac{\mathtt{k_i}}{V\left( t \right)}]{\frac{\mathtt{k_p} \left( 1 + \sin\left( t \right) \right)}{V\left( t \right)}} \mathrm{\mathtt{G^P}} \\ \frac{\mathrm{d} V\left( t \right)}{\mathrm{d}t} &= g \mathtt{G^P}\left( t \right) \end{align*} \]

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)
SDEProblem with uType Vector{Float64} and tType Float64. In-place: true
Initialization status: FULLY_DETERMINED
Non-trivial mass matrix: false
timespan: (0.0, 20.0)
u0: 3-element Vector{Float64}:
 50.0
  0.0
 25.0

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)
Example block output

Getting Help

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

Reproducibility

The documentation of this SciML package was built using these direct dependencies,
Status `~/work/Catalyst.jl/Catalyst.jl/docs/Project.toml`
  [6e4b80f9] BenchmarkTools v1.6.0
  [0f109fa4] BifurcationKit v0.4.16
  [13f3f980] CairoMakie v0.13.7
  [479239e8] Catalyst v15.0.8 `~/work/Catalyst.jl/Catalyst.jl`
  [a93c6f00] DataFrames v1.7.0
  [82cc6244] DataInterpolations v8.0.1
  [2b5f629d] DiffEqBase v6.175.0
  [31c24e10] Distributions v0.25.120
  [e30172f5] Documenter v1.11.4
  [61744808] DynamicalSystems v3.4.1
  [069e79ea] FiniteStateProjection v0.3.2
  [af5da776] GlobalSensitivity v2.7.0
  [1ecd5474] GraphMakie v0.5.14
  [86223c79] Graphs v1.12.1
  [f213a82b] HomotopyContinuation v2.14.0
  [40713840] IncompleteLU v0.2.1
  [ccbc3e58] JumpProcesses v9.14.3
  [23fbe1c1] Latexify v0.16.8
  [7ed4a6bd] LinearSolve v3.16.0
⌅ [961ee093] ModelingToolkit v9.80.1
  [46757867] NetworkLayout v0.4.10
  [8913a72c] NonlinearSolve v4.9.0
  [429524aa] Optim v1.12.0
  [7f7a1694] Optimization v4.3.0
  [3e6eede4] OptimizationBBO v0.4.1
  [cb963754] OptimizationEvolutionary v0.4.1
  [4e6fcdb7] OptimizationNLopt v0.3.2
  [36348300] OptimizationOptimJL v0.4.3
  [42dfb2eb] OptimizationOptimisers v0.3.7
  [6ad6398a] OrdinaryDiffEqBDF v1.5.1
  [50262376] OrdinaryDiffEqDefault v1.4.0
  [43230ef6] OrdinaryDiffEqRosenbrock v1.10.1
  [2d112036] OrdinaryDiffEqSDIRK v1.3.0
  [b1df2697] OrdinaryDiffEqTsit5 v1.1.0
  [79d7bb75] OrdinaryDiffEqVerner v1.2.0
  [48d54b35] PEtab v3.8.3
  [91a5bcdd] Plots v1.40.13
  [8a4e6c94] QuasiMonteCarlo v0.3.3
  [0bca4576] SciMLBase v2.96.0
  [1ed8b502] SciMLSensitivity v7.84.0
  [276daf66] SpecialFunctions v2.5.1
  [90137ffa] StaticArrays v1.9.13
  [9672c7b4] SteadyStateDiffEq v2.5.0
  [789caeaf] StochasticDiffEq v6.80.0
  [220ca800] StructuralIdentifiability v0.5.14
  [0c5d862f] Symbolics v6.40.0
  [56ddb016] Logging v1.11.0
Info Packages marked with ⌅ have new versions available but compatibility constraints restrict them from upgrading. To see why use `status --outdated`
and using this machine and Julia version.
Julia Version 1.11.5
Commit 760b2e5b739 (2025-04-14 06:53 UTC)
Build Info:
  Official https://julialang.org/ release
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 4 × AMD EPYC 7763 64-Core Processor
  WORD_SIZE: 64
  LLVM: libLLVM-16.0.6 (ORCJIT, znver3)
Threads: 1 default, 0 interactive, 1 GC (on 4 virtual cores)