init

Author: TorkelE

README.md

@@ -137,9 +137,9 @@ model. Here we instead show how various Catalyst features can compose to create
 a much more advanced model. Our model describes how the volume of a cell ($V$)
 is affected by a growth factor ($G$). The growth factor only promotes growth
 while in its phosphorylated form ($G^P$). The phosphorylation of $G$ ($G \to G^P$)
-is promoted by sunlight (modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$),
-which phosphorylates the growth factor (producing $G^P$). When the cell reaches a
-critical volume ($V_m$) it undergoes cell division. First, we declare our model:
+is promoted by sunlight, which is modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$. 
+When the cell reaches a critical volume ($V_m$) it undergoes cell division. First, we 
+declare our model:
 ```julia
 using Catalyst
 cell_model = @reaction_network begin

docs/src/devdocs/dev_guide.md

@@ -4,7 +4,7 @@
 Beginning with v15, Catalyst is using a new release process to try to ensure
 continuing stability of releases. Before making a release one should
 
-1. Create a new release branch, i.e. "release-15.0.0"
+1. Create a new release branch, i.e. "release-15.0.0".
 2. On this branch, cap major dependencies to their latest version that works and
    for which tests pass.
    - Caps need to be included in both Project.toml and docs/Project.toml.
@@ -16,13 +16,13 @@ continuing stability of releases. Before making a release one should
    issues can arise that do not lead to actual errors in the doc CI).
 4. Release via the [registration
    issue](https://github.com/SciML/Catalyst.jl/issues/127) with the
-   command:
+   command:  
 
-    ```
-    @JuliaRegistrator register branch=release-15.0.0
-    ```
+   ```
+   @JuliaRegistrator register branch=release-15.0.0
+   ```
 
-    modifying as appropriate for the version you are releasing.
+   modifying as appropriate for the version you are releasing.
 
 If there is subsequently a need to increment the version of a dependency, this
 should be done via a new release that follows the above process, and modifies
@@ -38,7 +38,9 @@ Catalyst release branch*.
 
 ### Checking doc builds for errors
 When updating documentation, Catalyst will run any Julia code provided within example blocks to dynamically create figures and outputs. In addition to automatically creating these for us, it also provides an automatic check that all code in documentation is correct. Here, if any of the documentation code throws an error, the build job will fail. The documentation build job can be found at the bottom of a PRs conversation, here is an example of a failed one:
+
 ![Failed builddocs link](../assets/devdocs/failed_builddocs_link.png)
+
 To check what errors were produced, click on the "Details" link of the job. Next, any errors can be found at the bottom of the "Build and deploy" section (which should be opened automatically).
 
 ### Inspecting documentation of a PR or branch

docs/src/index.md

@@ -164,9 +164,9 @@ model. Here we instead show how various Catalyst features can compose to create
 a much more advanced model. Our model describes how the volume of a cell ($V$)
 is affected by a growth factor ($G$). The growth factor only promotes growth
 while in its phosphorylated form ($G^P$). The phosphorylation of $G$ ($G \to G^P$)
-is promoted by sunlight (modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$),
-which phosphorylates the growth factor (producing $G^P$). When the cell reaches a
-critical volume ($V_m$) it undergoes cell division. First, we declare our model:
+is promoted by sunlight, which is modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$.
+When the cell reaches a critical volume ($V_m$) it undergoes cell division. First, we 
+declare our model:
 ```@example home_elaborate_example
 using Catalyst
 cell_model = @reaction_network begin

docs/src/model_creation/dsl_basics.md

