https://github.com/waterfutures/epyt-flow
A Python package designed for the easy generation of hydraulic and water quality scenario data of water distribution networks.
https://github.com/waterfutures/epyt-flow
epanet epanet-python-toolkit hydraulics python simulation water water-distribution-networks
Last synced: 3 months ago
JSON representation
A Python package designed for the easy generation of hydraulic and water quality scenario data of water distribution networks.
- Host: GitHub
- URL: https://github.com/waterfutures/epyt-flow
- Owner: WaterFutures
- License: mit
- Created: 2024-01-04T14:07:18.000Z (over 2 years ago)
- Default Branch: dev
- Last Pushed: 2026-02-27T07:34:16.000Z (3 months ago)
- Last Synced: 2026-03-02T11:33:47.728Z (3 months ago)
- Topics: epanet, epanet-python-toolkit, hydraulics, python, simulation, water, water-distribution-networks
- Language: Python
- Homepage: https://epyt-flow.readthedocs.io/en/stable
- Size: 7.72 MB
- Stars: 38
- Watchers: 6
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
[](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
EPyT-Flow is a Python package building on top of [EPANET-PLUS](https://github.com/WaterFutures/EPANET-PLUS) --
an extension and interface of [EPANET](https://github.com/OpenWaterAnalytics/EPANET)
and [EPANET-MSX](https://github.com/OpenWaterAnalytics/epanet-msx) --
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 all functions of EPANET
and EPANET-MSX.
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.10 - 3.14
Note that EPyT-Flow builds upon [EPANET-PLUS](https://github.com/WaterFutures/EPANET-PLUS) which
constitutes a C extension and Python package.
In the rare case that the pre-build package of EPANET-PLUS does not work on your system,
you have to build and install it manually -- please follow the instructions provided
[here](https://epanet-plus.readthedocs.io/en/stable/installation.html).
### 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
```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
## 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).