Merge pull request #1142 from vyudu/sfr-docs

Refactoring network analysis docs

Author: vyudu

docs/pages.jl

@@ -17,7 +17,6 @@ pages = Any[
         "model_creation/model_file_loading_and_export.md",
         "model_creation/model_visualisation.md",
         "model_creation/reactionsystem_content_accessing.md",
-        "model_creation/network_analysis.md",
         "model_creation/chemistry_related_functionality.md",
         "Examples" => Any[
             "model_creation/examples/basic_CRN_library.md",
@@ -40,6 +39,11 @@ pages = Any[
             "model_simulation/examples/interactive_brusselator_simulation.md"
         ]
     ],
+    "Network Analysis" => Any[
+        "network_analysis/odes.md",
+        "network_analysis/crn_theory.md",
+        "network_analysis/network_properties.md"
+    ],
     "Steady state analysis" => Any[
         "steady_state_functionality/homotopy_continuation.md",
         "steady_state_functionality/nonlinear_solve.md",
@@ -69,6 +73,9 @@ pages = Any[
         "spatial_modelling/spatial_jump_simulations.md"
     ],
     "FAQs" => "faqs.md",
-    "API" => "api.md",
+    "API" => Any[
+                 "api/core_api.md",
+                 "api/network_analysis_api.md"
+                ],
     "Developer Documentation" => "devdocs/dev_guide.md"
 ]

docs/src/api.md renamed to 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 allow one to supply additional information to a [`ReactionSystem`](@ref) created with 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.
@@ -100,7 +100,6 @@ of all options currently available.
 - [`continuous_events`](@ref constraint_equations_events): Allows the creation of continuous events.
 - [`discrete_events`](@ref constraint_equations_events): Allows the creation of discrete events.
 - [`combinatoric_ratelaws`](@ref faq_combinatoric_ratelaws): Takes a single option (`true` or `false`), which sets whether to use combinatorial rate laws.
-- [`require_declaration`](@ref dsl_advanced_options_require_dec): Turns off all inference of parameters, species, variables, the default differential, and observables (requiring these to be explicitly declared using e.g. `@species`).
 
 ## [ModelingToolkit and Catalyst accessor functions](@id api_accessor_functions)
 A [`ReactionSystem`](@ref) is an instance of a
@@ -124,8 +123,7 @@ direct access to the corresponding internal fields of the `ReactionSystem`)
   entries in `get_species(rn)` correspond to the first `length(get_species(rn))`
   components in `get_unknowns(rn)`.
 * `ModelingToolkit.get_ps(rn)` is a vector that collects all the parameters
-  defined *within* reactions in `rn`. This includes initialisation parameters (which
-  are added to the system by ModelingToolkit, and not the user).
+  defined *within* reactions in `rn`.
 * `ModelingToolkit.get_eqs(rn)` is a vector that collects all the
   [`Reaction`](@ref)s and `Symbolics.Equation` defined within `rn`, ordering all
   `Reaction`s before `Equation`s.
@@ -240,32 +238,6 @@ ModelingToolkit.compose
 Catalyst.flatten
 ```
 
-## Network analysis and representations
-Note, currently API functions for network analysis and conservation law analysis
-do not work with constant species (currently only generated by SBMLToolkit).
-
-```@docs
-conservationlaws
-conservedquantities
-conservedequations
-conservationlaw_constants
-ReactionComplexElement
-ReactionComplex
-reactioncomplexmap
-reactioncomplexes
-incidencemat
-complexstoichmat
-complexoutgoingmat
-incidencematgraph
-linkageclasses
-deficiency
-subnetworks
-linkagedeficiencies
-isreversible
-isweaklyreversible
-reset_networkproperties!
-```
-
 ## Network comparison
 ```@docs
 ==(rn1::Reaction, rn2::Reaction)

docs/src/api/network_analysis_api.md

@@ -0,0 +1,42 @@
+# [Network analysis and representations](@id api_network_analysis)
+```@meta
+CurrentModule = Catalyst
+```
+
+Note, currently API functions for network analysis and conservation law analysis
+do not work with constant species (which are generated by SBML, and can be [declared
+in Catalyst as well](@ref dsl_advanced_options_constant_species).
+
+For more information about these functions, please see the sections of the docs on
+[network ODE representation](@ref network_analysis_odes) and [chemical reaction network theory](@ref network_analysis_structural_aspects).
+
+```@docs
+conservationlaws
+conservedquantities
+conservedequations
+conservationlaw_constants
+ReactionComplexElement
+ReactionComplex
+reactioncomplexmap
+reactioncomplexes
+incidencemat
+incidencematgraph
+complexstoichmat
+complexoutgoingmat
+fluxmat
+adjacencymat
+laplacianmat
+massactionvector
+linkageclasses
+deficiency
+linkagedeficiencies
+satisfiesdeficiencyone
+satisfiesdeficiencyzero
+subnetworks
+isreversible
+isweaklyreversible
+iscomplexbalanced
+isdetailedbalanced
+robustspecies
+reset_networkproperties!
+```

docs/src/index.md

@@ -23,7 +23,7 @@ etc).
 - The [Catalyst.jl API](@ref api) provides functionality for building networks programmatically and for composing multiple networks together.
 - 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 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 network_analysis) permits the computation of linkage classes, deficiencies, reversibility, and other network properties.
+- A [network analysis suite](@ref network_analysis_structural_aspects) permits the computation of linkage classes, deficiencies, reversibility, and other network properties.
 - [Conservation laws can be detected and utilized](@ref conservation_laws) 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 constraint_equations_coupling_constraints) (which are then incorporated during conversion to ODEs, SDEs, and steady state equations).
 - Models can be [coupled with events](@ref constraint_equations_events) that affect the system and its state during simulations.