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
added some topics to the documentation. Expecially the structure subsection is still work in progress, but we need a place to start describing thing...
Copy file name to clipboardexpand all lines: build_docs/source/manual/structure.rst
+24-15
Original file line number
Diff line number
Diff line change
@@ -2,49 +2,58 @@ Structure
2
2
=========
3
3
* Schema
4
4
The package represents domain knowledge by two sets:
5
+
5
6
* A set of variables called `MVars` and
6
7
* A set of functions called `Computers`, operating on sets of instaces of these types.
7
8
8
-
The instance sets form the nodes and the computers the edges of a directed graph G.
9
+
Sets of `MVars` form the nodes and the computers the edges of a directed graph G.
9
10
We call G the computability graph because a desired `Mvar` (target) can be computed from
10
11
a set of `Mvars` (src) if there is a path from src to target.
11
-
We can also use
12
-
13
-
defined (or instanciated) in the user provided model descritpion in `models/NameOfTheModel/source.py` by the users and the (growing) set of computers represented by the `bgc_md/resolve/MvarsAndComputers.py`
14
-
Every model folder contains at least one file
15
-
```bash
16
-
source.py
17
-
```
18
-
That can contain import other module that can live in the same directory or be accessible globally.
19
-
The (minimal) purpose of the model file is usually that an instance of either a CompartmentalModel or a ModelRun can be created.
20
-
This can be done
21
-
* directly, by calling one of the constructors (of a CompartmentalModels) or
22
-
* indirectly by some definitions of variables with special names from which the ingredients for the constructor calls can be infered.
23
-
12
+
13
+
`MVars` are instanciated and combined into `MVarSets` by user provided python code, typically placed in a file `models/NameOfTheModel/source.py`.
14
+
This is however just a convention (with some support by helper functions). It is also possible to place the code elsewhere.
15
+
The `models` submodule of `bgc_md2` can thus be seen as a set of examples
16
+
The (minimal) purpose of the model file is usually that an instance of
17
+
either a CompartmentalModel or a ModelRun can be created.
18
+
This can be done
19
+
* directly, by calling one of the constructors (of a CompartmentalModels) or
20
+
21
+
* indirectly by some definitions of variables with special names from which the ingredients for the constructor calls can be infered.
22
+
23
+
The set of computers represented by the `bgc_md/resolve/MvarsAndComputers.py`
24
+
25
+
24
26
The package does not use standard database technology like SQL but stores available data connected to a model as a set of
25
27
variables of predefined types (from now on called MVars).
26
28
In terms of a database one can think of every Mvar type as a table
27
29
with two columns model_id
30
+
28
31
* Models
32
+
29
33
* Notebooks
34
+
30
35
* For single models
36
+
31
37
* For model comparisons
32
38
33
39
* Notes on implementation
40
+
34
41
* Library vs. Framework
35
42
CompartmentalSystems and LAPM can be considered
36
43
libraries that can be called in different parallelisation scenarios and with
37
44
different data.
38
45
bgc-md has both library and framework characteristics.
46
+
39
47
* The (types) of MVars and computers (functions) connecting them represents a domain knowledge
40
48
in form of a library.
49
+
41
50
* The collection of different models enforces some rules on the way a
42
51
single model has to be formulated in order to be comparable to other
43
52
models.
44
53
In this sense it comprises a framework into which different models can be
45
54
plugged.
46
55
47
-
* Viewed from a high level of abstraction models (symbolic) models and (climatic driver) data seem to be orthogonal to each other.
56
+
* Viewed from a high level of abstraction (symbolic) models and (climatic driver) data seem to be orthogonal to each other.
48
57
but they are also connected by a mapping between the dataset and the models realized by model specific data preparation code.
49
58
A model with more pools and connections we will
50
59
need more data and will connect the data to different pools or fluxes.
0 commit comments