Skip to content
BranchesTags

Repository files navigation

SWMM_GNN_Metamodel (v2.0) - Evaluation of Graph Neural Networks for Urban Drainage Metamodeling: Key Components and Transferability Analysis

Paper repository for "Evaluation of Graph Neural Networks for Urban Drainage Metamodeling: Key Components and Transferability Analysis" by Alexander Garzón, Zoran Kapelan, Jeroen Langeveld, and Riccardo Taormina.

License: MIT

(Version 2.0.0 - Dec. 10th, 2025)

🌐 Overview

This repository contains the code for evaluating the performance and transferability of graph neural network-based metamodels of SWMM. It comprises three main components:

  1. Improved functionality This is an improved version of the repository SWMM GNN - Machine Learning Metamodels for Urban Drainage Systems with SWMM. This version extends the previous code to support training models that predict flowrates, evaluate combinations of hyperparameters and training settings, among other minor improvements. The original functionality includes dataset creation from SWMM simulations, machine learning model training, and model evaluation.

  2. Component evaluation of the GNN-based metamodels, namely, the type and number of graph layers, and the number of prediction steps per model execution. These components are highlighted in Figure 2.

  3. Transferability analysis across case studies and across tasks. In particular, the scripts test multiple training configurations for leveraging previous training process or examples on one drainage system for reusage in another one. All these configurations are shown in Figure 3.

The code uses Python as programming language and relies on the libraries PyTorch and PyTorch Geometric for the development of the neural networks.

🚀 Quick Demonstration

Spatial distribution of error and timeseries showcase. This dashboard shows an example of the metamodel predictions vs SWMM.

Figure 1: Spatial distribution of error and timeseries showcase. This dashboard shows an example of the metamodel predictions vs SWMM..

Details On the left panel, it shows the spatial distribution of RMSE for every pipe in the drainage system. Other properties such as predictions, SWMM values, and R2 values can be visualized. The right panel shows the time series of a pipe in the system for both SWMM and the metamodel.

To quickly explore the capabilities of the SWMM GNN Metamodel without waiting for model training, follow these steps:

  1. Install the required packages as described in the Installation section below.
  2. Download the case study data from the provided link in the Dataset Generation section, and place it in the correct folder structure (data/ and saved_objects/).
  3. Set up your environment variables by copying .env_example to .env and updating the paths to match your system.
  4. Open the notebook notebooks/Model_development.ipynb in Jupyter or VS Code.
  5. Run all cells in the notebook. The notebook is pre-configured to use configs/yaml_files/config.yaml, and the required data and saved objects (windows, pre-trained weights, normalizer) are already available. This allows you to immediately explore the behaviour and results of a pre-trained model, including predictions and interactive visualizations, without needing to run the time-consuming training process.

Note: You can change the configuration file or data paths later to run your own experiments or retrain models as needed.

Table of Contents

🎯 Scope

This repository is designed for researchers and practitioners working on urban drainage systems and hydraulic modeling. The code provides a comprehensive framework for:

  • Metamodel Development: Training and evaluating graph neural network-based surrogate models that can rapidly approximate SWMM simulations.
  • Hyperparameter Optimization: Systematic exploration of model architectures and training configurations to identify optimal settings.
  • Transfer Learning: Investigating the transferability of trained models across different drainage systems and prediction tasks.

💡 Potential Uses

The code can be applied to various scenarios in urban water management:

  • Real-time flood forecasting: Deploy trained metamodels for rapid prediction of hydraulic conditions during rainfall events, enabling timely flood warnings.
  • Uncertainty quantification: Generate ensemble predictions by training multiple models with different configurations to quantify prediction uncertainty.
  • Scenario analysis: Quickly evaluate multiple what-if scenarios for urban planning, infrastructure design, or climate change adaptation studies.
  • Optimization studies: Use metamodels as fast surrogate objectives in optimization algorithms for drainage system design.
  • Educational purposes: Demonstrate the application of graph neural networks to physical systems and transfer learning techniques.
  • Model comparison: Benchmark different GNN architectures and training strategies for hydraulic modeling applications.

