WIP: beginning to refactor network analysis docs #1142

vyudu · 2024-12-02T19:07:18Z

Probably worth discussing more but my thought here is to make Network Analysis its own section of the Catalyst docs, with subsections for the ODE decompositions, structural properties and chemical reaction network theory, and a third section for advanced stuff that links to CatalystNetworkAnalysis.

Added sections for the new API functions in #1134 and building symbolic functions from the ODEs to the ODE docs. Added a section on complex/detailed balance to the CRNT docs.

Need to: add a section on the deficiency one theorem, bring in the CatalystNetworkAnalysis docs, add code examples to the complex/detailed balance section (including stuff about the precision limitations of isdetailedbalanced)

isaacsas · 2024-12-20T17:01:04Z

Having network analysis be its own section is fine. LMK when you feel this is ready to review.

docs/src/network_analysis/advanced_analysis.md

docs/src/network_analysis/odes.md

docs/src/network_analysis/crnt.md

TorkelE · 2025-04-02T21:46:41Z

docs/src/api/core_api.md

 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.
+- [`parameters`]:(@ref dsl_advanced_options_declaring_species_and_parameters) Allows the designation of a set of symbols as system parameter.


these two changes seems wrong?

TorkelE · 2025-04-02T21:48:57Z

docs/src/api/network_analysis_api.md

+```
+
+Note, currently API functions for network analysis and conservation law analysis
+do not work with constant species (currently only generated by SBMLToolkit).


We allow the definition of constant species in Catalyst (https://docs.sciml.ai/Catalyst/stable/model_creation/dsl_advanced/#dsl_advanced_options_constant_species)?

Also, maybe say SBML generally (I think currently SBMLImporters is the more reliable SBML importer. I think i both covers more cases and also handles jump systems a lot better)

TorkelE · 2025-04-02T21:49:38Z

docs/src/api/network_analysis_api.md

+isdetailedbalanced
+robustspecies
+reset_networkproperties!
+```


Might be useful (for some, although personally I do not use API that way really) to split into sections? Only if there actually is an easy split that makes sense.

TorkelE · 2025-04-02T21:52:18Z

docs/src/network_analysis/network_properties.md

+in `rn` a variety of information. For example the first call to
+```julia
+rcs,B = reactioncomplexes(rn)
+```


Could this be made dynamic by creating a simple rn model and then applying these on it? The output doesn't;t really matter, so can add nothing # hide at the end of each block.

TorkelE · 2025-04-02T21:52:57Z

docs/src/network_analysis/odes.md

+Network Theory*[^1] for more discussion about the concepts on this page.
+
+Note, currently API functions for network analysis and conservation law analysis
+do not work with constant species (currently only generated by SBMLToolkit).


same as previous comment

TorkelE · 2025-04-02T21:54:17Z

docs/src/network_analysis/odes.md

+       μ, P₃ --> ∅
+end
+```
+In the [Introduction to Catalyst](@ref introduction_to_catalyst)


Since when we initially wrote this, we have a dedicated tutorial and section for this kind of visualisation: https://docs.sciml.ai/Catalyst/stable/model_creation/model_visualisation/#visualisation_graphs. Might make sense to link that directly instead?

(admitedly that repressilator is implemented using a slightly simplified network)

TorkelE · 2025-04-02T21:56:26Z

docs/src/network_analysis/odes.md

+![Repressilator solution](../assets/repressilator.svg)
+
+We also showed in the [Introduction to Catalyst](@ref introduction_to_catalyst) tutorial that
+the reaction rate equation ODE model for the repressilator is


first mention of the RRE, maybe change this to "reaction rate equation (RRE)" and use rre later on?

TorkelE · 2025-04-02T21:58:20Z

docs/src/network_analysis/odes.md

+```@example s1
+rn = @reaction_network begin
+ k, 2*A + 3*B --> A + 2*C + D
+ b, C + D --> 2*A + 3*B


Think, generally, we have used k, 2A + 3B --> A + 2C + D (no *) across the docs. But feel free to use your preferred notation.

TorkelE · 2025-04-02T22:01:31Z

docs/src/network_analysis/odes.md

