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/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)
@@ -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>&gt;=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 &middot; '
124
+ f'scroll to zoom &middot; 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)