🛠️ Functionality

Metamodel Development - Additions and Improvements

This codebase extends previous implementations to support a wider range of applications:

Flowrate Prediction

  • Models can now predict not only water levels at junctions but also flow rates in pipes
  • Visual dashboard (EdgesDashboard) for analyzing flow patterns
  • Multi-task trainer that optimizes for both predictions simultaneously
  • Quality control metrics for both heads and flows

Hyperparameter Exploration

  • Systematic sweep functionality for testing combinations of model settings
  • Efficiently run dozens of experiments in parallel with different architectures
  • Automatic result tracking and comparison

Lateral Inflows

  • Support for irregular inflow patterns in addition to rainfall data
  • Improved normalizer that handles variable inflow conditions
  • Enhanced SWMM simulation parser

Curriculum Learning

  • Models start by learning easy predictions (1-step ahead) then gradually progress to harder predictions (50+ steps ahead)
  • Two approaches: deterministic schedule or self-paced based on performance

Component Evaluation

Methodology image

Figure 2: How the GNN metamodel makes predictions. Three key components are evaluated: 1) Type of graph layer, 2) Depth of graph processor, and 3) Number of prediction steps.

Details Data Pre-processing: Time series data from SWMM is divided into windows and standardized using statistics from the training set. Inputs include past water levels, runoff, and system information (topology, elevations, pipe sizes).

Feature Encoding: Neural networks separately process information from junctions and pipes, creating condensed representations that the graph network can work with.

Graph Processing (Core): The graph neural network learns how water propagates through the system by examining how each junction interacts with its neighbors. We test two types: GINEConv and GATv2Conv, with network depths from 1 to 15 layers.

Output Decoding: The processed information is converted back into physical predictions (water levels, flows). These predictions are then fed back as inputs to predict the next time step, enabling long-term forecasting.

Transferability Analysis

Methodology image

Figure 3: Testing whether models trained on one drainage system can be reused for another, and whether knowledge learned for water levels helps predict flows.

Details Cross-System Transfer (Does a model trained in one city work in another?)
  • Zero-shot: Apply a model trained in System A directly to System B without any retraining
  • Fine-tuning: Take weights from System A and adapt them with a little more training on System B data
  • Joint training: Train one model using data from both systems simultaneously
  • Selective fine-tuning: After joint training, specialize the model for one specific system

Cross-Task Transfer (Does learning to predict water levels help predict flows?)

  • Sequential: First train on water levels, then use those weights as a starting point for flow prediction
    • Full update: All weights can change during flow training
    • Partial update: Only the flow-specific components are adjusted
  • Simultaneous: Train on both tasks from the beginning to see if the network finds shared patterns
    • Standard: Train for normal number of epochs
    • Extended: Double training time to match total compute of sequential approaches

🧰 Installation

For running the code in this repository you need to set up 3 parts: Code, environment, and the .env file.

  1. For the code, clone this repository to your computer.

    git clone git@github.com:alextremo0205/SWMM_GNN_Component_Evaluation_and_Transferability_Analysis.git

  2. For the environment, create a virtual environment with the following command. This program was developed in Python 3.12.3.

    python -m venv .venv

    Then, activate the environment.

    source .venv/Scripts/activate

    There are two ways of installing the required libraries:

    a) Using Poetry (recommended)

    1. Make sure you have Poetry installed. If not, follow the instructions on the Poetry documentation.

    2. Install Poetry and the project dependencies:

      pip install poetry
poetry install

      The pyproject.toml file contains all required libraries.

    b) Using pip

    Alternatively, install dependencies directly from requirements.txt:

    pip install -r requirements.txt --no-deps
  1. Environment Variables Setup

The code uses environment variables to manage paths and experiment tracking. The .env file can be created as a copy of the file '.env_example', and renamed to be .env. There, the paths to the respectives folders must be set to the correct places in your computer. Example:

