Merge pull request #1129 from vyudu/dsl-no-infer-docs

`@require_declaration` docs

Author: isaacsas

HISTORY.md

@@ -25,6 +25,22 @@
   StructuralIdentifiability has with Julia 1.10.5 and 1.11.
 - A tutorial on making interactive plot displays using Makie has been added.
 - The BifurcationKit extension has been updated to v.4.
+- There is a new DSL option `@require_declaration` that will turn off automatic inferring for species, parameters, and variables in the DSL. For example, the following will now error:
+  ```julia
+  rn = @reaction_network begin
+    @require_declaration
+    (k1, k2), A <--> B
+  end
+  ```
+  When this flag is set, all symbolics must be explicitly declared. 
+  ```julia
+  rn = @reaction_network begin
+    @species A(t) B(t)
+    @parameters k1 k2
+    @require_declaration
+    (k1, k2), A <--> B
+  end
+  ```
 
 ## Catalyst 14.4.1
 - Support for user-defined functions on the RHS when providing coupled equations 

docs/src/faqs.md

@@ -309,3 +309,16 @@ end
 In some cases, it may be necessary or desirable to register functions with
 Symbolics.jl before their use in Catalyst, see the discussion
 [here](https://symbolics.juliasymbolics.org/stable/manual/functions/).
+
+## How can I turn off automatic inferring of species and parameters when using the DSL?
+This option can be set using the `@require_declaration` option inside `@reaction_network`. In this case all the species, parameters, and variables in the system must be pre-declared using one of the `@species`, `@parameters`, or `@variables` macros. For more information about what is inferred automatically and not, please see the section on [`@require_declaration`](@ref dsl_advanced_options_require_dec).
+
+```@example faq9
+using Catalyst
+rn = @reaction_network begin
+    @require_declaration
+    @species A(t) B(t)
+    @parameters k1 k2
+    (k1, k2), A <--> B
+end
+```

docs/src/model_creation/dsl_advanced.md

@@ -205,7 +205,7 @@ ModelingToolkit.getdescription(two_state_system.kA)
 
 ### [Designating constant-valued/fixed species parameters](@id dsl_advanced_options_constant_species)
 
-Catalyst enables the designation of parameters as `constantspecies`. These parameters can be used as species in reactions, however, their values are not changed by the reaction and remain constant throughout the simulation (unless changed by e.g. the [occurrence of an event]@ref constraint_equations_events). Practically, this is done by setting the parameter's `isconstantspecies` metadata to `true`. Here, we create a simple reaction where the species `X` is converted to `Xᴾ` at rate `k`. By designating `X` as a constant species parameter, we ensure that its quantity is unchanged by the occurrence of the reaction.
+Catalyst enables the designation of parameters as `constantspecies`. These parameters can be used as species in reactions, however, their values are not changed by the reaction and remain constant throughout the simulation (unless changed by e.g. the [occurrence of an event](@ref constraint_equations_events). Practically, this is done by setting the parameter's `isconstantspecies` metadata to `true`. Here, we create a simple reaction where the species `X` is converted to `Xᴾ` at rate `k`. By designating `X` as a constant species parameter, we ensure that its quantity is unchanged by the occurrence of the reaction.
 ```@example dsl_advanced_constant_species
 using Catalyst # hide
 rn = @reaction_network begin
@@ -272,6 +272,39 @@ sol = solve(oprob)
 plot(sol)
 ```
 
+### [Turning off species, parameter, and variable inferring](@id dsl_advanced_options_require_dec)
+In some cases it may be desirable for Catalyst to not infer species and parameters from the DSL, as in the case of reaction networks with very many variables, or as a sanity check that variable names are written correctly. To turn off inferring, simply add the `@require_declaration` macro to one of the lines of the `@reaction_network` declaration. Having this macro means that every single variable, species, or parameter will have to be explicitly declared using the `@variable`, `@species`, or `@parameter` macro. In the case that the DSL parser encounters an undeclared symbolic, it will error with an `UndeclaredSymbolicError` and print the reaction or equation that the undeclared symbolic was found in. 
+
+```@example dsl_advanced_no_infer
+using Catalyst
+# The following case will throw an UndeclaredSymbolicError.
+try @macroexpand @reaction_network begin
+    @require_declaration
+    (k1, k2), A <--> B
+end
+catch e
+    println(e.msg)
+end
+```
+In order to avoid an error in this case all the relevant species and parameters will have to be declared.
+```
+# The following case will not error. 
+t = default_t()
+rn = @reaction_network begin
+    @require_declaration
+    @species A(t) B(t)
+    @parameters k1 k2
+    (k1, k2), A <--> B
+end
+```
+
+The following cases in which the DSL would normally infer variables will all throw errors if `@require_declaration` is set and the variables are not explicitly declared.
+- Inferring a species in a reaction, as in the example above
+- Inferring a parameter in a reaction rate expression, as in the reaction line `k*n, A --> B`
+- Inferring a parameter in the stoichiometry of a species, as in the reaction line `k, n*A --> B`
+- Inferring a differential variable on the LHS of a coupled differential equation, as in `A` in `@equations D(A) ~ A^2`
+- Inferring an [observable](@ref dsl_advanced_options_observables) that is declared using `@observables`
+
 ## [Naming reaction networks](@id dsl_advanced_options_naming)
 Each reaction network model has a name. It can be accessed using the `nameof` function. By default, some generic name is used:
 ```@example dsl_advanced_names