You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
ProcessBasedModelling.jl is an extension to [ModelingToolkit.jl](https://docs.sciml.ai/ModelingToolkit/stable/) (MTK) for building a model of equations using symbolic expressions.
10
10
It is an alternative framework to MTK's [native component-based modelling](https://docs.sciml.ai/ModelingToolkit/stable/tutorials/acausal_components/), but, instead of components, there are "processes".
11
-
This approach is useful in the modelling of physical/biological/whatever systems, where each variable corresponds to particular physical concept or observable and there are few (or any) duplicate variables to make the definition of MTK "factories" worthwhile, while, there plenty of different physical representations, or _processes_ to represent the given physical concept.
12
-
In many fields this approach parallels modelling reasoning line of the researcher more closely than the "components" approach.
11
+
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.
12
+
On the other hand, there plenty of different physical representations, or _processes_ to represent a given physical concept.
13
+
In many scientific fields this approach parallels the modelling reasoning of the researcher more closely than the "components" approach.
13
14
14
15
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.
Copy file name to clipboardExpand all lines: docs/src/index.md
+25-18Lines changed: 25 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -41,7 +41,7 @@ To make the equations we want, we can use MTK directly, and call
41
41
```@example MAIN
42
42
eqs = [
43
43
Differential(t)(z) ~ x^2 - z
44
-
Differential(x) ~ 0.1y
44
+
Differential(t)(x) ~ 0.1y
45
45
y ~ z - x
46
46
]
47
47
@@ -50,30 +50,32 @@ model = ODESystem(eqs, t; name = :example)
50
50
equations(model)
51
51
```
52
52
53
-
All good. Now, if we missed the process for one variable (because of our own error/sloppyness/very-large-codebase), MTK will not throw an error at model construction,
53
+
All good. Now, if we missed the process for one variable (because of our own error/sloppyness/very-large-codebase), MTK will throw an error when we try to _structurally simplify_ the model (a step necessary before solving the ODE problem):
54
54
55
55
```@example MAIN
56
56
model = ODESystem(eqs[1:2], t; name = :example)
57
-
model = structural_simplify(model)
58
-
equations(model)
59
-
```
60
-
61
-
only at the construction of the "problem" (here the `ODEProblem`)
62
-
63
-
```@example MAIN
64
57
try
65
-
prob = ODEProblem(model)
58
+
model = structural_simplify(model)
66
59
catch e
67
60
return e.msg
68
61
end
69
62
```
70
63
71
-
Interestingly, the error is wrong. ``x`` is defined and has an equation, at least on the basis of our scientific reasoning. However ``y`` that ``x`` introduced does not have an equation. Moreover, in our experience these errors messages become increasingly less useful when a model has many equations and/or variables, as many variables get cited as "missing" from the variable map even when only one should be.
64
+
As you can see, the error message is unhelpful even with such a trivial system of equations,
65
+
as all variables are reported as "potentially missing".
66
+
At least on the basis of our scientific reasoning however, both ``x, z`` have an equation.
67
+
It is ``y`` that ``x`` introduced that does not have an equation.
68
+
Moreover, in our experience these errors messages become increasingly less useful when a model has many equations and/or variables, as many variables get cited as "missing" from the variable map even when only one should be.
69
+
70
+
**PBM** resolves these problems and always gives accurate error messages when it comes to
71
+
the construction of the system of equations.
72
+
This is because on top of the variable map that MTK constructs automatically, **PBM** requires the user to implicitly provide a map of variables to processes that govern said variables. **PBM** creates the map automatically, the only thing the user has to do is to define the equations in terms of what [`processes_to_mtkmodel`](@ref) wants (which are either [`Process`](@ref)es or `Equation`s as above).
72
73
73
-
**PBM** resolves these problems and always gives accurate error messages. This is because on top of the variable map that MTK constructs automatically, **PBM** requires the user to implicitly provide a map of variables to processes that govern said variables. **PBM** creates the map automatically, the only thing the user has to do is to define the equations in terms of what [`processes_to_mtkmodel`](@ref) wants (which are either [`Process`](@ref)es or `Equation`s as above).
74
-
Here is what the user defines to make the same system of equations:
74
+
Here is what the user defines to make the same system of equations via **PBM**:
75
75
76
76
```@example MAIN
77
+
using ProcessBasedModelling
78
+
77
79
processes = [
78
80
ExpRelaxation(z, x^2), # introduces x variable
79
81
TimeDerivative(x, 0.1*y), # introduces y variable
@@ -82,14 +84,17 @@ processes = [
82
84
```
83
85
84
86
which is then given to
87
+
85
88
```@example MAIN
86
89
model = processes_to_mtkmodel(processes; name = :example)
87
90
equations(model)
88
91
```
89
92
90
93
Notice that the resulting **MTK** model is not `structural_simplify`-ed, to allow composing it with other models. By default `t` is taken as the independent variable.
91
94
92
-
Now, in contrast to before, if we "forgot" a process, **PBM** will react accordingly. For example, if we forgot the 2nd process, then the construction will error informatively, telling us exactly which variable is missing, and because of which processes it is missing:
95
+
Now, in contrast to before, if we "forgot" a process, **PBM** will react accordingly.
96
+
For example, if we forgot the 2nd process, then the construction will error informatively,
97
+
telling us exactly which variable is missing, and because of which processes it is missing:
93
98
```@example MAIN
94
99
try
95
100
model = processes_to_mtkmodel(processes[[1, 3]])
@@ -109,7 +114,7 @@ parameters(model)
109
114
```
110
115
111
116
Lastly, [`processes_to_mtkmodel`](@ref) also allows the concept of "default" processes, that can be used for introduced "process-less" variables.
112
-
Default processes like `processes` given as a 2nd argument to [`process_to_mtkmodel`](@ref).
117
+
Default processes are like `processes` and given as a 2nd argument to [`process_to_mtkmodel`](@ref).
113
118
For example,
114
119
115
120
```@example MAIN
@@ -119,14 +124,14 @@ equations(model)
119
124
120
125
does not throw any warnings as it obtained a process for ``y`` from the given default processes.
121
126
122
-
###Special handling of timescales
127
+
## Special handling of timescales
123
128
124
129
In dynamical systems modelling the timescale associated with a process is a special parameter. That is why, if a timescale is given for either the [`TimeDerivative`](@ref) or [`ExpRelaxation`](@ref) processes, it is converted to a named `@parameter` by default:
125
130
126
131
```@example MAIN
127
132
processes = [
128
-
ExpRelaxation(z, x^2, 2.0), # third argument is the timescale
129
-
TimeDerivative(x, 0.1*y, 0.5),
133
+
ExpRelaxation(z, x^2, 2.0), # third argument is the timescale
134
+
TimeDerivative(x, 0.1*y, 0.5), # third argument is the timescale
130
135
y ~ z-x,
131
136
]
132
137
@@ -163,6 +168,7 @@ This API describes how you can implement your own `Process` subtype, if the [exi
0 commit comments