# Experiment Tracking (Weights & Biases)
PROJECT_NAME=SWMM_GNN_Metamodel        # Name of your project in Weights & Biases
JOB_TYPE=Training                      # Type of job (e.g., Training, Evaluation)
TAGS=GNN,Transfer_Learning             # Tags for organizing experiments
NOTES="Component evaluation study"     # Notes describing this experiment run
WANDB_MODE=online                      # online, offline, or disabled
WANDB_DIR=./wandb                      # Local directory for wandb files
WANDB_ENTITY=user_name                 # Your username or company name in Weights & Biases

# Data and Model Storage
DATA_FOLDER=./data                     # Root folder containing SWMM simulations
SAVED_OBJECTS_FOLDER=./saved_objects   # Folder for saving models, normalizers, and results
YAML_FOLDER=./configs                  # Folder containing configuration files

# SWMM Software
SWMM_EXECUTABLE_PATH=C:\Program Files (x86)\EPA SWMM 5.1.015\swmm5.exe

Key variables explained:

  • WANDB_MODE: Controls how experiment results are logged. Use online to sync with the cloud, offline for local-only logging or disabled for not logging wandb runs.
  • DATA_FOLDER: Should contain your SWMM simulation results in the structure: DATA_FOLDER/[CaseStudyName]/simulations/
  • SAVED_OBJECTS_FOLDER: Automatically organized into subfolders: saved_models/, saved_normalizers/, saved_windows/, etc.

Adjust the paths according to your system. Use absolute paths to avoid issues across different terminals or notebooks.

🧭 Project Architecture

This project is organized into several key components that work together to train and evaluate drainage system metamodels:

Core Components

MLExperiment (SWMMMetamodel/MLExperiment.py)

  • The main orchestrator that manages the entire training workflow
  • Handles data preparation, model setup, training, and result evaluation
  • Automatically logs all results to Weights & Biases for experiment tracking

Data Pipeline

  • SWMM_Simulation.py: Reads SWMM binary output files (.out) containing simulation results
  • Windows: Time-window slices of the simulations, formatted as network graphs (nodes = junctions, edges = pipes)
  • Normalizer.py: Standardizes input features based on training data statistics, applied consistently across all datasets
  • Data Loaders: PyTorch Geometric DataLoaders that handle batch processing during training

Model Architecture

  • All models inherit from PyTorch's nn.Module
  • Use ModelFactory("ModelName") to instantiate models from configuration files
  • Two main types of outputs:
    • Heads-only: Predicts water surface elevations at junctions
    • Heads + Flows: Simultaneously predicts elevations and pipe flow rates

Training System

  • Trainer.py: Handles the training loop with support for curriculum learning and multi-task training
  • Curriculum Learning: Gradually increases prediction difficulty (multi-step-ahead predictions) during training
  • Transfer Learning: Reuses trained weights from previous experiments to accelerate learning in new systems

Evaluation & Results

  • MetricCalculator.py: Computes accuracy metrics (R², RMSE, MAE) for different conditions (dry, wet, overall)
  • QualityController.py: Validates experiment completeness and consistency
  • Profiler.py: Measures model execution speed compared to SWMM simulations

File Organization

SWMMMetamodel/
├── MLExperiment.py           # Main orchestrator
├── Trainer.py                # Training loops with curriculum learning
├── Normalizer.py             # Data standardization
├── SWMM_Simulation.py        # SWMM file parsing
├── MetricCalculator.py       # Performance metrics
├── models/
│   ├── Model_main.py         # Factory for instantiating models
│   ├── Layers.py             # Neural network layer definitions
│   └── [model variants]      # Different GNN architectures
configs/
├── yaml_files/               # Configuration templates for different case studies
└── sweep_files/              # Hyperparameter sweep definitions
saved_objects/
├── saved_models/             # Trained model weights
├── saved_normalizers/        # Data normalizers
├── saved_windows/            # Pre-processed time windows

🗂️ Configuration Files (YAML)

YAML configuration files control all aspects of an experiment. Here's what each section does:

Data & Network Settings

