---

name: powergraph-gnn-research description: Research pipeline for topology-aware GNN representation learning on power grids using the PowerGraph benchmark. Use when (1) building physics-guided GNNs for power flow (PF), optimal power flow (OPF), or cascading failure prediction, (2) implementing self-supervised pretraining for power systems, (3) evaluating cascade explanation fidelity against ground-truth masks, or (4) conducting reproducible ML-for-power-systems research. Triggers include "PowerGraph", "power flow GNN", "OPF surrogate", "cascade prediction", "physics-guided GNN", "grid analytics ML", "power system representation learning".

PowerGraph GNN Research Pipeline

Primary claim: A grid-specific self-supervised, physics-consistent GNN encoder improves PF/OPF learning (especially low-label/OOD), and transfers to cascading-failure prediction and explanation.

Scripts

Workflow

1. Data → PowerGraph → PyG (PF/OPF node targets + cascade graph labels + exp masks)
2. Baseline → PF regression with sin/cos angles + physics residual metric
3. Multi-task → Shared encoder + PF/OPF/Cascade heads
4. SSL → Masked injection/edge reconstruction → fine-tune
5. Evaluation → Explanation AUC vs ground-truth masks + robustness tests

Validity Anchors (Critical)

Angle handling: Predict sin(θ), cos(θ), recover via atan2. Direct MSE on raw angles fails at ±π wrap-around.

Physics residual: Report KCL mismatch alongside accuracy. Ground truth ≈ 0, random >> 1.

Blocked splits: PowerGraph uses 1-year load @ 15-min. Use months 1-9 train / 10 val / 11-12 test. Random splits leak seasonal patterns.

Explanation fidelity: Use PowerGraph exp.mat ground-truth masks. Report AUC + Precision@K.

Reference Docs

• references/data_pipeline.md — PowerGraph → PyG conversion, splits
• references/model_architecture.md — Physics-guided message passing, heads
• references/ssl_pretraining.md — Masked tasks, low-label experiments
• references/uncertainty_quantification.md — Ensembles, MC dropout, calibration
• references/evaluation_protocols.md — Metrics, robustness, statistical tests
• references/publication_soundness.md — Reviewer risks, claim framing
• references/experiment_configs.md — YAML config structure, sweeps

Common Pitfalls

Publication Checklist

• Ablation: single-task vs multi-task vs SSL+multi-task
• Low-label curves: 10/20/50/100% training data
• Physics residual alongside accuracy metrics
• Blocked splits (not random)
• Explanation AUC against exp.mat ground truth
• Robustness under edge-drop perturbations
• Statistical significance with 95% CI
• One-command reproducibility (python analysis/run_all.py)