init

Author: TorkelE

HISTORY.md

@@ -76,6 +76,21 @@
   functions (as a parameter) in a model. For more details on how to use these,
   please read:
   https://docs.sciml.ai/Catalyst/stable/model_creation/functional_parameters/.
+- We have introduced a restriction on bundling of reactions in the DSL. Now,
+  bundling is not permitted if multiple rates are provided but only one set each
+  of substrates/products. E.g. this model:
+ ```julia
+  @reaction_network begin
+    (k1,k2), X --> Y
+  end
+ ```
+  will now throw an error. The reason that users attempting to write bi-directional 
+  reactions but typing `-->` instead of `<-->` would get a wrong model. We decided that
+  this kind of bundling was unlikely to be used, and throwing errors for people who
+  made the typo was more important. 
+
+  If you use this type of bundling and it indeed is useful to you, please raise and issue
+  and we will see if we can sort something out.
 - Scoped species/variables/parameters are now treated similar to the latest MTK
   releases (≥ 9.49).
 - A tutorial on making interactive plot displays using Makie has been added.

docs/src/model_creation/dsl_basics.md

@@ -188,6 +188,15 @@ end
 ```
 However, like for the above model, bundling reactions too zealously can reduce (rather than improve) a model's readability.
 
+The one exception to reaction bundling is that we do not permit the user to provide multiple rates but only set one set each for the substrates and products. I.e.
+```julia
+rn = @reaction_network begin
+    (k1,k2), X --> Y
+end
+```
+is not permitted (due to this notation's similarity to a bidirectional reaction). However, if multiples are provided for substrates and/or products, like `(k1,k2), (X1,X2) --> Y`, then bundling works.
+
+
 ## [Non-constant reaction rates](@id dsl_description_nonconstant_rates)
 So far we have assumed that all reaction rates are constant (being either a number of a parameter). Non-constant rates that depend on one (or several) species are also possible. More generally, the rate can be any valid expression of parameters and species.
 

src/dsl.jl

@@ -365,6 +365,13 @@ function get_reactions(exprs::Vector{Expr})
         # Reads core reaction information.
         arrow, rate, reaction, metadata = read_reaction_line(line)
 
+        # Currently, reaction bundling where rates (but neither substrates nor products) are
+        # bundled, is disabled. See discussion in https://github.com/SciML/Catalyst.jl/issues/1219.
+        if !in(arrow, double_arrows) && Meta.isexpr(rate, :tuple) &&
+                !Meta.isexpr(reaction.args[2], :tuple) && !Meta.isexpr(reaction.args[3], :tuple)
+            error("Bundling of reactions with multiple rates but singular substrates and product sets is disallowed. This error is potentially due to a bidirectional (`<-->`) reaction being types as `-->`.")
+        end
+
         # Checks which type of line is used, and calls `push_reactions!` on the processed line.
         if in(arrow, double_arrows)
             (typeof(rate) != Expr || rate.head != :tuple) &&

test/dsl/dsl_basic_model_construction.jl

@@ -179,7 +179,7 @@ let
     different_arrow_8 = @reaction_network begin
         p, 2X1 < ∅
         k1, X2 ← X1
-        (k2, k3), X3 ⟻ X2
+        (k2, k3), X3 ⟻ (X2,X2)
         d, ∅ ↼ X3
     end
     push!(identical_networks_1, reaction_networks_standard[8] => different_arrow_8)
@@ -298,10 +298,11 @@ let
 
     no_parameters_10 = @reaction_network begin
         0.01, ∅ ⟶ X1
-        (3.1, 3.2), X1 → X2
-        (0.0, 2.1), X2 → X3
-        (901.0, 63.5), X3 → X4
-        (7, 8), X4 → X5
+        (3.1, 3.2), (X1,X1) → X2
+        (0.0, 2.1), X2 → (X3,X3)
+        (901.0, 63.5), (X3,X3) → (C4,X4)
+        7, X4 → X5
+        8, X4 → X5
         1.0, X5 ⟶ ∅
     end
     push!(identical_networks_3, reaction_networks_standard[10] => no_parameters_10)
@@ -591,3 +592,20 @@ let
         d, X ⇻ 0
     end
 end
+
+# Tests that bundling, but where the rate only have been given multiple alternatives, errors.
+# Checks for two, more than two, and for functional rates. Uses different arrow types and directions.
+let
+    @test_throws Exception @eval @reaction_network begin
+        (k1,k2), X --> 0
+    end
+    @test_throws Exception @eval @reaction_network begin
+        (k1,k2,k3), X → 0
+    end
+    @test_throws Exception @eval @reaction_network begin
+        (k1,k1), X => Y
+    end
+    @test_throws Exception @eval @reaction_network begin
+        (mm(X,v1,K1),mm(X,v2,K2)), 0 <-- 0
+    end
+end

test/test_networks.jl

@@ -64,7 +64,8 @@ end
 reaction_networks_standard[8] = @reaction_network rns8 begin
     p, ∅ → 2X1
     k1, X1 → X2
-    (k2, k3), X2 → X3
+    k2, X2 → X3
+    k3, X2 → X3
     d, X3 → ∅
 end
 
@@ -78,10 +79,10 @@ end
 
 reaction_networks_standard[10] = @reaction_network rns10 begin
     p, ∅ ⟶ X1
-    (k1, k2), X1 → X2
-    (k3, k4), X2 → X3
-    (k5, k6), X3 → X4
-    (k7, k8), X4 → X5
+    (k1, k2), (X1,X1) → X2
+    (k3, k4), (X2,X2) → X3
+    (k5, k6), (X3,X3) → X4
+    (k7, k8), (X4,X4) → X5
     d, X5 ⟶ ∅
 end