+```
+
+Note that we have used `isequal` instead of `==` here because `laplacianmat`
+returns a `Matrix{Num}`, since some of its entries are symbolic rate constants.


I might add a parenthesis or something here explaining that == does not work for symbolic variables (i.e. Nums). Don't think this is common knowledge to many new-to intermediate users.

TorkelE · 2025-04-02T22:03:24Z

docs/src/network_analysis/odes.md

+laplacianmat(rn, parammap)
+```
+
+# Symbolic ODE functions


I think so far (not sure by chance or planning, but I stick to it these days) we only use # Title for the first header of each doc page. Then subsequent ones uses ## Sub heading and ### Subsub heading and such.

TorkelE · 2025-04-02T22:07:06Z

src/dsl.jl

@@ -681,10 +681,12 @@ end
 # Reads the variables options. Outputs a list of the variables inferred from the equations,
 # as well as the equation vector. If the default differential was used, update the `diffsexpr`
 # expression so that this declares this as well.
-function read_equations_option!(diffsexpr, options, syms_unavailable, tiv; requiredec = false)
+function read_equations_option!(
+        diffsexpr, options, syms_unavailable, tiv; requiredec = false)


I'd probably make the line break after tiv;, if possible.

TorkelE · 2025-04-02T22:07:24Z

src/dsl.jl

@@ -739,7 +741,8 @@ end
 # Reads the observables options. Outputs an expression for creating the observable variables,
 # a vector containing the observable equations, and a list of all observable symbols (this
 # list contains both those declared separately or inferred from the `@observables` option` input`).
-function read_observables_option(options, all_ivs, us_declared, all_syms; requiredec = false)
+function read_observables_option(
+        options, all_ivs, us_declared, all_syms; requiredec = false)


I'd probably make the line break after all_syms;, if possible.

TorkelE · 2025-04-02T22:09:32Z

src/reactionsystem.jl

