ProcessBasedModelling.jl

ProcessBasedModelling.jl is an extension to ModelingToolkit.jl (MTK) for building a model of equations using symbolic expressions. It is an alternative framework to MTK's native component-based modelling, but, instead of components, there are "processes". This approach is useful in the modelling of physical/biological/whatever systems, where each variable corresponds to a particular physical concept or observable and there are few (or none) duplicate variables to make the definition of MTK "factories" worthwhile. On the other hand, there plenty of different physical representations, or processes to represent a given physical concept in equation form. In many scientific fields this approach parallels the modelling reasoning of the researcher more closely than the "components" approach.

Beyond this reasoning style, the biggest strength of ProcessBasedModelling.jl is the informative errors and automation it provides regarding incorrect/incomplete equations. When building the MTK model via ProcessBasedModelling.jl the user provides a vector of "processes": equations or custom types that have a well defined and single left-hand-side variable. This allows ProcessBasedModelling.jl to:

1. Iterate over the processes and collect new variables that have been introduced by a provided process but do not themselves have a process assigned to them.
2. For these collected "process-less" variables:
   • If there is a default process defined, incorporate this one into the model
   • If there is no default process but the variable has a default value, equate the variable to a parameter that has the same default value and throw an informative warning.
   • Else, throw an informative error saying exactly which originally provided variable introduced this new "process-less" variable.
3. Throw an informative error if a variable has two processes assigned to it (by mistake).

In our experience, and as we also highlight explicitly in the online documentation, this approach typically yields simpler, less ambiguous, and more targeted warning or error messages than the native MTK one's. This leads to faster identification and resolution of the problems with the composed equations.

ProcessBasedModelling.jl is particularly suited for developing a model about a physical/biological/whatever system and being able to try various physical "rules" (couplings, feedbacks, mechanisms, ...) for a given physical observable efficiently. This means switching arbitrarily between different processes that correspond to the same variable. Hence, the target application of ProcessBasedModelling.jl is to be a framework to develop field-specific libraries that offer predefined processes without themselves relying on the existence of context-specific predefined components. An example usage is in ConceptualClimateModels.jl.

Besides the informative errors, ProcessBasedModelling.jl also

1. Provides a couple of common process subtypes out of the box to accelerate development of field-specific libraries.
2. Makes named MTK variables and parameters automatically, corresponding to parameters introduced by the by-default provided processes. This typically leads to intuitive names without being explicitly coded, while being possible to opt-out.
3. Provides some utility functions for further building field-specific libraries.

See the documentation online for details on how to use this package as well as examples highlighting its usefulness.

ProcessBasedModelling.jl development is funded by UKRI's Engineering and Physical Sciences Research Council, grant no. EP/Y01653X/1 (grant agreement for a EU Marie Sklodowska-Curie Postdoctoral Fellowship for George Datseris).

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. Use the function processes_to_mtkeqs to obtain the raw Vector{Equation} before it is passed to the MTK model/system like ODESystem.

During construction, the following automations improve user experience:

• Variable(s) introduced in processes that does not itself have a process obtain a default process from default.
• If no default exists, but the variable(s) itself has a default numerical value, a ParameterProcess is created for said variable and a warning is thrown.
• Else, an informative error is thrown.
• An error is also thrown if any variable has two or more processes assigned to it.

processes is a Vector whose elements can be:

1. Any instance of a subtype of Process. Process is a wrapper around Equation that provides some conveniences, e.g., handling of timescales or not having limitations on the left-hand-side (LHS) form.
2. An Equation. The LHS format of the equation is limited. Let x be a @variable and p be a @parameter. Then, the LHS can only be one of: x, Differential(t)(x), Differential(t)(x)*p, p*Differential(t)(x), however, the versions with p may fail unexpectedly. Anything else will error.
3. A Vector of the above two, which is then expanded. This allows the convenience of functions representing a physical process that may require many equations to be defined (because e.g., they may introduce more variables).
4. A ModelingToolkit.jl XDESystem, in which case the equations of the system are expanded as if they were given as a vector of equations like above. This allows the convenience of straightforwardly coupling with already existing XDESystems.

Default processes

processes_to_mtkmodel allows for specifying default processes by giving default. These default processes are assigned to variables introduced in the main input processes, but themselves do not have an assigned process in the main input.

default can be a Vector of individual processes (Equation or Process). Alternatively, default can be a Module. The recommended way to build field-specific modelling libraries based on ProcessBasedModelling.jl is to define modules/submodules that offer a pool of pre-defined variables and processes. Modules may register their own default processes via the function register_default_process!. These registered processes are used when default is a Module.

Keyword arguments

• type = ODESystem: the model type to make.
• name = nameof(type): the name of the model.
• independent = t: the independent variable (default: @variables t). t is also exported by ProcessBasedModelling.jl for convenience.
• 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.

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.

You can use default_processes to obtain the list of tracked default processes.

module MyProcesses
# ...

function __init__()
    register_default_process!.(
        [
            process1,
            process2,
            # ...
        ],
        Ref(MyProcesses)
    )
end

end # module

default_processes(m::Module)

Return the dictionary of default processes tracked by the given module. See also default_processes_eqs.

default_processes_eqs(m::Module)

Same as default_processes, but return the equations of all processes in a vector format, which is rendered as LaTeX in Markdown to HTML processing by e.g., Documenter.jl.

ParameterProcess(variable, value = default_value(variable)) <: Process

