Merge pull request #588 from SciML/some_doc_changes

Starting documentation reordering

Project.toml

@@ -1,6 +1,6 @@
 name = "Catalyst"
 uuid = "479239e8-5488-4da2-87a7-35f2df7eef83"
-version = "13.0.0-DEV"
+version = "13.0.0"
 
 [deps]
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"

docs/Project.toml

@@ -13,7 +13,7 @@ SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 
 [compat]
 BifurcationKit = "0.2"
-Catalyst = "12.3"
+Catalyst = "13"
 DifferentialEquations = "7.6"
 Distributions = "0.25"
 Documenter = "0.27"

docs/pages.jl

@@ -1,15 +1,15 @@
 pages = Any["Home" => "index.md",
-            "Catalyst for new Julia users" => Any["catalyst_for_new_julia_users/intro_to_catalyst.md"],
-            "Tutorials" => Any["tutorials/using_catalyst.md",
-                               "tutorials/dsl.md",
-                               "tutorials/reaction_systems.md",
-                               "tutorials/basic_examples.md",
-                               "tutorials/compositional_modeling.md",
-                               "tutorials/symbolic_stoich.md",
-                               "tutorials/reaction_network_representation.md",
-                               "tutorials/homotopy_continuation_tutorial.md",
-                               "tutorials/bifurcation_diagram.md",
-                               "tutorials/parameter_estimation.md",
-                               "tutorials/generating_reactions_programmatically.md"],
+            "Introduction to Catalyst" => Any["intro_to_catalyst/catalyst_for_new_julia_users.md",
+                                              "intro_to_catalyst/using_catalyst.md"],
+            "Catalyst Functionality" => Any["catalyst_functionality/dsl_description.md",
+                                            "catalyst_functionality/programmatic_CRN_construction.md",
+                                            "catalyst_functionality/compositional_modeling.md",
+                                            "catalyst_functionality/parametric_stoichiometry.md",
+                                            "catalyst_functionality/network_analysis.md"],
+            "Catalyst Applications" => Any["tutorials/homotopy_continuation.md",
+                                           "tutorials/bifurcation_diagrams.md",
+                                           "tutorials/parameter_estimation.md"],
+            "Example Networks" => Any["example_networks/basic_CRN_examples.md",
+                                      "example_networks/smoluchowski_coagulation_equation.md"],
             "FAQs" => "faqs.md",
-            "API" => Any["api/catalyst_api.md"]]
+            "API" => "api/catalyst_api.md"]

docs/src/api/catalyst_api.md

@@ -150,7 +150,7 @@ Below we list the remainder of the Catalyst API accessor functions mentioned
 above.
 
 ## Basic System Properties
-See [Programmatic Construction of Symbolic Reaction Systems](@ref) for examples and [ModelingToolkit and
+See [Programmatic Construction of Symbolic Reaction Systems](@ref programmatic_CRN_construction) for examples and [ModelingToolkit and
 Catalyst Accessor Functions](@ref) for more details on the basic accessor
 functions.
 

docs/src/tutorials/compositional_modeling.md → docs/src/catalyst_functionality/compositional_modeling.md

@@ -1,4 +1,4 @@
-# Compositional Modeling of Reaction Systems
+# [Compositional Modeling of Reaction Systems](@id compositional_modeling)
 Catalyst supports the construction of models in a compositional fashion, based
 on ModelingToolkit's subsystem functionality. In this tutorial we'll see how we
 can construct the earlier repressilator model by composing together three

docs/src/tutorials/dsl.md → docs/src/catalyst_functionality/dsl_description.md

@@ -1,10 +1,10 @@
-# The Reaction DSL
+# [The Reaction DSL](@id dsl_description)
 This tutorial covers some of the basic syntax for building chemical reaction
 network models using Catalyst's domain specific language (DSL). Examples showing
 how to both construct and solve ODE, SDE, and jump models are provided in [Basic
-Chemical Reaction Network Examples](@ref). To learn more about the symbolic
+Chemical Reaction Network Examples](@ref basic_CRN_examples). To learn more about the symbolic
 [`ReactionSystem`](@ref)s generated by the DSL, and how to use them directly, see
