gridplan 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- gridplan/__init__.py +31 -0
- gridplan/congestion.py +192 -0
- gridplan/expansion.py +154 -0
- gridplan/gnn.py +376 -0
- gridplan/interactive.py +164 -0
- gridplan/network.py +119 -0
- gridplan/visualize.py +140 -0
- gridplan-0.1.0.dist-info/METADATA +168 -0
- gridplan-0.1.0.dist-info/RECORD +12 -0
- gridplan-0.1.0.dist-info/WHEEL +5 -0
- gridplan-0.1.0.dist-info/licenses/LICENSE +21 -0
- gridplan-0.1.0.dist-info/top_level.txt +1 -0
gridplan/gnn.py
ADDED
|
@@ -0,0 +1,376 @@
|
|
|
1
|
+
"""
|
|
2
|
+
A Graph Neural Network that learns to approximate DC power flow.
|
|
3
|
+
|
|
4
|
+
IMPORTANT FRAMING - read this before the code:
|
|
5
|
+
|
|
6
|
+
Computing flows for a *given* set of generator/load injections is NOT an
|
|
7
|
+
optimization problem - it's just solving the linear system P = B @ theta,
|
|
8
|
+
where B is the bus susceptance matrix built from line reactances. That's
|
|
9
|
+
what `exact_dc_powerflow()` below does, in a few lines of numpy, exactly
|
|
10
|
+
and instantly. dcopf.py is the OPTIMIZATION layer on top of this: it
|
|
11
|
+
additionally *chooses* generator dispatch to minimize cost, subject to
|
|
12
|
+
that same physics.
|
|
13
|
+
|
|
14
|
+
So why train a neural net to approximate something you can already solve
|
|
15
|
+
exactly and near-instantly? At THIS toy scale (9 buses), you shouldn't -
|
|
16
|
+
the exact linear solve is faster than a GNN forward pass and always exact.
|
|
17
|
+
The real motivation for a learned power-flow surrogate shows up at scale:
|
|
18
|
+
|
|
19
|
+
- Contingency screening: utilities routinely need to check "what if
|
|
20
|
+
line X trips?" across thousands of N-1/N-2 combinations. Refactorizing
|
|
21
|
+
a large admittance matrix (or resolving an LP) for each one is
|
|
22
|
+
expensive; a trained GNN forward pass is a single fast batched matrix
|
|
23
|
+
multiply, and (in principle, if trained on varied topologies) can
|
|
24
|
+
generalize to topology changes it wasn't explicitly solved for.
|
|
25
|
+
- Embedding inside a bigger optimization loop (e.g., a stochastic
|
|
26
|
+
planning model evaluating thousands of scenarios) where re-solving
|
|
27
|
+
an exact power flow inside the loop is the bottleneck.
|
|
28
|
+
- Very large meshed networks where the admittance matrix is big enough
|
|
29
|
+
that repeated exact solves actually do dominate runtime.
|
|
30
|
+
|
|
31
|
+
This script is an honest, small-scale demonstration of the technique -
|
|
32
|
+
including a benchmark at the end that shows the exact solve winning at
|
|
33
|
+
this size, so you can see where the crossover would need to happen for a
|
|
34
|
+
GNN to actually pay off.
|
|
35
|
+
"""
|
|
36
|
+
import os
|
|
37
|
+
import time
|
|
38
|
+
import numpy as np
|
|
39
|
+
import torch
|
|
40
|
+
import torch.nn as nn
|
|
41
|
+
|
|
42
|
+
from .network import Network
|
|
43
|
+
|
|
44
|
+
BASE_MVA = 100.0
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
# ---------------------------------------------------------------------------
|
|
48
|
+
# Exact DC power flow via linear algebra (ground truth generator - no ML,
|
|
49
|
+
# no optimization solver, just P = B @ theta)
|
|
50
|
+
# ---------------------------------------------------------------------------
|
|
51
|
+
def build_susceptance_matrix(net):
|
|
52
|
+
"""Returns (B, bus_ids, line_ids, line_endpoints, line_susceptance)."""
|
|
53
|
+
bus_ids = sorted(net.buses.keys())
|
|
54
|
+
idx = {b: i for i, b in enumerate(bus_ids)}
|
|
55
|
+
n = len(bus_ids)
|
|
56
|
+
B = np.zeros((n, n))
|
|
57
|
+
|
|
58
|
+
lines = net.existing_lines()
|
|
59
|
+
line_ids = list(lines.keys())
|
|
60
|
+
line_endpoints = []
|
|
61
|
+
line_susceptance = []
|
|
62
|
+
|
|
63
|
+
for lid in line_ids:
|
|
64
|
+
ln = lines[lid]
|
|
65
|
+
b_l = BASE_MVA / ln.reactance_pu # susceptance
|
|
66
|
+
i, j = idx[ln.from_bus], idx[ln.to_bus]
|
|
67
|
+
B[i, i] += b_l
|
|
68
|
+
B[j, j] += b_l
|
|
69
|
+
B[i, j] -= b_l
|
|
70
|
+
B[j, i] -= b_l
|
|
71
|
+
line_endpoints.append((i, j))
|
|
72
|
+
line_susceptance.append(b_l)
|
|
73
|
+
|
|
74
|
+
return B, bus_ids, idx, line_ids, line_endpoints, np.array(line_susceptance)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def exact_dc_powerflow(B, injections, slack_idx):
|
|
78
|
+
"""
|
|
79
|
+
Solve P = B @ theta for theta, given net injections (gen - demand) at
|
|
80
|
+
every bus, with slack bus angle fixed to 0. injections can be a single
|
|
81
|
+
vector (n,) or a batch (n_samples, n).
|
|
82
|
+
"""
|
|
83
|
+
n = B.shape[0]
|
|
84
|
+
keep = [i for i in range(n) if i != slack_idx]
|
|
85
|
+
B_red = B[np.ix_(keep, keep)]
|
|
86
|
+
|
|
87
|
+
single = injections.ndim == 1
|
|
88
|
+
if single:
|
|
89
|
+
injections = injections[None, :]
|
|
90
|
+
|
|
91
|
+
P_red = injections[:, keep] # (n_samples, n-1)
|
|
92
|
+
theta_red = np.linalg.solve(B_red, P_red.T).T # (n_samples, n-1)
|
|
93
|
+
|
|
94
|
+
theta = np.zeros((injections.shape[0], n))
|
|
95
|
+
theta[:, keep] = theta_red
|
|
96
|
+
# slack column stays 0
|
|
97
|
+
|
|
98
|
+
if single:
|
|
99
|
+
theta = theta[0]
|
|
100
|
+
return theta
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def flows_from_theta(theta, line_endpoints, line_susceptance):
|
|
104
|
+
"""theta: (n_samples, n_buses) or (n_buses,). Returns matching-shaped flows."""
|
|
105
|
+
single = theta.ndim == 1
|
|
106
|
+
if single:
|
|
107
|
+
theta = theta[None, :]
|
|
108
|
+
flows = np.zeros((theta.shape[0], len(line_endpoints)))
|
|
109
|
+
for k, (i, j) in enumerate(line_endpoints):
|
|
110
|
+
flows[:, k] = line_susceptance[k] * (theta[:, i] - theta[:, j])
|
|
111
|
+
if single:
|
|
112
|
+
flows = flows[0]
|
|
113
|
+
return flows
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
# ---------------------------------------------------------------------------
|
|
117
|
+
# Training data: random-but-plausible injection scenarios
|
|
118
|
+
# ---------------------------------------------------------------------------
|
|
119
|
+
def sample_injections(net, bus_ids, idx, n_samples, seed=0):
|
|
120
|
+
"""
|
|
121
|
+
Sample net injection (generation - demand) at every bus, keeping total
|
|
122
|
+
generation = total demand (required for power flow to have a solution).
|
|
123
|
+
Demand buses draw from the historical range in loads.csv; one
|
|
124
|
+
generator (the largest-capacity one) acts as the balancing/slack
|
|
125
|
+
generator to make the sample feasible, mirroring how a utility's
|
|
126
|
+
largest baseload/regulating plant absorbs the residual in practice.
|
|
127
|
+
"""
|
|
128
|
+
rng = np.random.default_rng(seed)
|
|
129
|
+
n = len(bus_ids)
|
|
130
|
+
|
|
131
|
+
# Historical demand range per bus, from the sample loads.csv
|
|
132
|
+
demand_range = {}
|
|
133
|
+
for b in bus_ids:
|
|
134
|
+
vals = [snap.get(b, 0.0) for snap in net.loads.values()]
|
|
135
|
+
vals = [v for v in vals if v > 0]
|
|
136
|
+
if vals:
|
|
137
|
+
demand_range[b] = (min(vals) * 0.8, max(vals) * 1.15)
|
|
138
|
+
|
|
139
|
+
gens = net.generators
|
|
140
|
+
gen_ids = list(gens.keys())
|
|
141
|
+
# balancing generator = largest capacity
|
|
142
|
+
slack_gen = max(gen_ids, key=lambda g: gens[g].capacity_mw)
|
|
143
|
+
other_gens = [g for g in gen_ids if g != slack_gen]
|
|
144
|
+
|
|
145
|
+
injections = np.zeros((n_samples, n))
|
|
146
|
+
kept = 0
|
|
147
|
+
attempts = 0
|
|
148
|
+
while kept < n_samples and attempts < n_samples * 20:
|
|
149
|
+
attempts += 1
|
|
150
|
+
demand_by_bus = {b: rng.uniform(*demand_range[b]) for b in demand_range}
|
|
151
|
+
total_demand = sum(demand_by_bus.values())
|
|
152
|
+
|
|
153
|
+
other_gen_out = {g: rng.uniform(0, gens[g].capacity_mw) for g in other_gens}
|
|
154
|
+
residual = total_demand - sum(other_gen_out.values())
|
|
155
|
+
if residual < 0 or residual > gens[slack_gen].capacity_mw:
|
|
156
|
+
continue # infeasible draw, resample
|
|
157
|
+
|
|
158
|
+
gen_by_bus = {gens[g].bus_id: gens[g].bus_id for g in []} # noop init
|
|
159
|
+
inj = np.zeros(n)
|
|
160
|
+
for b, d in demand_by_bus.items():
|
|
161
|
+
inj[idx[b]] -= d
|
|
162
|
+
for g, out in other_gen_out.items():
|
|
163
|
+
inj[idx[gens[g].bus_id]] += out
|
|
164
|
+
inj[idx[gens[slack_gen].bus_id]] += residual
|
|
165
|
+
|
|
166
|
+
injections[kept] = inj
|
|
167
|
+
kept += 1
|
|
168
|
+
|
|
169
|
+
if kept < n_samples:
|
|
170
|
+
injections = injections[:kept]
|
|
171
|
+
return injections
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
# ---------------------------------------------------------------------------
|
|
175
|
+
# GNN model - hand-rolled message passing (no torch_geometric dependency,
|
|
176
|
+
# so it's a plain `pip install torch` on any machine including Windows)
|
|
177
|
+
# ---------------------------------------------------------------------------
|
|
178
|
+
class SusceptanceGraphConv(nn.Module):
|
|
179
|
+
"""
|
|
180
|
+
One message-passing layer. Each bus updates its representation using
|
|
181
|
+
(a) its own features and (b) a weighted sum of neighbor features, where
|
|
182
|
+
the weight is the line susceptance - i.e. the graph structure itself
|
|
183
|
+
(not just "is there an edge") is fed into the aggregation, mirroring
|
|
184
|
+
how real DC power flow weights neighbor influence by 1/reactance.
|
|
185
|
+
"""
|
|
186
|
+
def __init__(self, in_dim, out_dim):
|
|
187
|
+
super().__init__()
|
|
188
|
+
self.self_lin = nn.Linear(in_dim, out_dim)
|
|
189
|
+
self.neigh_lin = nn.Linear(in_dim, out_dim)
|
|
190
|
+
|
|
191
|
+
def forward(self, h, A_weighted):
|
|
192
|
+
# h: (batch, n_buses, in_dim); A_weighted: (n_buses, n_buses) susceptance-weighted adjacency
|
|
193
|
+
agg = torch.matmul(A_weighted, h) # weighted sum of neighbor features
|
|
194
|
+
return self.self_lin(h) + self.neigh_lin(agg)
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
class PowerFlowGNN(nn.Module):
|
|
198
|
+
def __init__(self, n_buses, hidden_dim=32, n_layers=3):
|
|
199
|
+
super().__init__()
|
|
200
|
+
self.n_buses = n_buses
|
|
201
|
+
dims = [1] + [hidden_dim] * (n_layers - 1) + [1]
|
|
202
|
+
self.layers = nn.ModuleList([
|
|
203
|
+
SusceptanceGraphConv(dims[i], dims[i + 1]) for i in range(n_layers)
|
|
204
|
+
])
|
|
205
|
+
self.act = nn.Tanh()
|
|
206
|
+
|
|
207
|
+
def forward(self, injections, A_weighted, slack_idx):
|
|
208
|
+
# injections: (batch, n_buses) -> (batch, n_buses, 1)
|
|
209
|
+
h = injections.unsqueeze(-1)
|
|
210
|
+
for i, layer in enumerate(self.layers):
|
|
211
|
+
h = layer(h, A_weighted)
|
|
212
|
+
if i < len(self.layers) - 1:
|
|
213
|
+
h = self.act(h)
|
|
214
|
+
theta_pred = h.squeeze(-1) # (batch, n_buses)
|
|
215
|
+
# Enforce the reference bus: subtract its predicted angle from all
|
|
216
|
+
# buses, exactly like fixing slack angle = 0 in the exact solve.
|
|
217
|
+
# This is a physics-informed constraint baked into the architecture
|
|
218
|
+
# rather than something the network has to learn.
|
|
219
|
+
theta_pred = theta_pred - theta_pred[:, slack_idx:slack_idx + 1]
|
|
220
|
+
return theta_pred
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def normalized_adjacency(B, line_endpoints, line_susceptance, n):
|
|
224
|
+
"""Off-diagonal susceptance-weighted adjacency (no self-loops), row-normalized
|
|
225
|
+
by total susceptance at each bus so message scale doesn't blow up with degree."""
|
|
226
|
+
A = np.zeros((n, n))
|
|
227
|
+
for (i, j), b_l in zip(line_endpoints, line_susceptance):
|
|
228
|
+
A[i, j] = b_l
|
|
229
|
+
A[j, i] = b_l
|
|
230
|
+
row_sum = A.sum(axis=1, keepdims=True)
|
|
231
|
+
row_sum[row_sum == 0] = 1.0
|
|
232
|
+
return A / row_sum
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
# ---------------------------------------------------------------------------
|
|
236
|
+
# Train + evaluate
|
|
237
|
+
# ---------------------------------------------------------------------------
|
|
238
|
+
def train_and_evaluate(net, n_samples=4000, epochs=300, seed=0, out_dir=None):
|
|
239
|
+
B, bus_ids, idx, line_ids, line_endpoints, line_susc = build_susceptance_matrix(net)
|
|
240
|
+
n = len(bus_ids)
|
|
241
|
+
slack_idx = 0 # same convention as dcopf.py: first bus in the dict
|
|
242
|
+
|
|
243
|
+
injections = sample_injections(net, bus_ids, idx, n_samples, seed=seed)
|
|
244
|
+
theta_true = exact_dc_powerflow(B, injections, slack_idx)
|
|
245
|
+
flows_true = flows_from_theta(theta_true, line_endpoints, line_susc)
|
|
246
|
+
|
|
247
|
+
# Normalize injections to roughly unit scale - raw MW values (tens to
|
|
248
|
+
# hundreds) saturate tanh activations and slow convergence a lot.
|
|
249
|
+
inj_scale = np.abs(injections).std()
|
|
250
|
+
injections_norm = injections / inj_scale
|
|
251
|
+
|
|
252
|
+
n_total = injections.shape[0]
|
|
253
|
+
n_train = int(n_total * 0.8)
|
|
254
|
+
rng = np.random.default_rng(seed)
|
|
255
|
+
perm = rng.permutation(n_total)
|
|
256
|
+
train_idx, test_idx = perm[:n_train], perm[n_train:]
|
|
257
|
+
|
|
258
|
+
X_train = torch.tensor(injections_norm[train_idx], dtype=torch.float32)
|
|
259
|
+
X_test = torch.tensor(injections_norm[test_idx], dtype=torch.float32)
|
|
260
|
+
theta_train = torch.tensor(theta_true[train_idx], dtype=torch.float32)
|
|
261
|
+
theta_test_np = theta_true[test_idx]
|
|
262
|
+
flows_test_np = flows_true[test_idx]
|
|
263
|
+
|
|
264
|
+
A_weighted = torch.tensor(normalized_adjacency(B, line_endpoints, line_susc, n),
|
|
265
|
+
dtype=torch.float32)
|
|
266
|
+
|
|
267
|
+
model = PowerFlowGNN(n_buses=n, hidden_dim=32, n_layers=3)
|
|
268
|
+
opt = torch.optim.Adam(model.parameters(), lr=0.01)
|
|
269
|
+
loss_fn = nn.MSELoss()
|
|
270
|
+
|
|
271
|
+
loss_history = []
|
|
272
|
+
for epoch in range(epochs):
|
|
273
|
+
model.train()
|
|
274
|
+
opt.zero_grad()
|
|
275
|
+
theta_pred = model(X_train, A_weighted, slack_idx)
|
|
276
|
+
loss = loss_fn(theta_pred, theta_train)
|
|
277
|
+
loss.backward()
|
|
278
|
+
opt.step()
|
|
279
|
+
loss_history.append(loss.item())
|
|
280
|
+
if epoch % 50 == 0 or epoch == epochs - 1:
|
|
281
|
+
print(f"epoch {epoch:4d} train MSE (angle, rad^2): {loss.item():.6f}")
|
|
282
|
+
|
|
283
|
+
# --- Evaluate on held-out test set ---
|
|
284
|
+
model.eval()
|
|
285
|
+
with torch.no_grad():
|
|
286
|
+
theta_pred_test = model(X_test, A_weighted, slack_idx).numpy()
|
|
287
|
+
flows_pred_test = flows_from_theta(theta_pred_test, line_endpoints, line_susc)
|
|
288
|
+
|
|
289
|
+
angle_mae = np.mean(np.abs(theta_pred_test - theta_test_np))
|
|
290
|
+
flow_mae = np.mean(np.abs(flows_pred_test - flows_test_np))
|
|
291
|
+
flow_mae_pct_of_range = flow_mae / (np.abs(flows_true).max()) * 100
|
|
292
|
+
|
|
293
|
+
print(f"\nHeld-out test set ({len(test_idx)} scenarios):")
|
|
294
|
+
print(f" angle MAE: {angle_mae:.5f} rad")
|
|
295
|
+
print(f" flow MAE: {flow_mae:.2f} MW ({flow_mae_pct_of_range:.2f}% of max observed flow)")
|
|
296
|
+
|
|
297
|
+
# --- Speed comparison: exact linear solve vs GNN forward pass, batched ---
|
|
298
|
+
n_bench = 2000
|
|
299
|
+
bench_injections = injections[:n_bench] if n_bench <= n_total else \
|
|
300
|
+
sample_injections(net, bus_ids, idx, n_bench, seed=seed + 1)
|
|
301
|
+
|
|
302
|
+
t0 = time.perf_counter()
|
|
303
|
+
_ = exact_dc_powerflow(B, bench_injections, slack_idx)
|
|
304
|
+
exact_time = time.perf_counter() - t0
|
|
305
|
+
|
|
306
|
+
X_bench = torch.tensor(bench_injections / inj_scale, dtype=torch.float32)
|
|
307
|
+
with torch.no_grad():
|
|
308
|
+
t0 = time.perf_counter()
|
|
309
|
+
_ = model(X_bench, A_weighted, slack_idx)
|
|
310
|
+
gnn_time = time.perf_counter() - t0
|
|
311
|
+
|
|
312
|
+
print(f"\nSpeed, {n_bench} scenarios in one batch:")
|
|
313
|
+
print(f" exact linear solve (numpy): {exact_time*1000:.2f} ms")
|
|
314
|
+
print(f" GNN forward pass (torch): {gnn_time*1000:.2f} ms")
|
|
315
|
+
if exact_time < gnn_time:
|
|
316
|
+
print(" -> exact solve wins at this network size (9 buses) - expected. "
|
|
317
|
+
"The GNN would need a much larger network, or topology variation "
|
|
318
|
+
"the exact solve can't easily reuse work across, to pay off.")
|
|
319
|
+
else:
|
|
320
|
+
print(" -> GNN forward pass wins here.")
|
|
321
|
+
|
|
322
|
+
if out_dir:
|
|
323
|
+
_save_diagnostic_plots(loss_history, theta_pred_test, theta_test_np,
|
|
324
|
+
flows_pred_test, flows_test_np, line_ids, out_dir)
|
|
325
|
+
|
|
326
|
+
return {
|
|
327
|
+
"model": model,
|
|
328
|
+
"angle_mae": angle_mae,
|
|
329
|
+
"flow_mae_mw": flow_mae,
|
|
330
|
+
"exact_time_ms": exact_time * 1000,
|
|
331
|
+
"gnn_time_ms": gnn_time * 1000,
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
def _save_diagnostic_plots(loss_history, theta_pred, theta_true, flows_pred, flows_true,
|
|
336
|
+
line_ids, out_dir):
|
|
337
|
+
import matplotlib
|
|
338
|
+
matplotlib.use("Agg")
|
|
339
|
+
import matplotlib.pyplot as plt
|
|
340
|
+
|
|
341
|
+
os.makedirs(out_dir, exist_ok=True)
|
|
342
|
+
fig, axes = plt.subplots(1, 3, figsize=(15, 4.5))
|
|
343
|
+
|
|
344
|
+
axes[0].plot(loss_history)
|
|
345
|
+
axes[0].set_yscale("log")
|
|
346
|
+
axes[0].set_xlabel("epoch")
|
|
347
|
+
axes[0].set_ylabel("train MSE (angle, rad^2)")
|
|
348
|
+
axes[0].set_title("Training loss")
|
|
349
|
+
|
|
350
|
+
axes[1].scatter(theta_true.flatten(), theta_pred.flatten(), s=6, alpha=0.3)
|
|
351
|
+
lims = [theta_true.min(), theta_true.max()]
|
|
352
|
+
axes[1].plot(lims, lims, "r--", linewidth=1)
|
|
353
|
+
axes[1].set_xlabel("true angle (rad)")
|
|
354
|
+
axes[1].set_ylabel("GNN-predicted angle (rad)")
|
|
355
|
+
axes[1].set_title("Bus angles: predicted vs. true (test set)")
|
|
356
|
+
|
|
357
|
+
axes[2].scatter(flows_true.flatten(), flows_pred.flatten(), s=6, alpha=0.3)
|
|
358
|
+
lims = [flows_true.min(), flows_true.max()]
|
|
359
|
+
axes[2].plot(lims, lims, "r--", linewidth=1)
|
|
360
|
+
axes[2].set_xlabel("true flow (MW)")
|
|
361
|
+
axes[2].set_ylabel("GNN-predicted flow (MW)")
|
|
362
|
+
axes[2].set_title("Line flows: predicted vs. true (test set)")
|
|
363
|
+
|
|
364
|
+
fig.tight_layout()
|
|
365
|
+
path = os.path.join(out_dir, "gnn_powerflow_diagnostics.png")
|
|
366
|
+
fig.savefig(path, dpi=150)
|
|
367
|
+
plt.close(fig)
|
|
368
|
+
print(f"\nSaved diagnostic plots to {path}")
|
|
369
|
+
|
|
370
|
+
|
|
371
|
+
if __name__ == "__main__":
|
|
372
|
+
data_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))),
|
|
373
|
+
"examples", "sample_data")
|
|
374
|
+
net = Network.from_csv(data_dir)
|
|
375
|
+
out_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "outputs")
|
|
376
|
+
train_and_evaluate(net, n_samples=4000, epochs=300, out_dir=out_dir)
|
gridplan/interactive.py
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Interactive HTML versions of the network diagrams - open the .html output
|
|
3
|
+
in any browser and drag nodes around, zoom, pan, and hover over
|
|
4
|
+
buses/lines for details. Uses pyvis (a thin wrapper around the vis.js
|
|
5
|
+
JavaScript network library), so no server is needed - just double-click
|
|
6
|
+
the generated .html file.
|
|
7
|
+
|
|
8
|
+
This mirrors visualize.py's three diagrams (topology, congestion,
|
|
9
|
+
expansion plan) but as draggable HTML instead of static PNGs.
|
|
10
|
+
"""
|
|
11
|
+
import os
|
|
12
|
+
from pyvis.network import Network as VisNetwork
|
|
13
|
+
|
|
14
|
+
from .network import Network
|
|
15
|
+
|
|
16
|
+
ZONE_COLORS = {"North": "#4C72B0", "Central": "#55A868", "South": "#C44E52"}
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def build_interactive_topology(net, out_path, include_candidates=True,
|
|
20
|
+
congestion=None, lmps=None, build_decision=None,
|
|
21
|
+
title="Transmission Network"):
|
|
22
|
+
"""
|
|
23
|
+
congestion: optional dict of line_id -> loading_pct, e.g. built from
|
|
24
|
+
{lid: lf.loading_pct for lid, lf in result.line_flows.items()}
|
|
25
|
+
where result = congestion.solve_congestion(...)
|
|
26
|
+
lmps: optional dict of bus_id -> $/MWh, from result.lmps (same result object),
|
|
27
|
+
shown in each bus's hover tooltip if provided
|
|
28
|
+
build_decision: optional dict of candidate line_id -> bool, from
|
|
29
|
+
expansion.solve_expansion(...).build_decision
|
|
30
|
+
"""
|
|
31
|
+
net_vis = VisNetwork(height="750px", width="100%", bgcolor="#ffffff",
|
|
32
|
+
font_color="#222222", directed=False, notebook=False,
|
|
33
|
+
cdn_resources="in_line")
|
|
34
|
+
|
|
35
|
+
# Physics settles the initial layout nicely, then the user can drag
|
|
36
|
+
# freely; "stabilization" just controls the initial settle-down.
|
|
37
|
+
net_vis.set_options("""
|
|
38
|
+
{
|
|
39
|
+
"physics": {
|
|
40
|
+
"stabilization": {"iterations": 200},
|
|
41
|
+
"barnesHut": {"gravitationalConstant": -12000, "springLength": 180, "springConstant": 0.04}
|
|
42
|
+
},
|
|
43
|
+
"interaction": {"hover": true, "tooltipDelay": 100, "dragNodes": true}
|
|
44
|
+
}
|
|
45
|
+
""")
|
|
46
|
+
|
|
47
|
+
for bus_id, b in net.buses.items():
|
|
48
|
+
tooltip = f"{b.name}\nZone: {b.zone}\n{b.base_kv} kV"
|
|
49
|
+
if lmps and lmps.get(bus_id) is not None:
|
|
50
|
+
tooltip += f"\nLMP: ${lmps[bus_id]}/MWh"
|
|
51
|
+
net_vis.add_node(
|
|
52
|
+
bus_id,
|
|
53
|
+
label=b.name.replace("_", "\n"),
|
|
54
|
+
title=tooltip,
|
|
55
|
+
color=ZONE_COLORS.get(b.zone, "#888888"),
|
|
56
|
+
shape="dot",
|
|
57
|
+
size=22,
|
|
58
|
+
)
|
|
59
|
+
|
|
60
|
+
line_set = dict(net.existing_lines())
|
|
61
|
+
if include_candidates:
|
|
62
|
+
line_set.update(net.candidate_lines())
|
|
63
|
+
|
|
64
|
+
for lid, ln in line_set.items():
|
|
65
|
+
edge_kwargs = dict(title=f"{lid}: {ln.from_bus}->{ln.to_bus}\nCapacity: {ln.capacity_mw} MW")
|
|
66
|
+
|
|
67
|
+
if ln.status == "existing":
|
|
68
|
+
if congestion and lid in congestion:
|
|
69
|
+
pct = congestion[lid]
|
|
70
|
+
edge_kwargs["title"] += f"\nLoading: {pct}%"
|
|
71
|
+
if pct >= 95:
|
|
72
|
+
color, width = "#B22222", 5
|
|
73
|
+
elif pct >= 70:
|
|
74
|
+
color, width = "#E08214", 3.5
|
|
75
|
+
else:
|
|
76
|
+
color, width = "#4C4C4C", 2
|
|
77
|
+
else:
|
|
78
|
+
color, width = "#4C4C4C", 2
|
|
79
|
+
edge_kwargs.update(color=color, width=width)
|
|
80
|
+
else: # candidate line
|
|
81
|
+
edge_kwargs["title"] += f"\nCandidate - ${ln.cost_million_usd}M"
|
|
82
|
+
if build_decision and build_decision.get(lid):
|
|
83
|
+
edge_kwargs.update(color="#2CA02C", width=4, dashes=False)
|
|
84
|
+
edge_kwargs["title"] += "\n>> RECOMMENDED TO BUILD"
|
|
85
|
+
else:
|
|
86
|
+
edge_kwargs.update(color="#999999", width=1.5, dashes=True)
|
|
87
|
+
edge_kwargs["title"] += "\n(not recommended)"
|
|
88
|
+
|
|
89
|
+
net_vis.add_edge(ln.from_bus, ln.to_bus, **edge_kwargs)
|
|
90
|
+
|
|
91
|
+
# Use generate_html() + our own UTF-8 write, rather than pyvis's
|
|
92
|
+
# write_html(), which on Windows can crash with UnicodeEncodeError
|
|
93
|
+
# (it opens the file using the OS default encoding, e.g. cp1252,
|
|
94
|
+
# which can't represent some characters in the embedded JS/CSS).
|
|
95
|
+
html = net_vis.generate_html(notebook=False)
|
|
96
|
+
with open(out_path, "w", encoding="utf-8") as f:
|
|
97
|
+
f.write(html)
|
|
98
|
+
|
|
99
|
+
# Inject a title heading + simple legend at the top of the page
|
|
100
|
+
with open(out_path, "r", encoding="utf-8") as f:
|
|
101
|
+
html = f.read()
|
|
102
|
+
legend_items = "".join(
|
|
103
|
+
f'<span style="margin-right:16px;"><span style="display:inline-block;width:12px;height:12px;'
|
|
104
|
+
f'background:{c};border-radius:50%;margin-right:4px;"></span>{z}</span>'
|
|
105
|
+
for z, c in ZONE_COLORS.items()
|
|
106
|
+
)
|
|
107
|
+
if congestion:
|
|
108
|
+
legend_items += (
|
|
109
|
+
'<span style="margin-right:16px;"><span style="display:inline-block;width:20px;height:3px;'
|
|
110
|
+
'background:#B22222;margin-right:4px;"></span>>=95% loaded</span>'
|
|
111
|
+
'<span style="margin-right:16px;"><span style="display:inline-block;width:20px;height:3px;'
|
|
112
|
+
'background:#E08214;margin-right:4px;"></span>70-95% loaded</span>'
|
|
113
|
+
)
|
|
114
|
+
if include_candidates:
|
|
115
|
+
legend_items += (
|
|
116
|
+
'<span style="margin-right:16px;"><span style="display:inline-block;width:20px;height:3px;'
|
|
117
|
+
'background:#2CA02C;margin-right:4px;"></span>Recommended new line</span>'
|
|
118
|
+
)
|
|
119
|
+
header = (
|
|
120
|
+
f'<div style="font-family:sans-serif;padding:12px 16px;border-bottom:1px solid #ddd;">'
|
|
121
|
+
f'<h2 style="margin:0 0 8px 0;">{title}</h2>'
|
|
122
|
+
f'<div style="font-size:13px;color:#444;">{legend_items}</div>'
|
|
123
|
+
f'<div style="font-size:12px;color:#888;margin-top:6px;">Drag nodes to rearrange · '
|
|
124
|
+
f'scroll to zoom · hover for details</div></div>'
|
|
125
|
+
)
|
|
126
|
+
html = html.replace("<body>", f"<body>{header}", 1)
|
|
127
|
+
with open(out_path, "w", encoding="utf-8") as f:
|
|
128
|
+
f.write(html)
|
|
129
|
+
|
|
130
|
+
return out_path
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
if __name__ == "__main__":
|
|
134
|
+
from .congestion import solve_congestion
|
|
135
|
+
from .expansion import solve_expansion
|
|
136
|
+
|
|
137
|
+
data_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))),
|
|
138
|
+
"examples", "sample_data")
|
|
139
|
+
net = Network.from_csv(data_dir)
|
|
140
|
+
out_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "outputs")
|
|
141
|
+
os.makedirs(out_dir, exist_ok=True)
|
|
142
|
+
|
|
143
|
+
# 1) Plain interactive topology
|
|
144
|
+
build_interactive_topology(
|
|
145
|
+
net, os.path.join(out_dir, "topology_interactive.html"),
|
|
146
|
+
title="Network Topology (drag nodes to explore)")
|
|
147
|
+
|
|
148
|
+
# 2) Congestion snapshot, interactive
|
|
149
|
+
r = solve_congestion(net, "summer_peak_h17")
|
|
150
|
+
congestion = {lid: lf.loading_pct for lid, lf in r.line_flows.items()}
|
|
151
|
+
build_interactive_topology(
|
|
152
|
+
net, os.path.join(out_dir, "congestion_peak_interactive.html"),
|
|
153
|
+
congestion=congestion, lmps=r.lmps,
|
|
154
|
+
title="Line Loading at Summer Peak (17:00)")
|
|
155
|
+
|
|
156
|
+
# 3) Expansion plan, interactive
|
|
157
|
+
exp_result = solve_expansion(net)
|
|
158
|
+
build_interactive_topology(
|
|
159
|
+
net, os.path.join(out_dir, "expansion_plan_interactive.html"),
|
|
160
|
+
congestion=congestion, build_decision=exp_result.build_decision,
|
|
161
|
+
title="Recommended Expansion Plan")
|
|
162
|
+
|
|
163
|
+
print(f"Saved interactive HTML diagrams to {out_dir}/")
|
|
164
|
+
print("Open any .html file in a browser - nodes are draggable, edges show details on hover.")
|
gridplan/network.py
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
"""Core data model: Bus, Line, Generator, and the Network container."""
|
|
2
|
+
import csv
|
|
3
|
+
import os
|
|
4
|
+
from dataclasses import dataclass, field
|
|
5
|
+
from typing import Optional
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
@dataclass
|
|
9
|
+
class Bus:
|
|
10
|
+
bus_id: int
|
|
11
|
+
name: str
|
|
12
|
+
zone: str
|
|
13
|
+
base_kv: float
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass
|
|
17
|
+
class Line:
|
|
18
|
+
line_id: str
|
|
19
|
+
from_bus: int
|
|
20
|
+
to_bus: int
|
|
21
|
+
reactance_pu: float
|
|
22
|
+
capacity_mw: float
|
|
23
|
+
status: str # "existing" or "candidate"
|
|
24
|
+
length_km: float
|
|
25
|
+
cost_million_usd: Optional[float] = None
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass
|
|
29
|
+
class Generator:
|
|
30
|
+
gen_id: str
|
|
31
|
+
bus_id: int
|
|
32
|
+
name: str
|
|
33
|
+
capacity_mw: float
|
|
34
|
+
marginal_cost_per_mwh: float
|
|
35
|
+
fuel_type: str
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass
|
|
39
|
+
class Network:
|
|
40
|
+
"""
|
|
41
|
+
A transmission network: buses, lines (existing + candidate), generators,
|
|
42
|
+
and per-snapshot loads. Build one with `Network.from_csv(data_dir)`.
|
|
43
|
+
"""
|
|
44
|
+
buses: dict = field(default_factory=dict) # bus_id -> Bus
|
|
45
|
+
lines: dict = field(default_factory=dict) # line_id -> Line
|
|
46
|
+
generators: dict = field(default_factory=dict) # gen_id -> Generator
|
|
47
|
+
loads: dict = field(default_factory=dict) # snapshot -> {bus_id: demand_mw}
|
|
48
|
+
snapshots: list = field(default_factory=list)
|
|
49
|
+
|
|
50
|
+
def existing_lines(self):
|
|
51
|
+
return {lid: l for lid, l in self.lines.items() if l.status == "existing"}
|
|
52
|
+
|
|
53
|
+
def candidate_lines(self):
|
|
54
|
+
return {lid: l for lid, l in self.lines.items() if l.status == "candidate"}
|
|
55
|
+
|
|
56
|
+
def total_demand(self, snapshot):
|
|
57
|
+
return sum(self.loads.get(snapshot, {}).values())
|
|
58
|
+
|
|
59
|
+
def total_capacity(self):
|
|
60
|
+
return sum(g.capacity_mw for g in self.generators.values())
|
|
61
|
+
|
|
62
|
+
@classmethod
|
|
63
|
+
def from_csv(cls, data_dir):
|
|
64
|
+
"""
|
|
65
|
+
Load a network from a directory containing buses.csv, lines.csv,
|
|
66
|
+
generators.csv, and loads.csv. See the README for the schema.
|
|
67
|
+
"""
|
|
68
|
+
net = cls()
|
|
69
|
+
|
|
70
|
+
with open(os.path.join(data_dir, "buses.csv")) as f:
|
|
71
|
+
for row in csv.DictReader(f):
|
|
72
|
+
bus_id = int(row["bus_id"])
|
|
73
|
+
net.buses[bus_id] = Bus(
|
|
74
|
+
bus_id=bus_id,
|
|
75
|
+
name=row["name"],
|
|
76
|
+
zone=row["zone"],
|
|
77
|
+
base_kv=float(row["base_kv"]),
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
with open(os.path.join(data_dir, "lines.csv")) as f:
|
|
81
|
+
for row in csv.DictReader(f):
|
|
82
|
+
cost = row.get("cost_million_usd", "")
|
|
83
|
+
net.lines[row["line_id"]] = Line(
|
|
84
|
+
line_id=row["line_id"],
|
|
85
|
+
from_bus=int(row["from_bus"]),
|
|
86
|
+
to_bus=int(row["to_bus"]),
|
|
87
|
+
reactance_pu=float(row["reactance_pu"]),
|
|
88
|
+
capacity_mw=float(row["capacity_mw"]),
|
|
89
|
+
status=row["status"],
|
|
90
|
+
length_km=float(row["length_km"]),
|
|
91
|
+
cost_million_usd=float(cost) if cost not in ("", None) else None,
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
with open(os.path.join(data_dir, "generators.csv")) as f:
|
|
95
|
+
for row in csv.DictReader(f):
|
|
96
|
+
net.generators[row["gen_id"]] = Generator(
|
|
97
|
+
gen_id=row["gen_id"],
|
|
98
|
+
bus_id=int(row["bus_id"]),
|
|
99
|
+
name=row["name"],
|
|
100
|
+
capacity_mw=float(row["capacity_mw"]),
|
|
101
|
+
marginal_cost_per_mwh=float(row["marginal_cost_per_mwh"]),
|
|
102
|
+
fuel_type=row["fuel_type"],
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
with open(os.path.join(data_dir, "loads.csv")) as f:
|
|
106
|
+
for row in csv.DictReader(f):
|
|
107
|
+
snap = row["snapshot"]
|
|
108
|
+
bus_id = int(row["bus_id"])
|
|
109
|
+
demand = float(row["demand_mw"])
|
|
110
|
+
net.loads.setdefault(snap, {})[bus_id] = demand
|
|
111
|
+
if snap not in net.snapshots:
|
|
112
|
+
net.snapshots.append(snap)
|
|
113
|
+
|
|
114
|
+
return net
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def load_network(data_dir):
|
|
118
|
+
"""Deprecated alias for Network.from_csv - kept for backward compatibility."""
|
|
119
|
+
return Network.from_csv(data_dir)
|