The simplest process which equates a given variable to a constant value that is encapsulated in a parameter. If value isa Real, then a named parameter with the name of variable and _0 appended is created. Else, if valua isa Num then it is taken as the paremeter directly.

Example:

@variables T(t) = 0.5
proc = ParameterProcess(T)

will create the equation T ~ T_0, where T_0 is a @parameter with default value 0.5.

TimeDerivative(variable, expression [, τ])

The second simplest process that equates the time derivative of the variable to the given expression while providing some conveniences over manually constructing an Equation.

It creates the equation τ_$(variable) Differential(t)(variable) ~ expression by constructing a new @parameter with default value τ (if τ is already a @parameter, it is used as-is). If τ is not given, then 1 is used at its place and no parameter is created.

Note that if iszero(τ), then the process variable ~ expression is created.

ExpRelaxation(variable, expression [, τ]) <: Process

A common process for creating an exponential relaxation of variable towards the given expression, with timescale τ. It creates the equation:

τn*Differential(t)(variable) ~ expression - variable

Where τn is a new named @parameter with the value of τ and name τ_($(variable)). If instead τ is nothing, then 1 is used in its place (this is the default behavior). If iszero(τ), then the equation variable ~ expression is created instead.

The convenience function

ExpRelaxation(process, τ)

allows converting an existing process (or equation) into an exponential relaxation by using the rhs(process) as the expression in the equation above.

AdditionProcess(process, added...)

A convenience process for adding processes added to the rhs of the given process. added can be a single symbolic expression. Otherwise, added can be a Process or Equation, or multitude of them, in which case it is checked that the lhs_variable across all added components matches the process.

Process

A new process must subtype Process and can be used in processes_to_mtkmodel. The type must extend the following functions from the module ProcessBasedModelling:

• lhs_variable(p) which returns the variable the process describes (left-hand-side variable). There is a default implementation lhs_variable(p) = p.variable if the field exists.
• rhs(p) which is the right-hand-side expression, i.e., the "actual" process.
• (optional) timescale(p), which defaults to NoTimeDerivative.
• (optional) lhs(p) which returns the left-hand-side. Let τ = timescale(p). Then default lhs(p) behaviour depends on τ as follows:
  • Just lhs_variable(p) if τ == NoTimeDerivative().
  • Differential(t)(p) if τ == nothing, or multiplied with a number if τ isa LiteralParameter.
  • τ_var*Differential(t)(p) if τ isa Union{Real, Num}. If real, a new named parameter τ_var is created that has the prefix :τ_ and then the lhs-variable name and has default value τ. Else if Num, τ_var = τ as given.
  • Explicitly extend lhs_variable if the above do not suit you.

ProcessBasedModelling.lhs_variable(p::Process)

Return the variable (a single symbolic variable) corresponding to p.

ProcessBasedModelling.rhs(process)

Return the right-hand-side of the equation governing the process.

ProcessBasedModelling.timescale(p::Process)

Return the timescale associated with p. See Process for more.

ProcessBasedModelling.NoTimeDerivative()

Singleton value that is the default output of the timescale function for variables that do not vary in time autonomously, i.e., they have no d/dt derivative and hence the concept of a "timescale" does not apply to them.

ProcessBasedModelling.lhs(p::Process)
ProcessBasedModelling.lhs(eq::Equation)

Return the right-hand-side of the equation governing the process. If timescale is implemented for p, typically lhs does not need to be as well. See Process for more.

new_derived_named_parameter(variable, value, extra::String; kw...)

If value isa Num return value. If value isa LiteralParameter, replace it with its literal value. Otherwise, create a new MTK @parameter whose name is created from variable (which could also be just a Symbol) by adding the extra string.

Keywords:

• prefix = true: whether the extra is added at the start or the end, connecting with the with the connector.
• connector = "_": what to use to connect extra with the name.

For example,

@variables x(t)
p = new_derived_named_parameter(x, 0.5, "τ")

Now p will be a parameter with name :τ_x and default value 0.5.

@convert_to_parameters vars...

Convert all variables vars into @parameters with name the same as vars and default value the same as the value of vars. The macro leaves unaltered inputs that are of type Num, assumming they are already parameters. It also replaces LiteralParameter inputs with its literal values. This macro is extremely useful to convert e.g., keyword arguments into named parameters, while also allowing the user to give custom parameter names, or to leave some keywords as numeric literals.

Example:

julia> A, B = 0.5, 0.5
(0.5, 0.5)

julia> C = first(@parameters X = 0.5)

julia> @convert_to_parameters A B C
3-element Vector{Num}:
 A
 B
 X

julia> typeof(A) # `A` is not a number anymore!
Num

julia> default_value(A)
0.5

julia> C # the binding `C` still corresponds to parameter named `:X`!
 X

LiteralParameter(p)

A wrapper around a value p to indicate to new_derived_named_parameter or @convert_to_parameters to not convert the given parameter p into a named @parameters instance, but rather keep it as a numeric literal in the generated equations.

default_value(x)

Return the default value of a symbolic variable x or nothing if it doesn't have any. Return x if x is not a symbolic variable. The difference with ModelingToolkit.getdefault is that this function will not error on the absence of a default value.

has_symbolic_var(eqs, var)

Return true if symbolic variable var exists in the equation(s) eq, false otherwise. This works for either @parameters or @variables. If var is a Symbol isntead of a Num, all variables are converted to their names and equality is checked on the basis of the name only.

has_symbolic_var(model, var)

When given a MTK model (such as ODESystem) search in all the equations of the system, including observed variables.