powergrid_synth.transmission.generator

Main module for generating synthetic grid topology based on Chung-Lu-Chain start graph model.

Inputs:

  • Desired same-voltage degrees: \(\mathbf{d}^{X_1}, \dots, \mathbf{d}^{X_k}\) for each same-voltage graph \(X_i\).

  • Desured same-voltage diameters: \(\delta^{X_1},\dots \delta^{X_k}\).

  • Transformer degrees: \(\mathbf{t}[X_i,X_j]\) for each pair \(i,j\in\{1,\dots,k\}\)

Output:

Full edge list.

Module Contents

class powergrid_synth.transmission.generator.PowerGridGenerator(seed=None)[source]

Generative model for an entire power grid graph on k voltage levels.

Implements Algorithm 4 (CLCStars) from Aksoy et al. (2018). Phase 1 generates each same-voltage subgraph via the CLC model, and Phase 2 inserts transformer edges via the random-star model.

Parameters:

seed (int or None, optional) – Random seed for reproducibility. Default is None.

_generate_subgraphs(k, degrees_by_level, diameters_by_level, level_offsets, level_node_counts, all_edges)[source]

Generate same-voltage subgraphs (Phase 1) for all k levels.

For each voltage level, runs Preprocessor.run_setup() followed by EdgeCreator.generate_edges(), converting local node IDs to global IDs using cumulative offsets.

Parameters:

  • k (int) – Number of voltage levels.

  • degrees_by_level (list of list of int) – Desired degree sequences, one per voltage level.

  • diameters_by_level (list of int) – Desired diameters, one per voltage level.

  • level_offsets (list of int) – Mutated in place — filled with the global node-ID offset for each level.

  • level_node_counts (list of int) – Mutated in place — filled with the actual node count (after degree-sequence inflation) for each level.

  • all_edges (dict) – Mutated in place — {(u, v): {'type': 'line'}} entries are added for each generated edge.

Example

1# Level 0 generated (5 nodes) -> Local IDs: 0, 1, 2, 3, 4
2level_offsets[0] = 0
3current_global_offset becomes 5
4
5# Level 1 generated (3 nodes) -> Local IDs: 0, 1, 2
6# We shift them by current_global_offset (5):
7# Global IDs: 5, 6, 7
8level_offsets[1] = 5
9current_global_offset becomes 8
_generate_transformer_connections(k, transformer_degrees, level_node_counts, level_offsets, all_edges)[source]

Insert transformer edges between voltage levels (Phase 2).

For each pair of levels (i, j), runs TransformerConnector.generate_transformer_edges() and converts local node IDs to global IDs.

Parameters:

  • k (int) – Number of voltage levels.

  • transformer_degrees (dict) – Mapping (i, j) -> (t_i_j, t_j_i) of transformer degree lists.

  • level_node_counts (list of int) – Actual node counts per level (from Phase 1).

  • level_offsets (list of int) – Global node-ID offsets per level (from Phase 1).

  • all_edges (dict) – Mutated in place — {(u, v): {'type': 'transformer'}} entries are added.

generate_grid(degrees_by_level, diameters_by_level, transformer_degrees, keep_lcc=False)[source]

Generate a multi-level power grid graph (CLCStars, Algorithm 4).

Runs Phase 1 (CLC for each voltage level) and Phase 2 (random-star transformer edges for each pair of levels), then combines results.

Parameters:

  • degrees_by_level (list of list of int) – Desired degree sequences \(\mathbf{d}^{X_1},\dots,\mathbf{d}^{X_k}\), one per voltage level.

  • diameters_by_level (list of int) – Desired diameters \(\delta^{X_1},\dots,\delta^{X_k}\), one per voltage level.

  • transformer_degrees (dict) – Mapping (i, j) -> (t_i_j, t_j_i) where t_i_j is the transformer degree list for level-i nodes toward level j, and t_j_i is the reverse.

  • keep_lcc (bool, optional) – If True, return only the largest connected component with contiguous node IDs. Default is False.

Returns:

The generated grid graph with voltage_level node attributes and type ('line' or 'transformer') edge attributes.

Return type:

PowerGridGraph