Add gprc4bmi dockerfile, instructions/docs.

Dockerfile

@@ -1,11 +1,13 @@
-
 FROM ghcr.io/ecoextreml/stemmus_scope:1.5.0
+
+LABEL maintainer="Bart Schilperoort <[email protected]>"
 LABEL org.opencontainers.image.source = "https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing"
 
 # Requirements for building Python 3.10
 RUN apt-get update && apt-get -y upgrade
 RUN apt-get install -y build-essential zlib1g-dev libncurses5-dev libgdbm-dev \
     libnss3-dev libssl-dev libreadline-dev libffi-dev libsqlite3-dev wget libbz2-dev
+RUN apt-get install -y libhdf5-serial-dev
 
 # Get Python source and compile
 WORKDIR /python
@@ -22,9 +24,10 @@ COPY . /opt/PyStemmusScope
 RUN pip3.10 install /opt/PyStemmusScope/[docker]
 RUN pip3.10 install grpc4bmi==0.5.0
 
-# Set the STEMMUS_SCOPE environmental variable, so the BMI can find the executable
+# # Set the STEMMUS_SCOPE environmental variable, so the BMI can find the executable
 WORKDIR /
-ENV STEMMUS_SCOPE ./STEMMUS_SCOPE
+ENV STEMMUS_SCOPE /STEMMUS_SCOPE
 
+EXPOSE 55555
 # Start grpc4bmi server
 CMD run-bmi-server --name "PyStemmusScope.bmi.implementation.StemmusScopeBmi" --port 55555 --debug

docs/bmi.md

@@ -43,11 +43,20 @@ Alternatively, if the environmental variable `STEMMUS_SCOPE` is configured, the
 
 ## Using the BMI
 
-A [notebook demonstration the use of the Basic Model Interface](../notebooks/BMI_demo/) is available.
+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-gprc4bmi) in which the model as well as the Python BMI have been wrapped in a container.
+This allows communication with a STEMMUS_SCOPE BMI through [gprc4bmi](https://grpc4bmi.readthedocs.io/en/latest/).
+
+Doing so avoids the needs to install PyStemmusScope yourself, only Docker/apptainer and a python environment with gprc4bmi are required.
+
+A demonstration is available [here](notebooks/gprc4bmi_demo.ipynb)
+
 ## Developer instructions
 
 The Python BMI implemented in this package communicates with the Matlab code through STDIN/STDOUT, or via a socket to the Docker container.

docs/notebooks/gprc4bmi_demo.ipynb

@@ -0,0 +1,149 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# grpc4bmi demonstration\n",
+    "\n",
+    "If you want to run the model plus BMI in a container, this is possible with the `stemmus_scope_grpc4bmi` docker image.\n",
+    "\n",
+    "The image contains both the STEMMUS_SCOPE model and the Python BMI. The interface uses [`grpc4bmi`](https://grpc4bmi.readthedocs.io/) for communication with the running container.\n",
+    "\n",
+    "To run this notebook you need to have grpc4bmi installed in your python environment."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from grpc4bmi.bmi_client_docker import BmiClientDocker\n",
+    "\n",
+    "model = BmiClientDocker(\n",
+    "    image='ghcr.io/ecoextreml/stemmus_scope-gprc4bmi:1.5.0', \n",
+    "    image_port=55555,\n",
+    "    work_dir=\"/home/bart/tmp/stemmus_scope\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can ensure that the model is named STEMMUS_SCOPE:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'STEMMUS_SCOPE'"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "model.get_component_name()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Initialization works like normal. Note that you do not want to have the `DockerImage` or `ExeFilePath` entries in your configuration file (!):"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": []
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "model.initialize(\"/home/bart/tmp/stemmus_scope/config_grpc4bmi.txt\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "model.update()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can succesfully request values from the model:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "array([3.6085965])"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import numpy as np\n",
+    "model.get_value(\"respiration\", dest=np.zeros(1))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "PyStemmusScope",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

mkdocs.yml

@@ -9,6 +9,7 @@ nav:
   - BMI:
     - "BMI instructions": bmi.md
     - "BMI demonstration": notebooks/BMI_demo.ipynb
+    - "grpc4bmi demonstration": notebooks/gprc4bmi_demo.ipynb
   - Contributing guide: CONTRIBUTING.md
   - API reference: reference.md