Merge pull request #917 from SciML/docs_internal_references_additions

doc updates

Author: TorkelE

docs/pages.jl

@@ -2,21 +2,18 @@ pages = Any[
     "Home" => "index.md",
     "Introduction to Catalyst" => Any[
         "introduction_to_catalyst/catalyst_for_new_julia_users.md",
-        # "introduction_to_catalyst/introduction_to_catalyst.md"
-        # Advanced introduction.
+        "introduction_to_catalyst/introduction_to_catalyst.md"
     ],
     "Model Creation and Properties" => Any[
         "model_creation/dsl_basics.md",
         "model_creation/dsl_advanced.md",
-        #"model_creation/programmatic_CRN_construction.md",
+        "model_creation/programmatic_CRN_construction.md",
         "model_creation/compositional_modeling.md",
-        #"model_creation/constraint_equations.md",
-        # Events.
-        "model_creation/parametric_stoichiometry.md",# Distributed parameters, rates, and initial conditions.
-        "model_creation/model_file_loading_and_export.md",# Distributed parameters, rates, and initial conditions.
-        # Loading and writing models to files.
+        "model_creation/constraint_equations.md",
+        "model_creation/parametric_stoichiometry.md",
+        "model_creation/model_file_loading_and_export.md",
         "model_creation/model_visualisation.md",
-        #"model_creation/network_analysis.md",
+        "model_creation/network_analysis.md",
         "model_creation/chemistry_related_functionality.md",
         "Model creation examples" => Any[
             "model_creation/examples/basic_CRN_library.md",
@@ -30,11 +27,7 @@ pages = Any[
         "model_simulation/simulation_plotting.md",
         "model_simulation/simulation_structure_interfacing.md",
         "model_simulation/ensemble_simulations.md",
-        # Stochastic simulation statistical analysis.
         "model_simulation/ode_simulation_performance.md",
-        # SDE Performance considerations/advice.
-        # Jump Performance considerations/advice.
-        # Finite state projection
     ],
     "Steady state analysis" => Any[
         "steady_state_functionality/homotopy_continuation.md",
@@ -44,28 +37,15 @@ pages = Any[
         "steady_state_functionality/dynamical_systems.md"
     ],
     "Inverse Problems" => Any[
-        # Inverse problems introduction.
         "inverse_problems/optimization_ode_param_fitting.md",
         # "inverse_problems/petab_ode_param_fitting.md",
-        # ODE parameter fitting using Turing.
-        # SDE/Jump fitting.
         "inverse_problems/behaviour_optimisation.md",
-        "inverse_problems/structural_identifiability.md", # Broken on Julia v1.10.3, requires v1.10.2 or 1.10.4.
-        # Practical identifiability.
+        "inverse_problems/structural_identifiability.md",
         "inverse_problems/global_sensitivity_analysis.md",
         "Inverse problem examples" => Any[
             "inverse_problems/examples/ode_fitting_oscillation.md"
         ]
     ],
-    "Spatial modelling" => Any[
-        # Intro.
-        # Lattice ODEs.
-        # Lattice Jumps.
-    ],
-    # "Developer Documentation" => Any[
-    #     # Contributor's guide.
-    #     # Repository structure.
-    # ],
     "FAQs" => "faqs.md",
     "API" => "api.md"
 ]

docs/src/introduction_to_catalyst/introduction_to_catalyst.md

@@ -285,7 +285,7 @@ For details on what information can be specified via the DSL see the [The
 Reaction DSL](@ref dsl_description) tutorial.
 
 ---
-## Reaction rate laws used in simulations
+## [Reaction rate laws used in simulations](@id introduction_to_catalyst_ratelaws)
 In generating mathematical models from a [`ReactionSystem`](@ref), reaction
 rates are treated as *microscopic* rates. That is, for a general mass action
 reaction of the form $n_1 S_1 + n_2 S_2 + \dots n_M S_M \to \dots$ with

docs/src/inverse_problems/behaviour_optimisation.md

@@ -4,7 +4,7 @@ In previous tutorials we have described how to use [PEtab.jl](@ref petab_paramet
 ## [Maximising the pulse amplitude of an incoherent feed forward loop](@id behaviour_optimisation_IFFL_example)
 Incoherent feedforward loops (network motifs where a single component both activates and deactivates a downstream component) are able to generate pulses in response to step inputs[^2]. In this tutorial we will consider such an incoherent feedforward loop, attempting to generate a system with as prominent a response pulse as possible.
 
-Our model consists of 3 species: $X$ (the input node), $Y$ (an intermediary), and $Z$ (the output node). In it, $X$ activates the production of both $Y$ and $Z$, with $Y$ also deactivating $Z$. When $X$ is activated, there will be a brief time window where $Y$ is still inactive, and $Z$ is activated. However, as $Y$ becomes active, it will turn $Z$ off. This creates a pulse of $Z$ activity. To trigger the system, we create [an event](@ref ref), which increases the production rate of $X$ ($pX$) by a factor of $10$ at time $t = 10$.
+Our model consists of 3 species: $X$ (the input node), $Y$ (an intermediary), and $Z$ (the output node). In it, $X$ activates the production of both $Y$ and $Z$, with $Y$ also deactivating $Z$. When $X$ is activated, there will be a brief time window where $Y$ is still inactive, and $Z$ is activated. However, as $Y$ becomes active, it will turn $Z$ off. This creates a pulse of $Z$ activity. To trigger the system, we create [an event](@ref constraint_equations_events), which increases the production rate of $X$ ($pX$) by a factor of $10$ at time $t = 10$.
 ```@example behaviour_optimization
 using Catalyst
 incoherent_feed_forward = @reaction_network begin

docs/src/inverse_problems/global_sensitivity_analysis.md

@@ -8,7 +8,7 @@ GSA can be carried out using the [GlobalSensitivity.jl](https://github.com/SciML
 ### [Global vs local sensitivity](@id global_sensitivity_analysis_global_vs_local_sensitivity)
 A related concept to global sensitivity is *local sensitivity*. This, rather than measuring a function's sensitivity (with regards to its inputs) across its entire (or large part of its) domain, measures it at a specific point. This is equivalent to computing the function's gradients at a specific point in phase space, which is an important routine for most gradient-based optimisation methods (typically carried out through [*automatic differentiation*](https://en.wikipedia.org/wiki/Automatic_differentiation)). For most Catalyst-related functionalities, local sensitivities are computed using the [SciMLSensitivity.jl](https://github.com/SciML/SciMLSensitivity.jl) package. While certain GSA methods can utilise local sensitivities, this is not necessarily the case.
 
-While local sensitivities are primarily used as a subroutine of other methodologies (such as optimisation schemes), it also has direct uses. E.g., in the context of fitting parameters to data, local sensitivity analysis can be used to, at the parameter set of the optimal fit, [determine the cost function's sensitivity to the system parameters](@ref ref).
+While local sensitivities are primarily used as a subroutine of other methodologies (such as optimisation schemes), it also has direct uses. E.g., in the context of fitting parameters to data, local sensitivity analysis can be used to, at the parameter set of the optimal fit, determine the cost function's sensitivity to the system parameters.
 
 ## [Basic example](@id global_sensitivity_analysis_basic_example)
 We will consider a simple [SEIR model of an infectious disease](https://en.wikipedia.org/wiki/Compartmental_models_in_epidemiology). This is an expansion of the classic [SIR model](@ref basic_CRN_library_sir) with an additional *exposed* state, $E$, denoting individuals who are latently infected but currently unable to transmit their infection to others.

docs/src/model_creation/dsl_advanced.md

@@ -86,7 +86,7 @@ Generally, there are four main reasons for specifying species/parameters using t
 4. To designate a species or parameters that do not occur in reactions, but are still part of the model (e.g a [parametric initial condition](@ref dsl_advanced_options_parametric_initial_conditions))
 
 !!! warn
-    Catalyst's DSL automatically infer species and parameters from the input. However, it only does so for *quantities that appear in reactions*. Until now this has not been relevant. However, this tutorial will demonstrate cases where species/parameters that are not part of reactions are used. These *must* be designated using either the `@species` or `@parameters` options (or the `@variables` option, which is described [later](@ref ref)).
+    Catalyst's DSL automatically infer species and parameters from the input. However, it only does so for *quantities that appear in reactions*. Until now this has not been relevant. However, this tutorial will demonstrate cases where species/parameters that are not part of reactions are used. These *must* be designated using either the `@species` or `@parameters` options (or the `@variables` option, which is described [later](@ref constraint_equations)).
 
 ### [Setting default values for species and parameters](@id dsl_advanced_options_default_vals)
 When declaring species/parameters using the `@species` and `@parameters` options, one can also assign them default values (by appending them with `=` followed by the desired default value). E.g here we set `X`'s default initial condition value to $1.0$, and `p` and `d`'s default values to $1.0$ and $0.2$, respectively:
@@ -207,7 +207,7 @@ It is not possible for the user to directly designate their own metadata. These
 
 ### [Designating constant-valued/fixed species parameters](@id dsl_advanced_options_constant_species)
 
-Catalyst enables the designation of parameters as `constantspecies`. These parameters can be used as species in reactions, however, their values are not changed by the reaction and remain constant throughout the simulation (unless changed by e.g. the [occurrence of an event]@ref ref). Practically, this is done by setting the parameter's `isconstantspecies` metadata to `true`. Here, we create a simple reaction where the species `X` is converted to `Xᴾ` at rate `k`. By designating `X` as a constant species parameter, we ensure that its quantity is unchanged by the occurrence of the reaction.
+Catalyst enables the designation of parameters as `constantspecies`. These parameters can be used as species in reactions, however, their values are not changed by the reaction and remain constant throughout the simulation (unless changed by e.g. the [occurrence of an event]@ref constraint_equations_events). Practically, this is done by setting the parameter's `isconstantspecies` metadata to `true`. Here, we create a simple reaction where the species `X` is converted to `Xᴾ` at rate `k`. By designating `X` as a constant species parameter, we ensure that its quantity is unchanged by the occurrence of the reaction.
 ```@example dsl_advanced_constant_species
 using Catalyst # hide
 rn = @reaction_network begin
@@ -357,7 +357,7 @@ plot!(ylimit = (minimum(sol[:Xtot])*0.95, maximum(sol[:Xtot])*1.05)) # hide
 ```
 to plot the observables (rather than the species).
 
-Observables can be defined using complicated expressions containing species, parameters, and [variables](@ref ref) (but not other observables). In the following example (which uses a [parametric stoichiometry](@ref dsl_description_stoichiometries_parameters)) `X` polymerises to form a complex `Xn` containing `n` copies of `X`. Here, we create an observable describing the total number of `X` molecules in the system:
+Observables can be defined using complicated expressions containing species, parameters, and [variables](@ref constraint_equations) (but not other observables). In the following example (which uses a [parametric stoichiometry](@ref dsl_description_stoichiometries_parameters)) `X` polymerises to form a complex `Xn` containing `n` copies of `X`. Here, we create an observable describing the total number of `X` molecules in the system:
 ```@example dsl_advanced_observables
 rn = @reaction_network begin
     @observables Xtot ~ X + n*Xn
@@ -377,7 +377,7 @@ end
 nothing # hide
 ```
 
-Observables are by default considered [variables](@ref ref) (not species). To designate them as a species, they can be pre-declared using the `@species` option. I.e. Here `Xtot` becomes a species:
+Observables are by default considered [variables](@ref constraint_equations) (not species). To designate them as a species, they can be pre-declared using the `@species` option. I.e. Here `Xtot` becomes a species:
 ```@example dsl_advanced_observables
 rn = @reaction_network begin
     @species Xtot(t)

docs/src/model_creation/dsl_basics.md

@@ -1,7 +1,7 @@
 # [The Catalyst DSL - Introduction](@id dsl_description)
 In the [introduction to Catalyst](@ref introduction_to_catalyst) we described how the `@reaction_network` [macro](https://docs.julialang.org/en/v1/manual/metaprogramming/#man-macros) can be used to create chemical reaction network (CRN) models. This macro enables a so-called [domain-specific language](https://en.wikipedia.org/wiki/Domain-specific_language) (DSL) for creating CRN models. This tutorial will give a basic introduction on how to create Catalyst models using this macro (from now onwards called "*the Catalyst DSL*"). A [follow-up tutorial](@ref dsl_advanced_options) will describe some of the DSL's more advanced features.
 
-The Catalyst DSL generates a [`ReactionSystem`](@ref) (the [julia structure](https://docs.julialang.org/en/v1/manual/types/#Composite-Types) Catalyst uses to represent CRN models). These can be created through alternative methods (e.g. [programmatically](@ref programmatic_CRN_construction) or [compositionally](@ref compositional_modeling)). A summary of the various ways to create `ReactionSystems`s can be found [here](@ref ref). [Previous](@ref ref) and [following](@ref simulation_intro) tutorials describe how to simulate models once they have been created using the DSL. This tutorial will solely focus on model creation.
+The Catalyst DSL generates a [`ReactionSystem`](@ref) (the [julia structure](https://docs.julialang.org/en/v1/manual/types/#Composite-Types) Catalyst uses to represent CRN models). These can be created through alternative methods (e.g. [programmatically](@ref programmatic_CRN_construction) or [compositionally](@ref compositional_modeling)). A summary of the various ways to create `ReactionSystems`s can be found [here](@ref ref). [Previous](@ref introduction_to_catalyst) and [following](@ref simulation_intro) tutorials describe how to simulate models once they have been created using the DSL. This tutorial will solely focus on model creation.
 
 Before we begin, we will first load the Catalyst package (which is required to run the code).
 ```@example dsl_basics_intro
@@ -88,7 +88,7 @@ rn5 = @reaction_network begin
     kD, X2 --> 2X
 end
 ```
-Reactants whose stoichiometries are not defined are assumed to have stoichiometry `1`. Any integer number can be used, furthermore, [decimal numbers and parameters can also be used as stoichiometries](@ref dsl_description_stoichiometries). A discussion of non-unitary (i.e. not equal to `1`) stoichiometries affecting the created model can be found [here](@ref ref).
+Reactants whose stoichiometries are not defined are assumed to have stoichiometry `1`. Any integer number can be used, furthermore, [decimal numbers and parameters can also be used as stoichiometries](@ref dsl_description_stoichiometries). A discussion of non-unitary (i.e. not equal to `1`) stoichiometries affecting the created model can be found [here](@ref introduction_to_catalyst_ratelaws).
 
 Stoichiometries can be combined with `()` to define them for multiple reactants. Here, the following (mock) model declares the same reaction twice, both with and without this notation:
 ```@example dsl_basics

docs/src/model_creation/examples/basic_CRN_library.md

@@ -265,7 +265,7 @@ brusselator = @reaction_network begin
     1, X --> ∅
 end
 ```
-It is generally known to (for reaction rate equation-based ODE simulations) produce oscillations when $B > 1 + A^2$. However, this result is based on models generated when *combinatorial adjustment of rates is not performed*. Since Catalyst [automatically perform these adjustments](@ref ref), and one reaction contains a stoichiometric constant $>1$, the threshold will be different. Here, we trial two different values of $B$. In both cases, $B < 1 + A^2$, however, in the second case the system can generate oscillations.
+It is generally known to (for reaction rate equation-based ODE simulations) produce oscillations when $B > 1 + A^2$. However, this result is based on models generated when *combinatorial adjustment of rates is not performed*. Since Catalyst [automatically perform these adjustments](@ref introduction_to_catalyst_ratelaws), and one reaction contains a stoichiometric constant $>1$, the threshold will be different. Here, we trial two different values of $B$. In both cases, $B < 1 + A^2$, however, in the second case the system can generate oscillations.
 ```@example crn_library_brusselator
 using OrdinaryDiffEq, Plots
 u0 = [:X => 1.0, :Y => 1.0]

docs/src/model_creation/model_file_loading_and_export.md

@@ -52,7 +52,7 @@ complete(rs)
 end
 ```
 !!! note
-    The code that `save_reactionsystem` prints uses [programmatic modelling](@ref ref) to generate the written model. 
+    The code that `save_reactionsystem` prints uses [programmatic modelling](@ref programmatic_CRN_construction) to generate the written model. 
 
 In addition to transferring models between Julia sessions, the `save_reactionsystem` function can also be used or print a model to a text file where you can easily inspect its components.
 

docs/src/model_simulation/simulation_structure_interfacing.md

@@ -21,7 +21,7 @@ oprob = ODEProblem(cc_system, u0, tspan, ps)
 nothing    # hide
 ```
 
-We can find a species's (or [variable's](@ref ref)) initial condition value by simply indexing with the species of interest as input. Here we check the initial condition value of $C$:
+We can find a species's (or [variable's](@ref constraint_equations)) initial condition value by simply indexing with the species of interest as input. Here we check the initial condition value of $C$:
 ```@example structure_indexing
 oprob[:C]
 ```

docs/src/steady_state_functionality/nonlinear_solve.md

@@ -1,6 +1,6 @@
 # [Finding Steady States using NonlinearSolve.jl and SteadyStateDiffEq.jl](@id steady_state_solving)
 
-Catalyst `ReactionSystem` models can be converted to ODEs (through [the reaction rate equation](@ref ref)). We have previously described how these ODEs' steady states can be found through [homotopy continuation](@ref homotopy_continuation). Generally, homotopy continuation (due to its ability to find *all* of a system's steady states) is the preferred approach. However, Catalyst supports two additional approaches for finding steady states:
+Catalyst `ReactionSystem` models can be converted to ODEs (through [the reaction rate equation](@ref introduction_to_catalyst_ratelaws)). We have previously described how these ODEs' steady states can be found through [homotopy continuation](@ref homotopy_continuation). Generally, homotopy continuation (due to its ability to find *all* of a system's steady states) is the preferred approach. However, Catalyst supports two additional approaches for finding steady states:
 - Through solving the nonlinear system produced by setting all ODE differentials to 0.
 - Through forward ODE simulation from an initial condition until a steady state has been reached.