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, cyber-attacks, etc.)
• Wide variety of pre-defined types of 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.12

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()

        # Show sensor readings over the entire simulation
        print(f"Pressure readings: {scada_data.get_data_pressures()}")
        print(f"Flow readings: {scada_data.get_data_flows()}")

Documentation

Documentation is available on readthedocs:https://epyt-flow.readthedocs.io/en/latest/

License

MIT license -- see LICENSE

How to Cite?

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

@misc{github:epytflow,
        author = {André Artelt, Marios S. Kyriakou, Stelios G. Vrachimis, Demetrios G. Eliades, Barbara Hammer, Marios M. Polycarpou},
        title = {EPyT-Flow -- EPANET Python Toolkit - Flow},
        year = {2024},
        publisher = {GitHub},
        journal = {GitHub repository},
        howpublished = {\url{https://github.com/WaterFutures/EPyT-Flow}}
    }

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.