[](https://pypi.org/project/epyt-flow/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/WaterFutures/EPyT-Flow/actions/workflows/build_tests.yml)
[](https://epyt-flow.readthedocs.io/en/stable/?badge=stable)
[](https://pepy.tech/project/epyt-flow)
[](https://pepy.tech/project/epyt-flow)
[](https://doi.org/10.21105/joss.07104)
# EPyT-Flow -- EPANET Python Toolkit - Flow
<img src="https://github.com/WaterFutures/EPyT-Flow/blob/main/docs/_static/net1_plot.png?raw=true" align="right" height="230px"/>
EPyT-Flow is a Python package building on top of [EPyT](https://github.com/OpenWaterAnalytics/EPyT)
for providing easy access to water distribution network simulations.
It aims to provide a high-level interface for the easy generation of hydraulic and water quality scenario data.
However, it also provides access to low-level functions by [EPANET](https://github.com/USEPA/EPANET2.2)
and [EPANET-MSX](https://github.com/USEPA/EPANETMSX/).
EPyT-Flow provides easy access to popular benchmark data sets for event detection and localization.
Furthermore, it also provides an environment for developing and testing control algorithms.
## Unique Features
Unique features of EPyT-Flow that make it superior to other (Python) toolboxes are the following:
- High-performance hydraulic and (advanced) water quality simulation
- High- and low-level interface
- Object-orientated design that is easy to extend and customize
- Sensor configurations
- Wide variety of pre-defined events (e.g. leakages, sensor faults, actuator events, contamination, cyber-attacks, etc.)
- Wide variety of pre-defined types of global & local uncertainties (e.g. model uncertainties)
- Step-wise simulation and environment for training and evaluating control strategies
- Serialization module for easy exchange of data and (scenario) configurations
- REST API to make EPyT-Flow accessible in other applications
- Access to many WDNs and popular benchmarks (incl. their evaluation)
## Installation
EPyT-Flow supports Python 3.9 - 3.13
Note that [EPANET and EPANET-MSX sources](epyt_flow/EPANET/) are compiled and overwrite the binaries
shipped by EPyT **IF** EPyT-Flow is installed on a Unix system and the *gcc* compiler is available.
By this, we not only aim to achieve a better performance of the simulations but also avoid any
compatibility issues of pre-compiled binaries.
#### Prerequisites for macOS users
The "true" *gcc* compiler (version 15) is needed which is not the
*clang* compiler that is shipped with Xcode and is linked to gcc!
The correct version of the "true" *gcc* can be installed via [brew](https://brew.sh/):
```
brew install gcc@15
```
### PyPI
```
pip install epyt-flow
```
### Git
Download or clone the repository:
```
git clone https://github.com/WaterFutures/EPyT-Flow.git
cd EPyT-Flow
```
Install all requirements as listed in [REQUIREMENTS.txt](REQUIREMENTS.txt):
```
pip install -r REQUIREMENTS.txt
```
Install the toolbox:
```
pip install .
```
## Quick Example
<a target="_blank" href="https://colab.research.google.com/github/WaterFutures/EPyT-Flow/blob/main/docs/examples/basic_usage.ipynb">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
</a>
```python
from epyt_flow.data.benchmarks import load_leakdb_scenarios
from epyt_flow.simulation import ScenarioSimulator
from epyt_flow.utils import to_seconds
if __name__ == "__main__":
# Load first Hanoi scenario from LeakDB
network_config, = load_leakdb_scenarios(scenarios_id=["1"], use_net1=False)
# Create scenario
with ScenarioSimulator(scenario_config=network_config) as sim:
# Set simulation duration to two days
sim.set_general_parameters(simulation_duration=to_seconds(days=2))
# Place pressure sensors at nodes "13", "16", "22", and "30"
sim.set_pressure_sensors(sensor_locations=["13", "16", "22", "30"])
# Place a flow sensor at link/pipe "1"
sim.set_flow_sensors(sensor_locations=["1"])
# Run entire simulation
scada_data = sim.run_simulation()
# Print & plot sensor readings over the entire simulation
print(f"Pressure readings: {scada_data.get_data_pressures()}")
scada_data.plot_pressures()
print(f"Flow readings: {scada_data.get_data_flows()}")
scada_data.plot_flows()
```
### Generated plots
<div>
<img src="https://github.com/WaterFutures/EPyT-Flow/blob/dev/docs/_static/examples_basic_usage_pressure.png?raw=true" width="49%"/>
<img src="https://github.com/WaterFutures/EPyT-Flow/blob/dev/docs/_static/examples_basic_usage_flow.png?raw=true" width="49%"/>
</div>
## Documentation
Documentation is available on readthedocs: [https://epyt-flow.readthedocs.io/en/latest/](https://epyt-flow.readthedocs.io/en/stable)
## How to Get Started?
EPyT-Flow is accompanied by an extensive documentation
[https://epyt-flow.readthedocs.io/en/latest/](https://epyt-flow.readthedocs.io/en/stable)
(including many [examples](https://epyt-flow.readthedocs.io/en/stable/#examples)).
If you are new to water distribution networks, we recommend first to read the chapter on
[Modeling of Water Distribution Networks](https://epyt-flow.readthedocs.io/en/stable/tut.intro.html).
You might also want to check out some lecture notes on
[Smart Water Systems](https://github.com/KIOS-Research/ece808-smart-water-systems).
If you are already familiar with WDNs (and software such as EPANET), we recommend checking out
our [WDSA CCWI 2024 tutorial](https://github.com/WaterFutures/EPyT-and-EPyT-Flow-Tutorial) which
not only teaches you how to use EPyT and EPyT-Flow but also contains some examples of applying
Machine Learning in WDNs.
Besides that, you can read in-depth about the different functionalities of EPyT-Flow in the
[In-depth Tutorial](https://epyt-flow.readthedocs.io/en/stable/tutorial.html) of the documentation --
we recommend reading the chapters in the order in which they are presented;
you might decide to skip some of the last chapters if their content is not relevant to you.
## More Networks and Benchmarks
More Water Distribution Networks (WDNs) and benchmarks are available on the
[WaterBenchmarkHub](https://waterfutures.github.io/WaterBenchmarkHub) platform.
## More on Control
We recommend checking out [EPyT-Control](https://github.com/WaterFutures/EPyT-Control)
if you are intersted in (data-driven) control and relates tasks such as state estimation
and event diagnosis in Water Distribution Networks.
## License
MIT license -- see [LICENSE](LICENSE)
## How to Cite?
If you use this software, please cite it as follows:
```bibtex
@article{Artelt2024,
doi = {10.21105/joss.07104},
url = {https://doi.org/10.21105/joss.07104},
year = {2024},
publisher = {The Open Journal},
volume = {9},
number = {103},
pages = {7104},
author = {André Artelt and Marios S. Kyriakou and Stelios G. Vrachimis and Demetrios G. Eliades and Barbara Hammer and Marios M. Polycarpou},
title = {EPyT-Flow: A Toolkit for Generating Water Distribution Network Data},
journal = {Journal of Open Source Software}
}
```
## 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-Flow/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-flow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "epanet, water, networks, hydraulics, quality, simulations",
"author": null,
"author_email": "Andr\u00e9 Artelt <aartelt@techfak.uni-bielefeld.de>, \"Marios S. Kyriakou\" <kiriakou.marios@ucy.ac.cy>, \"Stelios G. Vrachimis\" <vrachimis.stelios@ucy.ac.cy>",
"download_url": "https://files.pythonhosted.org/packages/53/62/749f864d7d5ca53df1b7ee28dcf21c821347fc6f698fe9f6e525d01492d6/epyt_flow-0.14.2.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/epyt-flow/)\n[](https://opensource.org/licenses/MIT)\n\n[](https://github.com/WaterFutures/EPyT-Flow/actions/workflows/build_tests.yml)\n[](https://epyt-flow.readthedocs.io/en/stable/?badge=stable)\n[](https://pepy.tech/project/epyt-flow)\n[](https://pepy.tech/project/epyt-flow)\n[](https://doi.org/10.21105/joss.07104)\n\n# EPyT-Flow -- EPANET Python Toolkit - Flow\n\n<img src=\"https://github.com/WaterFutures/EPyT-Flow/blob/main/docs/_static/net1_plot.png?raw=true\" align=\"right\" height=\"230px\"/>\n\nEPyT-Flow is a Python package building on top of [EPyT](https://github.com/OpenWaterAnalytics/EPyT) \nfor providing easy access to water distribution network simulations.\nIt aims to provide a high-level interface for the easy generation of hydraulic and water quality scenario data.\nHowever, it also provides access to low-level functions by [EPANET](https://github.com/USEPA/EPANET2.2) \nand [EPANET-MSX](https://github.com/USEPA/EPANETMSX/).\n\nEPyT-Flow provides easy access to popular benchmark data sets for event detection and localization.\nFurthermore, it also provides an environment for developing and testing control algorithms.\n\n\n## Unique Features\n\nUnique features of EPyT-Flow that make it superior to other (Python) toolboxes are the following:\n\n- High-performance hydraulic and (advanced) water quality simulation\n- High- and low-level interface\n- Object-orientated design that is easy to extend and customize\n- Sensor configurations\n- Wide variety of pre-defined events (e.g. leakages, sensor faults, actuator events, contamination, cyber-attacks, etc.)\n- Wide variety of pre-defined types of global & local uncertainties (e.g. model uncertainties)\n- Step-wise simulation and environment for training and evaluating control strategies\n- Serialization module for easy exchange of data and (scenario) configurations\n- REST API to make EPyT-Flow accessible in other applications\n- Access to many WDNs and popular benchmarks (incl. their evaluation)\n\n\n## Installation\n\nEPyT-Flow supports Python 3.9 - 3.13\n\nNote that [EPANET and EPANET-MSX sources](epyt_flow/EPANET/) are compiled and overwrite the binaries\nshipped by EPyT **IF** EPyT-Flow is installed on a Unix system and the *gcc* compiler is available.\nBy this, we not only aim to achieve a better performance of the simulations but also avoid any\ncompatibility issues of pre-compiled binaries.\n\n#### Prerequisites for macOS users\nThe \"true\" *gcc* compiler (version 15) is needed which is not the\n*clang* compiler that is shipped with Xcode and is linked to gcc!\n\nThe correct version of the \"true\" *gcc* can be installed via [brew](https://brew.sh/):\n```\nbrew install gcc@15\n```\n\n### PyPI\n\n```\npip install epyt-flow\n```\n\n### Git\nDownload or clone the repository:\n```\ngit clone https://github.com/WaterFutures/EPyT-Flow.git\ncd EPyT-Flow\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## Quick Example\n\n<a target=\"_blank\" href=\"https://colab.research.google.com/github/WaterFutures/EPyT-Flow/blob/main/docs/examples/basic_usage.ipynb\">\n<img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n</a>\n\n```python\nfrom epyt_flow.data.benchmarks import load_leakdb_scenarios\nfrom epyt_flow.simulation import ScenarioSimulator\nfrom epyt_flow.utils import to_seconds\n\n\nif __name__ == \"__main__\":\n # Load first Hanoi scenario from LeakDB\n network_config, = load_leakdb_scenarios(scenarios_id=[\"1\"], use_net1=False)\n\n # Create scenario\n with ScenarioSimulator(scenario_config=network_config) as sim:\n # Set simulation duration to two days\n sim.set_general_parameters(simulation_duration=to_seconds(days=2))\n\n # Place pressure sensors at nodes \"13\", \"16\", \"22\", and \"30\"\n sim.set_pressure_sensors(sensor_locations=[\"13\", \"16\", \"22\", \"30\"])\n\n # Place a flow sensor at link/pipe \"1\"\n sim.set_flow_sensors(sensor_locations=[\"1\"])\n\n # Run entire simulation\n scada_data = sim.run_simulation()\n\n # Print & plot sensor readings over the entire simulation\n print(f\"Pressure readings: {scada_data.get_data_pressures()}\")\n scada_data.plot_pressures()\n\n print(f\"Flow readings: {scada_data.get_data_flows()}\")\n scada_data.plot_flows()\n```\n### Generated plots\n\n<div>\n <img src=\"https://github.com/WaterFutures/EPyT-Flow/blob/dev/docs/_static/examples_basic_usage_pressure.png?raw=true\" width=\"49%\"/>\n <img src=\"https://github.com/WaterFutures/EPyT-Flow/blob/dev/docs/_static/examples_basic_usage_flow.png?raw=true\" width=\"49%\"/>\n</div>\n\n## Documentation\n\nDocumentation is available on readthedocs: [https://epyt-flow.readthedocs.io/en/latest/](https://epyt-flow.readthedocs.io/en/stable)\n\n## How to Get Started?\n\nEPyT-Flow is accompanied by an extensive documentation\n[https://epyt-flow.readthedocs.io/en/latest/](https://epyt-flow.readthedocs.io/en/stable)\n(including many [examples](https://epyt-flow.readthedocs.io/en/stable/#examples)).\n\nIf you are new to water distribution networks, we recommend first to read the chapter on\n[Modeling of Water Distribution Networks](https://epyt-flow.readthedocs.io/en/stable/tut.intro.html).\nYou might also want to check out some lecture notes on\n[Smart Water Systems](https://github.com/KIOS-Research/ece808-smart-water-systems).\n\nIf you are already familiar with WDNs (and software such as EPANET), we recommend checking out\nour [WDSA CCWI 2024 tutorial](https://github.com/WaterFutures/EPyT-and-EPyT-Flow-Tutorial) which\nnot only teaches you how to use EPyT and EPyT-Flow but also contains some examples of applying\nMachine Learning in WDNs.\nBesides that, you can read in-depth about the different functionalities of EPyT-Flow in the\n[In-depth Tutorial](https://epyt-flow.readthedocs.io/en/stable/tutorial.html) of the documentation --\nwe recommend reading the chapters in the order in which they are presented;\nyou might decide to skip some of the last chapters if their content is not relevant to you.\n\n## More Networks and Benchmarks\n\nMore Water Distribution Networks (WDNs) and benchmarks are available on the\n[WaterBenchmarkHub](https://waterfutures.github.io/WaterBenchmarkHub) platform.\n\n## More on Control\n\nWe recommend checking out [EPyT-Control](https://github.com/WaterFutures/EPyT-Control)\nif you are intersted in (data-driven) control and relates tasks such as state estimation\nand event diagnosis in Water Distribution Networks.\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```bibtex\n@article{Artelt2024,\n doi = {10.21105/joss.07104},\n url = {https://doi.org/10.21105/joss.07104},\n year = {2024},\n publisher = {The Open Journal},\n volume = {9},\n number = {103},\n pages = {7104},\n author = {Andr\u00e9 Artelt and Marios S. Kyriakou and Stelios G. Vrachimis and Demetrios G. Eliades and Barbara Hammer and Marios M. Polycarpou},\n title = {EPyT-Flow: A Toolkit for Generating Water Distribution Network Data},\n journal = {Journal of Open Source Software}\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-Flow/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": null,
"summary": "EPyT-Flow -- EPANET Python Toolkit - Flow",
"version": "0.14.2",
"project_urls": {
"Documentation": "https://epyt-flow.readthedocs.io/en/stable/",
"Homepage": "https://github.com/WaterFutures/EPyT-Flow",
"Issues": "https://github.com/WaterFutures/EPyT-Flow/issues",
"Repository": "https://github.com/WaterFutures/EPyT-Flow.git"
},
"split_keywords": [
"epanet",
" water",
" networks",
" hydraulics",
" quality",
" simulations"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4f54eeca91123b1ea19a287dac99f7c996f5eaa91ea145f886196b526df337d8",
"md5": "c6d1a3bc2a7e7b95079b3b66b4a6b872",
"sha256": "5d736c027c634e9cb0f1bb2ca1ebf02192e42588288a029b755879ba17f92112"
},
"downloads": -1,
"filename": "epyt_flow-0.14.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6d1a3bc2a7e7b95079b3b66b4a6b872",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 541552,
"upload_time": "2025-09-01T19:41:29",
"upload_time_iso_8601": "2025-09-01T19:41:29.152569Z",
"url": "https://files.pythonhosted.org/packages/4f/54/eeca91123b1ea19a287dac99f7c996f5eaa91ea145f886196b526df337d8/epyt_flow-0.14.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5362749f864d7d5ca53df1b7ee28dcf21c821347fc6f698fe9f6e525d01492d6",
"md5": "16c9556141015a1ae12e4cc3d9a8b310",
"sha256": "cfa0f4c88f343d668f437c331f92ab5c5cd77c32453b7363d87ded2afa0c4b83"
},
"downloads": -1,
"filename": "epyt_flow-0.14.2.tar.gz",
"has_sig": false,
"md5_digest": "16c9556141015a1ae12e4cc3d9a8b310",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 478740,
"upload_time": "2025-09-01T19:41:31",
"upload_time_iso_8601": "2025-09-01T19:41:31.580213Z",
"url": "https://files.pythonhosted.org/packages/53/62/749f864d7d5ca53df1b7ee28dcf21c821347fc6f698fe9f6e525d01492d6/epyt_flow-0.14.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 19:41:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WaterFutures",
"github_project": "EPyT-Flow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "epyt-flow"
}
JSON