network: 'Tuindorp'                    # Name of your drainage system
use_saved_training_windows: True       # Load pre-processed windows if available
use_saved_validation_windows: True     # Skip window creation to save time
training_windows_names: 'Tuindorp_development_training_windows_100_events_lateral_inflow.pk'    # Training dataset 
validation_windows_name: 'Tuindorp_development_validation_windows_30_events_lateral_inflow.pk'  # Validation dataset

Transfer Learning Settings

use_pre_trained_weights: True          # Start with weights from a previous experiment
pre_trained_weights: 'Tuindorp_n_GNN_Layers_4_10_pred_zesty-glade-1908.pt.pt'  # Which model to load from
requires_freezing: False               # If True, prevents updating some layers (for fine-tuning)
layers_to_freeze:                      # List of parameter names that are frozen in case requires_freezing is activated
- nodeEncoder
- ...
use_saved_normalizer: True             # Use the a saved normalizer 
normalizer_name: 'normalizer_tuindorp.pk'

Training Configuration

trainer_name: 'Trainer_Heads'          # Type of trainer: Trainer_Heads or Trainer_Heads_Flows
epochs: 25                             # Number of training iterations
batch_size: 32                         # How many windows per batch
learning_rate: 0.00194                 # Step size for weight updates (start smaller, increase if needed)
weight_decay: 0.01                     # Regularization to prevent overfitting
min_expected_loss: 100                 # Stop training if loss exceeds this (prevents divergence)

Curriculum Learning (Progressive Training)

type_curriculum: 'Vanilla'             # 'Vanilla' or 'Self-paced'
initial_steps_ahead_N: 1               # Start by predicting 1 step ahead
final_steps_ahead: 50                  # Gradually increase to 50 steps ahead
jump_steps_ahead_N: 2                  # Increase prediction steps by this amount
curriculum_parameter: 10               # Increase difficulty every N epochs
steps_ahead_validation: 50             # How far ahead to evaluate during validation

Model Architecture Parameters

model_name: 'NN_GNN_NN_Flow'           # Which model architecture to use
hidden_dim: 32                         # Size of internal feature vectors (try 32-256)
n_hidden_layers: 2                     # Depth of neural networks (try 1-4)
steps_behind: 9                        # How many past time steps to use as input
prediction_steps: 1                    # How many steps ahead each prediction covers

# GNN-specific parameters
type_GNN: 'GINEConv'                   # Type of aggregation layer of the GNN
k_hops: 1                              # How many neighbors to consider in graph (1-3)
eps_gnn: 0.5                           # Tolerance for graph operations (0.01-1.0)

# Non-GNN models may ignore these parameters

Multi-Task Learning (Heads + Flows)

with_Q: True                           # Also predict flow rates (not just water levels)
node_loss_weight: 1.0                  # Importance of head predictions (0.1-2.0)
edge_loss_weight: 1.0                  # Importance of flow predictions (0.1-2.0)

Quick Reference for Hyperparameter Tuning

Parameter Range Effect
learning_rate 0.0001 - 0.01 Smaller = slower but more stable learning
hidden_dim 16 - 256 Larger = more expressive but slower
n_hidden_layers 1 - 8 Deeper network layers in MLPs. They need more data to avoid overfitting
batch_size 8 - 128 Larger = faster training but needs more GPU memory
weight_decay 0.0 - 0.1 Higher = stronger regularization (helps with overfitting)

🧮 YAML Files: Configuration vs. Sweep Files

The repository uses two types of YAML files with different purposes:

Configuration Files (Base Configs)

Location: configs/yaml_files/

Purpose: Define a complete, specific experiment setup. All parameters needed for training are specified with single values.

When to use:

  • Running a single experiment with known settings
  • Fine-tuning an existing setup
  • Serving as a template for sweep files

Structure: Complete parameter specification

# base_config_Loenen.yaml
network: 'Loenen'
use_saved_training_windows: True
training_windows_names: 'Loenen_training_windows_100_events.pk'
validation_windows_name: 'Loenen_validation_windows_30_events.pk'

