EPyT-Flow -- EPANET Python Toolkit - Flow

EPyT-Flow is a Python package building on top of 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 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.9 - 3.13

Note that EPANET and EPANET-MSX sources 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 12) 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:

brew install gcc@12

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:

pip install -r REQUIREMENTS.txt

Install the toolbox:

pip install .

Quick Example

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/

How to Get Started?

EPyT-Flow is accompanied by an extensive documentation https://epyt-flow.readthedocs.io/en/latest/ (including many examples).

If you are new to water distribution networks, we recommend first to read the chapter on Modeling of Water Distribution Networks. You might also want to check out some lecture notes on Smart Water Systems.

If you are already familiar with WDNs (and software such as EPANET), we recommend checking out our WDSA CCWI 2024 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 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 platform.

More on Control

We recommend checking out 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

How to Cite?

If you use this software, please cite it as follows:

@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 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 and follow the developers' guidelines.