-the tutorial on [Programmatic Construction of Symbolic Reaction Systems](@ref).
+the tutorial on [Programmatic Construction of Symbolic Reaction Systems](@ref programmatic_CRN_construction).
 
 We first load the needed packages for the code in the tutorial to run
 ```@example tut2
@@ -79,7 +79,7 @@ oprob = ODEProblem(rn, u0, tspan, [])
 ```
 
 For more detailed examples, see the [Basic Chemical Reaction Network
-Examples](@ref).
+Examples](@ref basic_CRN_examples).
 
 ## Defining parameters and species
 Numeric parameter values do not need to be set when the model is created, i.e.
@@ -454,7 +454,7 @@ The DSL allows Julia variables to be interpolated for the network name, within
 rate constant expressions, or for species/stoichiometry within reactions. Using
 the lower-level symbolic interface we can then define symbolic variables and
 parameters outside of the macro, which can then be used within expressions in
-the DSL (see the [Programmatic Construction of Symbolic Reaction Systems](@ref)
+the DSL (see the [Programmatic Construction of Symbolic Reaction Systems](@ref programmatic_CRN_construction)
 tutorial for details on the lower-level symbolic interface). For example,
 ```@example tut2
 @parameters k α

docs/src/tutorials/reaction_network_representation.md → docs/src/catalyst_functionality/network_analysis.md

@@ -1,4 +1,4 @@
-# Network Analysis in Catalyst
+# [Network Analysis in Catalyst](@id network_analysis)
 
 In this tutorial we introduce several of the Catalyst API functions for network
 analysis. A complete summary of the exported functions is given in the API
@@ -27,7 +27,7 @@ repressilator = @reaction_network Repressilator begin
        μ, P₃ --> ∅
 end
 ```
-In the [Using Catalyst](https://docs.sciml.ai/Catalyst/stable/tutorials/using_catalyst/)
+In the [Using Catalyst](@ref using_catalyst)
 tutorial we showed how the above network could be visualized as a
 species-reaction graph. There species are represented by the nodes of the graph
 and edges show the reactions in which a given species is a substrate or product.

docs/src/tutorials/symbolic_stoich.md → docs/src/catalyst_functionality/parametric_stoichiometry.md

@@ -1,4 +1,4 @@
-# Parametric Stoichiometry
+# [Parametric Stoichiometry](@id parametric_stoichiometry)
 Catalyst supports stoichiometric coefficients that involve parameters, species,
 or even general expressions. In this tutorial we show several examples of how to
 use parametric stoichiometry, and discuss several caveats to be aware of.

docs/src/tutorials/reaction_systems.md → docs/src/catalyst_functionality/programmatic_CRN_construction.md

@@ -1,8 +1,8 @@
-# Programmatic Construction of Symbolic Reaction Systems
+# [Programmatic Construction of Symbolic Reaction Systems](@id programmatic_CRN_construction)
 While the DSL provides a simple interface for creating `ReactionSystem`s, it can
 often be convenient to build or augment a [`ReactionSystem`](@ref)
 programmatically. In this tutorial we show how to build the repressilator model
-of the [Using Catalyst](@ref) tutorial directly using symbolic variables, and
+of the [Using Catalyst](@ref using_catalyst) tutorial directly using symbolic variables, and
 then summarize the basic API functionality for accessing information stored
 within `ReactionSystem`s.
 

docs/src/tutorials/basic_examples.md → docs/src/example_networks/basic_CRN_examples.md

@@ -1,4 +1,4 @@
-# Basic Chemical Reaction Network Examples
+# [Basic Chemical Reaction Network Examples](@id basic_CRN_examples)
 
 #### Example: Birth-Death Process
 

docs/src/tutorials/generating_reactions_programmatically.md → docs/src/example_networks/smoluchowski_coagulation_equation.md

@@ -1,4 +1,4 @@
-# Smoluchowski Coagulation Equation
+# [Smoluchowski Coagulation Equation](@id smoluchowski_coagulation_equation)
 This tutorial shows how to programmatically construct a [`ReactionSystem`](@ref) corresponding to the chemistry underlying the [Smoluchowski coagulation model](https://en.wikipedia.org/wiki/Smoluchowski_coagulation_equation) using [ModelingToolkit](http://docs.sciml.ai/ModelingToolkit/stable/)/[Catalyst](http://docs.sciml.ai/Catalyst/stable/). A jump process version of the model is then constructed from the [`ReactionSystem`](@ref), and compared to the model's analytical solution obtained by the [method of Scott](https://journals.ametsoc.org/view/journals/atsc/25/1/1520-0469_1968_025_0054_asocdc_2_0_co_2.xml) (see also [3](https://doi.org/10.1006/jcph.2002.7017)).
 
 The Smoluchowski coagulation equation describes a system of reactions in which monomers may collide to form dimers, monomers and dimers may collide to form trimers, and so on. This models a variety of chemical/physical processes, including polymerization and flocculation.

docs/src/catalyst_for_new_julia_users/intro_to_catalyst.md → docs/src/intro_to_catalyst/catalyst_for_new_julia_users.md

@@ -1,9 +1,9 @@
-# Introduction to Catalyst and Julia for new Julia users
+# [Introduction to Catalyst and Julia for new Julia users](@id catalyst_for_new_julia_users)
 The Catalyst tool for the modelling of chemical reaction networks is based in the Julia programming language. While experience in Julia programming is advantageous for using Catalyst, it is not necessary for accessing some of its basic features. This tutorial serves as an introduction to Catalyst for those unfamiliar with Julia, also introducing some basic Julia concepts. Anyone who plans on using Catalyst extensively is recommended to familiarise oneself more thoroughly with the Julia programming language. A collection of resources for learning Julia can be found [here](https://julialang.org/learning/), and a full documentation is available [here](https://docs.julialang.org/en/v1/).
 
 Julia can be downloaded [here](https://julialang.org/downloads/).
 
-*Users who are already familiar with Julia can skip to the [Using Catalyst](@ref) tutorial.*
+*Users who are already familiar with Julia can skip to the [Using Catalyst](@ref using_catalyst) tutorial.*
 
 ### Basic Julia usage
 On the surface, Julia has many similarities to languages like MATLAB, Python, and R.

docs/src/tutorials/using_catalyst.md → docs/src/intro_to_catalyst/using_catalyst.md

@@ -1,4 +1,4 @@
-# Using Catalyst
+# [Introduction to Catalyst](@id using_catalyst)
 In this tutorial we provide an introduction to using Catalyst to specify
 chemical reaction networks, and then to solve ODE, jump, and SDE models
 generated from them. At the end we show what mathematical rate laws and
@@ -19,7 +19,7 @@ using Catalyst, DifferentialEquations, Plots, Latexify
 
 We now construct the reaction network. The basic types of arrows and predefined
 rate laws one can use are discussed in detail within the tutorial, [The Reaction
-DSL](@ref). Here, we use a mix of first order, zero order, and repressive Hill
+DSL](@ref dsl_description). Here, we use a mix of first order, zero order, and repressive Hill
 function rate laws. Note, $\varnothing$ corresponds to the empty state, and is
 used for zeroth order production and first order degradation reactions:
 ```@example tut1
@@ -111,6 +111,7 @@ conditions. We can build such mappings in several ways. One is to use Julia
 pmap  = (:α => .5, :K => 40, :n => 2, :δ => log(2)/120,
          :γ => 5e-3, :β => log(2)/6, :μ => log(2)/60)
 u₀map = [:m₁ => 0., :m₂ => 0., :m₃ => 0., :P₁ => 20., :P₂ => 0., :P₃ => 0.]
+nothing   # hide
 ```
 Alternatively, we can use ModelingToolkit symbolic variables to specify these
 mappings like
@@ -120,6 +121,7 @@ mappings like
 psymmap  = (α => .5, K => 40, n => 2, δ => log(2)/120,
          γ => 5e-3, β => 20*log(2)/120, μ => log(2)/60)
 u₀symmap = [m₁ => 0., m₂ => 0., m₃ => 0., P₁ => 20., P₂ => 0., P₃ => 0.]
+nothing   # hide
 ```
 Knowing these mappings we can set up the `ODEProblem` we want to solve:
 
@@ -129,12 +131,14 @@ tspan = (0., 10000.)
 
 # create the ODEProblem we want to solve
 oprob = ODEProblem(repressilator, u₀map, tspan, pmap)
+nothing   # hide
 ```
 By passing `repressilator` directly to the `ODEProblem`, Catalyst has to
 (internally) call `convert(ODESystem, repressilator)` again to generate the
 symbolic ODEs. We could instead pass `odesys` directly like
 ```@example tut1
 oprob2 = ODEProblem(odesys, u₀symmap, tspan, psymmap)
+nothing   # hide
 ```
 `oprob` and `oprob2` are functionally equivalent, each representing the same
 underlying problem.
@@ -212,6 +216,7 @@ end
 p = (:c₁ => 1.0, :c₂ => 2.0, :c₃ => 50.)
 u₀ = [:X => 5.]
 tspan = (0.,4.)
+nothing   # hide
 ```
 
 The corresponding Chemical Langevin Equation SDE is then

docs/src/tutorials/bifurcation_diagram.md → docs/src/tutorials/bifurcation_diagrams.md

@@ -1,4 +1,4 @@
-# Bifurcation Diagrams
+# [Bifurcation Diagrams](@id bifurcation_diagrams)
 Bifurcation diagrams can be produced from Catalyst generated models through the
 use of the [BifurcationKit.jl](https://bifurcationkit.github.io/BifurcationKitDocs.jl/stable/)
 package. This tutorial gives a simple example of how to create such a
@@ -23,6 +23,7 @@ p = Dict(:S => 1., :D => 9., :τ => 1000., :v0 => 0.01,
 bif_par = :S           # bifurcation parameter
 p_span = (0.1, 20.)    # interval to vary S over
 plot_var = :X          # we will plot X vs S
+nothing   # hide
 ```
 When creating a bifurcation diagram, we typically start at some point in
 parameter phase-space. We will simply select the beginning of the interval over
@@ -35,13 +36,15 @@ be very accurate.
 p_bstart = copy(p)
 p_bstart[bif_par] = p_span[1]
 u0 = [:X => 1.0, :A => 1.0]
+nothing   # hide
 ```
 Finally, we extract the ODE derivative function and its jacobian in a form that
 BifurcationKit can use:
 ```@example ex1
 oprob = ODEProblem(rn, u0, (0.0,0.0), p_bstart; jac = true)
 F = (u,p) -> oprob.f(u, p, 0)
 J = (u,p) -> oprob.f.jac(u, p, 0)
+nothing   # hide
 ```
 
 In creating an `ODEProblem` an ordering is chosen for the initial condition and
@@ -56,6 +59,7 @@ the variable we wish to plot, `:X`. We calculate these as
 # find their indices in oprob.p and oprob.u0 respectively
 bif_idx  = findfirst(isequal(S), parameters(rn))
 plot_idx = findfirst(isequal(X), species(rn))
+nothing   # hide
 ```
 
 Now, we load the required packages to create and plot the bifurcation diagram.
@@ -66,6 +70,7 @@ using BifurcationKit, Plots, LinearAlgebra, Setfield
 
 bprob = BifurcationProblem(F, oprob.u0, oprob.p, (@lens _[bif_idx]);
                            recordFromSolution = (x, p) -> x[plot_idx], J = J)
+nothing   # hide
 ```
 Next, we need to specify the input options for the pseudo-arclength continuation method (PACM) which produces the diagram.
 ```@example ex1
@@ -76,6 +81,7 @@ bopts = ContinuationPar(dsmax = 0.05,          # Max arclength in PACM.
                         pMin = p_span[1],      # Min p-val (if hit, the method stops).
                         pMax = p_span[2],      # Max p-val (if hit, the method stops).
                         detectBifurcation = 3) # Value in {0,1,2,3}
+nothing   # hide
 ```
 Here `detectBifurcation` determines to what extent bifurcation points are
 detected and how accurately their values are determined. Three indicates to use the most
@@ -84,6 +90,7 @@ accurate method for calculating their values.
 We are now ready to compute the bifurcation diagram:
 ```@example ex1
 bf = bifurcationdiagram(bprob, PALC(), 2, (args...) -> bopts)
+nothing   # hide
 ```
 Finally, we can plot it:
 ```@example ex1

docs/src/tutorials/homotopy_continuation_tutorial.md → docs/src/tutorials/homotopy_continuation.md

@@ -1,4 +1,4 @@
-# Finding Steady States through Homotopy Continuation
+# [Finding Steady States through Homotopy Continuation](@id homotopy_continuation)
 
 The steady states of a dynamical system ${dx \over dt} = f(x)$ can be found by solving $0 = f(x)$. This is typically a hard problem, and generally, there is no method that guarantees to find all steady states for a system that has multiple ones. However, most CRNs generate polynomial systems (the main exception is when Hill functions with non-integer exponents are used). The roots of these can reliably be found through a *homotopy continuation* algorithm. This is implemented in Julia through the [HomotopyContinuation.jl](https://www.juliahomotopycontinuation.org/) package. In this tutorial, we will demonstrate how homotopy continuation can be used to find the steady states of a CNR implemented in  Catalyst.
 
@@ -13,6 +13,7 @@ wilhelm_2009_model = @reaction_network begin
     k4, X --> 0
 end
 p = [:k1 => 8.0, :k2 => 2.0, :k3 => 1.0, :k4 => 1.5]
+nothing   # hide
 ```
 Next, we will need to extract the actual equations from our model. In addition, we will substitute in our parameter values.
 ```@example hc1

docs/src/tutorials/parameter_estimation.md

@@ -1,4 +1,4 @@
-# Parameter Estimation
+# [Parameter Estimation](@id parameter_estimation)
 The parameters of a model, generated by Catalyst, can be estimated using various packages available in the Julia ecosystem. Refer [here](https://docs.sciml.ai/Overview/stable/highlevels/inverse_problems/) for more extensive information. Below follows a quick tutorial of how [DiffEqFlux](http://docs.sciml.ai/DiffEqFlux/stable/) can be used to fit a parameter set to data.
 
 First, we fetch the required packages.
@@ -17,6 +17,7 @@ brusselator = @reaction_network begin
     1, X → ∅
 end
 p_real = [1., 2.]
+nothing   # hide
 ```
 
 We simulate our model, and from the simulation generate sampled data points (with added noise), to which we will attempt to fit a parameter et.
@@ -29,6 +30,7 @@ prob = ODEProblem(brusselator, u0, tspan, p_real)
 sol_real = solve(prob, Rosenbrock23(), tstops=sample_times)
 
 sample_vals = [sol_real.u[findfirst(sol_real.t .>= ts)][var] * (1+(0.1rand()-0.05)) for var in 1:2, ts in sample_times];
+nothing   # hide
 ```
 
 We can plot the real solution, as well as the noisy samples.
@@ -50,6 +52,7 @@ function optimise_p(p_init,tend)
     end
     return DiffEqFlux.sciml_train(loss,p_init,ADAM(0.1),maxiters = 100)
 end
+nothing   # hide
 ```
 
 Next, we will fit a parameter set to the data on the interval [0,10].

src/reaction_network.jl

@@ -129,10 +129,10 @@ end
 """
     @reaction_network
 
-Generates a [`ReactionSystem`](@ref) that encodes a chemical reaction
+Generates a [`ReactionSystem`](@ref dsl_description) that encodes a chemical reaction
 network.
 
-See [The Reaction DSL](@ref) documentation for details on
+See [The Reaction DSL](@ref dsl_description) documentation for details on
 parameters to the macro.
 
 Examples: