Merge pull request #985 from SciML/src___refactoring___dsl_file

Refactor "src/dsl.jl" file

Author: TorkelE

docs/src/api.md

@@ -86,9 +86,9 @@ ReactionSystem
 ```
 
 ## [Options for the `@reaction_network` DSL](@id api_dsl_options)
-We have [previously described](@ref dsl_advanced_options) how options permits the user to supply non-reaction information to [`ReactionSystem`](@ref) created through the DSL. Here follows a list
+We have [previously described](@ref dsl_advanced_options) how options allow one to supply additional information to a [`ReactionSystem`](@ref) created with the DSL. Here follows a list
 of all options currently available.
-- [`parameters`]:(@ref dsl_advanced_options_declaring_species_and_parameters) Allows the designation of a set of symbols as system parameter.
+- [`parameters`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system parameters.
 - [`species`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system species.
 - [`variables`](@ref dsl_advanced_options_declaring_species_and_parameters): Allows the designation of a set of symbols as system non-species variables.
 - [`ivs`](@ref dsl_advanced_options_ivs): Allows the designation of a set of symbols as system independent variables.
@@ -100,6 +100,7 @@ of all options currently available.
 - [`continuous_events`](@ref constraint_equations_events): Allows the creation of continuous events.
 - [`discrete_events`](@ref constraint_equations_events): Allows the creation of discrete events.
 - [`combinatoric_ratelaws`](@ref faq_combinatoric_ratelaws): Takes a single option (`true` or `false`), which sets whether to use combinatorial rate laws.
+- [`require_declaration`](@ref dsl_advanced_options_require_dec): Turns off all inference of parameters, species, variables, the default differential, and observables (requiring these to be explicitly declared using e.g. `@species`).
 
 ## [ModelingToolkit and Catalyst accessor functions](@id api_accessor_functions)
 A [`ReactionSystem`](@ref) is an instance of a

docs/src/model_creation/dsl_advanced.md

@@ -204,7 +204,6 @@ 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.
 ```@example dsl_advanced_constant_species
 using Catalyst # hide
@@ -575,6 +574,45 @@ nothing # hide
 !!! note
     When using interpolation, expressions like `2$spec` won't work; the multiplication symbol must be explicitly included like `2*$spec`.
 
+## [Creating individual reaction using the `@reaction` macro](@id dsl_advanced_options_reaction_macro)
+Catalyst exports a macro `@reaction`, which can be used to generate a singular [`Reaction`](@ref) object of the same type which is stored within the [`ReactionSystem`](@ref) structure (which in turn can be generated by `@reaction_network`). Generally, `@reaction` follows [identical rules to those of `@reaction_network`](@ref dsl_description_reactions) for writing and interpreting reactions (however, bi-directional reactions are not permitted). E.g. here we create a simple dimerisation reaction:
+```@example dsl_advanced_reaction_macro
+using Catalyst # hide
+rx_dimerisation = @reaction kD, 2X --> X2
+```
+Here, `@reaction` is followed by a single line consisting of three parts:
+- A rate (at which the reaction occurs).
+- Any number of substrates (which are consumed by the reaction).
+- Any number of products (which are produced by the reaction).
+
+In the next example, we first create a simple [SIR model](@ref basic_CRN_library_sir). Then, we specify the same model by instead creating its individual reaction components using the `@reaction` macro. Finally, we confirm that these are identical to those stored in the initial model (using the [`reactions`](@ref) function).
+```@example dsl_advanced_reaction_macro
+sir_model = @reaction_network begin
+ α, S + I --> 2I
+ β, I --> R
+end
+infection_rx = @reaction α, S + I --> 2I
+recovery_rx = @reaction β, I --> R
+sir_rxs = [infection_rx, recovery_rx]
+issetequal(reactions(sir_model), sir_rxs)
+```
+One of the primary uses of the `@reaction` macro is to provide some of the convenience of the DSL to [*programmatic modelling](@ref programmatic_CRN_construction). E.g. here we can combine our reactions to create a `ReactionSystem` directly, and also confirm that this is identical to the model created through the DSL:
+```@example dsl_advanced_reaction_macro
+sir_programmatic = complete(ReactionSystem(sir_rxs, default_t(); name = :sir))
+sir_programmatic == sir_model
+```
+
+During programmatic modelling, it can be good to keep in mind that already declared symbolic variables can be [*interpolated*](@ref dsl_advanced_options_symbolics_and_DSL_interpolation). E.g. here we create two production reactions both depending on the same Michaelis-Menten function:
+```@example dsl_advanced_reaction_macro
+t = default_t()
+@species X(t)
+@parameters v K
+mm_term = Catalyst.mm(X, v, K)
+rx1 = @reaction $mm_term, 0 --> P1
+rx2 = @reaction $mm_term, 0 --> P2
+nothing # hide
+```
+
 ## [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:

src/Catalyst.jl

@@ -72,11 +72,6 @@ const CONSERVED_CONSTANT_SYMBOL = :Γ
 const forbidden_symbols_skip = Set([:ℯ, :pi, :π, :t, :∅])
 const forbidden_symbols_error = union(Set([:im, :nothing, CONSERVED_CONSTANT_SYMBOL]),
     forbidden_symbols_skip)
-const forbidden_variables_error = let
-    fvars = copy(forbidden_symbols_error)
-    delete!(fvars, :t)
-    fvars
-end
 
 ### Package Main ###
 

src/chemistry_functionality.jl

@@ -86,7 +86,7 @@ function make_compound(expr)
     # Cannot extract directly using e.g. "getfield.(composition, :reactant)" because then
     # we get something like :([:C, :O]), rather than :([C, O]).
     composition = Catalyst.recursive_find_reactants!(expr.args[3], 1,
-        Vector{ReactantStruct}(undef, 0))
+        Vector{DSLReactant}(undef, 0))
     components = :([])                                      # Becomes something like :([C, O]).
     coefficients = :([])                                    # Becomes something like :([1, 2]).
     for comp in composition