bmi-example-c-grpc4bmi

Set up a grpc4bmi server to run a containerized version of the Basic Model Interface (BMI) C example through Python.

Build

There are two options for building this project:

1. from a base image, source-base, where grpc and its dependent libraries, grpc4bmi, and the BMI C example are all built from source
2. from a base image, conda-base, where grpc and its dependent libraries are installed through conda-forge, the BMI C example is installed from a separate conda-based Docker image, and grpc4bmi is built from source

In each case, the grpc4bmi server is exposed through port 55555.

source-base

Build this example locally with:

docker build --tag bmi-example-c-grpc4bmi images/source-base

The image is (temporarily) built on the mdpiper/grpc4bmi base image. The OS is Linux/Ubuntu. The C BMI example, grpc4bmi, and the grpc4bmi server are installed in /usr/local.

conda-base

Build this example locally with:

docker build --tag bmi-example-c-grpc4bmi images/conda-base

The image is built on the csdms/grpc4bmi base image, which is built on the condaforge/miniforge3 base image. The OS is Linux/Ubuntu. The C BMI example, grpc4bmi, and the grpc4bmi server are installed in /opt/conda.

Run

Use the grpc4bmi Docker client to access the BMI methods of the containerized model.

Install with pip:

pip install grpc4bmi

Then, in a Python session, access the C Heat model in the image built above with:

from grpc4bmi.bmi_client_docker import BmiClientDocker


m = BmiClientDocker(image='bmi-example-c-grpc4bmi', image_port=55555, work_dir=".")
m.get_component_name()

del m  # stop container cleanly

If the image isn't found locally, it's pulled from Docker Hub (e.g., try the csdms/bmi-example-c-grpc4bmi image).

For more in-depth examples of running the Heat model through grpc4bmi, see the examples directory.

Developer notes

A versioned, multiplatform image built from the conda-base image in this repository is hosted on Docker Hub at csdms/bmi-example-c-grpc4bmi. This image is automatically built and pushed to Docker Hub with the release 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/bmi-example-c-grpc4bmi:latest --push .

A user can pull this image from Docker Hub with:

docker pull csdms/bmi-example-c-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, Frameworks: Collaborative Research: Integrative Cyberinfrastructure for Next-Generation Modeling Science.