[](https://pypi.org/project/epyt-control/)
[](https://opensource.org/licenses/MIT)
[](https://epyt-control.readthedocs.io/en/stable/?badge=stable)
[](https://pepy.tech/project/epyt-control)
[](https://pepy.tech/project/epyt-control)
# EPyT-Control -- EPANET Python Toolkit - Control
<img src="https://github.com/WaterFutures/EPyT-Control/blob/main/docs/_static/gimmick.png?raw=true" align="center" height="230px"/>
EPyT-Control is a Python package building on top of [EPyT-Flow](https://github.com/WaterFutures/EPyT-Flow)
for implementing and evaluating control algorithms & strategies in water distribution networks (WDNs).
A special focus of this Python package is Reinforcement Learning for data-driven control in WDNs and
therefore it provides full compatibility with the
[Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/) package.
## Unique Features
Unique features of EPyT-Control are the following:
- Support of hydraulic and (advanced) water quality simulation (i.e. EPANET and EPANET-MSX are supported)
- Compatibility with [Gymnasium](https://github.com/Farama-Foundation/Gymnasium) and integration of [Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/)
- Wide variety of pre-defined actions (e.g. pump state actions, pump speed actons, valve state actions, species injection actions, etc.)
- Implementation of classic control aglorithms such as PID controllers
- High- and low-level interface
- Object-orientated design that is easy to extend and customize
## Installation
EPyT-Control supports Python 3.9 - 3.13
### PyPI
```
pip install epyt-control
```
### Git
Download or clone the repository:
```
git clone https://github.com/WaterFutures/EPyT-Control.git
cd EPyT-Control
```
Install all requirements as listed in [REQUIREMENTS.txt](REQUIREMENTS.txt):
```
pip install -r REQUIREMENTS.txt
```
Install the toolbox:
```
pip install .
```
## Quick Example
#### Interface of Environments
Basic example demonstrating the environments' interface:
```python
# Define/Specify MyEnv
# ....
# Load hypothetical environment "MyEnv"
with MyEnv() as env:
# Show the observation space
print(f"Observation space: {env.observation_space}")
# Run 1000 iterations -- assuming that autorest=True
obs, info = env.reset()
for _ in range(1000):
# Sample and apply a random action from the action space.
# TODO: Replace with some smart RL/control method
action = env.action_space.sample()
obs, reward, terminated, _, _ = env.step(action)
# Show action and observed reward
print(action, reward)
```
#### Applying Reinforcement Learning to a given Environment
Simple example of using [Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/) for learning a policy to control the chlorine injection in a given environment called ```SimpleChlorineInjectionEnv```:
```python
from stable_baselines3 import PPO
from gymnasium.wrappers import NormalizeObservation
# Define/Specify SimpleChlorineInjectionEnv
# ....
# Load chlorine injection environment
with SimpleChlorineInjectionEnv() as env:
# Wrap environment
env = NormalizeObservation(env)
# Apply a simple policy learner
# You might want to add more wrappers (e.g. normalizing inputs, rewards, etc.) and logging here
# Also, inceasing the number of time steps might help as well
model = PPO("MlpPolicy", env, verbose=1)
model.learn(total_timesteps=1000)
model.save("my_model_clinject.zip") # Save policy
```
## Documentation
Documentation is available on readthedocs: [https://epyt-control.readthedocs.io/en/stable/](https://epyt-control.readthedocs.io/en/stable)
## License
MIT license -- see [LICENSE](LICENSE)
## How to Cite?
If you use this software, please cite it as follows:
```
@misc{github:epytcontrol,
author = {André Artelt},
title = {{EPyT-Control -- EPANET Python Toolkit - Control}},
year = {2025},
publisher = {GitHub},
journal = {GitHub repository},
howpublished = {\url{https://github.com/WaterFutures/EPyT-Control}}
}
```
## How to get Support?
If you come across any bug or need assistance please feel free to open a new
[issue](https://github.com/WaterFutures/EPyT-Control/issues/)
if non of the existing issues answers your questions.
## How to Contribute?
Contributions (e.g. creating issues, pull-requests, etc.) are welcome --
please make sure to read the [code of conduct](CODE_OF_CONDUCT.md) and
follow the [developers' guidelines](DEVELOPERS.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "epyt-control",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "epanet, water, networks, hydraulics, quality, simulations, control, reinforcement learning",
"author": null,
"author_email": "Andr\u00e9 Artelt <aartelt@techfak.uni-bielefeld.de>",
"download_url": "https://files.pythonhosted.org/packages/a0/f2/047b7d07847237221a606d20b96c27485bef8a43355b8feedfd65ed79e24/epyt_control-0.1.1.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/epyt-control/)\n[](https://opensource.org/licenses/MIT)\n\n[](https://epyt-control.readthedocs.io/en/stable/?badge=stable)\n[](https://pepy.tech/project/epyt-control)\n[](https://pepy.tech/project/epyt-control)\n\n# EPyT-Control -- EPANET Python Toolkit - Control\n\n<img src=\"https://github.com/WaterFutures/EPyT-Control/blob/main/docs/_static/gimmick.png?raw=true\" align=\"center\" height=\"230px\"/>\n\nEPyT-Control is a Python package building on top of [EPyT-Flow](https://github.com/WaterFutures/EPyT-Flow) \nfor implementing and evaluating control algorithms & strategies in water distribution networks (WDNs).\n\nA special focus of this Python package is Reinforcement Learning for data-driven control in WDNs and\ntherefore it provides full compatibility with the\n[Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/) package.\n\n\n## Unique Features\n\nUnique features of EPyT-Control are the following:\n\n- Support of hydraulic and (advanced) water quality simulation (i.e. EPANET and EPANET-MSX are supported)\n- Compatibility with [Gymnasium](https://github.com/Farama-Foundation/Gymnasium) and integration of [Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/)\n- Wide variety of pre-defined actions (e.g. pump state actions, pump speed actons, valve state actions, species injection actions, etc.)\n- Implementation of classic control aglorithms such as PID controllers\n- High- and low-level interface\n- Object-orientated design that is easy to extend and customize\n\n\n## Installation\n\nEPyT-Control supports Python 3.9 - 3.13\n\n### PyPI\n\n```\npip install epyt-control\n```\n\n### Git\nDownload or clone the repository:\n```\ngit clone https://github.com/WaterFutures/EPyT-Control.git\ncd EPyT-Control\n```\n\nInstall all requirements as listed in [REQUIREMENTS.txt](REQUIREMENTS.txt):\n```\npip install -r REQUIREMENTS.txt\n```\n\nInstall the toolbox:\n```\npip install .\n```\n\n\n## Quick Example\n\n#### Interface of Environments\n\nBasic example demonstrating the environments' interface:\n\n```python\n# Define/Specify MyEnv\n# ....\n\n# Load hypothetical environment \"MyEnv\"\nwith MyEnv() as env:\n # Show the observation space\n print(f\"Observation space: {env.observation_space}\")\n\n # Run 1000 iterations -- assuming that autorest=True\n obs, info = env.reset()\n for _ in range(1000):\n # Sample and apply a random action from the action space.\n # TODO: Replace with some smart RL/control method\n action = env.action_space.sample()\n obs, reward, terminated, _, _ = env.step(action)\n\n # Show action and observed reward\n print(action, reward)\n```\n\n#### Applying Reinforcement Learning to a given Environment\n\nSimple example of using [Stable-Baselines3](https://stable-baselines3.readthedocs.io/en/master/) for learning a policy to control the chlorine injection in a given environment called ```SimpleChlorineInjectionEnv```:\n\n```python\nfrom stable_baselines3 import PPO\nfrom gymnasium.wrappers import NormalizeObservation\n\n# Define/Specify SimpleChlorineInjectionEnv\n# ....\n\n# Load chlorine injection environment\nwith SimpleChlorineInjectionEnv() as env:\n # Wrap environment\n env = NormalizeObservation(env)\n\n # Apply a simple policy learner\n # You might want to add more wrappers (e.g. normalizing inputs, rewards, etc.) and logging here\n # Also, inceasing the number of time steps might help as well\n model = PPO(\"MlpPolicy\", env, verbose=1)\n model.learn(total_timesteps=1000)\n model.save(\"my_model_clinject.zip\") # Save policy\n```\n\n## Documentation\n\nDocumentation is available on readthedocs: [https://epyt-control.readthedocs.io/en/stable/](https://epyt-control.readthedocs.io/en/stable)\n\n## License\n\nMIT license -- see [LICENSE](LICENSE)\n\n## How to Cite?\n\nIf you use this software, please cite it as follows:\n\n```\n@misc{github:epytcontrol,\n author = {Andr\u00e9 Artelt},\n title = {{EPyT-Control -- EPANET Python Toolkit - Control}},\n year = {2025},\n publisher = {GitHub},\n journal = {GitHub repository},\n howpublished = {\\url{https://github.com/WaterFutures/EPyT-Control}}\n }\n```\n\n## How to get Support?\n\nIf you come across any bug or need assistance please feel free to open a new\n[issue](https://github.com/WaterFutures/EPyT-Control/issues/)\nif non of the existing issues answers your questions.\n\n## How to Contribute?\n\nContributions (e.g. creating issues, pull-requests, etc.) are welcome --\nplease make sure to read the [code of conduct](CODE_OF_CONDUCT.md) and\nfollow the [developers' guidelines](DEVELOPERS.md).\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "EPyT-Control -- EPANET Python Toolkit - Control",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://epyt-control.readthedocs.io/en/stable/",
"Homepage": "https://github.com/WaterFutures/EPyT-Control",
"Issues": "https://github.com/WaterFutures/EPyT-Control/issues",
"Repository": "https://github.com/WaterFutures/EPyT-Control.git"
},
"split_keywords": [
"epanet",
" water",
" networks",
" hydraulics",
" quality",
" simulations",
" control",
" reinforcement learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b611f7c38a87e6c93ab28d8ed06ea2e4ae9dbb4a6fbb47b6134b69aba9fe1402",
"md5": "3c02c99659d151c240a144db9ae85d83",
"sha256": "f9c612453fd94e368fa12735d254ff34c1e2c556b488b3c1aa525d2318d598e2"
},
"downloads": -1,
"filename": "epyt_control-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c02c99659d151c240a144db9ae85d83",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 19717,
"upload_time": "2025-02-01T13:48:18",
"upload_time_iso_8601": "2025-02-01T13:48:18.562008Z",
"url": "https://files.pythonhosted.org/packages/b6/11/f7c38a87e6c93ab28d8ed06ea2e4ae9dbb4a6fbb47b6134b69aba9fe1402/epyt_control-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0f2047b7d07847237221a606d20b96c27485bef8a43355b8feedfd65ed79e24",
"md5": "b6d7e0b0760d38bf5ece661d23cc01d6",
"sha256": "6d5355a482f092fbe0a16d1c7e0cdb5f6a2ecac0c0f75850641906e694b9e418"
},
"downloads": -1,
"filename": "epyt_control-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "b6d7e0b0760d38bf5ece661d23cc01d6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 283642,
"upload_time": "2025-02-01T13:48:21",
"upload_time_iso_8601": "2025-02-01T13:48:21.181835Z",
"url": "https://files.pythonhosted.org/packages/a0/f2/047b7d07847237221a606d20b96c27485bef8a43355b8feedfd65ed79e24/epyt_control-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-01 13:48:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WaterFutures",
"github_project": "EPyT-Control",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "epyt-control"
}
JSON
