How matthijsdej/gnn_pn_imitation_learning works
Project Type and Purpose
• Research pipeline for “Generalizable Graph Neural Networks for Robust Power Grid Topology Control”
• Composed of three sequential stages:
– Simulation of power‐grid control agents (Grid2Op environment)
– Analysis & preprocessing of state‐action logs into a training dataset
– Imitation‐learning training of neural models (FCNN/GCN)
• Top-level scripts coordinate each stage: simulate.py → preprocess_data.py → train_network.py
Main Components
A. Auxiliary Modules (shared)
• config.py: loads/validates user settings (config.yaml + CLI overrides)
• generate_action_space.py: builds valid action‐sets
• grid2op_util.py / util.py: helper functions for environment & generic utilities
B. Stage 1 – Simulation
• simulate.py: CLI entry point
• simulation/simulation.py: orchestrates Grid2Op env + Agent loop across days & scenarios
• simulation/strategy.py: AgentStrategy ABC + rule‐based/ML strategies
• parse_logs.py: aggregates/logs simulation results
• Outputs:
– evaluation log file
– raw state‐action vectors (Observation.to_vect())
C. Stage 2 – Data Analysis & Preprocessing
• data_preprocessing_analysis/data_analysis.ipynb: exploratory analysis
• data_preprocessing_analysis/data_preprocessing.py: processes raw observations →
• cleans topologies (removes disabled‐line endpoints)
• normalizes features & collects adjacency‐hash table
• shuffles via buffer sampling
• preprocess_data.py: CLI entry point
• Outputs:
– processed data folder (train/val/test .pt or .npy files)
– feature‐stats file (for normalization)
– adjacency‐hash lookup file
D. Stage 3 – Imitation Learning (IL)
• train_network.py: CLI entry point
• training/dataloader.py: DataLoader + ProcessDataPointStrategy (FCNN vs GCN)
• training/models.py: Model ABC → FCNN & GCN (homogeneous/heterogeneous)
• training/postprocessing.py: ActSpaceCache maps predictions → valid actions
• training/training.py: Run.start() implements training loop + incremental metrics + W&B logging
• training/evaluation.py: metrics tracking (IncrementalAverageMetrics)
• evaluation.ipynb: post‐training evaluation & plotting
• Outputs:
– trained model artifact
– W&B logs & plots
Component Relationships & Data Flow
1. User invokes simulate.py (Stage 1 CLI) → Auxiliary.config loads settings → simulation module spins up Grid2Op
2. simulate.py produces raw logs + state‐action vectors → parse_logs.py summarizes them
3. preprocess_data.py (Stage 2 CLI) reads raw vectors → data_preprocessing.py extracts/normalizes features → writes processed dataset + stats + adjacency hash
4. train_network.py (Stage 3 CLI) reads processed data → training pipeline:
• DataLoader → Model → Postprocessing → Metrics → W&B → Model checkpoint
5. Trained Model can be redeployed in Stage 1 simulation for new experiments
Architectural Patterns & Design Principles
• Pipeline structure: clear separation of concerns (Simulation → Preprocessing → Training)
• Strategy pattern: AgentStrategy & ProcessDataPointStrategy for interchangeable behaviors
• Abstract Base Classes: Model ABC, AgentStrategy ABC for extensibility
• Configuration centralization via config.yaml + config.py
• Modular I/O: top‐level CLI scripts isolate orchestration
• Notebook support for exploratory analysis & evaluation
Technologies & Frameworks
• Python 3.x
• Grid2Op environment (rte_case14_realistic)
• NumPy, PyTorch (torch.nn.Module)
• Jupyter Notebooks (analysis & evaluation)
• Weights & Biases (W&B) for experiment tracking
• YAML for configuration