fixes

Author: vyudu

docs/Project.toml

@@ -19,7 +19,6 @@ Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
 LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
-MultiDocumenter = "87ed4bf0-c935-4a67-83c3-2a03bee4197c"
 NetworkLayout = "46757867-2c16-5918-afeb-47bfcb05e46a"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 Optim = "429524aa-4258-5aef-a3af-852621145aeb"

docs/make.jl

@@ -2,7 +2,6 @@ using Documenter
 using Catalyst, ModelingToolkit
 # Add packages for plotting
 using GraphMakie, CairoMakie
-#using MultiDocumenter
 
 docpath = Base.source_dir()
 assetpath = joinpath(docpath, "src", "assets")
@@ -49,32 +48,5 @@ makedocs(sitename = "Catalyst.jl",
     pagesonly = true,
     warnonly = [:missing_docs])
 
-#clonedir = mktempdir()
-
-#docs = [MultiDocumenter.MultiDocRef(
-#        upstream = joinpath(@__DIR__, "build"),
-#        path = "docs",
-#        name = "Catalyst",
-#        fix_canonical_url = false,
-#        ),
-#        MultiDocumenter.MultiDocRef(
-#        upstream = joinpath(clonedir, "build"),
-#        path = "NetworkAnalysis",
-#        name = "CatalystNetworkAnalysis",
-#        giturl = "https://github.com/SciML/CatalystNetworkAnalysis.jl",
-#        )]
-
 deploydocs(repo = "github.com/SciML/Catalyst.jl.git";
     push_preview = true)
-
-#outpath = joinpath(@__DIR__, "build")
-#MultiDocumenter.make(outpath, docs;
-#                     assets_dir = "docs/src/assets",
-#                     search_engine = MultiDocumenter.SearchConfig(index_versions = [
-#                                                                      "stable",
-#                                                                  ],
-#                                                                  engine = MultiDocumenter.FlexSearch),
-#                     brand_image = MultiDocumenter.BrandImage("https://sciml.ai",
-#                                                              joinpath("assets",
-#                                                                       "logo.png")))
-#

docs/pages.jl

