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
where $\underline{x} = \underline{x}(t)$ are *system states* or *variables* and $\underline{b} = \underline{b}(t)$ are *external dependencies*.
14
+
15
+
Systems of ODEs are stored as a `VariablePortedObject` class. These ported objects store a set of ODEs, each an instance of the `DifferentialAssignment` class, and can expose the following ports:
16
+
17
+
-`InputPort`, capturing the external dependencies $\underline{b}$,
18
+
-`VariablePort`, which expose one of the variables $\underline{x}$.
19
+
20
+
The `VariablePortedObject` class is a key user-facing class.
21
+
22
+
# Example
23
+
24
+
Consider the following predator-prey system.
25
+
26
+
!!! example "Example: predator-prey system"
27
+
28
+
A two-species predator prey system has the form
29
+
30
+
$$
31
+
\begin{align}
32
+
\frac{dx}{dt} &= \alpha x - \beta xy \\
33
+
\frac{dy}{dt} &= \gamma xy - \delta x
34
+
\end{align}
35
+
$$
36
+
37
+
where:
38
+
39
+
* $\alpha > 0$ is the birth rate of prey population $x$,
40
+
* $\delta>0$ is the death rate of predator population $y$,
41
+
* $\beta>0$ is the predation rate of $y$ on $x$,
42
+
* $\gamma>0$ is the response rate of $y$ from the predation on $x$.
43
+
44
+
In `psymple`, this system can be captured as follows.
45
+
46
+
```py title="predator-prey as a VariablePortedObject"
47
+
from psymple.ported_objects import VariablePortedObject
1. Specifying variable ports does not create variables: the variables are created as the left-hand side of the assignments. Variable ports allow the variables created in assignments to be read or updated by other system components.
58
+
59
+
In this form, the parameters $a$, $b$, $c$ and $d$ are required inputs. To specify default values, a list of tuples, dictionaries or `InputPort` instances can be passed to the `input_ports` parameter. The following would be equivalent calls in this case:
Differential equations, along with functions, are the core building blocks of a `psymple` dynamic system.
3
+
Differential equationsare a core building blocks of a `psymple` system.
4
4
5
5
!!! info "Definition"
6
6
7
7
A differential equation in `psymple` is a first-order differential equation of the form
8
8
9
9
$$
10
-
\frac{dy}{dt} = f(y,t,\underline{x}),
10
+
\frac{dx}{dt} = f(x,t,\underline{b}),
11
11
$$
12
12
13
-
where $\underline{x}$ is a vector of to-be-defined dependencies.
13
+
where $\underline{b} = \underline{b}(t)$ are external dependencies.
14
14
15
-
Differential equations are stored as a [DifferentialAssignment](docs.assignments.md#differential-assignment) class
15
+
Differential equations are stored as a [DifferentialAssignment](docs.assignments.md#differential-assignment) class. In most cases, users will not interact directly with the `DifferentialAssignment` class, since they can be created automatically.
16
16
17
+
## Example
18
+
19
+
The logistic model is given by
20
+
21
+
$$
22
+
\frac{dx}{dt} = rx \left( 1-\frac{x}{k} \right)
23
+
$$
24
+
25
+
In `psymple` this equation is captured as follows.
26
+
27
+
```py title="Logistic equation as a DifferentialAssignment"
28
+
from psymple.variables import Variable
29
+
from psymple.ported_objects import DifferentialAssignment
30
+
31
+
pop_x = Variable(symbol="x",
32
+
initial_value=100,
33
+
description="Variable for population x",
34
+
)
35
+
36
+
assg_x = DifferentialAssignment(
37
+
symbol_container=pop_x,
38
+
expression="r*x*(1-x/k)",
39
+
)
40
+
```
41
+
42
+
If only the symbol for $x$ needs to be specified, the call for `DifferentialAssignment` can be streamlined.
43
+
44
+
```py3 title="Logistic equation as a DifferentialAssignment"
45
+
from psymple.ported_objects import DifferentialAssignment
Copy file name to clipboardExpand all lines: docs/systems.md
+82-4Lines changed: 82 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -1,16 +1,94 @@
1
1
# Modelling Systems
2
2
3
-
The package `psymple`facilitates the building and simulation of temporal dynamical systems models. It allows for a spectrum of models from purely mechanistic models to purely correlative models to be constructed by allowing arbitrary combinations of ordinary differential equations (ODEs) and multivariate functions to be combined together.
3
+
The package `psymple`implements the building and simulation of temporal dynamical systems models. While the package is designed to allow for the implementation of very general modelling paradigms, it was developed in response to the need for hybrid temporal ecological modelling.
4
4
5
-
!!! info "Defintion"
5
+
Temporal ecological modelling has classically been approached from two different schools of thought:
6
+
7
+
1. Mechanistic modelling, in which biological or physical principles are used to capture the flow of energy or resource between different species and systems in order to model population dynamics.
8
+
2. Correlative modelling, in which population distribution is modelled as a function of climatic predictor variables such as temperature, humidity and rainfall.
9
+
10
+
Since biological processes are complex and intricate, mechanistic modelling of ecological systems is not widely persued due to concerns about development time and accuracy. In contrast, correlative modelling is typically derived using multiple regression and machine learning techniques using observational data.
11
+
12
+
Correlative modelling has a natural limitation when used for predictive purposes in geographic or climatic ranges outside of the observational data. This becomes a particular concern when, for example, using correlative modelling to predict invasive species potential in new environments.
13
+
14
+
In response, and with the advances in computing capability, there has been growing interest in hybrid or spectrum models, which compose features of both mechanistic and correlative models. This package is designed to facilitate the construction of these models by easily allowing arbitrary combinations of mechanistic and correlative components.
15
+
16
+
## Mechanistic and correlative models
17
+
18
+
### Mechanistic models
19
+
20
+
Mechanistic models are dynamic models in which the evolution of the system is specified as a system of first-order ordinary differential equations (ODEs).
where $\underline{x}$ is a vector of *system states* or *variables*.
30
+
where $\underline{x} = \underline{x}(t)$ are *system states* or *variables* and $\underline{b} = \underline{b}(t)$ are *external dependencies*.
31
+
32
+
A familiar example of a mechanistic model is the Lotka-Volterra or predator-prey system.
33
+
34
+
!!! example "Example: predator-prey system"
35
+
36
+
A two-species predator prey system has the form
37
+
38
+
$$
39
+
\begin{align}
40
+
\frac{dx}{dt} &= \alpha x - \beta xy \\
41
+
\frac{dy}{dt} &= \gamma xy - \delta x
42
+
\end{align}
43
+
$$
44
+
45
+
where:
46
+
47
+
* $\alpha > 0$ is the birth rate of prey population $x$,
48
+
* $\delta>0$ is the death rate of predator population $y$,
49
+
* $\beta>0$ is the predation rate of $y$ on $x$,
50
+
* $\gamma>0$ is the response rate of $y$ from the predation on $x$.
51
+
52
+
### Correlative model
53
+
54
+
A correlative model is a general term for a model in which the evolution is specified explicitly in terms of time and the system states.
55
+
56
+
!!! info "Definition: correlative model"
57
+
58
+
A correlative model is of the form
59
+
60
+
$$
61
+
\underline{y} = \underline{f}(t, \underline{d})
62
+
$$
63
+
64
+
where $\underline{y} = \underline{y}(t)$ is a vector of *system states* and $\underline{d} = \underline{d}(t)$ are *external dependencies*.
65
+
66
+
Correlative models can be used to approximate the behaviour of a system component with other system states.
67
+
68
+
!!! example "Example: correlative ecological niche models"
69
+
70
+
Data may be used to model the prevalance of a certain species $y$ in response to temporal climatic features such as temperature $T$, relative humitidy $H_r$ and precipitation $P$. In this case the model will have the form
71
+
72
+
$$
73
+
y(t) = f(T, H_r, P)
74
+
$$
75
+
76
+
where $T=T(t)$, $H_r = H_r(t)$ and $P=P(t)$ are known in terms of $t$.
77
+
78
+
79
+
## Spectrum models
80
+
81
+
In `psymple`, spectrum models consistint of building blocks from purely mechanistic models and purely correlative models can be constructed by allowing arbitrary combinations of ordinary differential equations (ODEs) and multivariate functions to be combined together. A system in `psymple` is of the form
0 commit comments