Refactor "src/dsl.jl" file #985

TorkelE · 2024-07-13T22:49:31Z

Also does the "src/expression_utils.jl" file, as that primarily support the dsl file (the other relevant file is the chemistry one).

Primarily four types of changes:

Added comment to code which did not have (primarily older code).
Rewrite some old code (a lot of stuff in the dsl file is stuff I wrote over 6 years ago, which simply can be rewritten better now).
Do some organisations for where the options are handled in the main function. Been meaning to do this pretty much since I introduced them, and now when we have all *for the foreseeable future) it seemed like a good time to do it. Now it should also be easier to see where to add new options in the future.
Rewrite so that the @reaction_network and @network_component macros reuse minimal amount of code (where as previously it the second was basically ctrl+copied versions of the first.
Add a bunch of error checks to handle things which previously went through but shouldn't.

I also add some tests of all the various ways to create models via the DSL, mostly stuff that was not tested before.

src/Catalyst.jl

src/chemistry_functionality.jl

src/expression_utils.jl

src/dsl.jl

TorkelE · 2024-07-13T23:34:45Z

src/dsl.jl

    variables = vcat(variables_declared, vars_extracted)
-
-    # handle independent variables


Part of the organisations so that options are handled together (in two sets, some before and some after the reactions are considered, depending on whichever is possible for which option)

src/dsl.jl

TorkelE · 2024-07-13T23:39:44Z

src/dsl.jl

        symvec = gensym()
-        ex = quote
-            $symvec = $ex
+        expr = quote


in some places we used ex and some expr, here I just made it uniform

TorkelE · 2024-07-13T23:41:46Z

test/dsl/dsl_basic_model_construction.jl

+    isequivalent(rs_empty_1, rs_empty)
+    rs_empty_2 == rs_empty
+    rs_empty_3 == rs_empty
+end


WHen I remade how the macor inputs are handled at the top level (nothing, name, reactions, name + reactions) I wanted to add some tests that all of this works for all cases and both macros.

TorkelE · 2025-01-19T21:43:16Z

src/expression_utils.jl

-    allunique(syms) ||
-        error("Reaction network independent variables, parameters, species, and variables must all have distinct names, but a duplicate has been detected. ")
-    nothing
-end


Now only used in one place, there implemented directly.

TorkelE · 2025-01-19T21:43:45Z

src/expression_utils.jl

+    (length(expr.args) > 3) &&
+        error("An option input ($expr) is misformatted. Potentially, it has multiple inputs on a single lines, and these should be split across multiple lines using a `begin ... end` block.")
+    return expr.args[3]
+end


Helper function for handling error checks across multiple options.

TorkelE · 2025-01-19T21:44:28Z

src/spatial_reaction_systems/spatial_reactions.jl

-    sexprs = get_sexpr([species], Dict{Symbol, Expr}())
-    pexprs = get_pexpr(parameters, Dict{Symbol, Expr}())
+    sexprs = get_usexpr([species], Dict{Symbol, Expr}())
+    pexprs = get_psexpr(parameters, Dict{Symbol, Expr}())


Uses new names in the DSL file

TorkelE · 2025-01-19T21:47:42Z

test/dsl/dsl_options.jl

+# Tests error when disallowed name is used for variable.
+let
+    @test_throws Exception @eval @reaction_network begin
+        @variables π(t)


TorkelE · 2025-01-19T22:03:26Z

src/dsl.jl

-    probODE = ODEProblem(rn, args...; kwargs...)        # Using multiple dispatch the reaction network can be used as input to create ODE, SDE and Jump problems.
-    probSDE = SDEProblem(rn, args...; kwargs...)
-    probJump = JumpProblem(prob,aggregator::Direct,rn)
-"""


The first documentation of @reactio_network, but now not even a docstring and just a weird remnant. remove.

TorkelE · 2025-01-19T22:04:14Z

src/dsl.jl

-    probJump = JumpProblem(prob,aggregator::Direct,rn)
-"""
-
-### Constant Declarations ###


Not removed, now just line 1 and git got confused.

TorkelE · 2025-01-19T22:06:57Z

src/dsl.jl

+    (sum(length, [reaction_lines, option_lines]) != length(ex.args)) &&
+        error("@reaction_network input contain $(length(ex.args) - sum(length.([reaction_lines,option_lines]))) malformed lines.")
+    any(!in(option_keys), keys(options)) &&
+        error("The following unsupported options were used: $(filter(opt_in->!in(opt_in,option_keys), keys(options)))")


Step one, read the macro input and check that it is correctly formatted.

TorkelE · 2025-01-19T22:07:20Z

src/dsl.jl

+    if !allunique(syms_declared)
+        nonunique_syms = [s for s in syms_declared if count(x -> x == s, syms_declared) > 1]
+        error("The following symbols $(unique(nonunique_syms)) have explicitly been declared as multiple types of components (e.g. occur in at least two of the `@species`, `@parameters`, `@variables`, `@ivs`, `@compounds`, `@differentials`). This is not allowed.")
+    end


Step 2, read all options that explicitly declares symbols as stuff.

TorkelE · 2025-01-19T22:09:08Z

src/dsl.jl

+    continuous_events_expr = read_events_option(options, :continuous_events)
+    discrete_events_expr = read_events_option(options, :discrete_events)
+    default_reaction_metadata = read_default_noise_scaling_option(options)
+    combinatoric_ratelaws = read_combinatoric_ratelaws_option(options)


Step 4, read the other options.

TorkelE · 2025-01-19T22:09:28Z

src/dsl.jl

+    spsexpr, spsvar = scalarize_macro(spsexpr_init, "specs")
+    vsexpr, vsvar = scalarize_macro(vsexpr_init, "vars")
+    cmpsexpr, cmpsvar = scalarize_macro(cmpexpr_init, "comps")
+    rxsexprs = get_rxexprs(reactions, equations, all_syms)


Step 5, creates the various expressions to put in the macro.

TorkelE · 2025-01-19T22:12:36Z

src/dsl.jl

    end
+    union!(excluded_syms, species)


union! replaces foreach(s -> push!(excluded_syms, s), species)

TorkelE · 2025-01-20T11:22:53Z

test/dsl/dsl_options.jl

+    @test_throws Exception @eval @reaction_network begin
+        @combinatoric_ratelaws false false
+        d, 3X --> 0
+    end


Checks that new error checks work (don't think the one above actually errored either, but it should)

TorkelE · 2025-01-20T18:11:07Z

docs/src/model_creation/dsl_advanced.md

+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).


This bit

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).