@@ -29,8 +29,7 @@ pages = Any[
     "Network Analysis" => Any[
         "network_analysis/odes.md",
         "network_analysis/crn_theory.md",
-        "network_analysis/network_properties.md",
-        "network_analysis/advanced_analysis.md"
+        "network_analysis/network_properties.md"
     ],
     "Model simulation and visualization" => Any[
         "model_simulation/simulation_introduction.md",

docs/src/api/core_api.md

@@ -86,7 +86,7 @@ ReactionSystem
 ```
 
 ## [Options for the `@reaction_network` DSL](@id api_dsl_options)
-We have [previously described](@ref dsl_advanced_options) how options permits the user to supply non-reaction information to [`ReactionSystem`](@ref) created through the DSL. Here follows a list
+We have [previously described](@ref dsl_advanced_options) how options permit the user to supply non-reaction information to [`ReactionSystem`](@ref) created through the DSL. Here follows a list
 of all options currently available.
 - [`parameters`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system parameters.
 - [`species`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system species.

docs/src/network_analysis/advanced_analysis.md

@@ -262,8 +262,11 @@ which we see is mass action and has deficiency zero, but is not weakly
 reversible. As such, we can conclude that for any choice of rate constants the
 RRE ODEs cannot have a positive equilibrium solution.
 
-```@docs; canonical=false
-satisfiesdeficiencyzero
+There is an API function [`satisfiesdeficiencyzero`](@ref) that will let us check
+all these conditions easily:
+
+```@example s1
+satisfiesdeficiencyzero(def0_rn)
 ```
 
 ## Deficiency One Theorem
@@ -282,8 +285,31 @@ stoichiometric compatibility class for any choice of rate constants and paramete
 the deficiency zero theorem, networks obeying the deficiency one theorem are not guaranteed 
 to have stable solutions.
 
-```@docs; canonical=false
-satisfiesdeficiencyone
+Let's look at an example network.
+
+```@example s1
+def1_network = @reaction_network begin
+    (k1, k2), A <--> 2B
+    k3, C --> 2D
+    k4, 2D --> C + E
+    (k5, k6), C + E <--> E + 2D
+end
+plot_complexes(def1_network)
+```
+
+We can see from the complex graph that there are two linkage classes, the deficiency of the bottom one is zero and the deficiency of the top one is one.
+The total deficiency is one:
+
+```@example s1
+deficiency(def1_network)
+```
+
+And there is only one terminal linkage class in each, so our network satisfies all three conditions.
+As in the deficiency zero case, there is the API function [`satisfiesdeficiencyone`](@ref)
+for quickly checking these conditions:
+
+```@example s1
+satisfiesdeficiencyone(def1_network)
 ```
 
 ## [Complex and Detailed Balance](@id network_analysis_complex_and_detailed_balance)
@@ -296,7 +322,7 @@ Note that detailed balance at a given steady state implies complex balance for t
 i.e. detailed balance is a stronger property than complex balance.
 
 Remarkably, having just one positive steady state that is complex (detailed) balance implies that 
-complex (detailed) balance obtains at *every* positive steady state, so we say that a network 
+complex (detailed) balance holds for *every* positive steady state, so we say that a network 
 is complex (detailed) balanced if any one of its steady states are complex (detailed) balanced. 
 Additionally, there will be exactly one steady state in every positive stoichiometric 
 compatibility class, and this steady state is asymptotically stable. (For proofs of these results,
@@ -328,7 +354,7 @@ isdetailedbalanced
 
 ## [Concentration Robustness](@id network_analysis_concentration_robustness)
 Certain reaction networks have species that do not change their concentration,
-regardless of the system is perturbed to a different stoichiometric compatibility
+regardless of whether the system is perturbed to a different stoichiometric compatibility
 class. This is a very useful property to have in biological contexts, where it might
 be important to keep the concentration of a critical species relatively stable in
 the face of changes in its environment. 

docs/src/network_analysis/crn_theory.md

@@ -14,7 +14,7 @@ in Catalyst as well](@ref dsl_advanced_options_constant_species).
 ## [Network representation of the Repressilator `ReactionSystem`](@id network_analysis_repressilator_representation)
 We first load Catalyst and construct our model of the repressilator
 ```@example s1
-using Catalyst
+using Catalyst, CairoMakie, GraphMakie, NetworkLayout
 repressilator = @reaction_network Repressilator begin
        hillr(P₃,α,K,n), ∅ --> m₁
        hillr(P₁,α,K,n), ∅ --> m₂
@@ -34,10 +34,10 @@ In the [Model Visualization](@ref visualisation_graphs)
 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.
-```julia
-g = Graph(repressilator)
+
+```@example s1
+g = plot_network(repressilator)
 ```
-![Repressilator solution](../assets/repressilator.svg)
 
 We also showed in the [Introduction to Catalyst](@ref introduction_to_catalyst) tutorial that
 the reaction rate equation (RRE) ODE model for the repressilator is
@@ -197,7 +197,7 @@ plot_complexes(rn)
 ```
 
 while for the repressilator we find
-```julia
+```@example s1
 plot_complexes(repressilator)
 ```
 
@@ -211,15 +211,15 @@ So far we have covered two equivalent descriptions of the chemical reaction netw
 ```math
 \begin{align}
 \frac{d\mathbf{x}}{dt} &= N \mathbf{v}(\mathbf{x}(t),t) \\
-&= Z B \mathbf{v}(\mathbf{x}(t),t)
+&= Z B \mathbf{v}(\mathbf{x}(t),t).
 \end{align}
 ```
 
-In this section we discuss a further decomposition of the ODEs. Recall that the reaction rate vector $\mathbf{v}$, which is a vector of length $R$ whose elements are the rate expressions for each reaction. Its elements can be written as 
+In this section we discuss a further decomposition of the ODEs. Recall the reaction rate vector $\mathbf{v}$, which is a vector of length $R$ whose elements are the rate expressions for each reaction. Its elements can be written as 
 ```math
 \mathbf{v}_{y \rightarrow y'} = k_{y \rightarrow y'} \mathbf{x}^y,
 ```
-where $\mathbf{x}^y = \prod_s x_s^{y_s}$, the mass-action product of the complex $y$, where $y$ is the substrate complex of the reaction $y \rightarrow y'$. We can define a new vector called the mass action vector $\Phi(\mathbf{x}(t))$, a vector of length $C$ whose elements are the mass action products of each complex: 
+where $\mathbf{x}^y = \prod_s x_s^{y_s}$ denotes the mass-action product of the substrate complex $y$ from the $y \rightarrow y'$ reaction. We can define a new vector called the mass action vector $\Phi(\mathbf{x}(t))$, a vector of length $C$ whose elements are the mass action products of each complex: 
 ```@example s1
 Φ = massactionvector(rn)
 ```
@@ -262,24 +262,24 @@ returns a `Matrix{Num}`, since some of its entries are symbolic rate constants
 (symbolic variables and `Num`s cannot be compared using `==`, since `a == b`
 is interpreted as a symbolic expression).
 
-In sum, we have that
+In summary, we have that
 ```math
 \begin{align}
 \frac{d\mathbf{x}}{dt} &= N \mathbf{v}(\mathbf{x}(t),t) \\
 &= N K \Phi(\mathbf{x}(t),t) \\
-&= Z B K \Phi(\mathbf{x}(t),t). 
+&= Z B K \Phi(\mathbf{x}(t),t) \\ 
 &= Z A_k \Phi(\mathbf{x}(t),t). 
 \end{align}
 ```
 
-All three of the objects introduced in this section (the flux matrix, mass-action vector, Laplacian matrix) will return symbolic outputs by default, but can be made to return numerical outputs if values are specified. 
+All three of the objects introduced in this section (the flux matrix, mass-action vector, and Laplacian matrix) will return symbolic outputs by default, but can be made to return numerical outputs if values are specified. 
 For example, `massactionvector` will return a numerical output if a set of species concentrations is supplied using a dictionary, tuple, or vector of Symbol-value pairs.
 ```@example s1
 concmap = Dict([:A => 3., :B => 5., :C => 2.4, :D => 1.5])
 massactionvector(rn, concmap)
 ```
 
-`fluxmat` and `laplacianmat` will return numeric matrices if a set of rate constants and other aprameters are supplied the same way.
+`fluxmat` and `laplacianmat` will return numeric matrices if a set of rate constants and other parameters are supplied the same way.
 ```@example s1
 parammap = Dict([:k => 12., :b => 8.])
 fluxmat(rn, parammap)
@@ -303,7 +303,7 @@ f = eval(f_oop_expr)
 c = [3., 5., 2., 6.]
 f(c)
 ```
-The generated `f` now corresponds to the $f(\mathbf{x}(t))$ on the right-hand side of $\frac{d\mathbf{x}(t)}{dt} = f(\mathbf{x}(t))$. Given a vector of species concentrations $c$, `ode_func` will return the rate of change of each species. Steady state concentration vectors `c_ss` will satisfy `f(c_ss) = zeros(length(species(rn)))`.
+The generated `f` now corresponds to the $f(\mathbf{x}(t))$ on the right-hand side of $\frac{d\mathbf{x}(t)}{dt} = f(\mathbf{x}(t))$. Given a vector of species concentrations $c$, `f` will return the rate of change of each species. Steady state concentration vectors `c_ss` will satisfy `f(c_ss) = zeros(length(species(rn)))`.
 
 Above we have generated a numeric rate matrix to substitute the rate constants into the symbolic expressions. We could have used a symbolic rate matrix, but then we would need to define the parameters `k, b`, so that the function `f` knows what `k` and `b` in its output refer to.
 ```@example s1
@@ -333,7 +333,7 @@ Note also that `f` can take any vector with the right dimension (i.e. the number
 ## Properties of matrix null spaces
 The null spaces of the matrices discussed in this section often have special meaning. Below we will discuss some of these properties.
 
-Recall that we may write the net stoichiometry matrix ``N = YB``.
+Recall that we may write the net stoichiometry matrix ``N = ZB``, where `Z` is the complex stoichiometry matrix and `B` is the incidence matrix of the graph.
 
 [Conservation laws](@ref conservation_laws) arise as left null eigenvectors of the net stoichiometry matrix ``N``, and cycles arise as right null eigenvectors of the stoichiometry matrix. A cycle may be understood as a sequence of reactions that leaves the overall species composition unchanged. These do not necessarily have to correspond to actual cycles in the graph.