Improve default processes: allow registration per module (#8)

* allow DESystems in processes_to_mtkmodel

* allow Differential and differential*p in LHS of equations as processes

* add changelog entry

* add warning comment

* fix type of vector expansion container

* show that differential can be used in the docs

* add new info to docs

* add default function

* correct version parse

* add optinal code for default loading

* finish docstring of default

* ensure default dict is stored

* better code for deafult

* changelog

* tests

* bump version

* fix the tests

Author: Datseris

CHANGELOG.md

@@ -3,6 +3,14 @@
 ProcessBasedModelling.jl follows semver 2.0.
 Changelog is kept with respect to v1 release.
 
+## 1.2
+
+The API for default processes has been drastically improved.
+Now, each `Module` can track its own default processes via the new function
+`register_default_process!`. This allows creating submodules dedicated to
+physical "subsystems" which need to track their own list of variables,
+parameters, and default processes.
+
 ## 1.1
 
 - New keyword `warn_default` in `processes_to_mtkmodel`.

Project.toml

@@ -1,7 +1,7 @@
 name = "ProcessBasedModelling"
 uuid = "ca969041-2cf3-4b10-bc21-86f4417093eb"
 authors = ["Datseris <[email protected]>"]
-version = "1.1.0"
+version = "1.2.0"
 
 [deps]
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"

src/ProcessBasedModelling.jl

@@ -10,17 +10,13 @@ end ProcessBasedModelling
 using Reexport
 using ModelingToolkit: t_nounits as t, D_nounits as D
 @reexport using ModelingToolkit
-export t
 
 include("API.jl")
 include("utils.jl")
+include("default.jl")
 include("make.jl")
 include("processes_basic.jl")
 
-# TODO: Make an "addition process" that adds to processes
-# It checks whether they target the same variable
-
-# TODO: Perhaps not don't export `t`?
 export t
 export Process, ParameterProcess, TimeDerivative, ExpRelaxation, AdditionProcess
 export processes_to_mtkmodel

src/default.jl

@@ -0,0 +1,34 @@
+export register_default_process!, default_processes
+
+const _DEFAULT_PROCESSES = Dict{Module, Dict}()
+
+"""
+    register_default_process!(process, m::Module; warn = true)
+
+Register a `process` (`Equation` or `Process`) as a default process for its LHS variable
+in the list of default processes tracked by the given module.
+If `warn`, throw a warning if a default process with same LHS variable already
+exists and will be overwritten.
+"""
+function register_default_process!(process::Union{Process, Equation}, m::Module; warn = true)
+    mdict = default_processes(m)
+    lhsvar = lhs_variable(process)
+    # overwritting here should never happen but oh well.
+    if haskey(mdict, lhsvar) && warn
+        @warn("Overwritting default process for variable $(lhsvar)")
+    end
+    mdict[lhsvar] = process
+    return nothing
+end
+
+"""
+    default_processes(m::Module)
+
+Return the dictionary of default processes tracked by the given module.
+"""
+function default_processes(m::Module)
+    if !haskey(_DEFAULT_PROCESSES, m)
+        _DEFAULT_PROCESSES[m] = Dict{Num}{Any}()
+    end
+    return _DEFAULT_PROCESSES[m]
+end

src/make.jl

@@ -1,5 +1,5 @@
 """
-    processes_to_mtkmodel(processes::Vector, default::Vector = []; kw...)
+    processes_to_mtkmodel(processes::Vector [, default]; kw...)
 
 Construct a ModelingToolkit.jl model/system using the provided `processes` and `default` processes.
 The model/system is _not_ structurally simplified.
@@ -19,13 +19,16 @@ The model/system is _not_ structurally simplified.
    as if they were given as a vector of equations like above. This allows the convenience
    of straightforwardly coupling already existing systems.
 
-`default` is a vector that can contain the first two possibilities only
-as it contains default processes that may be assigned to individual variables introduced in
-`processes` but they don't themselves have an assigned process.
+## Default processes
 
-It is expected that downstream packages that use ProcessBasedModelling.jl to make a
-field-specific library implement a 1-argument version of `processes_to_mtkmodel`,
-or provide a wrapper function for it, and add a default value for `default`.
+`processes_to_mtkmodel` allows for specifying default processes by giving `default`.
+These default processes are assigned to variables introduced in the main input `processes`
+without themselves having an assigned process in the main input.
+
+`default` can be a `Vector` of individual processes (`Equation` or `Process`).
+Alternatively, `default` can be a `Module`. ProcessBasedModelling.jl allows modules to
+register their own default processes via the function [`register_default_process!`](@ref).
+These registered processes are used when `default` is a `Module`.
 
 ## Keyword arguments
 
@@ -36,11 +39,17 @@ or provide a wrapper function for it, and add a default value for `default`.
 - `warn_default::Bool = true`: if `true`, throw a warning when a variable does not
   have an assigned process but it has a default value so that it becomes a parameter instead.
 """
-function processes_to_mtkmodel(_processes::Vector, _default = [];
+processes_to_mtkmodel(procs::Vector; kw...) =
+processes_to_mtkmodel(procs, Dict{Num, Any}(); kw...)
+processes_to_mtkmodel(procs::Vector, m::Module; kw...) =
+processes_to_mtkmodel(procs, default_processes(m); kw...)
+processes_to_mtkmodel(procs::Vector, v::Vector; kw...) =
+processes_to_mtkmodel(procs, default_dict(v); kw...)
+
+function processes_to_mtkmodel(_processes::Vector, default::Dict{Num, Any};
         type = ODESystem, name = nameof(type), independent = t, warn_default::Bool = true,
     )
     processes = expand_multi_processes(_processes)
-    default = default_dict(_default)
     # Setup: obtain lhs-variables so we can track new variables that are not
     # in this vector. The vector has to be of type `Num`
     lhs_vars = Num[lhs_variable(p) for p in processes]

test/runtests.jl

@@ -208,4 +208,23 @@ end
     sys2 = processes_to_mtkmodel([sys, w ~ x*y])
     @test length(equations(sys2)) == 4
     @test sort(ModelingToolkit.getname.(unknowns(sys2))) == [:w, :x, :y, :z]
-end
+end
+
+module TestDefault
+    using ProcessBasedModelling
+    @variables x(t) = 0.5 y(t) = 0.2
+    register_default_process!.([
+        Differential(t)(x) ~ 0.2y - x,
+        y ~ x^2,
+    ], Ref(TestDefault))
+end
+
+@testset "registering default" begin
+    using .TestDefault
+    @variables z(t) = 0.1
+    eqs = [z ~ TestDefault.x - 1]
+    mtk = processes_to_mtkmodel(eqs, TestDefault)
+    @test length(unknowns(mtk)) == 3
+    @test has_symbolic_var(mtk, z)
+    @test has_symbolic_var(mtk, TestDefault.x)
+end