From b1e601bcee4ab786aace4c3584b83f5e7181c04c Mon Sep 17 00:00:00 2001
From: Torkel Loman <torkel.loman@gmail.com>
Date: Sun, 17 Nov 2024 14:43:23 +0000
Subject: [PATCH] init

---
 .../math_models_intro.md                      |  2 +-
 docs/src/model_creation/dsl_advanced.md       | 34 +++++++++++++++++++
 docs/src/model_creation/dsl_basics.md         |  2 +-
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/docs/src/introduction_to_catalyst/math_models_intro.md b/docs/src/introduction_to_catalyst/math_models_intro.md
index 0a2647a799..59a619a5f5 100644
--- a/docs/src/introduction_to_catalyst/math_models_intro.md
+++ b/docs/src/introduction_to_catalyst/math_models_intro.md
@@ -73,7 +73,7 @@ while the jump process propensity function is
 a(\mathbf{X}(t)) = k A (A-1) B.
 ```
 
-## Reaction Rate Equation (RRE) ODE Models
+## [Reaction Rate Equation (RRE) ODE Models](@id math_models_in_catalyst_rre_odes)
 The RRE ODE models Catalyst creates for a general system correspond to the coupled system of ODEs given by
 ```math
 \frac{d X_m}{dt} =\sum_{k=1}^K \nu_m^k a_k(\mathbf{X}(t),t), \quad m = 1,\dots,M.
diff --git a/docs/src/model_creation/dsl_advanced.md b/docs/src/model_creation/dsl_advanced.md
index ce4cb43f7f..31f92732f2 100644
--- a/docs/src/model_creation/dsl_advanced.md
+++ b/docs/src/model_creation/dsl_advanced.md
@@ -540,3 +540,37 @@ nothing # hide
 
 !!! note
     When using interpolation, expressions like `2$spec` won't work; the multiplication symbol must be explicitly included like `2*$spec`.
+
+## [Disabling mass action for reactions](@id dsl_advanced_options_disable_ma)
+
+As [described previously](@ref math_models_in_catalyst_rre_odes), Catalyst uses *mass action kinetics* to generate ODEs from reactions. Here, each reaction generates a term for each of its reactants, which consists of the reaction's rate, substrates, and the reactant's stoichiometry. E.g. the following reaction:
+```@example dsl_advanced_disable_ma
+using Catalyst # hide
+rn = @reaction_network begin
+  k, X --> ∅
+end
+```
+generates a single term $-k*[X]$:
+```@example dsl_advanced_disable_ma
+using Latexify
+latexify(rn; form = :ode)
+```
+
+It is possible to remove the substrate contribution by using any of the following non-filled arrows when declaring the reaction: `<=`, `⇐`, `⟽`, `=>`, `⇒`, `⟾`, `⇔`, `⟺`. This means that the reaction
+```@example faq7
+rn = @reaction_network begin
+  k, X => ∅
+end
+latexify(rn; form = :ode)
+```
+will occur at rate $d[X]/dt = -k$ (which might become a problem since $[X]$ will be degraded at a constant rate even when very small or equal to 0). This functionality allows the user to fully customise the ODEs generated by their models. 
+
+Note, stoichiometric coefficients are still included, i.e. the reaction
+```@example faq7
+rn = @reaction_network begin
+  k, 2*X ⇒ ∅
+end
+latexify(rn; form = :ode)
+```
+has rate $d[X]/dt = -2 k$.
+
diff --git a/docs/src/model_creation/dsl_basics.md b/docs/src/model_creation/dsl_basics.md
index 409e3b1f95..b1b5e6d889 100644
--- a/docs/src/model_creation/dsl_basics.md
+++ b/docs/src/model_creation/dsl_basics.md
@@ -373,4 +373,4 @@ It should be noted that the following symbols are *not permitted* to be used as
 - `∅` ([used for production/degradation reactions](@ref dsl_description_symbols_empty_set)).
 - `im` (used in Julia to represent [complex numbers](https://docs.julialang.org/en/v1/manual/complex-and-rational-numbers/#Complex-Numbers)).
 - `nothing` (used in Julia to denote [nothing](https://docs.julialang.org/en/v1/base/constants/#Core.nothing)).
-- `Γ` (used by Catalyst to represent conserved quantities).
+- `Γ` (used by Catalyst to represent [conserved quantities](@ref constraint_equations)).