When should I use powergraph-gnn-research?

powergraph-gnn-research is useful in the following scenarios: • Building physics-guided GNNs for power flow (PF) and optimal power flow (OPF) that maintain consistency with Kirchhoff's laws. • Implementing self-supervised pretraining (SSL) to improve GNN representation learning in low-label or out-of-distribution (OOD) power system datasets. • Evaluating the fidelity of cascading failure explanations by comparing model-generated masks against ground-truth data. • Conducting reproducible ML-for-power-systems research using standardized data ingestion, multi-task training workflows, and statistical significance testing. • Mitigating common pitfalls in power system ML, such as data leakage from random splits and angle wrap-around issues in regression.

powergraph-gnn-research

from majiayu000

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".

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026

When & Why to Use This Skill

The PowerGraph GNN Research Pipeline is a specialized Claude skill designed for researchers developing topology-aware Graph Neural Networks (GNNs) for power grid analytics. It streamlines the implementation of physics-guided machine learning, self-supervised pretraining, and rigorous evaluation of power flow (PF), optimal power flow (OPF), and cascading failure predictions using the PowerGraph benchmark. By integrating validity anchors like physics residual metrics and blocked time-series splits, it ensures high-fidelity, reproducible results suitable for top-tier academic publications.

Use Cases

Building physics-guided GNNs for power flow (PF) and optimal power flow (OPF) that maintain consistency with Kirchhoff's laws.
Implementing self-supervised pretraining (SSL) to improve GNN representation learning in low-label or out-of-distribution (OOD) power system datasets.
Evaluating the fidelity of cascading failure explanations by comparing model-generated masks against ground-truth data.
Conducting reproducible ML-for-power-systems research using standardized data ingestion, multi-task training workflows, and statistical significance testing.
Mitigating common pitfalls in power system ML, such as data leakage from random splits and angle wrap-around issues in regression.

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".

name

powergraph-gnn-research

description

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

Task	Script
Data ingestion	`scripts/load_powergraph.py`
PF baseline	`scripts/train_pf_baseline.py`
Physics metrics	`scripts/physics_residual.py`
SSL pretraining	`scripts/pretrain_ssl.py`
Multi-task training	`scripts/train_multitask.py`
Explanation eval	`scripts/eval_cascade_explanation.py`

Workflow

Data → PowerGraph → PyG (PF/OPF node targets + cascade graph labels + exp masks)
Baseline → PF regression with sin/cos angles + physics residual metric
Multi-task → Shared encoder + PF/OPF/Cascade heads
SSL → Masked injection/edge reconstruction → fine-tune
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

Issue	Fix
Angle wrap-around	sin/cos representation
Data leakage	Blocked time splits
Cascade imbalance	Weighted/focal loss
OOM large grids	Gradient checkpointing
SSL collapse	Stop-gradient + EMA encoder
Physics violations	Residual regularization

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)