Skip to content

Commit 315de8c

Browse files
SarahAlidoostSarahAlidoost
committed
update text in bmi doc
1 parent 6a495a8 commit 315de8c

2 files changed

Lines changed: 56 additions & 37 deletions

File tree

‎docs/bmi.md‎

Lines changed: 54 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,84 @@
11
# Basic Model Interface
22

3-
The [Basic Model Interface](https://csdms.colorado.edu/wiki/BMI) is a standard way of communicating with models.
4-
PyStemmusScope implements the Basic Model Interface for STEMMUS_SCOPE.
5-
6-
There are multiple ways to run the STEMMUS_SCOPE Basic Model Interface.
7-
For the model, we generated Matlab Compiler Runtime executable file (only available for x86 Linux).
8-
This requires installation of MCR.
9-
The other option is to use the Dockerized version of the executable, available on ghcr.io/ecoextreml/stemmus_scope.
10-
11-
For more information on each method, see the sections below.
3+
The [Basic Model Interface](https://csdms.colorado.edu/wiki/BMI) is a standard
4+
way of communicating with models. PyStemmusScope implements the Basic Model
5+
Interface for STEMMUS_SCOPE. There are multiple ways to run the STEMMUS_SCOPE
6+
Basic Model Interface. For the model, we generated Matlab Compiler Runtime
7+
executable file (only available for x86 Linux). This requires installation of
8+
MCR. The other option is to use the Dockerized version of the executable,
9+
available on
10+
[ghcr.io/ecoextreml/stemmus_scope](ghcr.io/ecoextreml/stemmus_scope). For more
11+
information on each method, see the sections below.
1212

1313
## Installation and setup
1414

1515
### Dockerized executable
1616

17-
STEMMUS_SCOPE has a Docker image available. This allows you to run the executable file without having to install MCR.
18-
The Docker image is available at https://ghcr.io/ecoextreml/stemmus_scope. The Docker image is created using the docker file [here](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/Dockerfile).
17+
STEMMUS_SCOPE has a Docker image available. This allows you to run the
18+
executable file without having to install MCR. The Docker image is available at
19+
[https://ghcr.io/ecoextreml/stemmus_scope](https://ghcr.io/ecoextreml/stemmus_scope).
20+
The Docker image is created using the docker file
21+
[here](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/Dockerfile). To use
22+
the Docker image, use the `DockerImage` setting in the configuration file:
1923

20-
To use the Docker image, use the `DockerImage` setting in the configuration file:
2124
```sh
2225
WorkDir=/home/username/tmp/stemmus_scope
2326
...
2427
DockerImage=ghcr.io/ecoextreml/stemmus_scope:1.6.2
2528
```
2629

27-
It is best to add the version tag here too (`:1.6.2`), this way the BMI will warn you if the version might be incompatible.
28-
29-
Note that the `docker` package for python is required here. Install this with `pip install PyStemmusScope[docker]`.
30-
Additionally, [Docker](https://docs.docker.com/get-docker/) itself has to be installed.
30+
It is best to add the version tag here too (`:1.6.2`), this way the BMI will
31+
warn you if the version might be incompatible. Note that the `docker` package
32+
for python is required. Install this with `pip install PyStemmusScope[docker]`.
33+
Additionally, [Docker](https://docs.docker.com/get-docker/) itself has to be
34+
installed.
3135

3236
### Local executable file
3337

34-
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).
38+
You can run the model using the executable file. It can be downloaded from the
39+
STEMMUS_SCOPE repository,
40+
[here](https://github.com/EcoExtreML/STEMMUS_SCOPE/tree/main/run_model_on_snellius/exe).
41+
To be able to run this executable, you need a Linux x86 system, along with
42+
Matlab Compiler Runtime R2023a. MCR is available
43+
[here](https://nl.mathworks.com/products/compiler/matlab-runtime.html). To use
44+
the local executable file, add the path to the executable file to the config
45+
file. E.g.:
3546

36-
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).
37-
38-
To use the local executable file, add the path to the executable file to the config file. E.g.:
3947
```
4048
WorkDir=/home/username/tmp/stemmus_scope
4149
...
4250
ExeFilePath=/path/to/executable/STEMMUS_SCOPE
4351
```
4452

45-
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.
53+
Alternatively, if the environmental variable `STEMMUS_SCOPE` is configured, the
54+
BMI will use this if the ExeFilePath or DockerImage are not set in the
55+
configuration file.
4656

4757
## Using the BMI
4858

49-
A [notebook demonstration the use of the Basic Model Interface](notebooks/BMI_demo.ipynb) is available.
50-
For more information on using BMI, see the [CSDMS website](https://csdms.colorado.edu/wiki/BMI).
51-
52-
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.
53-
54-
## grpc4bmi
55-
56-
A [Docker image is available](https://ghcr.io/ecoextreml/stemmus_scope-grpc4bmi) in which the model as well as the Python BMI have been wrapped in a container. The Docker image is created using the Docker file [here](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/blob/main/Dockerfile) and allows communication with a STEMMUS_SCOPE BMI through [grpc4bmi](https://grpc4bmi.readthedocs.io/en/latest/).
57-
58-
Doing so avoids the needs to install PyStemmusScope yourself, only Docker/apptainer and a python environment with grpc4bmi are required. Please note you should not specify `DockerImage` or `ExeFilePath` in the config file if you are using the grpc4bmi interface.
59-
60-
A demonstration is available [here](notebooks/grpc4bmi_demo.ipynb)
59+
A [notebook demonstration the use of the Basic Model
60+
Interface](notebooks/BMI_demo.ipynb) is available. For more information on using
61+
BMI, see the [CSDMS website](https://csdms.colorado.edu/wiki/BMI).
62+
63+
If you need access to other model variables that are not yet available in the
64+
BMI, please raise an issue on the [STEMMUS_SCOPE
65+
repository](https://github.com/EcoExtreML/STEMMUS_SCOPE/issues), or leave a
66+
comment if an issue is open already.
67+
68+
## Using grpc4bmi
69+
70+
A [Docker image is available](https://ghcr.io/ecoextreml/stemmus_scope-grpc4bmi)
71+
in which the model as well as the Python BMI have been wrapped in a container.
72+
The Docker image is created using the Docker file
73+
[here](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/blob/main/Dockerfile)
74+
and allows communication with a STEMMUS_SCOPE BMI through
75+
[grpc4bmi](https://grpc4bmi.readthedocs.io/en/latest/). Doing so avoids the
76+
needs to install PyStemmusScope yourself, only Docker/apptainer and a python
77+
environment with grpc4bmi are required. Please note you should not specify
78+
`DockerImage` or `ExeFilePath` in the config file if you are using the grpc4bmi
79+
interface. Only set the `STEMMUS_SCOPE` environmental variable with a path to
80+
the executable file. A demonstration is available
81+
[here](notebooks/grpc4bmi_demo.ipynb).
6182

6283
## Developer instructions
6384

‎docs/getting_started.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,5 @@ set in the configuration file:
3535
## Running the model
3636

3737
If you want to run the model using `PyStemmusScope`, follow the instructions in
38-
the `installation` and `Run the model` documentation.
39-
40-
If you want to add changes to the package `PyStemmusScope`, follow `Contributing
41-
guide` documnetation.
38+
the `installation` and `Run the model` documentation. If you want to add changes
39+
to the package `PyStemmusScope`, follow `Contributing guide` documnetation.

0 commit comments

Comments
 (0)