Skip to content

Commit

Permalink
update text in bmi doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@SarahAlidoost
SarahAlidoost committed Jan 8, 2025
1 parent 6a495a8 commit 315de8c
Show file tree
Hide file tree
Showing 2 changed files with 56 additions and 37 deletions.
87 changes: 54 additions & 33 deletions docs/bmi.md
View file
Original file line number Diff line number Diff line change
@@ -1,63 +1,84 @@
# Basic Model Interface

The [Basic Model Interface](https://csdms.colorado.edu/wiki/BMI) is a standard way of communicating with models.
PyStemmusScope implements the Basic Model Interface for STEMMUS_SCOPE.

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

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

## Installation and setup

### Dockerized executable

STEMMUS_SCOPE has a Docker image available. This allows you to run the executable file without having to install MCR.
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).
STEMMUS_SCOPE has a Docker image available. This allows you to run the
executable file without having to install MCR. The Docker image is available at
[https://ghcr.io/ecoextreml/stemmus_scope](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). To use
the Docker image, use the `DockerImage` setting in the configuration file:

To use the Docker image, use the `DockerImage` setting in the configuration file:
```sh
WorkDir=/home/username/tmp/stemmus_scope
...
DockerImage=ghcr.io/ecoextreml/stemmus_scope:1.6.2
```

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.

Note that the `docker` package for python is required here. Install this with `pip install PyStemmusScope[docker]`.
Additionally, [Docker](https://docs.docker.com/get-docker/) itself has to be installed.
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. Note that the `docker` package
for python is required. Install this with `pip install PyStemmusScope[docker]`.
Additionally, [Docker](https://docs.docker.com/get-docker/) itself has to be
installed.

### Local executable file

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).
You can run the model using the executable file. It can be downloaded from the
STEMMUS_SCOPE repository,
[here](https://github.com/EcoExtreML/STEMMUS_SCOPE/tree/main/run_model_on_snellius/exe).
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). To use
the local executable file, add the path to the executable file to the config
file. E.g.:

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).

To use the local executable file, add the path to the executable file to the config file. E.g.:
```
WorkDir=/home/username/tmp/stemmus_scope
...
ExeFilePath=/path/to/executable/STEMMUS_SCOPE
```

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.
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.

## Using the BMI

A [notebook demonstration the use of the Basic Model Interface](notebooks/BMI_demo.ipynb) is available.
For more information on using BMI, see the [CSDMS website](https://csdms.colorado.edu/wiki/BMI).

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.

## grpc4bmi

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/).

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.

A demonstration is available [here](notebooks/grpc4bmi_demo.ipynb)
A [notebook demonstration the use of the Basic Model
Interface](notebooks/BMI_demo.ipynb) is available. For more information on using
BMI, see the [CSDMS website](https://csdms.colorado.edu/wiki/BMI).

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.

## Using grpc4bmi

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/). 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. Only set the `STEMMUS_SCOPE` environmental variable with a path to
the executable file. A demonstration is available
[here](notebooks/grpc4bmi_demo.ipynb).

## Developer instructions

Expand Down
6 changes: 2 additions & 4 deletions docs/getting_started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,5 @@ set in the configuration file:
## Running the model

If you want to run the model using `PyStemmusScope`, follow the instructions in
the `installation` and `Run the model` documentation.

If you want to add changes to the package `PyStemmusScope`, follow `Contributing
guide` documnetation.
the `installation` and `Run the model` documentation. If you want to add changes
to the package `PyStemmusScope`, follow `Contributing guide` documnetation.

0 comments on commit 315de8c

Please sign in to comment.