trainer_name: 'Trainer_Heads'
epochs: 100
batch_size: 32
learning_rate: 0.00194
weight_decay: 0.01

model_name: 'NN_GNN_NN'
hidden_dim: 32
n_hidden_layers: 1

Key characteristics:

  • Every parameter has exactly ONE value
  • Ready to run: python main.py --config config.yaml
  • Organized by drainage system (Tuindorp, Loenen)

Sweep Files (Hyperparameter Search)

Location: configs/sweep_files/ (organized by study type)

Purpose: Define parameter ranges to test. The sweep controller automatically creates multiple experiments by combining all parameter combinations.

When to use:

  • Exploring which model architecture works best
  • Finding optimal hyperparameters
  • Comparing different training strategies
  • Running systematic ablation studies

Structure: Parameters with lists of values to test

# configs/sweep_files/Component_evaluation/Initial_grid_evaluation_Tuindorp.yaml
# Only override parameters you want to test - inherits base config values
n_GNN_layers:
  values:
    - 1
    - 5
    - 10
    - 15
prediction_steps:
  values:
    - 1
    - 10
    - 20
    - 30
    - 50
    - 100
type_GNN:
  values:
    - GINEConv
    - GATv2Conv

This sweep file with 4 n_GNN_layers options × 6 prediction_steps options × 2 layer options = 48 experiments total

Key characteristics:

  • Parameters can have lists of values (ranges to test)
  • Omitted parameters use values from base_config
  • Run with: python sweep_controller.py --sweep <sweep_file> --base_config <base_config file in configs/yaml_files> --count 16

How They Work Together

Example workflow for hyperparameter optimization:

  1. Start with a base config (base_config_Tuindorp.yaml)

    • Contains all defaults for your drainage system
    • Proven to work reasonably well

  2. Create a sweep file (Tuindorp_sweep.yaml)

    • Specifies only the parameters you want to test
    • Everything else comes from the base config

  3. Run the sweep

    python sweep_controller.py \
  --sweep configs/sweep_files/Component_evaluation/Tuindorp_sweep.yaml \
  --base_config base_config_Tuindorp.yaml \
  --script main.py \
  --count 55

  4. System automatically:

    • Loads the base config as a template
    • Creates 48 experiment configurations by combining sweep values
    • Runs them in parallel (respecting your GPU/CPU limits)
    • Logs all results to Weights & Biases for comparison

File Organization Pattern

configs/
├── yaml_files/                        # Complete configurations
│   ├── base_config_Tuindorp.yaml      # Template for Tuindorp experiments
│   ├── base_config_Loenen.yaml        # Template for Loenen experiments
│   └── base_config_both_case_studies.yaml  # Template for joint training
│
└── sweep_files/                       # Parameter ranges to test
    ├── Component_evaluation/
    │   ├── Initial_grid_evaluation_Tuindorp.yaml  # Basic architecture search
    │   ├── Tuindorp_1_2_type_and_depth_GNN_layers.yaml  # GNN architecture
    │   └── Tuindorp_3_prediction_steps.yaml  # Multi-step prediction
    │
    └── Transferability_Analysis/
        ├── Domain_Transfer/           # Test across different systems
        │   ├── 1_Tuindorp_Zero_Shot_N_Tuindorp.yaml
        │   ├── 2_Loenen_Zero_Shot_N_Loenen.yaml
        │   └── ... (5 different transfer scenarios)
        │
        └── Task_Transfer/             # Test across prediction tasks
            ├── 1_Tuindorp_Target_Task_fine_tuning.yaml
            ├── 2_Tuindorp_Target_Task_full_fine_tuning.yaml
            └── ... (4 different task scenarios)

Comparison Table

Aspect Configuration File Sweep File
Purpose Complete experiment setup Parameter ranges to test
Typical use Single training run Systematic exploration
Parameter format Single values only Lists of values
Example batch_size: 32 batch_size: [16, 32, 64]
Run command main.py sweep_controller.py
Location configs/yaml_files/ configs/sweep_files/
Results 1 trained model N trained models (one per combination)
Use case Fine-tuning known setup Finding best hyperparameters

