WDN-Synth: Water Distribution Network Synthetic Dataset Generator

An EPyT-first framework for generating highly realistic, physics-based synthetic datasets for Water Distribution Networks (WDNs). Designed specifically to benchmark anomaly detection algorithms (like HOT SAX or CUSUM) with realistic diurnal patterns, seasonal drifts, and physically consistent leak signatures.

Installation

The recommended way to install wdn-synth so it's globally available on your terminal (without messing with virtual environments or getting Linux externally-managed errors) is using pipx or uv:

# Recommended (install as a standalone app)
pipx install wdn-synth

# Alternatively, if you use uv:
uv tool install wdn-synth

If you prefer to install it into an active Python virtual environment (e.g. Conda or venv), you can use standard pip:

pip install wdn-synth

Graphical User Interface (GUI)

The easiest way to generate datasets is using the built-in Streamlit GUI. It provides a visual editor to configure your network, set stochastic demands, and visualize the leakage parameters.

To launch the GUI, simply run:

wdn-synth-gui

Command Line Interface (CLI)

For headless environments or automated workflows, you can use the CLI.

To run the entire pipeline (Plan -> Generate -> Validate) in one shot:

wdn-synth all profiles/your_config.yaml

If you prefer to run the steps individually:

wdn-synth validate profiles/your_config.yaml
wdn-synth plan profiles/your_config.yaml
wdn-synth generate profiles/your_config.yaml --shard 0
wdn-synth finalize profiles/your_config.yaml

License

This project is licensed under the European Union Public Licence v1.2 (EUPL-1.2).
For third-party licenses, simulation engines, and benchmark datasets, see THIRD_PARTY_NOTICES.md.

Acknowledgments & Funding

This research was developed at the University of Algarve (Universidade do Algarve - UAlg).

The authors acknowledge the computational support and resources provided by the Deucalion Supercomputer hosted at the Minho Advanced Computing Center (MACC) under the National Advanced Computing Network (RNCA) project grant F202514141CPCAA0X, funded by the Fundação para a Ciência e a Tecnologia (FCT, I.P.).