Overview

This README file provides detailed documentation for the dataset Deep Reinforcement Learning for Pressure Optimization in Water Distribution Networks with Multiple Pumping Stations: Case Study, ASCE Journal of Water Resources Planning and Management. It describes the folder structure, variable definitions, software environment, and step-by-step instructions required to reproduce the analyses and results. The abstract for this dataset is provided separately on the Dryad record page.

1. Directory Structure and File Descriptions

DataSetR02.zip/
│
├── Python Scripts
│   ├── env_001.py                      → Custom Gym environment for multi-pump network.
│   ├── evaluate_001.py                 → Evaluates trained SAC agent on validation sets.
│   ├── Evaluation_conventional_001.py  → Baseline evaluation using fixed setpoints.
│   ├── Evaluation_data_collection_001.py→ Collects training and evaluation data.
│   ├── Evaluation_diurnal_pattern_001.py→ Evaluation under diurnal demand variations.
│   ├── Evaluation_synthetic_DRL_001.py  → Evaluation with synthetic demand profiles.
│   ├── reward_tracker.py                → Tracks training rewards and performance metrics.
│   ├── SAC_Training_001.py              → Main training script using Soft Actor–Critic (SAC).
│   ├── Sys_001.py                       → Hydraulic solver and reward function.
│   ├── Testing_001.py                   → Tests trained agent on individual scenarios.
│   ├── Tool_001.py                      → Predicts optimal setpoint for given flow input.
│   └── sac_water_networkR3.zip          → Pre-trained SAC agent weights and replay buffer (PyTorch .zip, ~40 MB).
│
├── EPANET_FILES/
│   ├── network.inp → EPANET input file (network structure: nodes, pipes, pumps, reservoirs).
│   ├── network.rpt → EPANET report (simulation summary).
│   └── network.out → Binary output for data-driven processing.
│
├── Input/
│   ├── Input.xlsx           → Primary configuration and control-variable dataset.  
│   ├── Input_drnl.xlsx      → Diurnal flow pattern input for time-of-day variation training.  
│   ├── Input_evaluate.xlsx  → Field-scale validation dataset with observed values.  
│   └── Input_synt.xlsx      → Synthetic data for generalisation and sensitivity analysis.  
│
├── excel/
│   ├── Energy_Evaluation.xlsx  
│   ├── Energy_Evaluation_synthetic.xlsx  
│   ├── output_20250727_083046.xlsx  
│   ├── output_conventional_20250716_164258.xlsx  
│   ├── output_diurnal_pattern_20250728_093415.xlsx  
│   ├── output_synthetic_DRL20250929_181553.xlsx  
│   └── output_syth_conventional_20250929_183011.xlsx  
│
├── logs/ → TensorBoard training logs (events.out.tfevents.*)  
└── plot/
    ├── combined_plot_testing_2025-07-27_083401.png → Predicted vs observed pressures.  
    └── training_record_2025-07-27_082501.png → SAC training convergence plot.  

2. Excel Data Details

2.1 Input.xlsx

Defines control and training parameters for the DRL environment.

2.2 Input_drnl.xlsx

Represents randomised diurnal demand patterns used for training and testing the DRL agent. Each row corresponds to a normalized daily flow pattern for a pump station or demand scenario.

Note:
The diurnal profiles were derived and slightly randomized from field demand data to ensure generalisation and prevent overfitting to a single pattern.

2.3 Input_evaluate.xlsx

Contains evaluation and validation data used to assess the DRL model’s performance under observed operating conditions. Each row corresponds to one network junction or evaluation scenario.

Note:
This dataset was used to validate the DRL agent’s predictions by comparing simulated and actual performance across multiple flow and pressure conditions.

2.4 Input_synt.xlsx

Represents synthetic and randomised demand datasets generated to test the generalisation capability of the trained DRL agent under a wide range of operating conditions.

Note:
Each row defines a synthetic or randomised demand pattern of 100 points, ensuring the model’s robustness and stability during unseen operational scenarios.

2.5 Energy_Evaluation.xlsx and Energy_Evaluation_synthetic.xlsx

These files contain hourly energy and hydraulic performance data from the evaluation of the DRL-based and conventional control strategies. Each row represents one hourly time step during a 24-hour simulation.

Note:

• Both files summarize the energy and hydraulic performance for DRL-based (synthetic) and conventional (actual) control cases.
• Data were used to quantify energy savings, pressure stability, and compliance across diurnal and synthetic operating conditions.

2.6 Output_*.xlsx

Each file represents time-series or batch evaluation results for a specific simulation condition (e.g., diurnal, synthetic, or conventional control). The datasets record the DRL agent’s control actions, resulting pressures, and network responses across all demand management areas (DMAs).

Note:
Each output file (e.g., output_20250727_083046.xlsx, output_synthetic_DRL20250929_181553.xlsx) includes results from simulations under different operating scenarios — such as conventional, synthetic, or diurnal control cases. The data were used to assess the DRL agent’s performance in maintaining target pressures while minimizing energy consumption across all DMAs.

3. Software Environment and Execution

Tested on: Windows 11 (64-bit) operating system.

To reproduce results:

Use the SAC_Training_001.py script to retrain and regenerate the agent file (sac_water_networkR3.zip). The trained agent can then be evaluated using the provided input datasets to reproduce the results reported in the study. When applying the workflow to other hydraulic models, SAC_Training_001.py must be adapted to reflect the specific observation and action spaces of those models. All relevant hyperparameters should also be tuned to suit the new configuration.

4. Important Notes

This README contains all information required for independent reuse and re-analysis of the dataset without referring to the published article.

• Folder hierarchy must remain unchanged for scripts to run correctly.
• The dataset is self-contained and can be interpreted independently of the associated publication.
• Minor stochastic differences in results are expected when retraining.
• All data were aggregated and anonymized to remove sensitive information.
• TensorBoard logs can be visualized with tensorboard --logdir=logs/SAC_3/.
• Datasets cover Diurnal, Synthetic, and Conventional scenarios used in the article.