@@ -39,15 +39,15 @@ Finally, `rn = ` is used to store the model in the variable `rn` (a normal Julia
 ## [Defining parameters and species in the DSL](@id dsl_description_parameters_basics)
 Typically, the rates are not constants, but rather parameters (which values can be set e.g. at [the beginning of each simulation](@ref simulation_intro_ODEs)). To set parametric rates, simply use whichever symbol you wish to represent your parameter with. E.g. to set the above rates to `a` and `b`, we use:
 ```@example dsl_basics
-rn1 = @reaction_network begin
+rn = @reaction_network begin
     a, X --> Y
     b, Y --> X
 end
 ```
 
 Here we have used single-character symbols to designate all species and parameters. Multi-character symbols, however, are also permitted. E.g. we could call the rates `kX` and `kY`:
 ```@example dsl_basics
-rn1 = @reaction_network begin
+rn = @reaction_network begin
     kX, X --> Y
     kY, Y --> X
 end
@@ -59,22 +59,22 @@ Generally, anything that is a [permitted Julia variable name](https://docs.julia
 ### [Reactions with multiple substrates or products](@id dsl_description_reactions_multiples)
 Previously, our reactions have had a single substrate and a single product. However, reactions with multiple substrates and/or products are possible. Here, all the substrates (or products) are listed and separated by a `+`. E.g. to create a model where `X` and `Y` bind (at rate `kB`) to form `XY` (which then can dissociate, at rate `kD`, to form `XY`) we use:
 ```@example dsl_basics
-rn2 = @reaction_network begin
+rn = @reaction_network begin
     kB, X + Y --> XY
     kD, XY --> X + Y
 end
 ```
 Reactions can have any number of substrates and products, and their names do not need to have any relationship to each other, as demonstrated by the following mock model:
 ```@example dsl_basics
-rn3 = @reaction_network begin
+rn = @reaction_network begin
     k, X + Y + Z --> A + B + C + D
 end
 ```
 
 ### [Reactions with degradation or production](@id dsl_description_reactions_degradation_and_production)
 Some reactions have no products, in which case the substrate(s) are degraded (i.e. removed from the system). To denote this, set the reaction's right-hand side to `0`. Similarly, some reactions have no substrates, in which case the product(s) are produced (i.e. added to the system). This is denoted by setting the left-hand side to `0`. E.g. to create a model where a single species `X` is both created (in the first reaction) and degraded (in a second reaction), we use:
 ```@example dsl_basics
-rn4 = @reaction_network begin
+rn = @reaction_network begin
     p, 0 --> X
     d, X --> 0
 end
@@ -83,7 +83,7 @@ end
 ### [Reactions with non-unitary stoichiometries](@id dsl_description_reactions_stoichiometries)
 Reactions may include multiple copies of the same reactant (i.e. a substrate or a product). To specify this, the reactant is preceded by a number indicating its number of copies (also called the reactant's *stoichiometry*). E.g. to create a model where two copies of `X` dimerise to form `X2` (which then dissociate back to two `X` copies) we use:
 ```@example dsl_basics
-rn5 = @reaction_network begin
+rn = @reaction_network begin
     kB, 2X --> X2
     kD, X2 --> 2X
 end
@@ -92,7 +92,7 @@ Reactants whose stoichiometries are not defined are assumed to have stoichiometr
 
 Stoichiometries can be combined with `()` to define them for multiple reactants. Here, the following (mock) model declares the same reaction twice, both with and without this notation:
 ```@example dsl_basics
-rn6 = @reaction_network begin
+rn = @reaction_network begin
     k, 2X + 3(Y + 2Z) --> 5(V + W)
     k, 2X + 3Y + 6Z --> 5V + 5W
 end
@@ -103,28 +103,28 @@ end
 ### [Bi-directional (or reversible) reactions](@id dsl_description_reaction_bundling_reversible)
 As is the case for the following two-state model:
 ```@example dsl_basics
-rn7 = @reaction_network begin
+rn_bidir = @reaction_network begin
     k1, X1 --> X2
     k2, X2 --> X1
 end
 ```
 it is common that reactions occur in both directions (so-called *bi-directional* reactions). Here, it is possible to bundle the reactions into a single line by using the `<-->` arrow. When we do this, the rate term must include two separate rates (one for each direction, these are enclosed by a `()` and separated by a `,`). I.e. the two-state model can be declared using:
 ```@example dsl_basics
-rn7 = @reaction_network begin
+rn_bidir = @reaction_network begin
     (k1,k2), X1 <--> X2
 end
 ```
 Here, the first rate (`k1`) denotes the *forward rate* and the second rate (`k2`) the *backwards rate*.
 
 Catalyst also permits writing pure backwards reactions. These use identical syntax to forward reactions, but with the `<--` arrow:
 ```@example dsl_basics
-rn8 = @reaction_network begin
+rn_ytox = @reaction_network begin
     k, X <-- Y
 end
 ```
 Here, the substrate(s) are on the right-hand side and the product(s) are on the left-hand side. Hence, the above model can be written identically using:
 ```@example dsl_basics
-rn8 = @reaction_network begin
+rn_ytox = @reaction_network begin
     k, Y --> X
 end
 ```
@@ -133,56 +133,56 @@ Generally, using forward reactions is clearer than backwards ones, with the latt
 ### [Bundling similar reactions on a single line](@id dsl_description_reaction_bundling_similar)
 There exist additional situations where models contain similar reactions (e.g. systems where all system components degrade at identical rates). Reactions which share either rates, substrates, or products can be bundled into a single line. Here, the parts which are different for the reactions are written using `(,)` (containing one separate expression for each reaction). E.g., let us consider the following model where species `X` and `Y` both degrade at the rate `d`:
 ```@example dsl_basics
-rn8 = @reaction_network begin
+rn_deg = @reaction_network begin
     d, X --> 0
     d, Y --> 0
 end
 ```
 These share both their rates (`d`) and products (`0`), however, the substrates are different (`X` and `Y`). Hence, the reactions can be bundled into a single line using the common rate and product expression while providing separate substrate expressions:
 ```@example dsl_basics
-rn8 = @reaction_network begin
+rn_deg = @reaction_network begin
     d, (X,Y) --> 0
 end
 ```
 This declaration of the model is identical to the previous one. Reactions can share any subset of the rate, substrate, and product expression (the cases where they share all or none, however, do not make sense to use). I.e. if the two reactions also have different degradation rates:
 ```@example dsl_basics
-rn9 = @reaction_network begin
+rn_deg2 = @reaction_network begin
     dX, X --> 0
     dY, Y --> 0
 end
 ```
 This can be represented using:
 ```@example dsl_basics
-rn9 = @reaction_network begin
+rn_deg2 = @reaction_network begin
     (dX,dY), (X,Y) --> 0
 end
 ```
 
 It is possible to use bundling for any number of reactions. E.g. in the following model we bundle the conversion of a species $X$ between its various forms (where all reactions use the same rate $k$):
 ```@example dsl_basics
-rn10 = @reaction_network begin
+rn = @reaction_network begin
     k, (X0,X1,X2,X3) --> (X1,X2,X3,X4)
 end
 ```
 
 It is possible to combine bundling with bi-directional reactions. In this case, the rate is first split into the forward and backwards rates. These may then (or may not) indicate several rates. We exemplify this using the two following two (identical) networks, created with and without bundling.
 ```@example dsl_basics
-rn11 = @reaction_network begin
+rn_sp = @reaction_network begin
     kf, S --> P1
     kf, S --> P2
     kb_1, P1 --> S
     kb_2, P2 --> S
 end
 ```
 ```@example dsl_basics
-rn11 = @reaction_network begin
+rn_sp = @reaction_network begin
     (kf, (kb_1, kb_2)), S <--> (P1,P2)
 end
 ```
 
 Like when we designated stoichiometries, reaction bundling can be applied very generally to create some truly complicated reactions:
 ```@example dsl_basics
-rn12 = @reaction_network begin
+rn = @reaction_network begin
     ((pX, pY, pZ),d), (0, Y0, Z0) <--> (X, Y, Z1+Z2)
 end
 ```
@@ -193,38 +193,38 @@ So far we have assumed that all reaction rates are constant (being either a numb
 
 Let us consider a model with an activator (`A`, which degraded at a constant rate) and a protein (`P`). The production rate of `P` depends both on `A` and a parameter (`kP`). We model this through:
 ```@example dsl_basics
-rn_13 = @reaction_network begin
+rn_ap = @reaction_network begin
     d, A --> 0
     kP*A, 0 --> P
 end
 ```
 Here, `P`'s production rate will be reduced as `A` decays. We can [print the ODE this model produces with `Latexify`](@ref visualisation_latex):
 ```@example dsl_basics
 using Latexify
-latexify(rn_13; form = :ode)
+latexify(rn_ap; form = :ode)
 ```
 
 In this case, we can generate an equivalent model by instead adding `A` as both a substrate and a product to `P`'s production reaction:
 ```@example dsl_basics
-rn_13_alt = @reaction_network begin
+rn_ap_alt = @reaction_network begin
     d, A --> 0
     kp, A --> A + P
 end
 ```
 We can confirm that this generates the same ODE:
 ```@example dsl_basics
-latexify(rn_13_alt; form = :ode)
+latexify(rn_ap_alt; form = :ode)
 ```
 Here, while these models will generate identical ODE, SDE, and jump simulations, the chemical reaction network models themselves are not equivalent. Generally, as pointed out in the two notes below, using the second form is preferable.
 !!! warning
-    While `rn_13` and `rn_13_alt` will generate equivalent simulations, for jump simulations, the first model will have reduced performance as it generates a less performant representation of the system in JumpProcesses. It is generally recommended to write pure mass action reactions such that there is just a single constant within the rate constant expression for optimal performance of jump process simulations.
+    While `rn_ap` and `rn_ap_alt` will generate equivalent simulations, for jump simulations, the first model will have reduced performance as it generates a less performant representation of the system in JumpProcesses. It is generally recommended to write pure mass action reactions such that there is just a single constant within the rate constant expression for optimal performance of jump process simulations.
 
 !!! danger
     Catalyst automatically infers whether quantities appearing in the DSL are species or parameters (as described [here](@ref dsl_advanced_options_declaring_species_and_parameters)). Generally, anything that does not appear as a reactant is inferred to be a parameter. This means that if you want to model a reaction activated by a species (e.g. `kp*A, 0 --> P`), but that species does not occur as a reactant, it will be interpreted as a parameter. This can be handled by [manually declaring the system species](@ref dsl_advanced_options_declaring_species_and_parameters).
 
 Above we used a simple example where the rate was the product of a species and a parameter. However, any valid Julia expression of parameters, species, and values can be used. E.g the following is a valid model:
 ```@example dsl_basics
-rn_14 = @reaction_network begin
+rn = @reaction_network begin
     2.0 + X^2, 0 --> X + Y
     k1 + k2^k3, X --> ∅
     pi * X/(sqrt(2) + Y), Y → ∅
@@ -234,15 +234,15 @@ end
 ### [Using functions in rates](@id dsl_description_nonconstant_rates_functions)
 It is possible for the rate to contain Julia functions. These can either be functions from Julia's standard library:
 ```@example dsl_basics
-rn_16 = @reaction_network begin
+rn = @reaction_network begin
     d, A --> 0
     kp*sqrt(A), 0 --> P
 end
 ```
 or ones defined by the user:
 ```@example dsl_basics
 custom_function(p1, p2, X) = (p1 + X) / (p2 + X)
-rn_17 = @reaction_network begin
+rn = @reaction_network begin
     d, A --> 0
     custom_function(k1,k2,E), 0 --> P
 end
@@ -251,7 +251,7 @@ end
 ### [Pre-defined functions](@id dsl_description_nonconstant_rates_available_functions)
 Two functions frequently used within systems biology are the [*Michaelis-Menten*](https://en.wikipedia.org/wiki/Michaelis%E2%80%93Menten_kinetics) and [*Hill*](https://en.wikipedia.org/wiki/Hill_equation_(biochemistry)) functions. These are pre-defined in Catalyst and can be called using `mm(X,v,K)` and `hill(X,v,K,n)`. E.g. a self-activation loop where `X` activates its own production through a Hill function can be created using:
 ```@example dsl_basics
-rn_18 = @reaction_network begin
+rn = @reaction_network begin
     hill(X,v,K,n), 0 --> P
     d, X --> 0
 end
@@ -267,15 +267,15 @@ Catalyst comes with the following predefined functions:
 ### [Time-dependant rates](@id dsl_description_nonconstant_rates_time)
 Previously we have assumed that the rates are independent of the time variable, $t$. However, time-dependent reactions are also possible. Here, simply use `t` to represent the time variable. E.g., to create a production/degradation model where the production rate decays as time progresses, we can use:
 ```@example dsl_basics
-rn_14 = @reaction_network begin
+rn = @reaction_network begin
     kp/(1 + t), 0 --> P
     d, P --> 0
 end
 ```
 
 Like previously, `t` can be part of any valid expression. E.g. to create a reaction with a cyclic rate (e.g. to represent a [circadian system](https://en.wikipedia.org/wiki/Circadian_rhythm)) we can use:
 ```@example dsl_basics
-rn_15 = @reaction_network begin
+rn = @reaction_network begin
     A*(sin(2π*f*t - ϕ)+1)/2, 0 --> P
     d, P --> 0
 end
@@ -293,7 +293,7 @@ end
 ### [Non-integer stoichiometries](@id dsl_description_stoichiometries_decimal)
 Previously all stoichiometric constants have been integer numbers, however, decimal numbers are also permitted. Here we create a birth-death model where each production reaction produces 1.5 units of `X`:
 ```@example dsl_basics
-rn_16 = @reaction_network begin
+rn = @reaction_network begin
     p, 0 --> 1.5X
     d, X --> 0
 end
@@ -303,15 +303,15 @@ It is also possible to have non-integer stoichiometric coefficients for substrat
 ### [Parametric stoichiometries](@id dsl_description_stoichiometries_parameters)
 It is possible for stoichiometric coefficients to be parameters. E.g. here we create a generic polymerisation system where `n` copies of `X` bind to form `Xn`:
 ```@example dsl_basics
-rn_17 = @reaction_network begin
+rn = @reaction_network begin
     (kB,kD), n*X <--> Xn
 end
 ```
 Now we can designate the value of `n` through a parameter when we e.g. create an `ODEProblem`:
 ```@example dsl_basics
 u0 = [:X => 5.0, :Xn => 1.0]
 ps = [:kB => 1.0, :kD => 0.1, :n => 4]
-oprob = ODEProblem(rn_17, u0, (0.0, 1.0), ps)
+oprob = ODEProblem(rn, u0, (0.0, 1.0), ps)
 nothing # hide
 ```
 
@@ -321,7 +321,7 @@ Julia permits any Unicode characters to be used in variable names, thus Catalyst
 ### [Using ∅ in degradation/production reactions](@id dsl_description_symbols_empty_set)
 Previously, we described how `0` could be used to [create degradation or production reactions](@ref dsl_description_reactions_degradation_and_production). Catalyst permits the user to instead use the `∅` symbol. E.g. the production/degradation system can alternatively be written as:
 ```@example dsl_basics
-rn4 = @reaction_network begin
+rn_pd = @reaction_network begin
     p, ∅ --> X
     d, X --> ∅
 end
@@ -335,7 +335,7 @@ Catalyst uses `-->`, `<-->`, and `<--` to denote forward, bi-directional, and ba
 
 E.g. the production/degradation system can alternatively be written as:
 ```@example dsl_basics
-rn4 = @reaction_network begin
+rn_pd = @reaction_network begin
     p, ∅ → X
     d, X → ∅
 end
@@ -361,7 +361,7 @@ nothing # hide
 
 This functionality can also be used to create less serious models:
 ```@example dsl_basics
-rn_13 = @reaction_network begin
+rn = @reaction_network begin
     🍦, 😢 --> 😃
 end
 ```