Creating Your Own Files

To create a new base config:

  1. Copy an existing base config that matches your drainage system
  2. Update the network name
  3. Adjust paths to your data
  4. Run: python main.py --config your_config.yaml

To create a new sweep file:

  1. Choose what parameters to test (e.g., learning_rate, hidden_dim)
  2. Define ranges for each parameter
  3. List other parameters you want to override
  4. Omit everything else - it will use base config values
  5. Run: python sweep_controller.py --sweep your_sweep.yaml --base_config base_config_*.yaml --count N

▶️ Usage

Dataset generation

Reproducing the case study

In case you want to reproduce the models for the case study, you can find all the data used in the study in this link. Otherwise, you can generate the data by following the instructions below.

Required data

Create a folder structure as follows:

data
|__real_rainfalls
|__[Case study name]
  |__networks
    |__[SWMM input file].inp #This needs to have the same name as the case study, same as the folder
  |__rainfall_dats
    |__training
    |__validation
    |__testing

For the generation of the dataset, it is possible to count with the information of the real rainfalls in the folder "saved_objects\real_rainfalls". For the case study, the file contains rainfall events of 5 minutes resolution extracted from the files from KNMI - The Netherlands over the case study in the year 2014.

Alternatively, the rainfall events can be generated using the alternating block method, which is also in the notebooks.

  • In the folder "saved_objects", add your SWMM input file (.inp) in the folder [case study name]/networks
    • Optional: In case you have rainfall files (.dat), add them in the folders saved_objects/[case study name]/rainfall_dats/[training, validation, testing].
  • The code for generating the rainfall files (.dat) and the SWMM simulations is in the notebook Database_creation.
  • Inside the folder networks, there should be the SWMM input file (.inp) of the drainage network. This drainage network should have a rain gage with the name R1, and its data series should be called "PLACEHOLDER1". For example,
[RAINGAGES]
;;Name           Format    Interval SCF      Source
;;-------------- --------- ------ ------ ----------
; Name Format Interval SCF Source
R_1              INTENSITY 0:05     1.0      FILE       "PLACEHOLDER1" R1         MM
  • Adjust the time steps for the routing, the runoff and the reporting. For example, 1 minute for the Wet Weather runoff, 1 minute for the Dry Weather runoff, and 1 second for the routing.

Running Single Experiments

Once you have configured a YAML file with your desired settings, you can run an experiment in two ways:

Using Jupyter Notebook (Recommended for Exploration)

The notebook Model development provides an interactive way to:

  • Load and visualize your configuration
  • Run the complete training pipeline
  • View real-time training progress
  • Visualize predictions against SWMM results

Using Command Line (Recommended for Batch Processing)

Run the following command from the repository root:

python main.py --config <config_filename>

Example:

python main.py --config config.yaml

What happens during execution:

  1. Configuration is loaded from the YAML file
  2. SWMM simulation data is loaded (or loaded from cache if available)
  3. Time windows are created (or loaded from previous runs)
  4. Data normalizer is fitted on training data
  5. Model is initialized with specified architecture
  6. Training loop runs with curriculum learning progression
  7. Validation performance is monitored
  8. Results are automatically logged to Weights & Biases
  9. Best model is saved to saved_objects/saved_models/

Running Hyperparameter Studies

To systematically test different combinations of model parameters (learning rate, network depth, etc.), use the sweep controller:

python sweep_controller.py \
  --sweep configs/sweep_files/my_sweep.yaml \
  --base_config base_config_Tuindorp.yaml \
  --script main.py \
  --count 48

Parameters explained:

  • --sweep: YAML file defining which parameters to test and their ranges
  • --base_config: Base configuration that sweep parameters override
  • --count: Number of parallel experiments to run

Example sweep file structure:

hidden_dim:
  - 32
  - 64
  - 128
learning_rate:
  - 0.001
  - 0.005
  - 0.01

This would run 3 × 3 = 9 experiments with different combinations.

♻️ Reproducibility

