Python
If you have a BMI-compliant model written in python, grpc4bmi provides a quick way to set up a BMI service.
Installing Requirements
The grpc4bmi Python package should be installed.
Creating
To obtain a python BMI for your model, install the Python bmi package (bmipy) and implement the bmipy.Bmi
abstract base class for your model. For exposing this model as a GRPC service, it is necessary to have a constructor without arguments: all initialization state will be presented to the model via the configuration file in the initialize
method.
Running
The installation of the grpc4bmi package installs the run-bmi-server
command. You can run your model as a service by typing
$ run-bmi-server --name <PACKAGE>.<MODULE>.<CLASS>
where <PACKAGE>
, <MODULE>
are the python package and module containing your python BMI model, which should contain a python class <CLASS>
that implements Bmi. The script assumes that this class does not take any constructor arguments. Upon running, the server will report which networking port it has decided to use on the terminal. This port will later be needed by BMI clients to communicate with your service.
The port can also be specified by adding the option --port <PORT>
or pre-define the environment variable BMI_PORT
(the latter takes precedence over the former).
An extra system path can be specified by adding the option --path <PATH>
or pre-define the environment variable BMI_PATH
.
Example
As an example, suppose we have a package
$ mypackage
$ - __init__.py
$ - mymodule.py
and inside the mymodule.py
the bmi implementation
from bmipy import Bmi
class MyBmi(Bmi):
def __init__(self):
...
def get_component_name(self):
return "Hello world"
Then we launch this toy model as a service by executing
$ run-bmi-server --name mypackage.mymodule.MyBmi
This will report the chosen port number in the standard output stream. It can be used to connect to the service via the BMI grpc python client.
Legacy version
The grpc4bmi by default uses the v2.0 version of the Basic Model Interface (BMI) on the client and server side. Grpc4bmi has support for legacy version 0.2 of BMI on the server side.
A legacy model can be launched with
$ run-bmi-server --bmi-version 0.2 --name mypackage.mymodule.MyLegacyBmi
The functions only present in BMI v0.2 will not be callable:
update_frac
get_grid_connectivity
get_grid_offset
The functions only present in BMI v2.0 will throw not implemented errors:
get_var_location
get_grid_node_count
get_grid_edge_count
get_grid_face_count
get_grid_edge_nodes
get_grid_face_nodes
get_grid_face_edges
get_grid_nodes_per_face