is essentially a repeat of previous documentation. Probably unnecessary for most people and only relevant if we wish to keep this section self contained. happy to remove though.

TorkelE · 2025-01-20T18:19:20Z

test/dsl/dsl_advanced_model_construction.jl

+    @test_throws Exception @eval @reaction_network begin
+        d, X --> 0, [misc=>:misc; description="description"]
+    end
+end


One of several new sets of tests for stuff which we previously didn't actually test

TorkelE · 2025-01-20T18:20:38Z

test/dsl/dsl_basic_model_construction.jl

-    @test_throws LoadError @eval @reaction im, 0 --> B
-    @test_throws LoadError @eval @reaction nothing, 0 --> B
-    @test_throws LoadError @eval @reaction k, 0 --> im
-    @test_throws LoadError @eval @reaction k, 0 --> nothing


forbidden symbol tests now tested more extensively in a test block two blocks down ("# Check that forbidden symbols correctly generates errors"

TorkelE · 2025-01-20T18:23:39Z

src/dsl.jl

+    syms_inferred = union(sps_inferred, ps_inferred, vs_inferred, diffs_inferred)
+    all_syms = union(syms_declared, syms_inferred)
+    obsexpr, obs_eqs, obs_syms = read_observed_option(options, ivs,
+        union(sps_declared, vs_declared), all_syms; requiredec)


Step 3: Read all reactions and equations. Finds all symbols that are inferred as something.

TorkelE · 2025-01-20T18:38:17Z

src/dsl.jl

+function escape_equation!(eqexpr::Expr, all_syms)
+    eqexpr.args[2] = recursive_escape_functions!(eqexpr.args[2], all_syms)
+    eqexpr.args[3] = recursive_escape_functions!(eqexpr.args[3], all_syms)
+    eqexpr
 end


escape equations is called by get_rxexprs

TorkelE · 2025-01-20T18:55:29Z

src/dsl.jl


-    # Checks for input errors.
+    # Checks for input errors. Needed here but not in `@reaction_network` as `ReactionSystem` perform this check but `Reaction` don't.
    forbidden_symbol_check(union(species, parameters))


For @reaction_network this check is not needed as ReactionSystem does a similar one. We might consider whether Reaction should also perform this type of check (and we remove it from here entirely.

E.g. this works:

@parameters Γ @species X(t) Reaction(Γ, [X], [])

while this errors:

@reaction Γ, X --> 0

TorkelE · 2025-01-20T19:31:09Z

This should be ready now. However, Plots fails on precompilation, so have to wait until that is fixed.

Not high priority though, doesn't actually change anything (but should make further updates to the DSL easier).

Once this PR is merged, I will have a follow-up one which reorders the option handling functions to follow the order with which they are called.

…to src___refactoring___dsl_file

TorkelE added 10 commits May 27, 2024 19:26

save progress

efd44be

save progress

d2985c0

save progress

b06068f

save progress

5cc8f41

save progress

15273f1

add additional tests

b105b3e

up

1324428

fix

71c9b5c

Merge branch 'master' into dsl_file_improvements

9ab9290

merge fixes

d45f0a7