Skip to content

Commit 14cab4c

Browse files
BSchilperoortBSchilperoort
committed
Update BMI documentation, add to mkdocs
1 parent 10f41a4 commit 14cab4c

3 files changed

Lines changed: 69 additions & 27 deletions

File tree

‎docs/bmi.md‎

Lines changed: 52 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,31 @@ The [Basic Model Interface](https://csdms.colorado.edu/wiki/BMI) is a standard w
33
PyStemmusScope implements the Basic Model Interface for STEMMUS_SCOPE.
44

55
There are multiple ways to run the STEMMUS_SCOPE Basic Model Interface.
6-
The first is using a local Matlab Compiler Runtime executable file (only available for x86 Linux).
6+
For the model, we generated Matlab Compiler Runtime executable file (only available for x86 Linux).
77
This requires installation of MCR.
88
The other option is to use the Dockerized version of the executable, available on ghcr.io/ecoextreml/stemmus_scope.
99

1010
For more information on each method, see the sections below.
1111

12-
## Local executable file
12+
## Installation and setup
13+
14+
### Dockerized executable
15+
STEMMUS_SCOPE has a Docker image available. This allows you to run the executable file without having to install MCR.
16+
The Docker image is available at https://ghcr.io/ecoextreml/stemmus_scope
17+
18+
To use the Docker image, use the `DockerImage` setting in the configuration file:
19+
```sh
20+
WorkDir=/home/username/tmp/stemmus_scope
21+
...
22+
DockerImage=ghcr.io/ecoextreml/stemmus_scope:1.5.0
23+
```
24+
25+
It is best to add the version tag here too (`:1.5.0`), this way the BMI will warn you if the version might be incompatible.
26+
27+
Note that the `docker` package for python is required here. Install this with `pip install PyStemmusScope[docker]`.
28+
Additionally, [Docker](https://docs.docker.com/get-docker/) itself has to be installed.
29+
30+
### Local executable file
1331
The executable file can be downloaded from the STEMMUS_SCOPE repository. More specifically [here](https://github.com/EcoExtreML/STEMMUS_SCOPE/tree/main/run_model_on_snellius/exe).
1432

1533
To be able to run this executable, you need a Linux x86 system, along with Matlab Compiler Runtime R2023a. MCR is available [here](https://nl.mathworks.com/products/compiler/matlab-runtime.html).
@@ -23,18 +41,38 @@ ExeFilePath=/path/to/executable/STEMMUS_SCOPE
2341

2442
Alternatively, if the environmental variable `STEMMUS_SCOPE` is configured, the BMI will use this if the ExeFilePath or DockerImage are not set in the configuration file.
2543

26-
## Dockerized executable
27-
STEMMUS_SCOPE also has a Docker image available. This allows you to run the executable file without having to install MCR.
28-
The Docker image is available at https://ghcr.io/ecoextreml/stemmus_scope
44+
## Using the BMI
2945

30-
To use the Docker image, use the `DockerImage` setting in the configuration file:
31-
```sh
32-
WorkDir=/home/username/tmp/stemmus_scope
33-
...
34-
DockerImage=ghcr.io/ecoextreml/stemmus_scope:1.5.0
35-
```
46+
A [notebook demonstration the use of the Basic Model Interface](BMI_demo.ipynb) is available.
47+
For more information on using BMI, see the [CSDMS website](https://csdms.colorado.edu/wiki/BMI).
3648

37-
It is best to add the version tag here too (`:1.5.0`), this way the BMI will warn you if the version might be incompatible.
49+
If you need access to other model variables that are not yet available in the BMI, please raise an issue on the [STEMMUS_SCOPE repository](https://github.com/EcoExtreML/STEMMUS_SCOPE/issues), or leave a comment if an issue is open already.
3850

39-
Note that the `docker` package for python is required here. Install this with `pip install PyStemmusScope[docker]`.
40-
Additionally, [Docker](https://docs.docker.com/get-docker/) itself has to be installed.
51+
## Developer instructions
52+
53+
The Python BMI implemented in this package communicates with the Matlab code through STDIN/STDOUT, or via a socket to the Docker container.
54+
Over this interface, three commands can be sent to Matlab:
55+
56+
1. `initialize "path_to_cfg_file.txt"`
57+
2. `update`
58+
3. `finalize`
59+
60+
After the initialize and update steps, the Matlab process writes the state of any BMI exposed variables to an hdf5-file in the directory of `OutputPath` as defined in the configuration file.
61+
62+
The Python BMI interfaces with this file to allow the variables to be read and set.
63+
64+
### Adding/changing exposed variables
65+
66+
Step one of changing the exposed variables is to change the Matlab code and generating a new MCR executable (and possibly Docker image).
67+
The exposed variables are defined in [`STEMMUS_SCOPE/src/STEMMUS_SCOPE_exe.m`](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/src/STEMMUS_SCOPE_exe.m).
68+
Under the `bmiVarNames` variable.
69+
Make sure that you add the model variable here, as well as any info on the variable's grid.
70+
71+
The available variable names (`MODEL_INPUT_VARNAMES`, `MODEL_OUTPUT_VARNAMES`), their units (`VARNAME_UNITS`), datatypes (`VARNAME_DTYPE`) and grids (`VARNAME_GRID`) are defined in constants at the top of the file `PyStemmusScope/bmi/implementation.py`.
72+
These have to be updated to reflect the changes in the state file.
73+
74+
Lastly you have to update the `get_variable` and `set_variable` functions in `PyStemmusScope/bmi/implementation.py`.
75+
Here you define how the python code can access them.
76+
While writing the code you can inspect the state using `model.state`, which allows you to view the full contents of the HDF5 file for easier debugging.
77+
78+
When you release a new Docker image that is compatible with the new BMI implementation, you need to update the `compatible_tags` variable of the class `StemmusScopeDocker` in `PyStemmusScope/bmi/docker_process.py`.

‎docs/notebooks/BMI_demo.ipynb‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
"outputs": [],
1919
"source": [
2020
"cfg_file = \"/home/bart/tmp/stemmus_scope/config_docker.txt\"\n",
21-
"# cfg_file = \"/home/bart/tmp/stemmus_scope/config_exe.txt\""
21+
"#cfg_file = \"/home/bart/tmp/stemmus_scope/config_exe.txt\""
2222
]
2323
},
2424
{
@@ -35,6 +35,7 @@
3535
"outputs": [],
3636
"source": [
3737
"if \"exe.txt\" in cfg_file:\n",
38+
" from PyStemmusScope.config_io import read_config\n",
3839
" import os\n",
3940
" os.environ['LD_LIBRARY_PATH'] = (\n",
4041
" \"/home/bart/matlab_runtime/R2023a/runtime/glnxa64:\"\n",
@@ -43,7 +44,7 @@
4344
" \"/home/bart/matlab_runtime/R2023a/extern/bin/glnxa64:\"\n",
4445
" \"/home/bart/matlab_runtime/R2023a/sys/opengl/lib/glnxa64\"\n",
4546
" )\n",
46-
" os.environ[\"STEMMUS_SCOPE\"] = \"/home/bart/Downloads/STEMMUS_SCOPE\""
47+
" os.environ[\"STEMMUS_SCOPE\"] = read_config(cfg_file)[\"ExeFilePath\"]"
4748
]
4849
},
4950
{
@@ -158,7 +159,7 @@
158159
},
159160
{
160161
"cell_type": "code",
161-
"execution_count": 7,
162+
"execution_count": 6,
162163
"metadata": {},
163164
"outputs": [
164165
{
@@ -167,7 +168,7 @@
167168
"array([22.74423625])"
168169
]
169170
},
170-
"execution_count": 7,
171+
"execution_count": 6,
171172
"metadata": {},
172173
"output_type": "execute_result"
173174
}
@@ -188,7 +189,7 @@
188189
},
189190
{
190191
"cell_type": "code",
191-
"execution_count": 8,
192+
"execution_count": 7,
192193
"metadata": {},
193194
"outputs": [
194195
{
@@ -222,7 +223,7 @@
222223
},
223224
{
224225
"cell_type": "code",
225-
"execution_count": 9,
226+
"execution_count": 8,
226227
"metadata": {},
227228
"outputs": [],
228229
"source": [
@@ -255,7 +256,7 @@
255256
},
256257
{
257258
"cell_type": "code",
258-
"execution_count": 10,
259+
"execution_count": 9,
259260
"metadata": {},
260261
"outputs": [],
261262
"source": [
@@ -272,16 +273,16 @@
272273
},
273274
{
274275
"cell_type": "code",
275-
"execution_count": 11,
276+
"execution_count": 10,
276277
"metadata": {},
277278
"outputs": [
278279
{
279280
"data": {
280281
"text/plain": [
281-
"<matplotlib.collections.QuadMesh at 0x7f881ab5f010>"
282+
"<matplotlib.collections.QuadMesh at 0x7f082b8b4760>"
282283
]
283284
},
284-
"execution_count": 11,
285+
"execution_count": 10,
285286
"metadata": {},
286287
"output_type": "execute_result"
287288
},
@@ -309,7 +310,7 @@
309310
},
310311
{
311312
"cell_type": "code",
312-
"execution_count": 6,
313+
"execution_count": 11,
313314
"metadata": {},
314315
"outputs": [],
315316
"source": [
@@ -326,7 +327,7 @@
326327
],
327328
"metadata": {
328329
"kernelspec": {
329-
"display_name": "PyStemmusScope",
330+
"display_name": "Python 3 (ipykernel)",
330331
"language": "python",
331332
"name": "python3"
332333
},
@@ -344,5 +345,5 @@
344345
}
345346
},
346347
"nbformat": 4,
347-
"nbformat_minor": 2
348+
"nbformat_minor": 4
348349
}

‎mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ nav:
66
- Getting started: index.md
77
- Installation: installation_instructions.md
88
- Notebook page: notebooks/run_model_in_notebook.ipynb
9+
- BMI:
10+
"BMI instructions": bmi.md
11+
"BMI demonstration": notebooks/BMI_demo.ipynb
912
- Contributing guide: CONTRIBUTING.md
1013
- API reference: reference.md
1114

0 commit comments

Comments
 (0)