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 EUPL-1.2.