From 0aa69d590e21b9f48aec706f5f5fc8297d3e6f14 Mon Sep 17 00:00:00 2001 From: Torkel Date: Mon, 15 Apr 2024 15:59:28 -0400 Subject: [PATCH 01/27] save progress --- README.md | 57 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 0f8d03e474..fa9b723e4a 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,7 @@ documentation](https://docs.sciml.ai/Catalyst/stable/). The [in-development documentation](https://docs.sciml.ai/Catalyst/dev/) describes unreleased features in the current master branch. -Several Youtube video tutorials and overviews are also available, but note these use older -Catalyst versions with slightly different notation (for example, in building reaction networks): +Several Youtube video tutorials and overviews are also available (however, these use older versions of Catalyst, and some notation may be out-of-date): - From JuliaCon 2023: A short 15 minute overview of Catalyst as of version 13 is available in the talk [Catalyst.jl, Modeling Chemical Reaction Networks](https://www.youtube.com/watch?v=yreW94n98eM&ab_channel=TheJuliaProgrammingLanguage). - From JuliaCon 2022: A three hour tutorial workshop overviewing how to use @@ -63,6 +62,8 @@ Finally, an overview of the package and its features (as of version 13) can also ## Features +#### Features of Catalyst + - A DSL provides a simple and readable format for manually specifying chemical reactions. - Catalyst `ReactionSystem`s provide a symbolic representation of reaction networks, @@ -71,17 +72,19 @@ Finally, an overview of the package and its features (as of version 13) can also - 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](http://docs.sciml.ai/Catalyst/stable/api/catalyst_api) provides functionality for extending networks, - building networks programmatically, network analysis, and for composing multiple - networks together. +- The [Catalyst.jl API](http://docs.sciml.ai/Catalyst/stable/api/catalyst_api) provides functionality + for extending networks, building networks programmatically, network analysis, and for composing + multiple networks together. +- A network analysis suite permitting the computation of linkage classes, deficiencies, reversibilities. +- 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. - `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. + Catalyst models (and are incorporated during conversion to ODEs, SDEs, and steady + state equations). +- Modelling of simulation events. - 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 @@ -97,17 +100,38 @@ Finally, an overview of the package and its features (as of version 13) can also 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. +- Determination of steady state stabilities. + + +#### Features of Catalyst composing with other packages +- [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) Can be used to perform ODE simulation of CRN models. +- [StochasticDiffEq.jl](https://github.com/SciML/StochasticDiffEq.jl) Can be used to perform SDE simulation of CRN models. +- [JumpProcesses.jl](https://github.com/SciML/JumpProcesses.jl) Can be used to perform jump simulations of CRN models. +- Support for automatic parallelisation of all simulations, including parallelisation of ODE simulations using + [DiffEqGPU.jl](https://github.com/SciML/DiffEqGPU.jl). - [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 +- [HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl) can be used to computer *all* steady states for CRN models with + multiple steady states. +- [NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl) can be used to find single steady states of CRN models (offering higher + performance than the homotopy continuation approach). +- [BifurcationKit.jl](https://github.com/bifurcationkit/BifurcationKit.jl) can be used to compute bifurcation diagrams of CRN models' steady state + (including finding periodic orbits). +- [DynamicalSystems.jl](https://github.com/JuliaDynamics/DynamicalSystems.jl) can be used to computer basins of attraction and Lyaponov spectrum for CRN models. +- [StructuralIdentifiability.jl](https://github.com/SciML/StructuralIdentifiability.jl) can be used to perform structural identifiability analysis of + CRN models. +- [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 CRN model + parameters to data. +- [GlobalSensitivity.jl](https://github.com/SciML/GlobalSensitivity.jl) can be used to perform global sensitivity analysis of model behaviours. + +#### Features of packages built upon Catalyst - Catalyst [`ReactionSystem`](@ref)s can be imported from SBML files via - [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), and from BioNetGen .net - files and various stoichiometric matrix network representations using + [SBMLImporter.jl](https://github.com/SciML/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), + and from BioNetGen .net files 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, representing moment @@ -121,10 +145,11 @@ Finally, an overview of the package and its features (as of version 13) can also 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. +- [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. -## Illustrative examples +## Simple example #### Gillespie simulations of Michaelis-Menten enzyme kinetics ```julia @@ -164,6 +189,8 @@ ssol = solve(sprob, LambaEM(), reltol=1e-3) plot(ssol; lw = 2, title = "Adaptive SDE: Birth-Death Process") ``` +## Elaborate example + ![](https://user-images.githubusercontent.com/1814174/87864113-3bf9dd00-c932-11ea-8275-f903eef90b91.png) ## Getting help From 96439ca6a70eda722f93974861b2b047445bab90 Mon Sep 17 00:00:00 2001 From: Torkel Date: Thu, 25 Apr 2024 12:31:16 -0400 Subject: [PATCH 02/27] save progress --- README.md | 315 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 178 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index fa9b723e4a..6ea2ddc046 100644 --- a/README.md +++ b/README.md @@ -13,12 +13,12 @@ [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac) [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle) -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`](https://docs.sciml.ai/Catalyst/stable/catalyst_functionality/programmatic_CRN_construction/)s, which can be created programmatically or easily -specified using Catalyst's domain specific language (DSL). Leveraging -[ModelingToolkit](https://github.com/SciML/ModelingToolkit.jl) and +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 @@ -31,10 +31,9 @@ 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. +**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](HISTORY.md) file. +Breaking changes and new functionality are summarized in the [HISTORY.md](HISTORY.md) file. This also includes a special migration guide for version 14. ## Tutorials and documentation @@ -43,20 +42,20 @@ documentation](https://docs.sciml.ai/Catalyst/stable/). The [in-development documentation](https://docs.sciml.ai/Catalyst/dev/) describes unreleased features in the current master branch. -Several Youtube video tutorials and overviews are also available (however, these use older versions of Catalyst, and some notation may be out-of-date): -- From JuliaCon 2023: A short 15 minute overview of Catalyst as of version 13 is +Several YouTube video tutorials and overviews are also available (however, these use older versions of Catalyst, and some notation may be out-of-date): +- From JuliaCon 2023: A short 15-minute overview of Catalyst (version 13) is available in the talk [Catalyst.jl, Modeling Chemical Reaction Networks](https://www.youtube.com/watch?v=yreW94n98eM&ab_channel=TheJuliaProgrammingLanguage). -- From JuliaCon 2022: A three hour tutorial workshop overviewing how to use - Catalyst and its more advanced features as of version 12.1. [Workshop - video](https://youtu.be/tVfxT09AtWQ), [Workshop Pluto.jl - Notebooks](https://github.com/SciML/JuliaCon2022_Catalyst_Workshop). -- From SIAM CSE 2021: A short 15 minute overview of Catalyst as of version 6 is +- From JuliaCon 2022: A 3-hour tutorial workshop overviewing how to use + Catalyst (version 12.1) and its more advanced features. [Workshop + video](https://youtu.be/tVfxT09AtWQ), [Workshop Pluto.jl + Notebooks](https://github.com/SciML/JuliaCon2022_Catalyst_Workshop). +- From SIAM CSE 2021: A short 15-minute overview of Catalyst (version 6) is available in the talk [Modeling Biochemical Systems with Catalyst.jl](https://www.youtube.com/watch?v=5p1PJE5A5Jw). -- From JuliaCon 2018: A short 13 minute overview of Catalyst when it was known - as DiffEqBiological in older versions is available in the talk [Efficient - Modelling of Biochemical Reaction - Networks](https://www.youtube.com/watch?v=s1e72k5XD6s) +- From JuliaCon 2018: A short 13-minute overview of Catalyst (when it was known + as DiffEqBiological) is available in the talk [Efficient + Modelling of Biochemical Reaction + Networks](https://www.youtube.com/watch?v=s1e72k5XD6s) Finally, an overview of the package and its features (as of version 13) can also be found in its corresponding research paper, [Catalyst: Fast and flexible modeling of reaction networks](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530). @@ -64,157 +63,199 @@ Finally, an overview of the package and its features (as of version 13) can also #### Features of Catalyst -- 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 DSL](@ref ref) 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](http://docs.sciml.ai/Catalyst/stable/api/catalyst_api) provides functionality - for extending networks, building networks programmatically, network analysis, and for composing - multiple networks together. -- A network analysis suite permitting the computation of linkage classes, deficiencies, reversibilities. -- 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. -- `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, SDEs, and steady - state equations). -- Modelling of simulation events. + for extending networks, building networks programmatically, and for composing + multiple networks together. +- Generated systems can be simulated using any + [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) + [ODE/SDE/jump solver](@ref ref), and can be used within `EnsembleProblem`s for carrying + out [parallelized parameter sweeps and statistical sampling](@ref ref). Plot recipes + are available for [visualizing of all solutions](@ref ref). +- Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](@ref ref) for generating + ODE models, and symbolic expressions for stoichiometric coefficients [are supported](@ref ref) for + all system types. +- A [network analysis suite](@ref ref) permits the computation of linkage classes, deficiencies, and + reversibilities. +- [Conservation laws can be detected and utilised](@ref ref) 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 ref) + (which are then incorporated during conversion to ODEs, SDEs, and steady state equations). +- Models can be [coupled with events](@ref ref) 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 ref), [multithreading or parallelization of generated + derivative functions](@ref ref), [automatic classification of reactions into optimized + jump types for Gillespie type simulations](@ref ref), [automatic construction of + dependency graphs for jump systems](@ref ref), 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. -- Determination of steady state stabilities. + 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 ref) (and their [stabilities](@ref ref)) can be computed for model ODE representations. #### Features of Catalyst composing with other packages -- [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) Can be used to perform ODE simulation of CRN models. -- [StochasticDiffEq.jl](https://github.com/SciML/StochasticDiffEq.jl) Can be used to perform SDE simulation of CRN models. -- [JumpProcesses.jl](https://github.com/SciML/JumpProcesses.jl) Can be used to perform jump simulations of CRN models. -- Support for automatic parallelisation of all simulations, including parallelisation of ODE simulations using - [DiffEqGPU.jl](https://github.com/SciML/DiffEqGPU.jl). -- [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/).) -- [HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl) can be used to computer *all* steady states for CRN models with - multiple steady states. -- [NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl) can be used to find single steady states of CRN models (offering higher - performance than the homotopy continuation approach). -- [BifurcationKit.jl](https://github.com/bifurcationkit/BifurcationKit.jl) can be used to compute bifurcation diagrams of CRN models' steady state - (including finding periodic orbits). -- [DynamicalSystems.jl](https://github.com/JuliaDynamics/DynamicalSystems.jl) can be used to computer basins of attraction and Lyaponov spectrum for CRN models. -- [StructuralIdentifiability.jl](https://github.com/SciML/StructuralIdentifiability.jl) can be used to perform structural identifiability analysis of - CRN models. -- [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 CRN model - parameters to data. -- [GlobalSensitivity.jl](https://github.com/SciML/GlobalSensitivity.jl) can be used to perform global sensitivity analysis of model behaviours. +- [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) Can be used to [perform model ODE + simulations](@ref ref). +- [StochasticDiffEq.jl](https://github.com/SciML/StochasticDiffEq.jl) Can be used to [perform model + SDE simulations](@ref ref). +- [JumpProcesses.jl](https://github.com/SciML/JumpProcesses.jl) Can be used to [model jump + simulations](@ref ref). +- Support for [parallelisation of all simulations]((@ref ref)), including parallelisation of + [ODE simulations on GPUs](@ref ref) 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 ref) 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 ref) + (reusing the Graphviz interface created in [Catlab.jl](https://algebraicjulia.github.io/Catlab.jl/stable/).) +- Models steady states can be computed through 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 using + [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by nonlinear systems + solving 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 ref) 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 ref) and [Lyapunov spectrums](@ref ref). +- [StructuralIdentifiability.jl](https://github.com/SciML/StructuralIdentifiability.jl) can be used + to [perform structural identifiability analysis](@ref ref). +- [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](@ref ref). +- [GlobalSensitivity.jl](https://github.com/SciML/GlobalSensitivity.jl) can be used to perform + [global sensitivity analysis](@ref ref) of model behaviours. #### Features of packages built upon Catalyst -- Catalyst [`ReactionSystem`](@ref)s can be imported from SBML files via - [SBMLImporter.jl](https://github.com/SciML/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), - and from BioNetGen .net files 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, representing moment - closure approximations to moments of the Chemical Master Equation, from - reaction networks defined in Catalyst. +- Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](@ref ref) via + [SBMLImporter.jl](https://github.com/SciML/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), + and [from BioNetGen .net files](@ref ref) 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. + 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. + 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. + 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. + fitting reaction network ODEs to data. Input can be provided either as SBML files or as Catalyst + `ReactionSystem`s. -## Simple example -#### Gillespie simulations of Michaelis-Menten enzyme kinetics +## 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. ```julia -using Catalyst, Plots, JumpProcesses -rs = @reaction_network begin - c1, S + E --> SE - c2, SE --> S + E - c3, SE --> P + E +# Fetch required packages. +using Catalyst, DifferentialEquations, Plots + +# Create model. +model = @reaction_network begin + kB, S + E --> SE + kD, SE --> S + E + kP, SE --> P + E end -p = (:c1 => 0.00166, :c2 => 0.0001, :c3 => 0.1) -tspan = (0., 100.) -u0 = [:S => 301, :E => 100, :SE => 0, :P => 0] - -# solve JumpProblem -dprob = DiscreteProblem(rs, u0, tspan, p) -jprob = JumpProblem(rs, dprob, Direct()) -jsol = solve(jprob, SSAStepper()) -plot(jsol; lw = 2, title = "Gillespie: Michaelis-Menten Enzyme Kinetics") + +# Create an ODE that can be simulated. +u0 = [:S => 50, :E => 10, :SE => 0, :P => 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) ``` ![](https://user-images.githubusercontent.com/1814174/87864114-3bf9dd00-c932-11ea-83a0-58f38aee8bfb.png) -#### Adaptive time stepping SDEs for a birth-death process - +#### Stochastic jump simulations +The same model can be used as input to other types of simulations. E.g. here we instead perform a +jump simulation ```julia -using Catalyst, Plots, StochasticDiffEq -rs = @reaction_network begin - c1, X --> 2X - c2, X --> 0 - c3, 0 --> X -end -p = (:c1 => 1.0, :c2 => 2.0, :c3 => 50.) -tspan = (0.,10.) -u0 = [:X => 5.] -sprob = SDEProblem(rs, u0, tspan, p) -ssol = solve(sprob, LambaEM(), reltol=1e-3) -plot(ssol; lw = 2, title = "Adaptive SDE: Birth-Death Process") +# Create and simulate a jump process (here using Gillespie's direct algorithm). +dprob = DiscreteProblem(model, u0, tspan, ps) +jprob = JumpProblem(model, dprob, Direct()) +jump_sol = solve(jprob, SSAStepper()) +plot(jump_sol; lw = 2) ``` + ## Elaborate example -![](https://user-images.githubusercontent.com/1814174/87864113-3bf9dd00-c932-11ea-8275-f903eef90b91.png) +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$). Typically the growth factor is inactive ($Gi$), but it is activated ($Ga$) by the presence of sunlight (modelled as the cyclic sinusoid $kA*(sin(t)+1)$). When the cell reaches a critical volume ($V$) it goes through cell division. First, we declare our model: +```julia +cell_model = @reaction_network begin + @parameters V_thres g + @equations begin + D(V) ~ g*Ga + end + @continuous_events begin + [V ~ V_thres] => [V ~ V/2] + end + (kA*(sin(t)+1), kI), Gi <--> Ga +end +``` +Next, we can use [Latexify.jl](https://korsbo.github.io/Latexify.jl/stable/) to show the ordinary differential equations associated with this model: +```julia +using Latexify +latexify(cell_model; form = :ode) +``` +In this case we would like to perform stochastic simulations, so we transform our model to an SDE: +```julia +u0 = [:V => 0.5, :Gi => 1.0, :Ga => 0.0] +tspan = (0.0, 10.0) +ps = [:V_thres => 1.0, :g => 0.5, :kA => 5.0, :kI => 2.0] +sprob = SDEProblem(cell_model, u0, tspan, ps) +``` +Finally, we simulate it and plot the result. +```julia +sol = solve(oprob, Tsit5()) +plot(sol) +``` -## Getting 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). +## Getting help or getting involved +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). +If you are interested in participating in the development of Catalyst, or integrating your package(s) +with it, developer documentation can be found [here](@ref ref). Are you a student (or similar) who +wishes to do a Google Summer of Code (or similar) project tied to Catalyst? Information on how to get +involved, including good first issues to get familiar with working on the package, can be found [here](@ref ref). ## 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: +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}, } ``` + +We also maintain a user survey, asking basic questions about how users utilise the package. The survey +is available [here](ref), and only takes about 5 minutes to fill out. We are grateful to those who +fill out the survey, as this helps us further develop the package. \ No newline at end of file From 1fb33cf9686f11673613b6efb3f98ecfeed07f67 Mon Sep 17 00:00:00 2001 From: Torkel Date: Thu, 25 Apr 2024 15:41:28 -0400 Subject: [PATCH 03/27] save progress --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6ea2ddc046..56060608ac 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ large-scale simulations through auto-vectorization and parallelism. Symbolic 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). @@ -193,7 +193,7 @@ plot(jump_sol; lw = 2) ## 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$). Typically the growth factor is inactive ($Gi$), but it is activated ($Ga$) by the presence of sunlight (modelled as the cyclic sinusoid $kA*(sin(t)+1)$). When the cell reaches a critical volume ($V$) it goes through cell division. First, we declare our model: +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$). Typically the growth factor is inactive ($Gi$), but it is activated ($Ga$) by the presence of sunlight (modeled as the cyclic sinusoid $kA*(sin(t)+1)$). When the cell reaches a critical volume ($V$) it goes through cell division. First, we declare our model: ```julia cell_model = @reaction_network begin @parameters V_thres g From 8e636de6f2db03b8c51d8dfe4dafefe684e607cf Mon Sep 17 00:00:00 2001 From: Torkel Date: Sat, 18 May 2024 14:40:12 -0400 Subject: [PATCH 04/27] add simulation figures --- README.md | 80 +++++++++---------- docs/src/assets/readme_elaborate_sde_plot.svg | 50 ++++++++++++ docs/src/assets/readme_jump_plot.svg | 54 +++++++++++++ docs/src/assets/readme_ode_plot.svg | 54 +++++++++++++ 4 files changed, 196 insertions(+), 42 deletions(-) create mode 100644 docs/src/assets/readme_elaborate_sde_plot.svg create mode 100644 docs/src/assets/readme_jump_plot.svg create mode 100644 docs/src/assets/readme_ode_plot.svg diff --git a/README.md b/README.md index 56060608ac..3dd84bef27 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,7 @@ [![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged) [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://docs.sciml.ai/Catalyst/stable/) [![API Stable](https://img.shields.io/badge/API-stable-blue.svg)](https://docs.sciml.ai/Catalyst/stable/api/catalyst_api/) - +[![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged) [![Build Status](https://github.com/SciML/Catalyst.jl/workflows/CI/badge.svg)](https://github.com/SciML/Catalyst.jl/actions?query=workflow%3ACI) [![codecov.io](https://codecov.io/gh/SciML/Catalyst.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/Catalyst.jl) @@ -22,7 +21,7 @@ specified using Catalyst's domain-specific language (DSL). Leveraging [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 +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. @@ -37,27 +36,12 @@ Breaking changes and new functionality are summarized in the [HISTORY.md](HISTOR ## Tutorials and documentation -The latest tutorials and information on using the package are available in the [stable +The latest tutorials and information on using Catalyst are available in the [stable documentation](https://docs.sciml.ai/Catalyst/stable/). The [in-development documentation](https://docs.sciml.ai/Catalyst/dev/) describes unreleased features in the current master branch. -Several YouTube video tutorials and overviews are also available (however, these use older versions of Catalyst, and some notation may be out-of-date): -- From JuliaCon 2023: A short 15-minute overview of Catalyst (version 13) is -available in the talk [Catalyst.jl, Modeling Chemical Reaction Networks](https://www.youtube.com/watch?v=yreW94n98eM&ab_channel=TheJuliaProgrammingLanguage). -- From JuliaCon 2022: A 3-hour tutorial workshop overviewing how to use - Catalyst (version 12.1) and its more advanced features. [Workshop - video](https://youtu.be/tVfxT09AtWQ), [Workshop Pluto.jl - Notebooks](https://github.com/SciML/JuliaCon2022_Catalyst_Workshop). -- From SIAM CSE 2021: A short 15-minute overview of Catalyst (version 6) is -available in the talk [Modeling Biochemical Systems with -Catalyst.jl](https://www.youtube.com/watch?v=5p1PJE5A5Jw). -- From JuliaCon 2018: A short 13-minute overview of Catalyst (when it was known - as DiffEqBiological) is available in the talk [Efficient - Modelling of Biochemical Reaction - Networks](https://www.youtube.com/watch?v=s1e72k5XD6s) - -Finally, an overview of the package and its features (as of version 13) can also be found in its corresponding research paper, [Catalyst: Fast and flexible modeling of reaction networks](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530). +An overview of the package and its features (as of version 13) can also be found in its corresponding research paper, [Catalyst: Fast and flexible modeling of reaction networks](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530). ## Features @@ -71,7 +55,7 @@ Finally, an overview of the package and its features (as of version 13) can also - The [Catalyst.jl API](http://docs.sciml.ai/Catalyst/stable/api/catalyst_api) provides functionality for extending networks, building networks programmatically, and for composing multiple networks together. -- Generated systems can be simulated using any +- Generated models can be simulated using any [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) [ODE/SDE/jump solver](@ref ref), and can be used within `EnsembleProblem`s for carrying out [parallelized parameter sweeps and statistical sampling](@ref ref). Plot recipes @@ -157,13 +141,13 @@ an ordinary differential equation. ```julia # Fetch required packages. -using Catalyst, DifferentialEquations, Plots +using Catalyst, OrdinaryDiffEq, Plots # Create model. model = @reaction_network begin - kB, S + E --> SE - kD, SE --> S + E - kP, SE --> P + E + kB, S + E --> SE + kD, SE --> S + E + kP, SE --> P + E end # Create an ODE that can be simulated. @@ -176,34 +160,38 @@ ode = ODEProblem(model, u0, tspan, ps) sol = solve(ode) plot(sol; lw = 5) ``` - -![](https://user-images.githubusercontent.com/1814174/87864114-3bf9dd00-c932-11ea-83a0-58f38aee8bfb.png) +![ODE simulation](docs/src/assets/readme_ode_plot.svg) #### Stochastic jump simulations The same model can be used as input to other types of simulations. E.g. here we instead perform a jump simulation ```julia # Create and simulate a jump process (here using Gillespie's direct algorithm). +using JumpProcesses dprob = DiscreteProblem(model, u0, tspan, ps) jprob = JumpProblem(model, dprob, Direct()) jump_sol = solve(jprob, SSAStepper()) plot(jump_sol; lw = 2) ``` +![Jump simulation](docs/src/assets/readme_jump_plot.svg) ## 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$). Typically the growth factor is inactive ($Gi$), but it is activated ($Ga$) by the presence of sunlight (modeled as the cyclic sinusoid $kA*(sin(t)+1)$). When the cell reaches a critical volume ($V$) it goes through cell division. First, we declare our model: +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 (modelled as the cyclic sinusoid $kₐ*(sin(t)+1)$) phosphorylates the growth factor (producing $Gᴾ$). When the cell reaches a critical volume ($V$) it goes through cell division. First, we declare our model: ```julia +using Catalyst cell_model = @reaction_network begin - @parameters V_thres g - @equations begin - D(V) ~ g*Ga - end - @continuous_events begin - [V ~ V_thres] => [V ~ V/2] - end - (kA*(sin(t)+1), kI), Gi <--> Ga + @parameters Vₘₐₓ g Ω + @default_noise_scaling Ω + @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 ``` Next, we can use [Latexify.jl](https://korsbo.github.io/Latexify.jl/stable/) to show the ordinary differential equations associated with this model: @@ -211,18 +199,26 @@ Next, we can use [Latexify.jl](https://korsbo.github.io/Latexify.jl/stable/) to using Latexify latexify(cell_model; form = :ode) ``` -In this case we would like to perform stochastic simulations, so we transform our model to an SDE: +In this case, we would instead like to perform stochastic simulations, so we transform our model to an SDE: ```julia -u0 = [:V => 0.5, :Gi => 1.0, :Ga => 0.0] -tspan = (0.0, 10.0) -ps = [:V_thres => 1.0, :g => 0.5, :kA => 5.0, :kI => 2.0] +u0 = [:V => 0.5, :G => 1.0, :Gᴾ => 0.0] +tspan = (0.0, 20.0) +ps = [:Vₘₐₓ => 1.0, :g => 0.2, :kₚ => 5.0, :kᵢ => 2.0, :Ω => 0.1] sprob = SDEProblem(cell_model, u0, tspan, ps) ``` Finally, we simulate it and plot the result. ```julia -sol = solve(oprob, Tsit5()) -plot(sol) +using StochasticDiffEq +sol = solve(sprob, STrapezoid()) +plot(sol; xguide = "Time (au)", lw = 2) ``` +![Elaborate SDE simulation](docs/src/assets/readme_elaborate_sde_plot.svg) + +Some features we used here: +- The SDE was [simulated using StochasticDiffEq.jl], where we [scaled the SDE noise terms](@ref ref). +- The cell volume was [modelled as a differential equation, which was coupled to the reaction network model](@ref ref). +- The cell divisions were created by [incorporating events into the model](@ref ref). +- The model equations were [displayed using Latexify.jl](@ref ref), and the simulation [plotted using Plots.jl](@ref ref). ## Getting help or getting involved Catalyst developers are active on the [Julia Discourse](https://discourse.julialang.org/), diff --git a/docs/src/assets/readme_elaborate_sde_plot.svg b/docs/src/assets/readme_elaborate_sde_plot.svg new file mode 100644 index 0000000000..eeb1d0f2fd --- /dev/null +++ b/docs/src/assets/readme_elaborate_sde_plot.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/src/assets/readme_jump_plot.svg b/docs/src/assets/readme_jump_plot.svg new file mode 100644 index 0000000000..5c45563c97 --- /dev/null +++ b/docs/src/assets/readme_jump_plot.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/src/assets/readme_ode_plot.svg b/docs/src/assets/readme_ode_plot.svg new file mode 100644 index 0000000000..df9c2eb095 --- /dev/null +++ b/docs/src/assets/readme_ode_plot.svg @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 966355ed4a02e18b11f70223786bc175cedd9df4 Mon Sep 17 00:00:00 2001 From: Torkel Date: Sat, 18 May 2024 17:42:25 -0400 Subject: [PATCH 05/27] up --- README.md | 5 +- docs/Project.toml | 1 - docs/src/assets/readme_elaborate_sde_plot.svg | 72 +++++++++---------- 3 files changed, 37 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 3dd84bef27..0567a3a052 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Catalyst.jl -[![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged) [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://docs.sciml.ai/Catalyst/stable/) [![API Stable](https://img.shields.io/badge/API-stable-blue.svg)](https://docs.sciml.ai/Catalyst/stable/api/catalyst_api/) [![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged) +[![Citation](https://img.shields.io/badge/Publication-389826)](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530) [![Build Status](https://github.com/SciML/Catalyst.jl/workflows/CI/badge.svg)](https://github.com/SciML/Catalyst.jl/actions?query=workflow%3ACI) [![codecov.io](https://codecov.io/gh/SciML/Catalyst.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/Catalyst.jl) @@ -46,7 +46,6 @@ An overview of the package and its features (as of version 13) can also be found ## Features #### Features of Catalyst - - [The Catalyst DSL](@ref ref) 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, @@ -81,7 +80,6 @@ An overview of the package and its features (as of version 13) can also be found deterministic and stochastic terms within resulting ODE, SDE or jump models. - [Steady states](@ref ref) (and their [stabilities](@ref ref)) can be computed for model ODE representations. - #### Features of Catalyst composing with other packages - [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) Can be used to [perform model ODE simulations](@ref ref). @@ -177,7 +175,6 @@ plot(jump_sol; lw = 2) ## 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 (modelled as the cyclic sinusoid $kₐ*(sin(t)+1)$) phosphorylates the growth factor (producing $Gᴾ$). When the cell reaches a critical volume ($V$) it goes through cell division. First, we declare our model: ```julia using Catalyst diff --git a/docs/Project.toml b/docs/Project.toml index 28d446f257..bdd31db760 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -26,7 +26,6 @@ OptimizationOptimJL = "36348300-93cb-4f02-beb5-3c3902f8871e" OptimizationOptimisers = "42dfb2eb-d2b4-4451-abcd-913932933ac1" OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" -QuasiMonteCarlo = "8a4e6c94-4038-4cdc-81c3-7e6ffdb2a71b" SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462" SciMLSensitivity = "1ed8b502-d754-442c-8d5d-10ac956f44a1" Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46" diff --git a/docs/src/assets/readme_elaborate_sde_plot.svg b/docs/src/assets/readme_elaborate_sde_plot.svg index eeb1d0f2fd..a906bbbfc9 100644 --- a/docs/src/assets/readme_elaborate_sde_plot.svg +++ b/docs/src/assets/readme_elaborate_sde_plot.svg @@ -1,50 +1,50 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 16579e7fc73090bddedf8671bc25d39ab16d18ed Mon Sep 17 00:00:00 2001 From: Torkel Date: Sat, 18 May 2024 17:45:44 -0400 Subject: [PATCH 06/27] add missing compat entry --- docs/Project.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/Project.toml b/docs/Project.toml index bdd31db760..28d446f257 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -26,6 +26,7 @@ OptimizationOptimJL = "36348300-93cb-4f02-beb5-3c3902f8871e" OptimizationOptimisers = "42dfb2eb-d2b4-4451-abcd-913932933ac1" OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" +QuasiMonteCarlo = "8a4e6c94-4038-4cdc-81c3-7e6ffdb2a71b" SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462" SciMLSensitivity = "1ed8b502-d754-442c-8d5d-10ac956f44a1" Setfield = "efcf1570-3423-57d1-acb7-fd33fddbac46" From 8096b7e5fbbd724ee6ce3b7388c513032d966227 Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Wed, 22 May 2024 05:08:23 +0200 Subject: [PATCH 07/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0567a3a052..b130a28059 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ documentation](https://docs.sciml.ai/Catalyst/stable/). The [in-development documentation](https://docs.sciml.ai/Catalyst/dev/) describes unreleased features in the current master branch. -An overview of the package and its features (as of version 13) can also be found in its corresponding research paper, [Catalyst: Fast and flexible modeling of reaction networks](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530). +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](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530). ## Features From db34c5c45164e7b34d016df9d3e9ea0121e2b8b0 Mon Sep 17 00:00:00 2001 From: Torkel Date: Thu, 30 May 2024 17:27:42 -0400 Subject: [PATCH 08/27] add dev doc link back in --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b130a28059..8ee61c6382 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,9 @@ [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://docs.sciml.ai/Catalyst/stable/) [![API Stable](https://img.shields.io/badge/API-stable-blue.svg)](https://docs.sciml.ai/Catalyst/stable/api/catalyst_api/) +[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://docs.sciml.ai/Catalyst/dev/) +[![API Dev](https://img.shields.io/badge/API-dev-blue.svg)](https://docs.sciml.ai/Catalyst/dev/api/catalyst_api/) [![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged) -[![Citation](https://img.shields.io/badge/Publication-389826)](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530) [![Build Status](https://github.com/SciML/Catalyst.jl/workflows/CI/badge.svg)](https://github.com/SciML/Catalyst.jl/actions?query=workflow%3ACI) [![codecov.io](https://codecov.io/gh/SciML/Catalyst.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/SciML/Catalyst.jl) @@ -11,6 +12,7 @@ [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac) [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle) +[![Citation](https://img.shields.io/badge/Publication-389826)](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530) Catalyst.jl is a symbolic modeling package for analysis and high-performance simulation of chemical reaction networks. Catalyst defines symbolic From 039c1a02703b3c9101c04171e457e0e69a68488a Mon Sep 17 00:00:00 2001 From: Torkel Date: Thu, 30 May 2024 20:04:47 -0400 Subject: [PATCH 09/27] change some instances of UK english to US --- README.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 8ee61c6382..f539a1e80a 100644 --- a/README.md +++ b/README.md @@ -32,9 +32,11 @@ 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. +**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](HISTORY.md) file. This also includes a special migration guide for version 14. +Breaking changes and new functionality are summarized in the [HISTORY.md](HISTORY.md) file. +This also includes a special migration guide for version 14. ## Tutorials and documentation @@ -43,7 +45,8 @@ documentation](https://docs.sciml.ai/Catalyst/stable/). The [in-development documentation](https://docs.sciml.ai/Catalyst/dev/) 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](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530). +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](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011530). ## Features @@ -60,13 +63,13 @@ An overview of the package, its features, and comparative benchmarking (as of ve [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) [ODE/SDE/jump solver](@ref ref), and can be used within `EnsembleProblem`s for carrying out [parallelized parameter sweeps and statistical sampling](@ref ref). Plot recipes - are available for [visualizing of all solutions](@ref ref). + are available for [visualization of all solutions](@ref ref). - Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](@ref ref) for generating ODE models, and symbolic expressions for stoichiometric coefficients [are supported](@ref ref) for all system types. - A [network analysis suite](@ref ref) permits the computation of linkage classes, deficiencies, and reversibilities. -- [Conservation laws can be detected and utilised](@ref ref) to reduce system sizes, and to generate +- [Conservation laws can be detected and utilized](@ref ref) 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 ref) (which are then incorporated during conversion to ODEs, SDEs, and steady state equations). @@ -89,7 +92,7 @@ An overview of the package, its features, and comparative benchmarking (as of ve SDE simulations](@ref ref). - [JumpProcesses.jl](https://github.com/SciML/JumpProcesses.jl) Can be used to [model jump simulations](@ref ref). -- Support for [parallelisation of all simulations]((@ref ref)), including parallelisation of +- Support for [parallelization of all simulations](@ref ref), including parallelization of [ODE simulations on GPUs](@ref ref) using [DiffEqGPU.jl](https://github.com/SciML/DiffEqGPU.jl). - [Latexify](https://korsbo.github.io/Latexify.jl/stable/) can be used to [generate LaTeX @@ -97,7 +100,7 @@ An overview of the package, its features, and comparative benchmarking (as of ve underlying set of reactions. - [Graphviz](https://graphviz.org/) can be used to generate and [visualize reaction network graphs](@ref ref) (reusing the Graphviz interface created in [Catlab.jl](https://algebraicjulia.github.io/Catlab.jl/stable/).) -- Models steady states can be computed through homotopy continuation using [HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl) +- Model steady states can be computed through 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 using [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by nonlinear systems solving using [NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl). @@ -110,7 +113,7 @@ An overview of the package, its features, and comparative benchmarking (as of ve - [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](@ref ref). - [GlobalSensitivity.jl](https://github.com/SciML/GlobalSensitivity.jl) can be used to perform - [global sensitivity analysis](@ref ref) of model behaviours. + [global sensitivity analysis](@ref ref) of model behaviors. #### Features of packages built upon Catalyst - Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](@ref ref) via @@ -177,7 +180,13 @@ plot(jump_sol; lw = 2) ## 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 (modelled as the cyclic sinusoid $kₐ*(sin(t)+1)$) phosphorylates the growth factor (producing $Gᴾ$). When the cell reaches a critical volume ($V$) it goes through cell division. First, we declare our model: +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 (modelld 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 through cell division. First, we declare our model: ```julia using Catalyst cell_model = @reaction_network begin @@ -193,7 +202,8 @@ cell_model = @reaction_network begin kᵢ/V, Gᴾ --> G end ``` -Next, we can use [Latexify.jl](https://korsbo.github.io/Latexify.jl/stable/) to show the ordinary differential equations associated with this model: +Next, we can use [Latexify.jl](https://korsbo.github.io/Latexify.jl/stable/) to show the ordinary +differential equations associated with this model: ```julia using Latexify latexify(cell_model; form = :ode) @@ -214,8 +224,8 @@ plot(sol; xguide = "Time (au)", lw = 2) ![Elaborate SDE simulation](docs/src/assets/readme_elaborate_sde_plot.svg) Some features we used here: -- The SDE was [simulated using StochasticDiffEq.jl], where we [scaled the SDE noise terms](@ref ref). -- The cell volume was [modelled as a differential equation, which was coupled to the reaction network model](@ref ref). +- The SDE was [simulated using StochasticDiffEq.jl]. We also [scaled the SDE noise terms](@ref ref). +- The cell volume was [modeled as a differential equation, which was coupled to the reaction network model](@ref ref). - The cell divisions were created by [incorporating events into the model](@ref ref). - The model equations were [displayed using Latexify.jl](@ref ref), and the simulation [plotted using Plots.jl](@ref ref). From 8e4a3ef6b6b170cee61cfef83e0022d747b5ab81 Mon Sep 17 00:00:00 2001 From: Torkel Date: Thu, 30 May 2024 20:19:04 -0400 Subject: [PATCH 10/27] writing improvement --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f539a1e80a..259f110e8c 100644 --- a/README.md +++ b/README.md @@ -129,9 +129,9 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model - [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 +- [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 +- [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. From 1a2c1ab4b7dd679c70797a99245d5339203b109a Mon Sep 17 00:00:00 2001 From: Torkel Date: Thu, 30 May 2024 20:25:22 -0400 Subject: [PATCH 11/27] up --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 259f110e8c..1e3ab7922a 100644 --- a/README.md +++ b/README.md @@ -184,7 +184,7 @@ In the above example, we used basic Catalyst-based workflows to simulate a simpl 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 (modelld as the cyclic sinusoid $kₐ*(sin(t)+1)$), which +($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 through cell division. First, we declare our model: ```julia From ccb5f6fd36f29fa61ed85a466a9905f59084556a Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:08:25 -0400 Subject: [PATCH 12/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1e3ab7922a..3ef7efabd2 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model - The [Catalyst.jl API](http://docs.sciml.ai/Catalyst/stable/api/catalyst_api) provides functionality for extending networks, building networks programmatically, and for composing multiple networks together. -- Generated models can be simulated using any +- 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 ref), and can be used within `EnsembleProblem`s for carrying out [parallelized parameter sweeps and statistical sampling](@ref ref). Plot recipes From 56532045af725351e26170fc1184b6bbaf78da1e Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:08:35 -0400 Subject: [PATCH 13/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3ef7efabd2..09448d25e2 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model - Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](@ref ref) for generating ODE models, and symbolic expressions for stoichiometric coefficients [are supported](@ref ref) for all system types. -- A [network analysis suite](@ref ref) permits the computation of linkage classes, deficiencies, and +- A [network analysis suite](@ref ref) permits the computation of linkage classes, deficiencies, reversibility, and other network properties. reversibilities. - [Conservation laws can be detected and utilized](@ref ref) to reduce system sizes, and to generate non-singular Jacobians (e.g. during conversion to ODEs, SDEs, and steady state equations). From c766ca6abf72b5c5c299b3013da79a365aad0d16 Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:08:43 -0400 Subject: [PATCH 14/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 09448d25e2..4d9c5ab629 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,6 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model ODE models, and symbolic expressions for stoichiometric coefficients [are supported](@ref ref) for all system types. - A [network analysis suite](@ref ref) permits the computation of linkage classes, deficiencies, reversibility, and other network properties. - reversibilities. - [Conservation laws can be detected and utilized](@ref ref) 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 ref) From 4c64ea74675f238b871f75d8f638cfb1ea1827fc Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:10:42 -0400 Subject: [PATCH 15/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 4d9c5ab629..724d7fa5a4 100644 --- a/README.md +++ b/README.md @@ -101,8 +101,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model (reusing the Graphviz interface created in [Catlab.jl](https://algebraicjulia.github.io/Catlab.jl/stable/).) - Model steady states can be computed through 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 using - [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by nonlinear systems - solving using [NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl). + [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by numerically solving steady-state nonlinear equations 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 ref) of models' steady states (including finding periodic orbits). - [DynamicalSystems.jl](https://github.com/JuliaDynamics/DynamicalSystems.jl) can be used to compute From f6faa8f16eb3c6a580a52e516018d46784aa3589 Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:12:32 -0400 Subject: [PATCH 16/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 724d7fa5a4..80f6df5c52 100644 --- a/README.md +++ b/README.md @@ -85,8 +85,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model - [Steady states](@ref ref) (and their [stabilities](@ref ref)) can be computed for model ODE representations. #### Features of Catalyst composing with other packages -- [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) Can be used to [perform model ODE - simulations](@ref ref). +- [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 [perform model SDE simulations](@ref ref). - [JumpProcesses.jl](https://github.com/SciML/JumpProcesses.jl) Can be used to [model jump From 052a46015852abb97a45136e00a58e9c2528635d Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:12:52 -0400 Subject: [PATCH 17/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 80f6df5c52..29acbaea95 100644 --- a/README.md +++ b/README.md @@ -86,8 +86,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model #### Features of Catalyst composing with other packages - [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 [perform model - SDE simulations](@ref ref). +- [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 [model jump simulations](@ref ref). - Support for [parallelization of all simulations](@ref ref), including parallelization of From 171d3994c88d033f2818914b4792d2570eb22445 Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:17:03 -0400 Subject: [PATCH 18/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 29acbaea95..c536f84dd7 100644 --- a/README.md +++ b/README.md @@ -87,8 +87,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model #### Features of Catalyst composing with other packages - [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 [model jump - simulations](@ref ref). +- [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 ref), including parallelization of [ODE simulations on GPUs](@ref ref) using [DiffEqGPU.jl](https://github.com/SciML/DiffEqGPU.jl). From 37c660f3f25e4d3417a009b66169cb88c70e425f Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:17:21 -0400 Subject: [PATCH 19/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c536f84dd7..41f94843fe 100644 --- a/README.md +++ b/README.md @@ -181,7 +181,7 @@ model describes how the volume of a cell ($V$) is affected by a growth factor ($ 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 through cell division. First, we declare our model: +it undergoes cell division. First, we declare our model: ```julia using Catalyst cell_model = @reaction_network begin From d42ee6ad4794914def260f158488dd4c9c0b25a0 Mon Sep 17 00:00:00 2001 From: Torkel Loman Date: Fri, 28 Jun 2024 18:17:44 -0400 Subject: [PATCH 20/27] Update README.md Co-authored-by: Sam Isaacson --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 41f94843fe..8736460c20 100644 --- a/README.md +++ b/README.md @@ -185,7 +185,7 @@ it undergoes cell division. First, we declare our model: ```julia using Catalyst cell_model = @reaction_network begin - @parameters Vₘₐₓ g Ω + @parameters Vₘ g Ω @default_noise_scaling Ω @equations begin D(V) ~ g*Gᴾ From dfa9ede990ee4d2664de54314bc70f8b36de3c81 Mon Sep 17 00:00:00 2001 From: Torkel Date: Fri, 28 Jun 2024 18:21:09 -0400 Subject: [PATCH 21/27] remove stuff that we should add back in later on --- README.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/README.md b/README.md index 8736460c20..813985aa0f 100644 --- a/README.md +++ b/README.md @@ -230,11 +230,6 @@ the [Julia Slack](https://julialang.slack.com) channels \#sciml-bridged and \#sc [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). -If you are interested in participating in the development of Catalyst, or integrating your package(s) -with it, developer documentation can be found [here](@ref ref). Are you a student (or similar) who -wishes to do a Google Summer of Code (or similar) project tied to Catalyst? Information on how to get -involved, including good first issues to get familiar with working on the package, can be found [here](@ref ref). - ## 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 @@ -254,8 +249,4 @@ could cite our work: pages = {1-19}, number = {10}, } -``` - -We also maintain a user survey, asking basic questions about how users utilise the package. The survey -is available [here](ref), and only takes about 5 minutes to fill out. We are grateful to those who -fill out the survey, as this helps us further develop the package. \ No newline at end of file +``` \ No newline at end of file From 974a6fa50898f6959b3f7af9d4928b9ae6014c1a Mon Sep 17 00:00:00 2001 From: Torkel Date: Fri, 28 Jun 2024 19:40:44 -0400 Subject: [PATCH 22/27] up --- README.md | 102 +++++++++++++++++++++++++++--------------------------- 1 file changed, 51 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 813985aa0f..022788958b 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model ## Features #### Features of Catalyst -- [The Catalyst DSL](@ref ref) provides a simple and readable format for manually specifying reaction +- [The Catalyst DSL](https://docs.sciml.ai/Catalyst/dev/model_creation/dsl_basics/) 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 @@ -61,59 +61,60 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model 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 ref), and can be used within `EnsembleProblem`s for carrying - out [parallelized parameter sweeps and statistical sampling](@ref ref). Plot recipes - are available for [visualization of all solutions](@ref ref). -- Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](@ref ref) for generating - ODE models, and symbolic expressions for stoichiometric coefficients [are supported](@ref ref) for + [ODE/SDE/jump solver](https://docs.sciml.ai/Catalyst/dev/model_simulation/simulation_introduction/), and can be used within `EnsembleProblem`s for carrying + out [parallelized parameter sweeps and statistical sampling](https://docs.sciml.ai/Catalyst/dev/model_simulation/ensemble_simulations/). Plot recipes + are available for [visualization of all solutions](https://docs.sciml.ai/Catalyst/dev/model_simulation/simulation_plotting/). +- Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](https://docs.sciml.ai/Catalyst/dev/model_creation/dsl_basics/#dsl_description_stoichiometries_decimal) for generating + ODE models, and symbolic expressions for stoichiometric coefficients [are supported](https://docs.sciml.ai/Catalyst/dev/model_creation/parametric_stoichiometry/) for all system types. -- A [network analysis suite](@ref ref) permits the computation of linkage classes, deficiencies, reversibility, and other network properties. -- [Conservation laws can be detected and utilized](@ref ref) to reduce system sizes, and to generate +- A [network analysis suite](https://docs.sciml.ai/Catalyst/dev/model_creation/network_analysis/) permits the computation of linkage classes, deficiencies, reversibility, and other network properties. +- [Conservation laws can be detected and utilized](https://docs.sciml.ai/Catalyst/dev/model_creation/network_analysis/#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 ref) +- Catalyst reaction network models can be [coupled with differential and algebraic equations](https://docs.sciml.ai/Catalyst/dev/model_creation/constraint_equations/) (which are then incorporated during conversion to ODEs, SDEs, and steady state equations). -- Models can be [coupled with events](@ref ref) that affect the system and its state during simulations. +- Models can be [coupled with events](https://docs.sciml.ai/Catalyst/dev/model_creation/constraint_equations/#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](@ref ref), [multithreading or parallelization of generated - derivative functions](@ref ref), [automatic classification of reactions into optimized - jump types for Gillespie type simulations](@ref ref), [automatic construction of - dependency graphs for jump systems](@ref ref), and more. + of [dense or sparse Jacobians](https://docs.sciml.ai/Catalyst/dev/model_simulation/ode_simulation_performance/#ode_simulation_performance_sparse_jacobian), [multithreading or parallelization of generated + derivative functions](https://docs.sciml.ai/Catalyst/dev/model_simulation/ode_simulation_performance/#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. -- [Steady states](@ref ref) (and their [stabilities](@ref ref)) can be computed for model ODE representations. +- [Steady states](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/homotopy_continuation/) (and their [stabilities](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/steady_state_stability_computation/)) can be computed for model ODE representations. #### Features of Catalyst composing with other packages - [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 ref), including parallelization of - [ODE simulations on GPUs](@ref ref) using +- Support for [parallelization of all simulations](https://docs.sciml.ai/Catalyst/dev/model_simulation/ode_simulation_performance/#ode_simulation_performance_parallelisation), including parallelization of + [ODE simulations on GPUs](https://docs.sciml.ai/Catalyst/dev/model_simulation/ode_simulation_performance/#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 ref) corresponding to generated mathematical models or the + expressions](https://docs.sciml.ai/Catalyst/dev/model_creation/model_visualisation/#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 ref) - (reusing the Graphviz interface created in [Catlab.jl](https://algebraicjulia.github.io/Catlab.jl/stable/).) +- [Graphviz](https://graphviz.org/) can be used to generate and [visualize reaction network graphs](https://docs.sciml.ai/Catalyst/dev/model_creation/model_visualisation/#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 using [HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl) (which can find *all* steady states of systems with multiple ones), by forward ODE simulations using [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by numerically solving steady-state nonlinear equations 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 ref) of models' steady states (including finding periodic orbits). + bifurcation diagrams](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/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 ref) and [Lyapunov spectrums](@ref ref). + model [basins of attraction](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/dynamical_systems/#dynamical_systems_basins_of_attraction) and [Lyapunov spectrums](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/dynamical_systems/#dynamical_systems_lyapunov_exponents). - [StructuralIdentifiability.jl](https://github.com/SciML/StructuralIdentifiability.jl) can be used - to [perform structural identifiability analysis](@ref ref). + to [perform structural identifiability analysis](https://docs.sciml.ai/Catalyst/dev/inverse_problems/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](@ref ref). + 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 ref) of model behaviors. - + [global sensitivity analysis](https://docs.sciml.ai/Catalyst/dev/inverse_problems/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 -- Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](@ref ref) via +- Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](https://docs.sciml.ai/Catalyst/dev/model_creation/model_file_loading_and_export/#Loading-SBML-files-using-SBMLImporter.jl-and-SBMLToolkit.jl) via [SBMLImporter.jl](https://github.com/SciML/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), - and [from BioNetGen .net files](@ref ref) and various stoichiometric matrix network representations + and [from BioNetGen .net files](https://docs.sciml.ai/Catalyst/dev/model_creation/model_file_loading_and_export/#file_loading_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 @@ -126,9 +127,6 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model 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. ## Illustrative example @@ -149,7 +147,7 @@ model = @reaction_network begin end # Create an ODE that can be simulated. -u0 = [:S => 50, :E => 10, :SE => 0, :P => 0] +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) @@ -166,7 +164,8 @@ jump simulation ```julia # Create and simulate a jump process (here using Gillespie's direct algorithm). using JumpProcesses -dprob = DiscreteProblem(model, u0, tspan, ps) +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()) plot(jump_sol; lw = 2) @@ -180,49 +179,50 @@ instead show how various Catalyst features can compose to create a much more adv 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$) +phosphorylates the growth factor (producing $Gᴾ$). When the cell reaches a critical volume ($Vₘ$) it undergoes cell division. First, we declare our model: ```julia using Catalyst cell_model = @reaction_network begin - @parameters Vₘ g Ω - @default_noise_scaling Ω + @parameters Vₘ g @equations begin D(V) ~ g*Gᴾ end @continuous_events begin - [V ~ Vₘₐₓ] => [V ~ V/2] + [V ~ Vₘ] => [V ~ V/2] end kₚ*(sin(t)+1)/V, G --> Gᴾ kᵢ/V, Gᴾ --> G end ``` -Next, we can use [Latexify.jl](https://korsbo.github.io/Latexify.jl/stable/) to show the ordinary -differential equations associated with this model: -```julia -using Latexify -latexify(cell_model; form = :ode) -``` In this case, we would instead like to perform stochastic simulations, so we transform our model to an SDE: ```julia -u0 = [:V => 0.5, :G => 1.0, :Gᴾ => 0.0] +u0 = [:V => 25.0, :G => 50.0, :Gᴾ => 0.0] tspan = (0.0, 20.0) -ps = [:Vₘₐₓ => 1.0, :g => 0.2, :kₚ => 5.0, :kᵢ => 2.0, :Ω => 0.1] +ps = [:Vₘ => 50.0, :g => 0.2, :kₚ => 100.0, :kᵢ => 60.0] sprob = SDEProblem(cell_model, u0, tspan, ps) ``` -Finally, we simulate it and plot the result. +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*} +``` +where the $dW_1(t)$ and $dW_2(t)$ terms described the noise added through the Chemical Langevin Equations. Finally, we can simulate and plot the results. ```julia using StochasticDiffEq -sol = solve(sprob, STrapezoid()) +sol = solve(sprob, EM(); dt = 0.05) plot(sol; xguide = "Time (au)", lw = 2) ``` ![Elaborate SDE simulation](docs/src/assets/readme_elaborate_sde_plot.svg) Some features we used here: -- The SDE was [simulated using StochasticDiffEq.jl]. We also [scaled the SDE noise terms](@ref ref). -- The cell volume was [modeled as a differential equation, which was coupled to the reaction network model](@ref ref). -- The cell divisions were created by [incorporating events into the model](@ref ref). -- The model equations were [displayed using Latexify.jl](@ref ref), and the simulation [plotted using Plots.jl](@ref ref). +- The cell volume was [modeled as a differential equation, which was coupled to the reaction network model](https://docs.sciml.ai/Catalyst/dev/model_creation/constraint_equations/#constraint_equations_coupling_constraints). +- The cell divisions were created by [incorporating events into the model](https://docs.sciml.ai/Catalyst/dev/model_creation/constraint_equations/#constraint_equations_events). +- We designated a specific numeric [solver and corresponding solver options](https://docs.sciml.ai/Catalyst/dev/model_simulation/simulation_introduction/#simulation_intro_solver_options). +- The model simulation was [plotted using Plots.jl](https://docs.sciml.ai/Catalyst/dev/model_simulation/simulation_plotting/). ## Getting help or getting involved Catalyst developers are active on the [Julia Discourse](https://discourse.julialang.org/), From 5e210de2420c204c81e8aaa15850129d275a438f Mon Sep 17 00:00:00 2001 From: Torkel Date: Fri, 28 Jun 2024 19:44:57 -0400 Subject: [PATCH 23/27] link to stable docs --- README.md | 63 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 022788958b..125bc1ce5e 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,8 @@ [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://docs.sciml.ai/Catalyst/stable/) [![API Stable](https://img.shields.io/badge/API-stable-blue.svg)](https://docs.sciml.ai/Catalyst/stable/api/catalyst_api/) -[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://docs.sciml.ai/Catalyst/dev/) -[![API Dev](https://img.shields.io/badge/API-dev-blue.svg)](https://docs.sciml.ai/Catalyst/dev/api/catalyst_api/) +[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://docs.sciml.ai/Catalyst/stable/) +[![API Dev](https://img.shields.io/badge/API-dev-blue.svg)](https://docs.sciml.ai/Catalyst/stable/api/catalyst_api/) [![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged) [![Build Status](https://github.com/SciML/Catalyst.jl/workflows/CI/badge.svg)](https://github.com/SciML/Catalyst.jl/actions?query=workflow%3ACI) @@ -23,7 +23,7 @@ specified using Catalyst's domain-specific language (DSL). Leveraging [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 +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. @@ -42,7 +42,7 @@ This also includes a special migration guide for version 14. The latest tutorials and information on using Catalyst are available in the [stable documentation](https://docs.sciml.ai/Catalyst/stable/). The [in-development -documentation](https://docs.sciml.ai/Catalyst/dev/) describes unreleased features in +documentation](https://docs.sciml.ai/Catalyst/stable/) describes unreleased features in the current master branch. An overview of the package, its features, and comparative benchmarking (as of version 13) can also @@ -51,7 +51,7 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model ## Features #### Features of Catalyst -- [The Catalyst DSL](https://docs.sciml.ai/Catalyst/dev/model_creation/dsl_basics/) provides a simple and readable format for manually specifying reaction +- [The Catalyst DSL](https://docs.sciml.ai/Catalyst/stable/model_creation/dsl_basics/) 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 @@ -61,60 +61,60 @@ be found in its corresponding research paper, [Catalyst: Fast and flexible model 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](https://docs.sciml.ai/Catalyst/dev/model_simulation/simulation_introduction/), and can be used within `EnsembleProblem`s for carrying - out [parallelized parameter sweeps and statistical sampling](https://docs.sciml.ai/Catalyst/dev/model_simulation/ensemble_simulations/). Plot recipes - are available for [visualization of all solutions](https://docs.sciml.ai/Catalyst/dev/model_simulation/simulation_plotting/). -- Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](https://docs.sciml.ai/Catalyst/dev/model_creation/dsl_basics/#dsl_description_stoichiometries_decimal) for generating - ODE models, and symbolic expressions for stoichiometric coefficients [are supported](https://docs.sciml.ai/Catalyst/dev/model_creation/parametric_stoichiometry/) for + [ODE/SDE/jump solver](https://docs.sciml.ai/Catalyst/stable/model_simulation/simulation_introduction/), and can be used within `EnsembleProblem`s for carrying + out [parallelized parameter sweeps and statistical sampling](https://docs.sciml.ai/Catalyst/stable/model_simulation/ensemble_simulations/). Plot recipes + are available for [visualization of all solutions](https://docs.sciml.ai/Catalyst/stable/model_simulation/simulation_plotting/). +- Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](https://docs.sciml.ai/Catalyst/stable/model_creation/dsl_basics/#dsl_description_stoichiometries_decimal) for generating + ODE models, and symbolic expressions for stoichiometric coefficients [are supported](https://docs.sciml.ai/Catalyst/stable/model_creation/parametric_stoichiometry/) for all system types. -- A [network analysis suite](https://docs.sciml.ai/Catalyst/dev/model_creation/network_analysis/) permits the computation of linkage classes, deficiencies, reversibility, and other network properties. -- [Conservation laws can be detected and utilized](https://docs.sciml.ai/Catalyst/dev/model_creation/network_analysis/#network_analysis_deficiency) to reduce system sizes, and to generate +- A [network analysis suite](https://docs.sciml.ai/Catalyst/stable/model_creation/network_analysis/) permits the computation of linkage classes, deficiencies, reversibility, and other network properties. +- [Conservation laws can be detected and utilized](https://docs.sciml.ai/Catalyst/stable/model_creation/network_analysis/#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](https://docs.sciml.ai/Catalyst/dev/model_creation/constraint_equations/) +- Catalyst reaction network models can be [coupled with differential and algebraic equations](https://docs.sciml.ai/Catalyst/stable/model_creation/constraint_equations/) (which are then incorporated during conversion to ODEs, SDEs, and steady state equations). -- Models can be [coupled with events](https://docs.sciml.ai/Catalyst/dev/model_creation/constraint_equations/#constraint_equations_events) that affect the system and its state during simulations. +- Models can be [coupled with events](https://docs.sciml.ai/Catalyst/stable/model_creation/constraint_equations/#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](https://docs.sciml.ai/Catalyst/dev/model_simulation/ode_simulation_performance/#ode_simulation_performance_sparse_jacobian), [multithreading or parallelization of generated - derivative functions](https://docs.sciml.ai/Catalyst/dev/model_simulation/ode_simulation_performance/#ode_simulation_performance_parallelisation), [automatic classification of reactions into optimized + of [dense or sparse Jacobians](https://docs.sciml.ai/Catalyst/stable/model_simulation/ode_simulation_performance/#ode_simulation_performance_sparse_jacobian), [multithreading or parallelization of generated + derivative functions](https://docs.sciml.ai/Catalyst/stable/model_simulation/ode_simulation_performance/#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. -- [Steady states](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/homotopy_continuation/) (and their [stabilities](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/steady_state_stability_computation/)) can be computed for model ODE representations. +- [Steady states](https://docs.sciml.ai/Catalyst/stable/steady_state_functionality/homotopy_continuation/) (and their [stabilities](https://docs.sciml.ai/Catalyst/stable/steady_state_functionality/steady_state_stability_computation/)) can be computed for model ODE representations. #### Features of Catalyst composing with other packages - [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](https://docs.sciml.ai/Catalyst/dev/model_simulation/ode_simulation_performance/#ode_simulation_performance_parallelisation), including parallelization of - [ODE simulations on GPUs](https://docs.sciml.ai/Catalyst/dev/model_simulation/ode_simulation_performance/#ode_simulation_performance_parallelisation_GPU) using +- Support for [parallelization of all simulations](https://docs.sciml.ai/Catalyst/stable/model_simulation/ode_simulation_performance/#ode_simulation_performance_parallelisation), including parallelization of + [ODE simulations on GPUs](https://docs.sciml.ai/Catalyst/stable/model_simulation/ode_simulation_performance/#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](https://docs.sciml.ai/Catalyst/dev/model_creation/model_visualisation/#visualisation_latex) corresponding to generated mathematical models or the + expressions](https://docs.sciml.ai/Catalyst/stable/model_creation/model_visualisation/#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](https://docs.sciml.ai/Catalyst/dev/model_creation/model_visualisation/#visualisation_graphs) +- [Graphviz](https://graphviz.org/) can be used to generate and [visualize reaction network graphs](https://docs.sciml.ai/Catalyst/stable/model_creation/model_visualisation/#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 using [HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl) (which can find *all* steady states of systems with multiple ones), by forward ODE simulations using [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by numerically solving steady-state nonlinear equations using [NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl). - [BifurcationKit.jl](https://github.com/bifurcationkit/BifurcationKit.jl) can be used to [compute - bifurcation diagrams](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/bifurcation_diagrams/) of models' steady states (including finding periodic orbits). + bifurcation diagrams](https://docs.sciml.ai/Catalyst/stable/steady_state_functionality/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](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/dynamical_systems/#dynamical_systems_basins_of_attraction) and [Lyapunov spectrums](https://docs.sciml.ai/Catalyst/dev/steady_state_functionality/dynamical_systems/#dynamical_systems_lyapunov_exponents). + model [basins of attraction](https://docs.sciml.ai/Catalyst/stable/steady_state_functionality/dynamical_systems/#dynamical_systems_basins_of_attraction) and [Lyapunov spectrums](https://docs.sciml.ai/Catalyst/stable/steady_state_functionality/dynamical_systems/#dynamical_systems_lyapunov_exponents). - [StructuralIdentifiability.jl](https://github.com/SciML/StructuralIdentifiability.jl) can be used - to [perform structural identifiability analysis](https://docs.sciml.ai/Catalyst/dev/inverse_problems/structural_identifiability/). + to [perform structural identifiability analysis](https://docs.sciml.ai/Catalyst/stable/inverse_problems/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](https://docs.sciml.ai/Catalyst/dev/inverse_problems/global_sensitivity_analysis/) of model behaviors. + [global sensitivity analysis](https://docs.sciml.ai/Catalyst/stable/inverse_problems/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 -- Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](https://docs.sciml.ai/Catalyst/dev/model_creation/model_file_loading_and_export/#Loading-SBML-files-using-SBMLImporter.jl-and-SBMLToolkit.jl) via +- Catalyst [`ReactionSystem`](@ref)s can be [imported from SBML files](https://docs.sciml.ai/Catalyst/stable/model_creation/model_file_loading_and_export/#Loading-SBML-files-using-SBMLImporter.jl-and-SBMLToolkit.jl) via [SBMLImporter.jl](https://github.com/SciML/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), - and [from BioNetGen .net files](https://docs.sciml.ai/Catalyst/dev/model_creation/model_file_loading_and_export/#file_loading_rni_net) and various stoichiometric matrix network representations + and [from BioNetGen .net files](https://docs.sciml.ai/Catalyst/stable/model_creation/model_file_loading_and_export/#file_loading_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 @@ -163,6 +163,7 @@ The same model can be used as input to other types of simulations. E.g. here we jump simulation ```julia # Create and simulate a jump process (here using Gillespie's direct algorithm). +# Note that integer (not decimal) initial conditions are used. using JumpProcesses u0_integers = [:S => 50, :E => 10, :SE => 0, :P => 0] dprob = DiscreteProblem(model, u0_integers, tspan, ps) @@ -219,10 +220,10 @@ plot(sol; xguide = "Time (au)", lw = 2) ![Elaborate SDE simulation](docs/src/assets/readme_elaborate_sde_plot.svg) Some features we used here: -- The cell volume was [modeled as a differential equation, which was coupled to the reaction network model](https://docs.sciml.ai/Catalyst/dev/model_creation/constraint_equations/#constraint_equations_coupling_constraints). -- The cell divisions were created by [incorporating events into the model](https://docs.sciml.ai/Catalyst/dev/model_creation/constraint_equations/#constraint_equations_events). -- We designated a specific numeric [solver and corresponding solver options](https://docs.sciml.ai/Catalyst/dev/model_simulation/simulation_introduction/#simulation_intro_solver_options). -- The model simulation was [plotted using Plots.jl](https://docs.sciml.ai/Catalyst/dev/model_simulation/simulation_plotting/). +- The cell volume was [modeled as a differential equation, which was coupled to the reaction network model](https://docs.sciml.ai/Catalyst/stable/model_creation/constraint_equations/#constraint_equations_coupling_constraints). +- The cell divisions were created by [incorporating events into the model](https://docs.sciml.ai/Catalyst/stable/model_creation/constraint_equations/#constraint_equations_events). +- We designated a specific numeric [solver and corresponding solver options](https://docs.sciml.ai/Catalyst/stable/model_simulation/simulation_introduction/#simulation_intro_solver_options). +- The model simulation was [plotted using Plots.jl](https://docs.sciml.ai/Catalyst/stable/model_simulation/simulation_plotting/). ## Getting help or getting involved Catalyst developers are active on the [Julia Discourse](https://discourse.julialang.org/), From 730fa6a0d73110111235e468ff6ff00fc9644c5e Mon Sep 17 00:00:00 2001 From: Torkel Date: Tue, 2 Jul 2024 00:53:16 -0400 Subject: [PATCH 24/27] update sde example --- README.md | 2 +- docs/src/assets/readme_elaborate_sde_plot.svg | 74 +++++++++---------- 2 files changed, 38 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 13693b09cc..91ed58e007 100644 --- a/README.md +++ b/README.md @@ -201,7 +201,7 @@ In this case, we would instead like to perform stochastic simulations, so we tra ```julia u0 = [:V => 25.0, :G => 50.0, :Gᴾ => 0.0] tspan = (0.0, 20.0) -ps = [:Vₘ => 50.0, :g => 0.2, :kₚ => 100.0, :kᵢ => 60.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: diff --git a/docs/src/assets/readme_elaborate_sde_plot.svg b/docs/src/assets/readme_elaborate_sde_plot.svg index a906bbbfc9..503e76d2ee 100644 --- a/docs/src/assets/readme_elaborate_sde_plot.svg +++ b/docs/src/assets/readme_elaborate_sde_plot.svg @@ -1,50 +1,50 @@ - + - + - + - + - - + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 179d251701e09b0b3b89fce3b369cd9d894e27b0 Mon Sep 17 00:00:00 2001 From: Torkel Date: Tue, 2 Jul 2024 02:15:24 -0400 Subject: [PATCH 25/27] where the $dW_1(t)$ and $dW_2(t)$ terms described the noise added through the Chemical Langevin Equations. Finally, we can simulate and plot the results.transfer text updates from home pr --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 91ed58e007..a8137cb799 100644 --- a/README.md +++ b/README.md @@ -160,11 +160,10 @@ plot(sol; lw = 5) ![ODE simulation](docs/src/assets/readme_ode_plot.svg) #### Stochastic jump simulations -The same model can be used as input to other types of simulations. E.g. here we instead perform a -jump simulation +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. ```julia # Create and simulate a jump process (here using Gillespie's direct algorithm). -# Note that integer (not decimal) initial conditions are used. +# 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) @@ -197,7 +196,7 @@ cell_model = @reaction_network begin kᵢ/V, Gᴾ --> G end ``` -In this case, we would instead like to perform stochastic simulations, so we transform our model to an SDE: +We now study the system as a Chemical Langevin Dynamics SDE model, which can be generated as follows ```julia u0 = [:V => 25.0, :G => 50.0, :Gᴾ => 0.0] tspan = (0.0, 20.0) @@ -212,7 +211,7 @@ dGᴾ(t) &= \left( \frac{kₚ*(sin(t)+1)}{V(t)} G(t) - \frac{kᵢ}{V(t)} Gᴾ(t) dV(t) &= \left(g \cdot Gᴾ(t)\right) dt \end{align*} ``` -where the $dW_1(t)$ and $dW_2(t)$ terms described the noise added through the Chemical Langevin Equations. Finally, we can simulate and plot the results. +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. ```julia using StochasticDiffEq sol = solve(sprob, EM(); dt = 0.05) From 9c203cc3ccdb16dced5d3ad60b07e01fa028b461 Mon Sep 17 00:00:00 2001 From: Torkel Date: Tue, 2 Jul 2024 02:19:14 -0400 Subject: [PATCH 26/27] add using Plots in SDE example --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a8137cb799..705d689bf8 100644 --- a/README.md +++ b/README.md @@ -213,7 +213,7 @@ dV(t) &= \left(g \cdot Gᴾ(t)\right) dt ``` 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. ```julia -using StochasticDiffEq +using StochasticDiffEq, Plots sol = solve(sprob, EM(); dt = 0.05) plot(sol; xguide = "Time (au)", lw = 2) ``` From 0bf0c78b7bfedf113b3ba167ed61e0eda656fb24 Mon Sep 17 00:00:00 2001 From: Torkel Date: Tue, 2 Jul 2024 02:39:43 -0400 Subject: [PATCH 27/27] minor fix after re reading --- README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 705d689bf8..4017eeda1d 100644 --- a/README.md +++ b/README.md @@ -32,18 +32,15 @@ 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. +**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](HISTORY.md) file. Furthermore, a migration guide on how to adapt your workflows to the -the new v14 update can be found [here](https://docs.sciml.ai/Catalyst/stable/v14_migration_guide/). +Breaking changes and new functionality are summarized in the [HISTORY.md](HISTORY.md) file. Furthermore, a migration guide on how to adapt your workflows to the new v14 update can be found [here](https://docs.sciml.ai/Catalyst/stable/v14_migration_guide/). ## Tutorials and documentation The latest tutorials and information on using Catalyst are available in the [stable documentation](https://docs.sciml.ai/Catalyst/stable/). The [in-development -documentation](https://docs.sciml.ai/Catalyst/stable/) describes unreleased features in +documentation](https://docs.sciml.ai/Catalyst/dev/) describes unreleased features in the current master branch. An overview of the package, its features, and comparative benchmarking (as of version 13) can also