up

Author: TorkelE

docs/src/home.md

@@ -2,14 +2,14 @@
 
 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,
+[`ReactionSystem`](@ref)s,
 which can be created programmatically or easily
 specified using Catalyst's domain-specific language (DSL). Leveraging
 [ModelingToolkit.jl](https://github.com/SciML/ModelingToolkit.jl) and
 [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl), Catalyst enables
 large-scale simulations through auto-vectorization and parallelism. Symbolic
 `ReactionSystem`s can be used to generate ModelingToolkit-based models, allowing
-the easy simulation and parameter estimation of mass action ODE models, chemical
+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.
@@ -19,74 +19,70 @@ etc).
 ## [Features](@id doc_home_features)
 
 #### [Features of Catalyst](@id doc_home_features_catalyst)
-- [The Catalyst DSL](@ref ref) provides a simple and readable format for manually specifying reaction 
+- [The Catalyst DSL](@ref dsl_description) provides a simple and readable format for manually specifying reaction 
  network models using chemical reaction notation.
 - Catalyst `ReactionSystem`s provides a symbolic representation of reaction networks,
  built on [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) and
  [Symbolics.jl](https://docs.sciml.ai/Symbolics/stable/).
-- The [Catalyst.jl API](http://docs.sciml.ai/Catalyst/stable/api/catalyst_api) provides functionality 
+- The [Catalyst.jl API](@ref 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
- 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](@ref simulation_intro), and can be used within `EnsembleProblem`s for carrying
+ out [parallelized parameter sweeps and statistical sampling](@ref ensemble_simulations). Plot recipes
+ are available for [visualization of all solutions](@ref simulation_plotting).
+- Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](@ref dsl_description_stoichiometries_decimal) for generating
+ ODE models, and symbolic expressions for stoichiometric coefficients [are supported](@ref parametric_stoichiometry) for
  all system types.
-- A [network analysis suite](@ref ref) permits the computation of linkage classes, deficiencies, and
- reversibilities.
-- [Conservation laws can be detected and utilized](@ref ref) to reduce system sizes, and to generate
+- A [network analysis suite](@ref network_analysis) permits the computation of linkage classes, deficiencies, reversibility, and other network properties.
+- [Conservation laws can be detected and utilized](@ref network_analysis_deficiency) to reduce system sizes, and to generate
  non-singular Jacobians (e.g. during conversion to ODEs, SDEs, and steady state equations).
-- Catalyst reaction network models can be [coupled with differential and algebraic equations](@ref ref)
+- Catalyst reaction network models can be [coupled with differential and algebraic equations](@ref constraint_equations_coupling_constraints)
  (which are then incorporated during conversion to ODEs, SDEs, and steady state equations).
-- Models can be [coupled with events](@ref ref) that affect the system and its state during simulations.
+- Models can be [coupled with events](@ref constraint_equations_events) that affect the system and its state during simulations.
 - By leveraging ModelingToolkit, users have a variety of options for generating
  optimized system representations to use in solvers. These include construction
- of [dense or sparse Jacobians](@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](@ref ode_simulation_performance_sparse_jacobian), [multithreading or parallelization of generated
+ derivative functions](@ref ode_simulation_performance_parallelisation), [automatic classification of reactions into optimized
+ jump types for Gillespie type simulations](https://docs.sciml.ai/JumpProcesses/stable/jump_types/#jump_types), [automatic construction of
+ dependency graphs for jump systems](https://docs.sciml.ai/JumpProcesses/stable/jump_types/#Jump-Aggregators-Requiring-Dependency-Graphs), and more.
 - [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) symbolic
  expressions and Julia `Expr`s can be obtained for all rate laws and functions determining the 
  deterministic and stochastic terms within resulting ODE, SDE or jump models.
-- [Steady states](@ref ref) (and their [stabilities](@ref ref)) can be computed for model ODE representations.
+- [Steady states](@ref homotopy_continuation) (and their [stabilities](@ref steady_state_stability)) can be computed for model ODE representations.
 
 #### [Features of Catalyst composing with other packages](@id doc_home_features_composed)
-- [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 [parallelization of all simulations](@ref ref), including parallelization of 
- [ODE simulations on GPUs](@ref ref) using
+- [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) Can be used to numerically solver generated reaction rate equation ODE models.
+- [StochasticDiffEq.jl](https://github.com/SciML/StochasticDiffEq.jl) can be used to numerically solve generated Chemical Langevin Equation SDE models.
+- [JumpProcesses.jl](https://github.com/SciML/JumpProcesses.jl) can be used to numerically sample generated Stochastic Chemical Kinetics Jump Process models.
+- Support for [parallelization of all simulations](@ref ode_simulation_performance_parallelisation), including parallelization of 
+ [ODE simulations on GPUs](@ref ode_simulation_performance_parallelisation_GPU) using
  [DiffEqGPU.jl](https://github.com/SciML/DiffEqGPU.jl).
 - [Latexify](https://korsbo.github.io/Latexify.jl/stable/) can be used to [generate LaTeX 
- expressions](@ref ref) corresponding to generated mathematical models or the
+ expressions](@ref visualisation_latex) corresponding to generated mathematical models or the
  underlying set of reactions.
-- [Graphviz](https://graphviz.org/) can be used to generate and [visualize reaction network graphs](@ref ref) 
- (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).
+- [Graphviz](https://graphviz.org/) can be used to generate and [visualize reaction network graphs](@ref visualisation_graphs) 
+ (reusing the Graphviz interface created in [Catlab.jl](https://algebraicjulia.github.io/Catlab.jl/stable/)).
+- Model steady states can be [computed through homotopy continuation](@ref homotopy_continuation) using [HomotopyContinuation.jl](https://github.com/JuliaHomotopyContinuation/HomotopyContinuation.jl)
+ (which can find *all* steady states of systems with multiple ones), by [forward ODE simulations](@ref steady_state_solving_simulation) using
+ [SteadyStateDiffEq.jl)](https://github.com/SciML/SteadyStateDiffEq.jl), or by [numerically solving steady-state nonlinear equations](@ref steady_state_solving_nonlinear) using [NonlinearSolve.jl](https://github.com/SciML/NonlinearSolve.jl).
 - [BifurcationKit.jl](https://github.com/bifurcationkit/BifurcationKit.jl) can be used to [compute 
- bifurcation diagrams](@ref ref) of models' steady states (including finding periodic orbits).
+ bifurcation diagrams](@ref bifurcation_diagrams) of models' steady states (including finding periodic orbits).
 - [DynamicalSystems.jl](https://github.com/JuliaDynamics/DynamicalSystems.jl) can be used to compute 
- model [basins of attraction](@ref ref) and [Lyapunov spectrums](@ref ref).
+ model [basins of attraction](@ref dynamical_systems_basins_of_attraction) and [Lyapunov spectrums](@ref dynamical_systems_lyapunov_exponents).
 - [StructuralIdentifiability.jl](https://github.com/SciML/StructuralIdentifiability.jl) can be used 
- to [perform structural identifiability analysis](@ref ref).
+ to [perform structural identifiability analysis](@ref structural_identifiability).
 - [Optimization.jl](https://github.com/SciML/Optimization.jl), [DiffEqParamEstim.jl](https://github.com/SciML/DiffEqParamEstim.jl), 
- and [PEtab.jl](https://github.com/sebapersson/PEtab.jl) can all be used to [fit model parameters to data](@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](@ref global_sensitivity_analysis) of model behaviors.
+- [SciMLSensitivity.jl](https://github.com/SciML/SciMLSensitivity.jl) can be used to compute local sensitivities of functions containing forward model simulations.
 
 #### [Features of packages built upon Catalyst](@id doc_home_features_other_packages)
-- 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/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](@ref ref) 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 
@@ -99,14 +95,11 @@ etc).
  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.
 
 ## [How to read this documentation](@id doc_home_documentation)
 The Catalyst documentation is separated into sections describing Catalyst's various features. Where appropriate, some sections will also give advice on best practices for various modeling workflows, and provide links with further reading. Each section also contains a set of relevant example workflows. Finally, the [API](@ref api) section contains a list of all functions exported by Catalyst (as well as descriptions of them and their inputs and outputs).
 
-New users are recommended to start with either the [Introduction to Catalyst and Julia for New Julia users](@ref catalyst_for_new_julia_users) or [Introduction to Catalyst](@ref introduction_to_catalyst) sections (depending on whether they are familiar with Julia programming or not). This should be enough to carry out many basic Catalyst workflows. Next, [The Catalyst DSL](@ref ref) section gives a more throughout introduction to model creation, while the [Introduction to model simulation](@ref ref) section more through describes how simulations are carried out. Once you have gotten started using Catalyst, you can read whichever sections are relevant to your work (they should all be clearly labelled).
+New users are recommended to start with either the [Introduction to Catalyst and Julia for New Julia users](@ref catalyst_for_new_julia_users) or [Introduction to Catalyst](@ref introduction_to_catalyst) sections (depending on whether they are familiar with Julia programming or not). This should be enough to carry out many basic Catalyst workflows.
 
 This documentation contains code which is dynamically run whenever it is built. If you copy the code and run it in your Julia environment it should work. The exact Julia environment that is used in this documentation can be found [here](@ref doc_home_reproducibility).
 
@@ -167,7 +160,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)
@@ -182,8 +175,10 @@ The same model can be used as input to other types of simulations. E.g. here we
 jump simulation
 ```@example home_simple_example
 # Create and simulate a jump process (here using Gillespie's direct algorithm).
+# Note that integer (not decimal) initial conditions are used.
 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())
 jump_sol = solve(jprob, SSAStepper(); seed = 1234) # hide
@@ -196,40 +191,42 @@ 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$)
-it undergoes through cell division. First, we declare our model:
+phosphorylates the growth factor (producing $Gᴾ$). When the cell reaches a critical volume ($Vₘ$)
+it undergoes cell division. First, we declare our model:
 ```@example home_elaborate_example
 using Catalyst
 cell_model = @reaction_network begin
-    @parameters Vₘₐₓ g Ω
-    @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:
-```@example home_elaborate_example
-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:
 ```@example home_elaborate_example
-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.
 ```@example home_elaborate_example
 using StochasticDiffEq
-sol = solve(sprob, STrapezoid())
-sol = solve(sprob, STrapezoid(); seed = 1234) # hide
+sol = solve(sprob, EM(); dt = 0.05)
+sol = solve(sprob, EM(); dt = 0.05, seed = 1234) # hide
 plot(sol; xguide = "Time (au)", lw = 2)
 ```
 
@@ -260,10 +257,6 @@ could cite our work:
 }
 ```
 
-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.
-
 ## [Reproducibility](@id doc_home_reproducibility)
 ```@raw html
 <details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>

docs/src/steady_state_functionality/steady_state_stability_computation.md

@@ -1,4 +1,4 @@
-# Steady state stability computation
+# [Steady state stability computation](@id steady_state_stability)
 After system steady states have been found using [HomotopyContinuation.jl](@ref homotopy_continuation), [NonlinearSolve.jl](@ref nonlinear_solve), or other means, their stability can be computed using Catalyst's `steady_state_stability` function. Systems with conservation laws will automatically have these removed, permitting stability computation on systems with singular Jacobian.
 
 !!! warn