# BSM2-Python
[](https://gitlab.rrze.fau.de/evt/klaeffizient/bsm2-python/-/commits/main)
[](https://gitlab.rrze.fau.de/evt/klaeffizient/bsm2-python/-/commits/main)
[](https://badge.fury.io/py/bsm2-python)
[](https://doi.org/10.5281/zenodo.5555555)
A Python implementation of the Benchmark Simulation Model 2 (BSM2) plant layout according to the [IWA](http://iwa-mia.org/) standard.
A technical description of BSM2 can be found [here](https://iwaponline.com/ebooks/book-pdf/650794/wio9781780401171.pdf).
## Installation
### Easy way
To run the project, install the latest release via PyPI:
`pip install bsm2-python`
### Build from source
If you want the bleeding edge version from the repo, build it yourself via `hatch build`.
See the [Contribution Guide](CONTRIBUTING.md) for more details on how to install `hatch` (or simply use the [Docker image](#docker)).
Then you can install it to arbitrary environments via `pip install dist/bsm2_python<version-hash>.whl`
## Quickstart
### Run default model
You could then use the following convenience function:
```python
from bsm2_python import BSM2OL
# initialise the BSM2 Open Loop model
bsm2_ol = BSM2OL()
# run the simulation
bsm2_ol.simulate()
```
This will run the BSM2 Open Loop model for the default 609 days of simulation time.
It will then plot IQI, EQI and OCI values for the effluent over the last few days of simulation.
Further, relevant data will be saved to `data/output_evaluation.csv` for further analysis.
### Run with custom aeration
You can also run the BSM2 models with your own aeration control - this example selects a random kla value for each reactor every timestep.
The final performance is then saved in the `oci` variable:
```python
import numpy as np
from bsm2_python import BSM2OL
from tqdm import tqdm
bsm2_ol = BSM2OL()
# The kla values to choose from
select_klas = np.array([0, 60, 120, 180, 240])
for idx, _ in enumerate(tqdm(bsm2_ol.simtime)):
# select random klas for all five ASM1 reactors
klas = np.random.choice(select_klas, 5)
# make a step in the simulation with the specified kla values
bsm2_ol.step(idx, klas)
oci = bsm2_ol.get_final_performance()[-1]
```
### Run Closed Loop simulation with custom DO setpoint
You can also run the BSM2 Closed Loop model with your own dissolved oxygen (SO4) setpoints.
Please note: The Closed Loop model runs with a resolution of 1 minute for the sake of sensor stability, so it might take a while to run the simulation.
```python
from bsm2_python import BSM2CL
from tqdm import tqdm
bsm2_cl = BSM2CL()
# The custom DO setpoint for the BSM2 default aeration control
so4_ref = 1.5
for idx, _ in enumerate(tqdm(bsm2_cl.simtime)):
bsm2_cl.step(idx, so4_ref)
# get the final performance of the plant
oci = bsm2_cl.get_final_performance()[-1]
```
### Run with energy management model
We introduced a simple energy management model (including CHPs, Boilers, Flares and a small techno-economic analysis) that can be used to simulate the energy consumption and production of the plant.
```python
from bsm2_python import BSM2OLEM
bsm2_olem = BSM2OLEM()
bsm2_olem.simulate()
# get the cumulated cash flow of the plant
cash_flow = bsm2_olem.economics.cum_cash_flow
```
### And much more...
You can also implement your own plant layout. Lots of classes are available to choose from. See the [Documentation](docs/) for more information.
The [`tests`](tests/) folder contains a lot of examples on how to use the plant layouts.
## Dev container
There is also a fully functional Dev Container image available for development.
Just open the repo in VSCode and install the Remote Containers extension.
Then, open the repo in a container and you are ready to go.
## Project structure
The project is structured as follows:
```
bsm2-python
├───docs
│ └────Documentation of the project
├───notebooks
| └────Jupyter notebooks as explanatory examples
├───src
│ └────bsm2_python
│ | └─Root folder of the project code
│ │ Contains pre-defined plant layouts and controllers
│ ├───bsm2
│ │ │ └─All modules for the BSM2 plant layouts
│ │ └───init
│ │ └─Initialisation files for the BSM2 plant layouts
│ └───data
│ │ └─Standard datasets for influent data
│ │ and sensor noise
│ └───gas_management
│ │ └─Modules for the gas management side of the BSM2 plant
│ └───init
│ └─Initialisation files for the gas management side
└───tests
| └─Unit tests for the BSM2 components in both
│ steady state and dynamic mode
└───simulink_files
└─Reference files for validation purposes
```
## Usage
At the moment, you can choose between 3 different ready-to-use configurations of the plant:
1. BSM2OL: BSM2 without any control (dynamic or static influent data - you choose)
2. BSM2CL: BSM2 with aeration control in tanks 3-5
3. BSM2OLEM: BSM2OL with energy management model and a default gas management.
You can as well create your own plant layout. Just use the classes in the `bsm2` folder and mix them as you like.
The results of the pre-made configurations are saved inside the objects and can be accessed via calling the attribute names. For the plant effluent, just call `bsm2.y_eff_all`.
With `tempmodel` and `activate`, differential equations for temperature dependency and additional components can be added.
If you want to create your own plant layout, use the `bsm2_xx.py` files as template. Put your own parameters and values in separate `init` files.
## Support
Your help is highly appreciated! Please read through the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on our code of conduct, and the process for submitting pull requests to us.
If you find any issues inside the repo, don't hesitate to raise an Issue.
## Roadmap
In the future, this repo will be extended by the following features:
- [ ] Graphical User Interface for easy plant setup and parameter setting
- [ ] Faster computation through Rust-based backend
- [ ] Support of more experimental tools, e.g. photovoltaics, methanation or electrolysis
## Authors and acknowledgment
Thanks to Maike Böhm for first implementing the Activated Sludge Models in Python in her Masters Thesis.
Thanks as well to Lukas Meier for implementing the Gas management side of the BSM2 plant and Nick Salomon for prettifying the documentation.
The development of this package was done in the context of the [KLÄFFIZIENT] and [KLÄFFIZIENTER] projects. Both are funded by the German Federal Ministry for Economic Affairs and Climate Action ([BMWK]) and are part of the 7th and 8th Energy Research Program of the Federal Government.
## License
This project is licensed under [BSD 3 Clause](LICENSE.txt).
## Project status
As we are maintaining this repo in our free time, don't expect rapid development. However, if any Issues are popping up, we will try to fix them in time.
[KLÄFFIZIENT]: https://www.evt.tf.fau.eu/startseite-des-lehrstuhls-fur-energieverfahrenstechnik/research/research-topics-prof-karl/ag-energiesysteme/bmwi-project-klaffizient/
[KLÄFFIZIENTER]: https://www.evt.tf.fau.eu/startseite-des-lehrstuhls-fur-energieverfahrenstechnik/research/research-topics-prof-karl/ag-energiesysteme/bmwk-project-klaffizienter/
[BMWK]: http://bmwk.de/
## Citation
We are currently in the publication process of a peer-reviewed paper. In the meantime, please reference our work with
```
@misc{miederer2024bsm2python,
title={Energy Management Model for Wastewater Treatment Plants},
author={Jonas Miederer and Lukas Meier and Nora Elhaus and Simon Markthaler and J{\"u}rgen Karl},
year = {2024--},
url = "https://gitlab.rrze.fau.de/evt/klaeffizient/bsm2-python"
}
Raw data
{
"_id": null,
"home_page": null,
"name": "bsm2-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "benchmark simulation model 2, bsm2, simulation, system dynamics, wastewater treatment plant",
"author": null,
"author_email": "Jonas Miederer <jonas.miederer@fau.de>",
"download_url": "https://files.pythonhosted.org/packages/74/78/c27d4ec8f4d5614ca2158b3f3a73ef45672629f233d4b60d98799269a7e5/bsm2_python-0.0.12.tar.gz",
"platform": null,
"description": "# BSM2-Python\n\n[](https://gitlab.rrze.fau.de/evt/klaeffizient/bsm2-python/-/commits/main)\n[](https://gitlab.rrze.fau.de/evt/klaeffizient/bsm2-python/-/commits/main)\n[](https://badge.fury.io/py/bsm2-python)\n\n[](https://doi.org/10.5281/zenodo.5555555)\n\n\n\nA Python implementation of the Benchmark Simulation Model 2 (BSM2) plant layout according to the [IWA](http://iwa-mia.org/) standard.\nA technical description of BSM2 can be found [here](https://iwaponline.com/ebooks/book-pdf/650794/wio9781780401171.pdf).\n\n## Installation\n### Easy way\nTo run the project, install the latest release via PyPI:\n`pip install bsm2-python`\n### Build from source\nIf you want the bleeding edge version from the repo, build it yourself via `hatch build`.\nSee the [Contribution Guide](CONTRIBUTING.md) for more details on how to install `hatch` (or simply use the [Docker image](#docker)).\nThen you can install it to arbitrary environments via `pip install dist/bsm2_python<version-hash>.whl`\n\n## Quickstart\n### Run default model\nYou could then use the following convenience function:\n```python\nfrom bsm2_python import BSM2OL\n\n# initialise the BSM2 Open Loop model\nbsm2_ol = BSM2OL()\n\n# run the simulation\nbsm2_ol.simulate()\n\n```\nThis will run the BSM2 Open Loop model for the default 609 days of simulation time.\nIt will then plot IQI, EQI and OCI values for the effluent over the last few days of simulation.\nFurther, relevant data will be saved to `data/output_evaluation.csv` for further analysis.\n\n### Run with custom aeration\nYou can also run the BSM2 models with your own aeration control - this example selects a random kla value for each reactor every timestep.\nThe final performance is then saved in the `oci` variable:\n```python\nimport numpy as np\nfrom bsm2_python import BSM2OL\nfrom tqdm import tqdm\n\n\nbsm2_ol = BSM2OL()\n\n# The kla values to choose from\nselect_klas = np.array([0, 60, 120, 180, 240])\n\nfor idx, _ in enumerate(tqdm(bsm2_ol.simtime)):\n # select random klas for all five ASM1 reactors\n klas = np.random.choice(select_klas, 5)\n\n # make a step in the simulation with the specified kla values\n bsm2_ol.step(idx, klas)\n\n\noci = bsm2_ol.get_final_performance()[-1]\n```\n\n### Run Closed Loop simulation with custom DO setpoint\nYou can also run the BSM2 Closed Loop model with your own dissolved oxygen (SO4) setpoints.\nPlease note: The Closed Loop model runs with a resolution of 1 minute for the sake of sensor stability, so it might take a while to run the simulation.\n```python\nfrom bsm2_python import BSM2CL\nfrom tqdm import tqdm\n\n\nbsm2_cl = BSM2CL()\n\n# The custom DO setpoint for the BSM2 default aeration control\nso4_ref = 1.5\n\nfor idx, _ in enumerate(tqdm(bsm2_cl.simtime)):\n bsm2_cl.step(idx, so4_ref)\n\n# get the final performance of the plant\noci = bsm2_cl.get_final_performance()[-1]\n\n```\n\n### Run with energy management model\nWe introduced a simple energy management model (including CHPs, Boilers, Flares and a small techno-economic analysis) that can be used to simulate the energy consumption and production of the plant.\n```python\nfrom bsm2_python import BSM2OLEM\n\nbsm2_olem = BSM2OLEM()\n\nbsm2_olem.simulate()\n\n# get the cumulated cash flow of the plant\ncash_flow = bsm2_olem.economics.cum_cash_flow\n```\n\n### And much more...\nYou can also implement your own plant layout. Lots of classes are available to choose from. See the [Documentation](docs/) for more information.\nThe [`tests`](tests/) folder contains a lot of examples on how to use the plant layouts.\n\n## Dev container\nThere is also a fully functional Dev Container image available for development.\nJust open the repo in VSCode and install the Remote Containers extension.\nThen, open the repo in a container and you are ready to go.\n\n## Project structure\nThe project is structured as follows:\n```\nbsm2-python\n\u251c\u2500\u2500\u2500docs\n\u2502 \u2514\u2500\u2500\u2500\u2500Documentation of the project\n\u251c\u2500\u2500\u2500notebooks\n| \u2514\u2500\u2500\u2500\u2500Jupyter notebooks as explanatory examples\n\u251c\u2500\u2500\u2500src\n\u2502 \u2514\u2500\u2500\u2500\u2500bsm2_python\n\u2502 | \u2514\u2500Root folder of the project code\n\u2502 \u2502 Contains pre-defined plant layouts and controllers\n\u2502 \u251c\u2500\u2500\u2500bsm2\n\u2502 \u2502 \u2502 \u2514\u2500All modules for the BSM2 plant layouts\n\u2502 \u2502 \u2514\u2500\u2500\u2500init\n\u2502 \u2502 \u2514\u2500Initialisation files for the BSM2 plant layouts\n\u2502 \u2514\u2500\u2500\u2500data\n\u2502 \u2502 \u2514\u2500Standard datasets for influent data\n\u2502 \u2502 and sensor noise\n\u2502 \u2514\u2500\u2500\u2500gas_management\n\u2502 \u2502 \u2514\u2500Modules for the gas management side of the BSM2 plant\n\u2502 \u2514\u2500\u2500\u2500init\n\u2502 \u2514\u2500Initialisation files for the gas management side\n\u2514\u2500\u2500\u2500tests\n | \u2514\u2500Unit tests for the BSM2 components in both\n \u2502 steady state and dynamic mode\n \u2514\u2500\u2500\u2500simulink_files\n \u2514\u2500Reference files for validation purposes\n```\n## Usage\nAt the moment, you can choose between 3 different ready-to-use configurations of the plant:\n1. BSM2OL: BSM2 without any control (dynamic or static influent data - you choose)\n2. BSM2CL: BSM2 with aeration control in tanks 3-5\n3. BSM2OLEM: BSM2OL with energy management model and a default gas management.\nYou can as well create your own plant layout. Just use the classes in the `bsm2` folder and mix them as you like.\n\nThe results of the pre-made configurations are saved inside the objects and can be accessed via calling the attribute names. For the plant effluent, just call `bsm2.y_eff_all`.\nWith `tempmodel` and `activate`, differential equations for temperature dependency and additional components can be added.\nIf you want to create your own plant layout, use the `bsm2_xx.py` files as template. Put your own parameters and values in separate `init` files.\n\n## Support\nYour help is highly appreciated! Please read through the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on our code of conduct, and the process for submitting pull requests to us.\nIf you find any issues inside the repo, don't hesitate to raise an Issue.\n\n\n## Roadmap\nIn the future, this repo will be extended by the following features:\n- [ ] Graphical User Interface for easy plant setup and parameter setting\n- [ ] Faster computation through Rust-based backend\n- [ ] Support of more experimental tools, e.g. photovoltaics, methanation or electrolysis\n\n\n## Authors and acknowledgment\nThanks to Maike B\u00f6hm for first implementing the Activated Sludge Models in Python in her Masters Thesis.\nThanks as well to Lukas Meier for implementing the Gas management side of the BSM2 plant and Nick Salomon for prettifying the documentation.\n\n\nThe development of this package was done in the context of the [KL\u00c4FFIZIENT] and [KL\u00c4FFIZIENTER] projects. Both are funded by the German Federal Ministry for Economic Affairs and Climate Action ([BMWK]) and are part of the 7th and 8th Energy Research Program of the Federal Government.\n\n## License\nThis project is licensed under [BSD 3 Clause](LICENSE.txt).\n\n## Project status\nAs we are maintaining this repo in our free time, don't expect rapid development. However, if any Issues are popping up, we will try to fix them in time.\n\n[KL\u00c4FFIZIENT]: https://www.evt.tf.fau.eu/startseite-des-lehrstuhls-fur-energieverfahrenstechnik/research/research-topics-prof-karl/ag-energiesysteme/bmwi-project-klaffizient/\n[KL\u00c4FFIZIENTER]: https://www.evt.tf.fau.eu/startseite-des-lehrstuhls-fur-energieverfahrenstechnik/research/research-topics-prof-karl/ag-energiesysteme/bmwk-project-klaffizienter/\n\n[BMWK]: http://bmwk.de/\n\n## Citation\nWe are currently in the publication process of a peer-reviewed paper. In the meantime, please reference our work with\n```\n@misc{miederer2024bsm2python,\n title={Energy Management Model for Wastewater Treatment Plants},\n author={Jonas Miederer and Lukas Meier and Nora Elhaus and Simon Markthaler and J{\\\"u}rgen Karl},\n year = {2024--},\n url = \"https://gitlab.rrze.fau.de/evt/klaeffizient/bsm2-python\"\n}\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A Python implementation of the Benchmark Simulation Model 2 (BSM2) plant layout according to the IWA standard.",
"version": "0.0.12",
"project_urls": {
"Documentation": "https://bsm2-python.readthedocs.io/",
"Source": "https://gitlab.rrze.fau.de/evt/klaeffizient/bsm2-python"
},
"split_keywords": [
"benchmark simulation model 2",
" bsm2",
" simulation",
" system dynamics",
" wastewater treatment plant"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3dd852f61c9b418c8e82dcdb8bd3228aba5143143e7d31e56982994f31ab98a5",
"md5": "d522b54f680edc0af657aa1fa20ec43f",
"sha256": "514d7b9b7c52c22549d2edf08d68e1c4a540577320f9289fbbbb3eaf7daf99d7"
},
"downloads": -1,
"filename": "bsm2_python-0.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d522b54f680edc0af657aa1fa20ec43f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15427865,
"upload_time": "2025-01-11T09:05:58",
"upload_time_iso_8601": "2025-01-11T09:05:58.331537Z",
"url": "https://files.pythonhosted.org/packages/3d/d8/52f61c9b418c8e82dcdb8bd3228aba5143143e7d31e56982994f31ab98a5/bsm2_python-0.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7478c27d4ec8f4d5614ca2158b3f3a73ef45672629f233d4b60d98799269a7e5",
"md5": "3d85d239f352006f89719d3cd8b11d84",
"sha256": "77f6968c350f653514f1c75be636af5f139ae4e4517e5c4edbaa9ffca2a2f2fa"
},
"downloads": -1,
"filename": "bsm2_python-0.0.12.tar.gz",
"has_sig": false,
"md5_digest": "3d85d239f352006f89719d3cd8b11d84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15195612,
"upload_time": "2025-01-11T09:06:38",
"upload_time_iso_8601": "2025-01-11T09:06:38.444643Z",
"url": "https://files.pythonhosted.org/packages/74/78/c27d4ec8f4d5614ca2158b3f3a73ef45672629f233d4b60d98799269a7e5/bsm2_python-0.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-11 09:06:38",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bsm2-python"
}
JSON