Skip to content

Basic Model Interface

The Basic Model Interface 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 https://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. To use the Docker image, use the DockerImage setting in the configuration file:

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. Install this with pip install PyStemmusScope[docker]. Additionally, Docker itself has to be installed.

Local executable file

You can run the model using the executable file. It can be downloaded from the STEMMUS_SCOPE repository, here. To be able to run this executable, you need a Linux x86 system, along with Matlab Compiler Runtime R2023a. MCR is available here. 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.

Using the BMI

A notebook demonstration the use of the Basic Model Interface is available. For more information on using BMI, see the CSDMS website.

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, or leave a comment if an issue is open already.

Using grpc4bmi

A Docker image is available 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 and allows communication with a STEMMUS_SCOPE BMI through grpc4bmi. 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.

Developer instructions

Follow the instructions in the Contributing Guide.