For full, ready-to-run commands, see docs/REPRODUCIBILITY.md.

Quick pointers

  • Component evaluation: sweeps in configs/sweep_files/Component_evaluation/ with base configs in configs/yaml_files/.
    • Initial grid search: Initial_grid_evaluation_[Tuindorp|Loenen].yaml
    • GNN depth/type: *_1_2_type_and_depth_GNN_layers.yaml
    • Prediction steps: *_3_prediction_steps.yaml
  • Domain transfer (cross-system): configs/sweep_files/Transferability_Analysis/Domain_Transfer/
  • Task transfer (heads → flows): configs/sweep_files/Transferability_Analysis/Task_Transfer/

Run pattern:

python sweep_controller.py --sweep <sweep_yaml> --base_config <base_yaml> --script main.py --count <N>

See the detailed guide for the exact commands and recommended counts.

🩺 Troubleshooting

Common Issues

Problem Possible Cause Solution
FileNotFoundError when loading windows Windows haven't been generated yet Set use_saved_training_windows: False in config to generate them
IncorrectTrainerException Model output format doesn't match trainer Check that trainer_name matches model type (e.g., use Trainer_Heads_Flows for models with both outputs, activate the flag with_Q in the yaml file, and select the model NN_GNN_NN_Flow.)
GPU out of memory (OOM) Batch size too large for GPU Reduce batch_size in config (try 16, 8, or 4)
Training loss diverges (NaN) Learning rate too high Reduce learning_rate by a factor of 2-5
Model not improving after 50 epochs Curriculum learning settings Check initial_steps_ahead_N and curriculum_parameter settings
Import errors when running Python packages not installed Run pip install -r requirements.txt or poetry install
Weights & Biases not logging Environment variable issues Verify .env file has WANDB_MODE=online and correct paths

Debugging Tips

  1. Check the log output: The console shows detailed progress. Look for warnings about data shapes or loss values.
  2. Start small: Test with fewer epochs (e.g., 5) to quickly identify configuration issues.
  3. Verify data loading: Ensure SWMM .out files exist in the expected location.
  4. Use example configs: Start with config.yaml to verify the setup works.
  5. Check saved results: After training, examine saved_objects/saved_models/ to confirm files were saved.

⚠️ Current Limitations

  • The code can only handle systems with junctions, outfalls and pipes. It cannot handle systems with pumps, weirs, orifices, storage units or other types of special components.
  • The type of drainage systems that the code can handle is limited to the ones that can be represented in SWMM.
  • The code can only handle systems with one rain gage.
  • The code does not handle offsets of the pipes in the network, it assumes that all the pipes are connected to invert of the nodes.
  • The model does not support more parallel edges (e.g., two pipes connecting the same nodes).

📜 Citation

Please cite our paper as:

@article{
title = {Evaluation of graph neural networks for urban drainage metamodeling: Key components and transferability analysis},
journal = {Water Research},
pages = {125079},
year = {2025},
issn = {0043-1354},
doi = {https://doi.org/10.1016/j.watres.2025.125079},
url = {https://www.sciencedirect.com/science/article/pii/S0043135425019827},
author = {Alexander Garzón and Zoran Kapelan and Jeroen Langeveld and Riccardo Taormina},
keywords = {Sewer networks, Surrogate modelling, Deep learning, Transfer learning, SWMM},
}

🙏 Acknowledgements

The development of this code is supported by the TU Delft AI Labs programme as part of one of the PhD projects framed in AidroLab.

📝 Licensing and Waiver

Licensed under MIT, subject to waiver:

Technische Universiteit Delft hereby disclaims all copyright interest in the program "SWMM_GNN_Metamodel (v2.0)" (Evaluation of Graph Neural Networks for Urban Drainage Metamodeling: Key Components and Transferability Analysis) written by the Author(s).

Prof.dr.ir. Stefan Aarninkhof, Dean of Civil Engineering and Geosciences

Copyright (c) 2025 Jorge Alexander Garzón Díaz.

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

9 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

Packages

Contributors

Languages