grpc4bmi

目的

本软件允许您将您的 基本模型接口（BMI） 实现封装在服务器进程中，并通过包含的 Python 客户端与其通信。通信通过 GRPC 序列化为协议缓冲区，并在网络端口上发生。可以使用 Docker 或 Apptainer 在隔离容器中运行模型。

安装

可选地，创建您的虚拟环境并激活它，然后，在客户端（Python）端运行

pip install grpc4bmi

如果您的服务器模型是用 Python 实现的，则在服务器环境（例如 Docker 容器）中执行相同的操作。如果模型是用 R 实现的，则运行

pip install grpc4bmi[R]

如果模型是用 Julia 实现的，则在服务器环境中运行

pip install grpc4bmi[julia]

要从 GitHub 获取最新版本，请使用

pip install git+https://github.com/eWaterCycle/grpc4bmi.git#egg=grpc4bmi

最后，如果模型是用 C 或 C++ 实现的，请在此 git 仓库中克隆它，并在 cpp 文件夹中运行

make
make install

。

使用方法

用 Python 编写的模型

模型应该是 bmipy 包中的 Bmi 类的子类。

为了获取灵感，请查看测试目录中的 示例。

要启动一个服务器进程，该进程允许调用您的 BMI 实现，请输入

run-bmi-server --name <PACKAGE>.<MODULE>.<CLASS> --port <PORT> --path <PATH>

其中 <PACKAGE> 和 <MODULE> 是包含您的实现的 Python 包和模块，<CLASS> 是您的 bmi 模型类名，<PORT> 是主机系统上的任何可用端口，并且可选的 <PATH> 表示应添加到系统路径以使实现正常工作的附加路径。上面的名称选项是可选的，如果不提供，则脚本将查找环境变量 BMI_PACKAGE、BMI_MODULE 和 BMI_CLASS。同样，端口也可以由环境变量 BMI_PORT 定义。此软件假定您的实现构造函数没有参数。

C/C++ 编写的模型（beta版本）

创建一个类似于 cpp/run-bmi-server.cc 的可执行文件。您可以复制该文件并替换函数

Bmi* create_model_instance()
{
    /* Return your new BMI instance pointer here... */
}

用您的模型 BMI 的实例化来替换。模型需要实现 C 的 csdms BMI，但您也可以实现我们的更面向对象的 C++ 接口 BmiCppExtension。

R 编写的模型

如果模型是 AbstractBmi 的子类，则 grpc4bmi Python 包也可以运行用 R 编写的 BMI 模型。有关 R 和 Docker 的说明，请参阅 https://github.com/eWaterCycle/bmi-r。

用以下命令运行 R 模型作为服务器

run-bmi-server --lang R [--path <R file with BMI model>] --name [<PACKAGE>::]<CLASS> --port <PORT>

例如，使用 WALRUS，请使用

run-bmi-server --lang R --path ~/git/eWaterCycle/grpc4bmi-examples/walrus/walrus-bmi.r --name WalrusBmi --port 55555

用 Julia 编写的模型

如果模型实现了 BasicModelInterface.jl，则 grpc4bmi Python 包也可以运行用 Julia 编写的 BMI 模型。

用以下命令在 Python 中运行 Julia 模型

from grpc4bmi.bmi_julia_model import BmiJulia

mymodel = BmiJulia.from_name('<package>.<model>', 'BasicModelInterface')

例如，使用 Wflow.jl，请使用

# Install Wflow.jl package in the Julia environment managed by the juliacall Python package.
from juliacall import Main as jl
jl.Pkg.add("Wflow")
# Create the model
from grpc4bmi.bmi_julia_model import BmiJulia
mymodel = BmiJulia.from_name('Wflow.Model', 'Wflow.bmi.BMI')

Julia 模型必须在本地运行。它不能在默认的 gRPC 客户端/服务器 Docker 容器模式下运行，因为

1. Julia 没有gRPC服务器实现
2. 从 Python gRPC 服务器调用 Julia 方法会导致 100% CPU 使用率且没有进度
3. 从 C++ gRPC 服务器调用 Julia 方法会导致段错误

客户端

客户端仅有一种 Python 实现。默认 BMI 客户端假定在给定的端口上有一个正在运行的服务器进程。

from grpc4bmi.bmi_grpc_client import BmiClient
import grpc
mymodel = BmiClient(grpc.insecure_channel("localhost:<PORT>"))
print mymodel.get_component_name()
mymodel.initialize(<FILEPATH>)
...further BMI calls...

该包还包括一个客户端实现，它拥有服务器进程，可以是运行 run-bmi-server 脚本的 Python 子进程、Docker 容器、Singularity 容器或 Apptainer 容器。例如

from grpc4bmi.bmi_client_subproc import BmiClientSubProcess
mymodel = BmiClientSubProcess(<PACKAGE>.<MODULE>.<CLASS>)

将自动在子进程中启动服务器

from grpc4bmi.bmi_client_docker import BmiClientDocker
mymodel = BmiClientDocker(<IMAGE>, <WORK DIR TO MOUNT>, input_dirs=[<INPUT DIRECTORIES TO MOUNT>])

将基于提供的Docker镜像启动Docker容器，并将提供的目录挂载以在容器和主机之间共享文件。

from grpc4bmi.bmi_client_singularity import BmiClientSingularity
mymodel = BmiClientSingularity(<IMAGE>, <WORK DIR TO MOUNT>, input_dirs=[<INPUT DIRECTORIES TO MOUNT>])

将基于提供的Singularity镜像启动singularity容器，并将提供的目录挂载以在容器和主机之间共享文件。

from grpc4bmi.bmi_client_apptainer import BmiClientApptainer
mymodel = BmiClientApptainer(<IMAGE>, <WORK DIR TO MOUNT>, input_dirs=[<INPUT DIRECTORIES TO MOUNT>])

将基于提供的Apptainer镜像启动Apptainer容器，并将提供的目录挂载以在容器和主机之间共享文件。

更多文档请参阅 https://grpc4bmi.readthedocs.io/。

开发：生成gRPC代码

当开发者更改proto文件时，需要在Python环境中安装gRPC工具Python包。

# Create virtual env
python3 -m venv .venv
. venv/bin/activate
# Make sure latest pip and wheel are install
pip install -U pip wheel
pip install -r dev-requirements.txt
# For R integration also install the R extras with
pip install -e .[R]
# For building docs (cd docs && make html) also install the docs extras with
pip install -e .[docs]

并按照https://github.com/google/protobuf/blob/master/src/README.md中描述安装C++运行时和protoc命令。之后，只需执行proto_gen.sh脚本即可。