diff --git a/docs/src/api.md b/docs/src/api.md index f34cbfa8e3..67842c676e 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -1,4 +1,4 @@ -# Catalyst.jl API +# [Catalyst.jl API](@id api) ```@meta CurrentModule = Catalyst ``` diff --git a/docs/src/index.md b/docs/src/index.md index 8ad0ea19fe..cedc37bd76 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,160 +1,263 @@ -# Catalyst.jl for Reaction Network Modeling +# [Catalyst.jl for Reaction Network Modeling](@id doc_index) -Catalyst.jl is a symbolic modeling package for analysis and high performance +Catalyst.jl is a symbolic modeling package for analysis and high-performance simulation of chemical reaction networks. Catalyst defines symbolic -[`ReactionSystem`](@ref)s, which can be created programmatically or easily -specified using Catalyst's domain specific language (DSL). Leveraging -[ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) and -[Symbolics.jl](https://docs.sciml.ai/Symbolics/stable/), Catalyst enables +[`ReactionSystem`](@ref)s, +which can be created programmatically or easily +specified using Catalyst's domain-specific language (DSL). Leveraging +[ModelingToolkit.jl](https://github.com/SciML/ModelingToolkit.jl) and +[Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl), Catalyst enables large-scale simulations through auto-vectorization and parallelism. Symbolic `ReactionSystem`s 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 -[SciML](https://sciml.ai) ecosystem, including higher level SciML packages (e.g. +[SciML](https://sciml.ai) ecosystem, including higher-level SciML packages (e.g. for sensitivity analysis, parameter estimation, machine learning applications, etc). -## Features -- A DSL provides a simple and readable format for manually specifying chemical - reactions. -- Catalyst `ReactionSystem`s provide a symbolic representation of reaction networks, - built on [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) and - [Symbolics.jl](https://docs.sciml.ai/Symbolics/stable/). -- 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. -- The [Catalyst.jl API](@ref) provides functionality for extending networks, - building networks programmatically, network analysis, and for composing multiple - networks together. -- `ReactionSystem`s generated by the DSL can be converted to a variety of - `ModelingToolkit.AbstractSystem`s, including symbolic ODE, SDE and jump process - representations. -- Coupled differential and algebraic constraint equations can be included in - Catalyst models, and are incorporated during conversion to ODEs or steady - state equations. -- Conservation laws can be detected and applied to reduce system sizes, and - generate non-singular Jacobians, during conversion to ODEs, SDEs, and steady - state equations. +## [Features](@id doc_index_features) + +#### [Features of Catalyst](@id doc_index_features_catalyst) +- [The Catalyst DSL](@ref dsl_description) provides a simple and readable format for manually specifying reaction + network models using chemical reaction notation. +- Catalyst `ReactionSystem`s provides a symbolic representation of reaction networks, + built on [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) and + [Symbolics.jl](https://docs.sciml.ai/Symbolics/stable/). +- The [Catalyst.jl API](@ref api) provides functionality + for extending networks, 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](https://docs.sciml.ai/DiffEqDocs/stable/) + [ODE/SDE/jump solver](@ref simulation_intro), and can be used within `EnsembleProblem`s for carrying + out [parallelized parameter sweeps and statistical sampling](@ref ensemble_simulations). Plot recipes + are available for [visualization of all solutions](@ref simulation_plotting). +- Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](@ref dsl_description_stoichiometries_decimal) for generating + ODE models, and symbolic expressions for stoichiometric coefficients [are supported](@ref parametric_stoichiometry) for + all system types. +- A [network analysis suite](@ref network_analysis) permits the computation of linkage classes, deficiencies, reversibility, and other network properties. +- [Conservation laws can be detected and utilized](@ref network_analysis_deficiency) 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](@ref constraint_equations_coupling_constraints) + (which are then incorporated during conversion to ODEs, SDEs, and steady state equations). +- Models can be [coupled with events](@ref constraint_equations_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. -- Generated systems can be solved using any - [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) - ODE/SDE/jump solver, and can be used within `EnsembleProblem`s for carrying - out parallelized parameter sweeps and statistical sampling. Plot recipes - are available for visualizing the solutions. + optimized system representations to use in solvers. These include construction + of [dense or sparse Jacobians](@ref ode_simulation_performance_sparse_jacobian), [multithreading or parallelization of generated + derivative functions](@ref ode_simulation_performance_parallelisation), [automatic classification of reactions into optimized + jump types for Gillespie type simulations](https://docs.sciml.ai/JumpProcesses/stable/jump_types/#jump_types), [automatic construction of + dependency graphs for jump systems](https://docs.sciml.ai/JumpProcesses/stable/jump_types/#Jump-Aggregators-Requiring-Dependency-Graphs), and more. - [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) symbolic - expressions and Julia `Expr`s can be obtained for all rate laws and functions - determining the deterministic and stochastic terms within resulting ODE, SDE - or jump models. -- [Latexify](https://korsbo.github.io/Latexify.jl/stable/) can be used to generate - LaTeX expressions corresponding to generated mathematical models or the - underlying set of reactions. -- [Graphviz](https://graphviz.org/) can be used to generate and visualize - reaction network graphs. (Reusing the Graphviz interface created in - [Catlab.jl](https://algebraicjulia.github.io/Catlab.jl/stable/).) - -## Packages Supporting Catalyst -- Catalyst [`ReactionSystem`](@ref)s can be imported from SBML files via - [SBMLToolkit.jl](https://docs.sciml.ai/SBMLToolkit/stable/), and from BioNetGen .net - files and various stoichiometric matrix network representations using - [ReactionNetworkImporters.jl](https://docs.sciml.ai/ReactionNetworkImporters/stable/). -- [MomentClosure.jl](https://augustinas1.github.io/MomentClosure.jl/dev) allows - generation of symbolic ModelingToolkit `ODESystem`s, representing moment - closure approximations to moments of the Chemical Master Equation, from - reaction networks defined in Catalyst. -- [FiniteStateProjection.jl](https://kaandocal.github.io/FiniteStateProjection.jl/dev/) - allows the construction and numerical solution of Chemical Master Equation - models from reaction networks defined in Catalyst. -- [DelaySSAToolkit.jl](https://palmtree2013.github.io/DelaySSAToolkit.jl/dev/) can - augment Catalyst reaction network models with delays, and can simulate the - resulting stochastic chemical kinetics with delays models. -- [BondGraphs.jl](https://github.com/jedforrest/BondGraphs.jl) a package for - constructing and analyzing bond graphs models, which can take Catalyst models as input. -- [PEtab.jl](https://github.com/sebapersson/PEtab.jl) a package that implements the PEtab format for fitting reaction network ODEs to data. Input can be provided either as SBML files or as Catalyst `ReactionSystem`s. - - -## Installation -Catalyst can be installed through the Julia package manager: + expressions and Julia `Expr`s can be obtained for all rate laws and functions determining the + deterministic and stochastic terms within resulting ODE, SDE or jump models. +- [Steady states](@ref homotopy_continuation) (and their [stabilities](@ref steady_state_stability)) can be computed for model ODE representations. + +#### [Features of Catalyst composing with other packages](@id doc_index_features_composed) +- [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) Can be used to numerically solver generated reaction rate equation ODE models. +- [StochasticDiffEq.jl](https://github.com/SciML/StochasticDiffEq.jl) can be used to numerically solve generated Chemical Langevin Equation SDE models. +- [JumpProcesses.jl](https://github.com/SciML/JumpProcesses.jl) can be used to numerically sample generated Stochastic Chemical Kinetics Jump Process models. +- Support for [parallelization of all simulations](@ref ode_simulation_performance_parallelisation), including parallelization of + [ODE simulations on GPUs](@ref ode_simulation_performance_parallelisation_GPU) using + [DiffEqGPU.jl](https://github.com/SciML/DiffEqGPU.jl). +- [Latexify](https://korsbo.github.io/Latexify.jl/stable/) can be used to [generate LaTeX + expressions](@ref visualisation_latex) corresponding to generated mathematical models or the + underlying set of reactions. +- [Graphviz](https://graphviz.org/) can be used to generate and [visualize reaction network graphs](@ref visualisation_graphs) + (reusing the Graphviz interface created in [Catlab.jl](https://algebraicjulia.github.io/Catlab.jl/stable/)). +- Model steady states can be [computed through homotopy continuation](@ref homotopy_continuation) using [HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl) + (which can find *all* steady states of systems with multiple ones), by [forward ODE simulations](@ref steady_state_solving_simulation) using + [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by [numerically solving steady-state nonlinear equations](@ref steady_state_solving_nonlinear) using [NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl). +- [BifurcationKit.jl](https://github.com/bifurcationkit/BifurcationKit.jl) can be used to [compute + bifurcation diagrams](@ref bifurcation_diagrams) of models' steady states (including finding periodic orbits). +- [DynamicalSystems.jl](https://github.com/JuliaDynamics/DynamicalSystems.jl) can be used to compute + model [basins of attraction](@ref dynamical_systems_basins_of_attraction) and [Lyapunov spectrums](@ref dynamical_systems_lyapunov_exponents). +- [StructuralIdentifiability.jl](https://github.com/SciML/StructuralIdentifiability.jl) can be used + to [perform structural identifiability analysis](@ref structural_identifiability). +- [Optimization.jl](https://github.com/SciML/Optimization.jl), [DiffEqParamEstim.jl](https://github.com/SciML/DiffEqParamEstim.jl), + and [PEtab.jl](https://github.com/sebapersson/PEtab.jl) can all be used to [fit model parameters to data](https://sebapersson.github.io/PEtab.jl/stable/Define_in_julia/). +- [GlobalSensitivity.jl](https://github.com/SciML/GlobalSensitivity.jl) can be used to perform + [global sensitivity analysis](@ref global_sensitivity_analysis) of model behaviors. +- [SciMLSensitivity.jl](https://github.com/SciML/SciMLSensitivity.jl) can be used to compute local sensitivities of functions containing forward model simulations. + +#### [Features of packages built upon Catalyst](@id doc_index_features_other_packages) +- Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](@ref model_file_import_export_sbml) via + [SBMLImporter.jl](https://github.com/SciML/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), + and [from BioNetGen .net files](@ref model_file_import_export_sbml_rni_net) and various stoichiometric matrix network representations + using [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl). +- [MomentClosure.jl](https://github.com/augustinas1/MomentClosure.jl) allows generation of symbolic + ModelingToolkit `ODESystem`s that represent moment closure approximations to moments of the + Chemical Master Equation, from reaction networks defined in Catalyst. +- [FiniteStateProjection.jl](https://github.com/kaandocal/FiniteStateProjection.jl) + allows the construction and numerical solution of Chemical Master Equation + models from reaction networks defined in Catalyst. +- [DelaySSAToolkit.jl](https://github.com/palmtree2013/DelaySSAToolkit.jl) can + augment Catalyst reaction network models with delays, and can simulate the + resulting stochastic chemical kinetics with delays models. +- [BondGraphs.jl](https://github.com/jedforrest/BondGraphs.jl), a package for + constructing and analyzing bond graphs models, which can take Catalyst models as input. + +## [How to read this documentation](@id doc_index_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](@ref 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](@ref catalyst_for_new_julia_users) or [Introduction to Catalyst](@ref 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](@ref doc_index_reproducibility). + +For most code blocks in this documentation, the output of the last line of code is printed at the of the block, e.g. +```@example home_display +1 + 2 +``` +and +```@example home_display +using Catalyst # hide +@reaction_network begin + (p,d), 0 <--> X +end +``` +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: +```@example home_display +1 + 2 +nothing # hide +``` +and here: +```@example home_display +@reaction_network begin + (p,d), 0 <--> X +end +nothing # hide +``` + +## [Installation](@id doc_index_installation) +Catalyst is an officially registered Julia package, which can be installed through the Julia package manager: ```julia using Pkg Pkg.add("Catalyst") ``` -To solve Catalyst models and visualize solutions, it is also recommended to -install DifferentialEquations.jl and Plots.jl +Many Catalyst features require the installation of additional packages. E.g. for ODE-solving and simulation plotting ```julia Pkg.add("OrdinaryDiffEq") Pkg.add("Plots") ``` +is also needed. -## Illustrative Example -Here is a simple example of generating, visualizing and solving an SIR ODE -model. We first define the SIR reaction model using Catalyst -```@example ind1 -using Catalyst -rn = @reaction_network begin - α, S + I --> 2I - β, I --> R +A more throughout guide for setting up Catalyst and installing Julia packages can be found [here](@ref catalyst_for_new_julia_users_packages). + +## [Illustrative example](@id doc_index_example) + +#### [Deterministic ODE simulation of Michaelis-Menten enzyme kinetics](@id doc_index_example_ode) +Here we show a simple example where a model is created using the Catalyst DSL, and then simulated as +an ordinary differential equation. + +```@example home_simple_example +# 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) ``` -Assuming [Graphviz](https://graphviz.org/) and is installed and *command line -accessible*, the network can be visualized using the [`Graph`](@ref) command -```julia -Graph(rn) -``` -which in Jupyter notebooks will give the figure -![SIR Network Graph](assets/SIR_rn.svg) +#### [Stochastic jump simulations](@id doc_index_example_jump) +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. +```@example home_simple_example +# 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] +dprob = DiscreteProblem(model, u0_integers, tspan, ps) +jprob = JumpProblem(model, dprob, Direct()) +jump_sol = solve(jprob, SSAStepper()) +jump_sol = solve(jprob, SSAStepper(); seed = 1234) # hide +plot(jump_sol; lw = 2) +``` -To generate and solve a mass action ODE version of the model we use -```@example ind1 -using OrdinaryDiffEq -p = [:α => .1/1000, :β => .01] -tspan = (0.0,250.0) -u0 = [:S => 999.0, :I => 1.0, :R => 0.0] -op = ODEProblem(rn, u0, tspan, p) -sol = solve(op, Tsit5()) # use Tsit5 ODE solver +## [Elaborate example](@id doc_index_elaborate_example) +In the above example, we used basic Catalyst-based 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ᴾ$). The phosphorylation of $G$ +($G \to Gᴾ$) is promoted by sunlight (modeled as the cyclic sinusoid $kₐ*(sin(t)+1)$), which +phosphorylates the growth factor (producing $Gᴾ$). When the cell reaches a critical volume ($Vₘ$) +it undergoes cell division. First, we declare our model: +```@example home_elaborate_example +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 +```@example home_elaborate_example +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 produces the following equations: +```math +\begin{align*} +dG(t) &= - \left( \frac{kₚ*(sin(t)+1)}{V(t)} G(t) + \frac{kᵢ}{V(t)} Gᴾ(t) \right) dt - \sqrt{\frac{kₚ*(sin(t)+1)}{V(t)} G(t)} dW_1(t) + \sqrt{\frac{kᵢ}{V(t)} Gᴾ(t)} dW_2(t) & +dGᴾ(t) &= \left( \frac{kₚ*(sin(t)+1)}{V(t)} G(t) - \frac{kᵢ}{V(t)} Gᴾ(t) \right) dt + \sqrt{\frac{kₚ*(sin(t)+1)}{V(t)} G(t)} dW_1(t) - \sqrt{\frac{kᵢ}{V(t)} Gᴾ(t)} dW_2(t) & +dV(t) &= \left(g \cdot Gᴾ(t)\right) dt +\end{align*} ``` -which we can plot as -```@example ind1 -using Plots -plot(sol, lw=2) +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. +```@example home_elaborate_example +using StochasticDiffEq, Plots +sol = solve(sprob, EM(); dt = 0.05) +sol = solve(sprob, EM(); dt = 0.05, seed = 1234) # hide +plot(sol; xguide = "Time (au)", lw = 2) ``` -## Getting Help -Catalyst developers are active on the [Julia -Discourse](https://discourse.julialang.org/), and the [Julia -Slack's](https://julialang.slack.com) \#sciml-bridged and \#sciml-sysbio channels. -For bugs or feature requests [open an -issue](https://github.com/SciML/Catalyst.jl/issues). +## [Getting Help](@id doc_index_help) +Catalyst developers are active on the [Julia Discourse](https://discourse.julialang.org/), +the [Julia Slack](https://julialang.slack.com) channels \#sciml-bridged and \#sciml-sysbio, and the +[Julia Zulip sciml-bridged channel](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged). +For bugs or feature requests, [open an issue](https://github.com/SciML/Catalyst.jl/issues). -## [Supporting and Citing Catalyst.jl](@id catalyst_citation) -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: +## [Supporting and Citing Catalyst.jl](@id doc_index_citation) +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}, + 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 +## [Reproducibility](@id doc_index_reproducibility) ```@raw html
The documentation of this SciML package was built using these direct dependencies, ``` diff --git a/docs/src/introduction_to_catalyst/introduction_to_catalyst.md b/docs/src/introduction_to_catalyst/introduction_to_catalyst.md index 3fe15232c8..64f3819dc8 100644 --- a/docs/src/introduction_to_catalyst/introduction_to_catalyst.md +++ b/docs/src/introduction_to_catalyst/introduction_to_catalyst.md @@ -44,7 +44,7 @@ listed chemical species and unknowns. [`@reaction_network`](@ref) returns a [`ReactionSystem`](@ref), which we saved in the `repressilator` variable. It can be converted to a variety of other mathematical models represented as `ModelingToolkit.AbstractSystem`s, or analyzed in various ways using the -[Catalyst.jl API](@ref). For example, to see the chemical species, parameters, +[Catalyst.jl API](@ref api). For example, to see the chemical species, parameters, and reactions we can use ```@example tut1 species(repressilator) diff --git a/docs/src/inverse_problems/global_sensitivity_analysis.md b/docs/src/inverse_problems/global_sensitivity_analysis.md index cd65631c2f..e2a10759f9 100644 --- a/docs/src/inverse_problems/global_sensitivity_analysis.md +++ b/docs/src/inverse_problems/global_sensitivity_analysis.md @@ -142,7 +142,7 @@ Here, the function's sensitivity is evaluated with respect to each output indepe --- ## [Citations](@id global_sensitivity_analysis_citations) -If you use this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the following paper to support the authors of the GlobalSensitivity.jl package: +If you use this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the following paper to support the authors of the GlobalSensitivity.jl package: ``` @article{dixit2022globalsensitivity, title={GlobalSensitivity. jl: Performant and Parallel Global Sensitivity Analysis with Julia}, diff --git a/docs/src/model_creation/model_file_loading_and_export.md b/docs/src/model_creation/model_file_loading_and_export.md index 813ae5f401..43b6d16f22 100644 --- a/docs/src/model_creation/model_file_loading_and_export.md +++ b/docs/src/model_creation/model_file_loading_and_export.md @@ -1,7 +1,7 @@ -# Loading Chemical Reaction Network Models from Files +# [Loading Chemical Reaction Network Models from Files](@id model_file_import_export) Catalyst stores chemical reaction network (CRN) models in `ReactionSystem` structures. This tutorial describes how to load such `ReactionSystem`s from, and save them to, files. This can be used to save models between Julia sessions, or transfer them from one session to another. Furthermore, to facilitate the computation modelling of CRNs, several standardised file formats have been created to represent CRN models (e.g. [SBML](https://sbml.org/)). This enables CRN models to be shared between different softwares and programming languages. While Catalyst itself does not have the functionality for loading such files, we will here (briefly) introduce a few packages that can load different file types to Catalyst `ReactionSystem`s. -## Saving Catalyst models to, and loading them from, Julia files +## [Saving Catalyst models to, and loading them from, Julia files](@id model_file_import_export_crn_serialization) Catalyst provides a `save_reactionsystem` function, enabling the user to save a `ReactionSystem` to a file. Here we demonstrate this by first creating a [simple cross-coupling model](@ref basic_CRN_library_cc): ```@example file_handling_1 using Catalyst @@ -56,7 +56,7 @@ end In addition to transferring models between Julia sessions, the `save_reactionsystem` function can also be used or print a model to a text file where you can easily inspect its components. -## Loading and Saving arbitrary Julia variables using Serialization.jl +## [Loading and Saving arbitrary Julia variables using Serialization.jl](@id model_file_import_export_julia_serialisation) Julia provides a general and lightweight interface for loading and saving Julia structures to and from files that it can be good to be aware of. It is called [Serialization.jl](https://docs.julialang.org/en/v1/stdlib/Serialization/) and provides two functions, `serialize` and `deserialize`. The first allows us to write a Julia structure to a file. E.g. if we wish to save a parameter set associated with our model, we can use ```@example file_handling_2 using Serialization @@ -70,7 +70,7 @@ rm("saved_parameters.jls") # hide loaded_sol # hide ``` -## [Loading .net files using ReactionNetworkImporters.jl](@id file_loading_rni_net) +## [Loading .net files using ReactionNetworkImporters.jl](@id model_file_import_export_sbml_rni_net) A general-purpose format for storing CRN models is so-called .net files. These can be generated by e.g. [BioNetGen](https://bionetgen.org/). The [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl) package enables the loading of such files to Catalyst `ReactionSystem`. Here we load a [Repressilator](@ref basic_CRN_library_repressilator) model stored in the "repressilator.net" file: ```julia using ReactionNetworkImporters @@ -96,7 +96,7 @@ Note that, as all initial conditions and parameters have default values, we can A more detailed description of ReactionNetworkImporter's features can be found in its [documentation](https://docs.sciml.ai/ReactionNetworkImporters/stable/). -## Loading SBML files using SBMLImporter.jl and SBMLToolkit.jl +## [Loading SBML files using SBMLImporter.jl and SBMLToolkit.jl](@id model_file_import_export_sbml) The Systems Biology Markup Language (SBML) is the most widespread format for representing CRN models. Currently, there exist two different Julia packages, [SBMLImporter.jl](https://github.com/sebapersson/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), that are able to load SBML files to Catalyst `ReactionSystem` structures. SBML is able to represent a *very* wide range of model features, with both packages supporting most features. However, there exist SBML files (typically containing obscure model features such as events with time delays) that currently cannot be loaded into Catalyst models. SBMLImporter's `load_SBML` function can be used to load SBML files. Here, we load a [Brusselator](@ref basic_CRN_library_brusselator) model stored in the "brusselator.xml" file: @@ -104,7 +104,7 @@ SBMLImporter's `load_SBML` function can be used to load SBML files. Here, we loa using SBMLImporter prn, cbs = load_SBML("brusselator.xml", massaction = true) ``` -Here, while [ReactionNetworkImporters generates a `ParsedReactionSystem` only](@ref file_loading_rni_net), SBMLImporter generates a `ParsedReactionSystem` (here stored in `prn`) and a [so-called `CallbackSet`](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#CallbackSet) (here stored in `cbs`). While `prn` can be used to create various problems, when we simulate them, we must also supply `cbs`. E.g. to simulate our brusselator we use: +Here, while [ReactionNetworkImporters generates a `ParsedReactionSystem` only](@ref model_file_import_export_sbml_rni_net), SBMLImporter generates a `ParsedReactionSystem` (here stored in `prn`) and a [so-called `CallbackSet`](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#CallbackSet) (here stored in `cbs`). While `prn` can be used to create various problems, when we simulate them, we must also supply `cbs`. E.g. to simulate our brusselator we use: ```julia using Catalyst, OrdinaryDiffEq, Plots tspan = (0.0, 50.0) @@ -121,10 +121,10 @@ A more detailed description of SBMLImporter's features can be found in its [docu !!! note The `massaction = true` option informs the importer that the target model follows mass-action principles. When given, this enables SBMLImporter to make appropriate modifications to the model (which are important for e.g. jump simulation performance). -### SBMLImporter and SBMLToolkit +### [SBMLImporter and SBMLToolkit](@id model_file_import_export_package_alts) Above, we described how to use SBMLImporter to import SBML files. Alternatively, SBMLToolkit can be used instead. It has a slightly different syntax, which is described in its [documentation](https://github.com/SciML/SBMLToolkit.jl), and does not support as wide a range of SBML features as SBMLImporter. A short comparison of the two packages can be found [here](https://github.com/sebapersson/SBMLImporter.jl?tab=readme-ov-file#differences-compared-to-sbmltoolkit). Generally, while they both perform well, we note that for *jump simulations* SBMLImporter is preferable (its way for internally representing reaction event enables more performant jump simulations). -## Loading models from matrix representation using ReactionNetworkImporters.jl +## [Loading models from matrix representation using ReactionNetworkImporters.jl](@id model_file_import_export_matrix_representations) While CRN models can be represented through various file formats, they can also be represented in various matrix forms. E.g. a CRN with $m$ species and $n$ reactions (and with constant rates) can be represented with either - An $mxn$ substrate matrix (with each species's substrate stoichiometry in each reaction) and an $nxm$ product matrix (with each species's product stoichiometry in each reaction). @@ -136,7 +136,7 @@ The advantage of these forms is that they offer a compact and very general way t --- ## [Citations](@id petab_citations) -If you use any of this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the paper(s) corresponding to whichever package(s) you used: +If you use any of this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the paper(s) corresponding to whichever package(s) you used: ``` @software{2022ReactionNetworkImporters, author = {Isaacson, Samuel}, diff --git a/docs/src/model_creation/programmatic_CRN_construction.md b/docs/src/model_creation/programmatic_CRN_construction.md index a8e7f15d86..5232db3886 100644 --- a/docs/src/model_creation/programmatic_CRN_construction.md +++ b/docs/src/model_creation/programmatic_CRN_construction.md @@ -180,7 +180,7 @@ This ensured they were properly treated as species and not parameters. See the ## Basic querying of `ReactionSystems` -The [Catalyst.jl API](@ref) provides a large variety of functionality for +The [Catalyst.jl API](@ref api) provides a large variety of functionality for querying properties of a reaction network. Here we go over a few of the most useful basic functions. Given the `repressillator` defined above we have that ```@example ex @@ -247,5 +247,5 @@ rx1.prodstoich rx1.netstoich ``` -See the [Catalyst.jl API](@ref) for much more detail on the various querying and +See the [Catalyst.jl API](@ref api) for much more detail on the various querying and analysis functions provided by Catalyst. diff --git a/docs/src/steady_state_functionality/dynamical_systems.md b/docs/src/steady_state_functionality/dynamical_systems.md index 5b844e065d..ab48f99bac 100644 --- a/docs/src/steady_state_functionality/dynamical_systems.md +++ b/docs/src/steady_state_functionality/dynamical_systems.md @@ -124,7 +124,7 @@ More details on how to compute Lyapunov exponents using DynamicalSystems.jl can --- ## [Citations](@id dynamical_systems_citations) -If you use this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the following paper to support the author of the DynamicalSystems.jl package: +If you use this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the following paper to support the author of the DynamicalSystems.jl package: ``` @article{DynamicalSystems.jl-2018, doi = {10.21105/joss.00598}, diff --git a/docs/src/steady_state_functionality/nonlinear_solve.md b/docs/src/steady_state_functionality/nonlinear_solve.md index 0630da11fa..d5e438d89c 100644 --- a/docs/src/steady_state_functionality/nonlinear_solve.md +++ b/docs/src/steady_state_functionality/nonlinear_solve.md @@ -133,7 +133,7 @@ However, especially when the forward ODE simulation approach is used, it is reco --- ## [Citations](@id nonlinear_solve_citation) -If you use this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the following paper to support the authors of the NonlinearSolve.jl package: +If you use this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the following paper to support the authors of the NonlinearSolve.jl package: ``` @article{pal2024nonlinearsolve, title={NonlinearSolve. jl: High-Performance and Robust Solvers for Systems of Nonlinear Equations in Julia}, diff --git a/docs/src/steady_state_functionality/steady_state_stability_computation.md b/docs/src/steady_state_functionality/steady_state_stability_computation.md index b23a0b0d88..08e6fa69b2 100644 --- a/docs/src/steady_state_functionality/steady_state_stability_computation.md +++ b/docs/src/steady_state_functionality/steady_state_stability_computation.md @@ -1,10 +1,10 @@ -# Steady state stability computation +# [Steady state stability computation](@id steady_state_stability) After system steady states have been found using [HomotopyContinuation.jl](@ref homotopy_continuation), [NonlinearSolve.jl](@ref steady_state_solving), or other means, their stability can be computed using Catalyst's `steady_state_stability` function. Systems with conservation laws will automatically have these removed, permitting stability computation on systems with singular Jacobian. !!! warn Catalyst currently computes steady state stabilities using the naive approach of checking whether a system's largest eigenvalue real part is negative. While more advanced stability computation methods exist (and would be a welcome addition to Catalyst), there is no direct plans to implement these. Furthermore, Catalyst uses a tolerance `tol = 10*sqrt(eps())` to determine whether a computed eigenvalue is far away enough from 0 to be reliably used. This threshold can be changed through the `tol` keyword argument. -## Basic examples +## [Basic examples](@id steady_state_stability_basics) Let us consider the following basic example: ```@example stability_1 using Catalyst @@ -42,7 +42,7 @@ Finally, as described above, Catalyst uses an optional argument, `tol`, to deter nothing# hide ``` -## Pre-computing the Jacobian to increase performance when computing stability for many steady states +## [Pre-computing the Jacobian to increase performance when computing stability for many steady states](@id steady_state_stability_jacobian) Catalyst uses the system Jacobian to compute steady state stability, and the Jacobian is computed once for each call to `steady_state_stability`. If you repeatedly compute stability for steady states of the same system, pre-computing the Jacobian and supplying it to the `steady_state_stability` function can improve performance. In this example we use the self-activation loop from previously, pre-computes its Jacobian, and uses it to multiple `steady_state_stability` calls: diff --git a/docs/unpublished/petab_ode_param_fitting.md b/docs/unpublished/petab_ode_param_fitting.md index 9e503d7411..64b61df5bf 100644 --- a/docs/unpublished/petab_ode_param_fitting.md +++ b/docs/unpublished/petab_ode_param_fitting.md @@ -523,7 +523,7 @@ There exist several types of plots for both types of calibration results. More d --- ## [Citations](@id petab_citations) -If you use this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the following papers to support the authors of the PEtab.jl package (currently there is no article associated with this package) and the PEtab standard: +If you use this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the following papers to support the authors of the PEtab.jl package (currently there is no article associated with this package) and the PEtab standard: ``` @misc{2023Petabljl, author = {Ognissanti, Damiano AND Arutjunjan, Rafael AND Persson, Sebastian AND Hasselgren, Viktor},