Set up examples of running containerized model

.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Docker Hub
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      - '!v[0-9]+.[0-9]+.[0-9]+[ab][0-9]+'
+
+env:
+  REPO: csdms/cem-grpc4bmi
+
+jobs:
+
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Get version
+        id: vars
+        run: echo "version=${GITHUB_REF:11}" >> $GITHUB_OUTPUT
+
+      - name: Set up Docker buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          platforms: linux/amd64,linux/arm64
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ env.REPO }}:latest,${{ env.REPO }}:${{ steps.vars.outputs.version }}

.github/workflows/test.yml

@@ -0,0 +1,49 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: '47 4 3 * *'  # 4:47a on third day of the month
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+
+  test:
+    name: Run tests
+    if:
+      github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+    runs-on: ${{ matrix.os }}
+
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install requirements
+        run: pip install pytest nbmake -r examples/requirements.txt
+
+      - name: Check example script
+        working-directory: ${{ github.workspace }}/examples
+        run: |
+          python run-model-through-grpc4bmi.py
+
+      - name: Check example notebook
+        run: |
+          pytest examples --nbmake --nbmake-timeout=3000 -v

README.md

@@ -42,6 +42,23 @@ If the image isn't found locally, it's pulled from Docker Hub
 For more in-depth examples of running the CEM model through grpc4bmi,
 see the [examples](./examples) directory.
 
+## Developer notes
+
+A versioned, multiplatform image is hosted on Docker Hub
+at [csdms/cem-grpc4bmi](https://hub.docker.com/r/csdms/cem-grpc4bmi).
+This image is automatically built and pushed to Docker Hub
+with the [release](./.github/workflows/release.yml) CI workflow.
+The workflow is only run when the repository is tagged.
+To manually build and push an update, run:
+```
+docker buildx build --platform linux/amd64,linux/arm64 -t csdms/cem-grpc4bmi:latest --push .
+```
+A user can pull this image from Docker Hub with:
+```
+docker pull csdms/cem-grpc4bmi
+```
+optionally with the `latest` tag or with a version tag.
+
 ## Acknowledgment
 
 This work is supported by the U.S. National Science Foundation under Award No. [2103878](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2103878), *Frameworks: Collaborative Research: Integrative Cyberinfrastructure for Next-Generation Modeling Science*.

examples/README.md

@@ -0,0 +1,24 @@
+# examples
+
+Two examples--a [Python script](./run-model-through-grpc4bmi.py)
+and a [Jupyter notebook](./run-model-through-grpc4bmi.ipynb)--that demonstrate how to run
+the CEM model through the grpc4bmi server built in this project.
+
+In a virtual environment,
+install grpc4bmi and other dependencies:
+```sh
+pip install -r requirements.txt
+```
+
+Run the Python example:
+```sh
+python run-model-through-grpc4bmi.py
+```
+It'll produce output in the terminal,
+as well as two image files,
+`shoreline_initial.png` and `shoreline_final.png`.
+
+Start JupyterLab and run the example notebook:
+```sh
+jupyter lab run-model-through-grpc4bmi.ipynb
+```

examples/cem.txt

@@ -0,0 +1,2 @@
+50, 1000, 1000.0, 1
+0.01, 10.0, 0.001

examples/requirements.txt

@@ -0,0 +1,4 @@
+grpc4bmi
+jupyter
+matplotlib
+tqdm