# Remote BMI
[](CODE_OF_CONDUCT.md)
[](https://app.codecov.io/gh/eWaterCycle/remotebmi)
The [Basic Model Interface (BMI)](https://bmi.readthedocs.io/en/stable/) is a standard interface for models.
The interface is available in different languages and a [language agnosting version in SIDL](https://github.com/csdms/bmi/blob/stable/bmi.sidl).
To have a consumer of the model and the provider of the model seperated you can use [grpc4bmi](https://grpc4bmi.readthedocs.io/), but this only works on languages that have a grpc implementation.
This Python package replaced the gRPC protocol with an REST API.
The [REST API specification](https://github.com/eWaterCycle/remotebmi/blob/main/openapi.yaml) is in the [OpenAPI](https://swagger.io/specification/) format.
Remotebmi is available in other languages see [here](https://github.com/eWaterCycle/remotebmi?tab=readme-ov-file#structure).
## Difference from BMI
- Request body and response body are in JSON format
- On errors you get 4xx and 5xx responses with [Problem Details](https://tools.ietf.org/html/rfc7807) as response body
- Variable names must be URL safe
- Variable type must be in enum.
- get_value_ptr function is not available
## Consumer
Installation
```shell
pip install remotebmi
```
A client can connect to a running server with the following code.
```python
from remotebmi import RemoteBmiClient
model = RemoteBmiClient('http://localhost:50051')
# Now you can use the BMI methods on model
# for example
model.initialize('config.file')
model.update()
model.get_value('var_name')
```
A client can also start a [Apptainer](https://apptainer.org) container containing the model and the server.
```python
from remotebmi import BmiClientApptainer
model = BmiClientApptainer('my_model.sif', work_dir='/tmp')
```
The client picks a random port and expects the container to run the BMI web server on that port.
The port is passed to the container using the `BMI_PORT` environment variable.
A client can also start a [Docker](https://docs.docker.com/engine/) container containing the model and the server.
```python
from remotebmi import BmiClientDocker
model = BmiClientDocker('ewatercycle/wflowjl:0.7.3', work_dir='/tmp')
```
The BMI web server inside the Docker container should be running on port 50051.
If the port is different, you can pass the port as the `image_port` argument to the `BmiClientDocker` constructor.
## Provider
Given you have a model class called `MyModel` in a package `mypackage` then the web service can be started with the following command.
```shell
BMI_MODULE=mypackage BMI_CLASS=MyModel run-bmi-server
```
For example [leakybucket](https://github.com/eWaterCycle/leakybucket-bmi):
```shell
pip install leakybucket
BMI_MODULE=leakybucket.leakybucket_bmi BMI_CLASS=LeakyBucketBmi run-bmi-server
```
and the client can connect to it with the following code.
```python
> from remotebmi import RemoteBmiClient
> client = RemoteBmiClient('http://localhost:50051')
> client.get_component_name()
leakybucket
```
## Documentation
In a Python environment, go to the docs directory, do `pip install -r requirements.txt`
and then `make html`.
Raw data
{
"_id": null,
"home_page": null,
"name": "remotebmi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "BMI, Basic Model Interface, ewatercycle",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c9/b8/72cd61914903a2c174edbffa0b94c56fce17d4c1dbe4a8c86180f06a71f9/remotebmi-0.1.0.tar.gz",
"platform": null,
"description": "# Remote BMI\n\n[](CODE_OF_CONDUCT.md)\n[](https://app.codecov.io/gh/eWaterCycle/remotebmi)\n\nThe [Basic Model Interface (BMI)](https://bmi.readthedocs.io/en/stable/) is a standard interface for models. \nThe interface is available in different languages and a [language agnosting version in SIDL](https://github.com/csdms/bmi/blob/stable/bmi.sidl).\n\nTo have a consumer of the model and the provider of the model seperated you can use [grpc4bmi](https://grpc4bmi.readthedocs.io/), but this only works on languages that have a grpc implementation.\nThis Python package replaced the gRPC protocol with an REST API.\nThe [REST API specification](https://github.com/eWaterCycle/remotebmi/blob/main/openapi.yaml) is in the [OpenAPI](https://swagger.io/specification/) format.\n\nRemotebmi is available in other languages see [here](https://github.com/eWaterCycle/remotebmi?tab=readme-ov-file#structure).\n\n## Difference from BMI\n\n- Request body and response body are in JSON format\n- On errors you get 4xx and 5xx responses with [Problem Details](https://tools.ietf.org/html/rfc7807) as response body\n- Variable names must be URL safe\n- Variable type must be in enum.\n- get_value_ptr function is not available\n\n## Consumer\n\nInstallation\n\n```shell\npip install remotebmi\n```\n\nA client can connect to a running server with the following code.\n\n```python\nfrom remotebmi import RemoteBmiClient\n\nmodel = RemoteBmiClient('http://localhost:50051')\n# Now you can use the BMI methods on model\n# for example\nmodel.initialize('config.file')\nmodel.update()\nmodel.get_value('var_name')\n```\n\nA client can also start a [Apptainer](https://apptainer.org) container containing the model and the server.\n\n```python\nfrom remotebmi import BmiClientApptainer\n\nmodel = BmiClientApptainer('my_model.sif', work_dir='/tmp')\n```\n\nThe client picks a random port and expects the container to run the BMI web server on that port.\nThe port is passed to the container using the `BMI_PORT` environment variable.\n\nA client can also start a [Docker](https://docs.docker.com/engine/) container containing the model and the server.\n\n```python\nfrom remotebmi import BmiClientDocker\n\nmodel = BmiClientDocker('ewatercycle/wflowjl:0.7.3', work_dir='/tmp')\n```\n\nThe BMI web server inside the Docker container should be running on port 50051.\nIf the port is different, you can pass the port as the `image_port` argument to the `BmiClientDocker` constructor.\n\n## Provider\n\nGiven you have a model class called `MyModel` in a package `mypackage` then the web service can be started with the following command.\n\n```shell\nBMI_MODULE=mypackage BMI_CLASS=MyModel run-bmi-server \n```\n\nFor example [leakybucket](https://github.com/eWaterCycle/leakybucket-bmi):\n\n```shell\npip install leakybucket\nBMI_MODULE=leakybucket.leakybucket_bmi BMI_CLASS=LeakyBucketBmi run-bmi-server\n```\n\nand the client can connect to it with the following code.\n\n```python\n> from remotebmi import RemoteBmiClient\n> client = RemoteBmiClient('http://localhost:50051')\n> client.get_component_name()\nleakybucket\n```\n\n## Documentation\n\nIn a Python environment, go to the docs directory, do `pip install -r requirements.txt`\nand then `make html`.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Basic Model Interface over openapi specification",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/eWaterCycle/remotebmi#readme",
"Homepage": "https://github.com/eWaterCycle/remotebmi",
"Issues": "https://github.com/eWaterCycle/remotebmi/issues",
"Source": "https://github.com/eWaterCycle/remotebmi"
},
"split_keywords": [
"bmi",
" basic model interface",
" ewatercycle"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dab9abbfa2a098c8d0690068ad02c6558629ab583a6cda0308d89e7b204b5461",
"md5": "aac091b77b320192a7e384baba293527",
"sha256": "c6e9c198379478637d33d8d940934429d054afddc0f72dad869d1e990bec5e93"
},
"downloads": -1,
"filename": "remotebmi-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aac091b77b320192a7e384baba293527",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16871,
"upload_time": "2024-11-22T11:50:56",
"upload_time_iso_8601": "2024-11-22T11:50:56.717866Z",
"url": "https://files.pythonhosted.org/packages/da/b9/abbfa2a098c8d0690068ad02c6558629ab583a6cda0308d89e7b204b5461/remotebmi-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c9b872cd61914903a2c174edbffa0b94c56fce17d4c1dbe4a8c86180f06a71f9",
"md5": "609078c7c58588fcb68cd49d155ef024",
"sha256": "396a37f126df7207f12d16874130e0d490e51065f58c7c2faa45bb10a5ce863f"
},
"downloads": -1,
"filename": "remotebmi-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "609078c7c58588fcb68cd49d155ef024",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 55547,
"upload_time": "2024-11-22T11:50:58",
"upload_time_iso_8601": "2024-11-22T11:50:58.108511Z",
"url": "https://files.pythonhosted.org/packages/c9/b8/72cd61914903a2c174edbffa0b94c56fce17d4c1dbe4a8c86180f06a71f9/remotebmi-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 11:50:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eWaterCycle",
"github_project": "remotebmi#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "remotebmi"
}
JSON
