Merge remote-tracking branch 'origin/master' into formatting

Author: TorkelE

docs/make.jl

@@ -42,6 +42,7 @@ makedocs(sitename = "Catalyst.jl",
     pages = pages,
     pagesonly = true,
     warnonly = true)
+         warnonly = [:missing_docs])
 
 deploydocs(repo = "github.com/SciML/Catalyst.jl.git";
     push_preview = true)

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",
@@ -29,8 +26,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
+        "model_simulation/ode_simulation_performance.md",
     ],
     "Steady state analysis" => Any[
         "steady_state_functionality/homotopy_continuation.md",
@@ -40,28 +36,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

@@ -12,9 +12,9 @@ We first import the basic packages we'll need:
 
 ```@example tut1
 # If not already installed, first hit "]" within a Julia REPL. Then type:
-# add Catalyst DifferentialEquations Plots Latexify
+# add Catalyst OrdinaryDiffEq Plots Latexify
 
-using Catalyst, DifferentialEquations, Plots, Latexify
+using Catalyst, OrdinaryDiffEq, Plots, Latexify
 ```
 
 We now construct the reaction network. The basic types of arrows and predefined
@@ -160,7 +160,7 @@ underlying problem.
 
 At this point we are all set to solve the ODEs. We can now use any ODE solver
 from within the
-[DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/)
+[OrdinaryDiffEq.jl](https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/)
 package. We'll use the recommended default explicit solver, `Tsit5()`, and then
 plot the solutions:
 
@@ -169,7 +169,7 @@ sol = solve(oprob, Tsit5(), saveat=10.)
 plot(sol)
 ```
 We see the well-known oscillatory behavior of the repressilator! For more on the
-choices of ODE solvers, see the [DifferentialEquations.jl
+choices of ODE solvers, see the [OrdinaryDiffEq.jl
 documentation](https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/).
 
 ---
@@ -182,6 +182,9 @@ Gillespie's `Direct` method, and then solve it to generate one realization of
 the jump process:
 
 ```@example tut1
+# imports the JumpProcesses packages 
+using JumpProcesses
+
 # redefine the initial condition to be integer valued
 u₀map = [:m₁ => 0, :m₂ => 0, :m₃ => 0, :P₁ => 20, :P₂ => 0, :P₃ => 0]
 
@@ -237,6 +240,9 @@ model by creating an `SDEProblem` and solving it similarly to what we did for OD
 above:
 
 ```@example tut1
+# imports the StochasticDiffEq package for SDE simulations
+using StochasticDiffEq
+
 # SDEProblem for CLE
 sprob = SDEProblem(bdp, u₀, tspan, p)
 
@@ -285,7 +291,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/constraint_equations.md

@@ -28,7 +28,7 @@ creating these two systems.
 Here, to create differentials with respect to time (for our differential equations), we must import the time differential operator from Catalyst. We do this through `D = default_time_deriv()`. Here, `D(V)` denotes the differential of the variable `V` with respect to time.
 
 ```@example ceq1
-using Catalyst, DifferentialEquations, Plots
+using Catalyst, OrdinaryDiffEq, Plots
 t = default_t()
 D = default_time_deriv()
 
@@ -58,6 +58,7 @@ We can now merge the two systems into one complete `ReactionSystem` model using
 [`ModelingToolkit.extend`](@ref):
 ```@example ceq1
 @named growing_cell = extend(osys, rn)
+growing_cell = complete(growing_cell)
 ```
 
 We see that the combined model now has both the reactions and ODEs as its
@@ -72,7 +73,7 @@ plot(sol)
 As an alternative to the previous approach, we could have constructed our
 `ReactionSystem` all at once by directly using the symbolic interface:
 ```@example ceq2
-using Catalyst, DifferentialEquations, Plots
+using Catalyst, OrdinaryDiffEq, Plots
 t = default_t()
 D = default_time_deriv()
 
@@ -83,6 +84,7 @@ rx1 = @reaction $V, 0 --> P
 rx2 = @reaction 1.0, P --> 0
 @named growing_cell = ReactionSystem([rx1, rx2, eq], t)
 setdefaults!(growing_cell, [:P => 0.0])
+growing_cell = complete(growing_cell)
 
 oprob = ODEProblem(growing_cell, [], (0.0, 1.0))
 sol = solve(oprob, Tsit5())
@@ -100,12 +102,11 @@ the associated [ModelingToolkit
 tutorial](https://docs.sciml.ai/ModelingToolkit/stable/basics/Events/) for more
 details on the types of events that can be represented symbolically. A
 lower-level approach for creating events via the DifferentialEquations.jl
-callback interface is illustrated in the [Advanced Simulation Options](@ref
-advanced_simulations) tutorial.
+callback interface is illustrated [here](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/) tutorial.
 
 Let's first create our equations and unknowns/species again
 ```@example ceq3
-using Catalyst, DifferentialEquations, Plots
+using Catalyst, OrdinaryDiffEq, Plots
 t = default_t()
 D = default_time_deriv()
 
@@ -124,6 +125,7 @@ continuous_events = [V ~ 2.0] => [V ~ V/2, P ~ P/2]
 We can now create and simulate our model
 ```@example ceq3
 @named rs = ReactionSystem([rx1, rx2, eq], t; continuous_events)
+rs = complete(rs)
 
 oprob = ODEProblem(rs, [], (0.0, 10.0))
 sol = solve(oprob, Tsit5())
@@ -148,6 +150,7 @@ p = [k_on => 100.0, switch_time => 2.0, k_off => 10.0]
 Simulating our model, 
 ```@example ceq3
 @named osys = ReactionSystem(rxs, t, [A, B], [k_on, k_off, switch_time]; discrete_events)
+osys = complete(osys)
 
 oprob = ODEProblem(osys, u0, tspan, p)
 sol = solve(oprob, Tsit5(); tstops = 2.0)

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