Skip to content

Commit 80611a9

Browse files
romeokienzlerromeokienzler
committed
add missing doc
1 parent 7030042 commit 80611a9

5 files changed

Lines changed: 396 additions & 1 deletion

File tree

‎docs/index.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,12 @@ This library is brought to you by the GridFM team to train, finetune and interac
1414

1515

1616

17-
## Citation: TBD
17+
## Citation:
18+
```bibtex
19+
@software{gridfm_graphkit_2024,
20+
author = {Matteo Mazzonelli, Celia Cintas, Alban Puech and others},
21+
title = {GridFM GraphKit},
22+
url = {https://github.com/gridfm/gridfm-graphkit},
23+
year = {2024}
24+
}
25+
```

‎docs/tasks/optimal_power_flow.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Optimal Power Flow Task
2+
3+
The Optimal Power Flow (OPF) task solves the optimization problem of determining the most economical operation of a power system while satisfying physical and operational constraints. This task predicts optimal generator setpoints, voltage profiles, and reactive power dispatch.
4+
5+
## Overview
6+
7+
Optimal Power Flow is a fundamental optimization problem in power systems that minimizes generation costs while ensuring:
8+
9+
- **Power balance**: Supply meets demand at all buses
10+
- **Voltage constraints**: Bus voltages remain within acceptable limits
11+
- **Thermal limits**: Branch flows don't exceed capacity
12+
- **Generator limits**: Active and reactive power generation within bounds
13+
- **Angle difference limits**: Voltage angle differences across branches are acceptable
14+
15+
The `OptimalPowerFlowTask` extends the `ReconstructionTask` to include OPF-specific physics-based constraints and economic metrics.
16+
17+
## Key Features
18+
19+
- **Economic optimization**: Tracks generation costs and optimality gap
20+
- **Constraint violation monitoring**: Measures violations of thermal, voltage, and angle limits
21+
- **Physics-based evaluation**: Computes power balance errors and residuals
22+
- **Bus type differentiation**: Separate metrics for PQ, PV, and REF buses
23+
- **Comprehensive reporting**: Generates detailed CSV reports and correlation plots
24+
25+
## OptimalPowerFlowTask
26+
27+
::: gridfm_graphkit.tasks.opf_task.OptimalPowerFlowTask
28+
29+
## Metrics
30+
31+
The Optimal Power Flow task computes extensive metrics during testing:
32+
33+
### Economic Metrics
34+
- **Optimality Gap (%)**: Percentage difference between predicted and optimal generation costs
35+
- **Generation Cost**: Total cost computed from quadratic cost curves (c₀ + c₁·Pg + c₂·Pg²)
36+
37+
### Power Balance Metrics
38+
- **Active Power Loss (MW)**: Mean absolute active power residual across all buses
39+
- **Reactive Power Loss (MVar)**: Mean absolute reactive power residual across all buses
40+
41+
### Constraint Violations
42+
- **Branch Thermal Violations (MVA)**:
43+
- Forward direction: Mean excess flow above thermal limits
44+
- Reverse direction: Mean excess flow above thermal limits
45+
- **Branch Angle Violations (radians)**: Mean violation of angle difference constraints
46+
- **Reactive Power Violations**:
47+
- PV buses: Mean Qg violation (exceeding min/max limits)
48+
- REF buses: Mean Qg violation (exceeding min/max limits)
49+
50+
### Prediction Accuracy (RMSE)
51+
Computed separately for each bus type (PQ, PV, REF):
52+
- **Voltage Magnitude (Vm)**: p.u.
53+
- **Voltage Angle (Va)**: radians
54+
- **Active Power Generation (Pg)**: MW
55+
- **Reactive Power Generation (Qg)**: MVar
56+
57+
### Residual Statistics (when verbose=True)
58+
For each bus type and power type (P, Q):
59+
- Mean residual per graph
60+
- Maximum residual per graph
61+
62+
## Bus Types
63+
64+
The task evaluates performance separately for three bus types:
65+
66+
- **PQ Buses**: Load buses with specified active and reactive power demand
67+
- **PV Buses**: Generator buses with specified active power and voltage magnitude
68+
- **REF Buses**: Reference/slack buses that balance the system
69+
70+
## Outputs
71+
72+
### CSV Reports
73+
Two CSV files are generated per test dataset:
74+
75+
1. **`{dataset}_RMSE.csv`**: RMSE metrics by bus type
76+
- Columns: Metric, Pg (MW), Qg (MVar), Vm (p.u.), Va (radians)
77+
- Rows: RMSE-PQ, RMSE-PV, RMSE-REF
78+
79+
2. **`{dataset}_metrics.csv`**: Comprehensive metrics including:
80+
- Average active/reactive residuals
81+
- RMSE for generator active power
82+
- Mean optimality gap
83+
- Branch thermal violations (from/to)
84+
- Branch angle difference violations
85+
- Qg violations for PV and REF buses
86+
87+
### Visualizations (when verbose=True)
88+
89+
1. **Cost Correlation Plot**: Predicted vs. ground truth generation costs with correlation coefficient
90+
2. **Residual Histograms**: Distribution of power balance residuals by bus type
91+
3. **Feature Correlation Plots**: Predictions vs. targets for Vm, Va, Pg, Qg by bus type, including Qg violation highlighting
92+
93+
## Configuration Example
94+
95+
```yaml
96+
task:
97+
name: OptimalPowerFlow
98+
verbose: true
99+
100+
training:
101+
batch_size: 32
102+
epochs: 100
103+
losses: ["MaskedMSE", "PBE"]
104+
loss_weights: [0.01, 0.99]
105+
106+
optimizer:
107+
name: Adam
108+
lr: 0.001
109+
```
110+
111+
## Physics-Based Constraints
112+
113+
The task uses specialized layers to compute physical quantities:
114+
115+
- **`ComputeBranchFlow`**: Calculates active (Pft) and reactive (Qft) power flows on branches
116+
- **`ComputeNodeInjection`**: Aggregates branch flows to compute net injections at buses
117+
- **`ComputeNodeResiduals`**: Computes power balance violations (residuals)
118+
119+
These ensure predictions are evaluated not just on accuracy but also on physical feasibility.
120+
121+
## Usage
122+
123+
The Optimal Power Flow task is automatically selected when you specify `task.name: OptimalPowerFlow` in your YAML configuration file. The task:
124+
125+
1. Performs forward pass through the model
126+
2. Inverse normalizes predictions and targets
127+
3. Computes branch flows and power balance residuals
128+
4. Evaluates constraint violations
129+
5. Calculates economic metrics (costs, optimality gap)
130+
6. Generates comprehensive reports and visualizations
131+
132+
## Related
133+
134+
- [Power Flow Task](power_flow.md): For standard power flow analysis without optimization
135+
- [State Estimation Task](state_estimation.md): For state estimation from measurements
136+
- [Feature Reconstruction](feature_reconstruction.md): Base reconstruction task

