Metadata-Version: 2.4
Name: wdn-synth
Version: 0.1.3
Summary: EPyT-first WDN Synthetic Dataset Generator
Author-email: Ilyass Hankrir <ihankrir@ualg.pt>
License: EUPL-1.2
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0
Requires-Dist: epyt>=1.0.8
Requires-Dist: h5py>=3.8
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: networkx>=3.0
Requires-Dist: streamlit>=1.60.0
Requires-Dist: wntr>=1.1.0
Requires-Dist: plotly>=6.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: wntr>=1.1.0; extra == "dev"

# 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`:

```bash
# 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:
```bash
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:
```bash
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:
```bash
wdn-synth all profiles/your_config.yaml
```

If you prefer to run the steps individually:
```bash
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](LICENSES/EUPL-1.2.txt)).  
For third-party licenses, simulation engines, and benchmark datasets, see [THIRD_PARTY_NOTICES.md](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.)**.