@@ -1461,7 +1472,8 @@ Notes:
 - Returns a new `ReactionSystem` and does not modify `rs`.
 - By default, the new `ReactionSystem` will have the same name as `sys`.
 """
-function ModelingToolkit.compose(sys::ReactionSystem, systems::AbstractArray; name = nameof(sys))
+function ModelingToolkit.compose(
+        sys::ReactionSystem, systems::AbstractArray; name = nameof(sys))


I'd probably put the line break after systems::AbstractArray;, if possible.

TorkelE · 2025-04-02T22:13:33Z

docs/src/network_analysis/crn_theory.md

@@ -0,0 +1,332 @@
+> Note, currently API functions for network analysis and conservation law analysis
+> do not work with constant species (currently only generated by SBMLToolkit).


I'd probably remove this one, doesn't feel like something we need everywhere, given the niche ness of the situation.

If it is something that can yield a silent error, it might make sense to add it as a warning later on. Howeverstarting the tutorial with a note about something that most users won't know about or encounter seems irrelevant. And if it is restricted to SBMLToolkit the warning might be better there.

TorkelE · 2025-04-02T22:16:10Z

docs/src/network_analysis/crn_theory.md

+
+Broadly, results from chemical reaction network theory relate a purely
+graph-structural property (e.g. deficiency) to dynamical properties of the reaction system
+(e.g. complex balance). The relevant graph here is the one corresponding to the [reaction complex representation](@ref network_analysis_reaction_complexes)


Here I'd make the deficiency and complex balance links to corresponding sections (if nothing else to mark that these are terms we do not necessarily expect the reader to know at this stage).

TorkelE · 2025-04-02T22:17:54Z

docs/src/network_analysis/crn_theory.md

+
+## [Deficiency of the network](@id network_analysis_structural_aspects_deficiency)
+A famous theorem in Chemical Reaction Network Theory, the Deficiency Zero
+Theorem [^1], allows us to use knowledge of the net stoichiometry matrix and the


No space in Theorem [^1]

I.e. Theorem[^1]

TorkelE · 2025-04-02T22:18:02Z

docs/src/network_analysis/crn_theory.md

+calculate a network's deficiency.
+
+The rank, ``r``, of a reaction network is defined as the dimension of the
+subspace spanned by the net stoichiometry vectors of the reaction-network [^1],


No space in Theorem [^1]

TorkelE · 2025-04-02T22:21:38Z

docs/src/network_analysis/crn_theory.md

+
+For the set of reactions $A \to B, B \to A, B \to C$, $\{A, B, C\}$ is a linkage class, and $\{A, B\}$ is a strong linkage class (since A is reachable from B and vice versa). However, $\{A, B\}$ is not a terminal linkage class, because the reaction $B \to C$ goes to a complex outside the linkage class. 
+
+If these conditions are met, then the network will have at most one steady state in each stoichiometric compatibility class for any choice of rate constants and parameters.


no line break

TorkelE · 2025-04-02T22:25:40Z

docs/pages.jl

+        "network_analysis/odes.md",
+        "network_analysis/crn_theory.md",
+        "network_analysis/network_properties.md",
+        "network_analysis/advanced_analysis.md"


Thinking about this order, having the ODE section first makes sense as it nicely feeds into the next one. On the other hand, most users will likely have more use of the subsequent sections, which makes it make sense to have that earlier.

Maybe keep it for now, and then as this gets more fleshed out we can make a "Introduction to Network" analysis section, which basically explains what this is all about, when it can be useful, and where to find the useful bits.
(i.e. a new user that know very little should likely first know about the network analysis summary function, and maybe be directed to know about conservation laws).

isaacsas · 2025-04-02T22:41:31Z

Can you remove the full repo format? We haven’t been using formatter due to the bugs it introduced in one release last year. While I’m fine with re-enabling it that should really be in a separate PR so we can check nothing is getting broken. (Feel free to run it on the files you are actually editing here though.)

vyudu marked this pull request as ready for review February 5, 2025 02:43

TorkelE reviewed Feb 6, 2025

View reviewed changes

docs/src/network_analysis/advanced_analysis.md Show resolved Hide resolved

TorkelE reviewed Feb 6, 2025

View reviewed changes

docs/src/network_analysis/odes.md Show resolved Hide resolved

TorkelE reviewed Feb 6, 2025

View reviewed changes

docs/src/network_analysis/crnt.md Outdated Show resolved Hide resolved

vyudu mentioned this pull request Mar 27, 2025

Catalyst V15 TODO version 2 #1202

Open

7 tasks

vyudu added 24 commits April 2, 2025 15:08

init

a0d3ccd

up

c8bd84b

up

9bb2711

up

ef6465a

Up

28dbab1

add API functions

53c84f2

up

c7daa43

up

ce09a85

init multidocumenter

9d3c1c5

up

b7e351b

up

307ab34

up

8e80c3d

fix references

6d20af8

load Catalyst

b108f6d

fix

1cfcfd0

up

7aac9f6

up

1296311

up

e0f8ec8

change pages

3dc7820

up

b6bf3e6

up

7942665

fix docstrings and docs

699bdbb

fix file name

e37343e

fix blocks

0e07475

vyudu added 3 commits April 2, 2025 15:13

docs: remove MultiDocumenter for now

69f147c

format

50ec948

fix laplacianmat docstring

3f8b036

vyudu force-pushed the sfr-docs branch from af5737c to 3f8b036 Compare April 2, 2025 19:18

TorkelE reviewed Apr 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: beginning to refactor network analysis docs #1142

WIP: beginning to refactor network analysis docs #1142

vyudu commented Dec 2, 2024 •

edited

Loading

isaacsas commented Dec 20, 2024

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

TorkelE Apr 2, 2025

isaacsas commented Apr 2, 2025

		@@ -0,0 +1,332 @@
		> Note, currently API functions for network analysis and conservation law analysis
		> do not work with constant species (currently only generated by SBMLToolkit).


		For the set of reactions $A \to B, B \to A, B \to C$, $\{A, B, C\}$ is a linkage class, and $\{A, B\}$ is a strong linkage class (since A is reachable from B and vice versa). However, $\{A, B\}$ is not a terminal linkage class, because the reaction $B \to C$ goes to a complex outside the linkage class.

		If these conditions are met, then the network will have at most one steady state in each stoichiometric compatibility class for any choice of rate constants and parameters.

WIP: beginning to refactor network analysis docs #1142

Are you sure you want to change the base?

WIP: beginning to refactor network analysis docs #1142

Conversation

vyudu commented Dec 2, 2024 • edited Loading

isaacsas commented Dec 20, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

isaacsas commented Apr 2, 2025

vyudu commented Dec 2, 2024 •

edited

Loading