‎docs/tasks/power_flow.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Power Flow Task
2+
3+
The Power Flow task solves the fundamental problem of determining the steady-state operating conditions of a power system. Given load demands and generator setpoints, it computes voltage magnitudes, voltage angles, and power flows throughout the network.
4+
5+
## Overview
6+
7+
Power Flow (also known as Load Flow) analysis is essential for power system planning and operation. It determines:
8+
9+
- **Voltage profiles**: Magnitude and angle at each bus
10+
- **Power flows**: Active and reactive power on transmission lines
11+
- **Power injections**: Net power generation/consumption at buses
12+
- **System losses**: Total active and reactive power losses
13+
14+
The `PowerFlowTask` extends the `ReconstructionTask` to include physics-based power balance evaluation and comprehensive metrics for different bus types.
15+
16+
## Key Features
17+
18+
- **Physics-based validation**: Computes power balance errors (PBE) to verify physical consistency
19+
- **Bus type differentiation**: Separate metrics for PQ, PV, and REF buses
20+
- **Distributed training support**: Handles multi-GPU training with proper metric aggregation
21+
- **Detailed predictions**: Provides per-bus predictions with residuals for analysis
22+
- **Comprehensive reporting**: Generates CSV reports and correlation plots
23+
24+
## PowerFlowTask
25+
26+
::: gridfm_graphkit.tasks.pf_task.PowerFlowTask
27+
28+
## Metrics
29+
30+
The Power Flow task computes the following metrics during testing:
31+
32+
### Power Balance Metrics
33+
- **Active Power Loss (MW)**: Mean absolute active power residual across all buses
34+
- **Reactive Power Loss (MVar)**: Mean absolute reactive power residual across all buses
35+
- **PBE Mean**: Mean Power Balance Error magnitude across all buses (√(P² + Q²))
36+
- **PBE Max**: Maximum Power Balance Error across all buses
37+
38+
### Prediction Accuracy (RMSE)
39+
Computed separately for each bus type (PQ, PV, REF):
40+
- **Voltage Magnitude (Vm)**: p.u.
41+
- **Voltage Angle (Va)**: radians
42+
- **Active Power Generation (Pg)**: MW
43+
- **Reactive Power Generation (Qg)**: MVar
44+
45+
### Residual Statistics (when verbose=True)
46+
For each bus type (PQ, PV, REF) and power type (P, Q):
47+
- Mean residual per graph
48+
- Maximum residual per graph
49+
50+
## Bus Types
51+
52+
The task evaluates performance separately for three bus types:
53+
54+
- **PQ Buses**: Load buses with specified active and reactive power demand
55+
- **PV Buses**: Generator buses with specified active power and voltage magnitude
56+
- **REF Buses**: Reference/slack buses that balance the system
57+
58+
## Power Balance Error (PBE)
59+
60+
The Power Balance Error is a critical metric that measures how well predictions satisfy Kirchhoff's laws:
61+
62+
$$
63+
\text{PBE} = \sqrt{(\Delta P)^2 + (\Delta Q)^2}
64+
$$
65+
66+
where:
67+
- $\Delta P$ = Active power residual (generation - demand - losses)
68+
- $\Delta Q$ = Reactive power residual (generation - demand - losses)
69+
70+
Lower PBE values indicate better physical consistency of the predictions.
71+
72+
## Outputs
73+
74+
### CSV Reports
75+
Two CSV files are generated per test dataset:
76+
77+
1. **`{dataset}_RMSE.csv`**: RMSE metrics by bus type
78+
- Columns: Metric, Pg (MW), Qg (MVar), Vm (p.u.), Va (radians)
79+
- Rows: RMSE-PQ, RMSE-PV, RMSE-REF
80+
81+
2. **`{dataset}_metrics.csv`**: Power balance metrics
82+
- Avg. active res. (MW)
83+
- Avg. reactive res. (MVar)
84+
- PBE Mean
85+
- PBE Max
86+
87+
### Visualizations (when verbose=True)
88+
89+
1. **Residual Histograms**: Distribution of power balance residuals by bus type (PQ, PV, REF)
90+
2. **Feature Correlation Plots**: Predictions vs. targets for Vm, Va, Pg, Qg by bus type
91+
92+
### Prediction Output
93+
94+
The `predict_step` method returns detailed per-bus information:
95+
96+
```python
97+
{
98+
'scenario': scenario IDs,
99+
'bus': bus indices,
100+
'pd_mw': active power demand,
101+
'qd_mvar': reactive power demand,
102+
'vm_pu_target': target voltage magnitude,
103+
'va_target': target voltage angle,
104+
'pg_mw_target': target active power generation,
105+
'qg_mvar_target': target reactive power generation,
106+
'is_pq': PQ bus indicator,
107+
'is_pv': PV bus indicator,
108+
'is_ref': REF bus indicator,
109+
'vm_pu': predicted voltage magnitude,
110+
'va': predicted voltage angle,
111+
'pg_mw': predicted active power generation,
112+
'qg_mvar': predicted reactive power generation,
113+
'active res. (MW)': active power residual,
114+
'reactive res. (MVar)': reactive power residual,
115+
'PBE': power balance error magnitude
116+
}
117+
```
118+
119+
## Configuration Example
120+
121+
```yaml
122+
task:
123+
name: PowerFlow
124+
verbose: true
125+
126+
training:
127+
batch_size: 32
128+
epochs: 100
129+
losses: ["MaskedMSE", "PBE"]
130+
loss_weights: [0.01, 0.99]
131+
132+
optimizer:
133+
name: Adam
134+
lr: 0.001
135+
```
136+
137+
## Physics-Based Constraints
138+
139+
The task uses specialized layers to compute physical quantities:
140+
141+
- **`ComputeBranchFlow`**: Calculates active (Pft) and reactive (Qft) power flows on branches using the power flow equations
142+
- **`ComputeNodeInjection`**: Aggregates branch flows to compute net power injections at each bus
143+
- **`ComputeNodeResiduals`**: Computes power balance violations by comparing injections with generation and demand
144+
145+
These layers ensure that predictions are evaluated not only on accuracy but also on their adherence to fundamental power system physics.
146+
147+
## Distributed Training
148+
149+
The PowerFlowTask includes special handling for distributed training:
150+
151+
- **Metric aggregation**: Uses `sync_dist=True` to properly aggregate metrics across GPUs
152+
- **Verbose output gathering**: Collects test outputs from all ranks to rank 0 for complete visualization
153+
- **Max reduction for PBE Max**: Uses `reduce_fx="max"` to find the global maximum PBE across all processes
154+
155+
## Usage
156+
157+
The Power Flow task is automatically selected when you specify `task.name: PowerFlow` in your YAML configuration file. The task:
158+
159+
1. Performs forward pass through the model
160+
2. Inverse normalizes predictions and targets
161+
3. Computes branch flows using power flow equations
162+
4. Calculates power balance residuals and PBE
163+
5. Evaluates metrics separately for each bus type
164+
6. Generates comprehensive reports and visualizations
165+
7. Provides detailed per-bus predictions for analysis
166+
167+
## Related
168+
169+
- [Optimal Power Flow Task](optimal_power_flow.md): For optimization-based power flow with economic objectives
170+
- [State Estimation Task](state_estimation.md): For state estimation from noisy measurements
171+
- [Feature Reconstruction](feature_reconstruction.md): Base reconstruction task

0 commit comments

Comments
 (0)