powergrid_synth.transmission.input_configurator

This calss assists the operation mode II in grid topology generation, where one takes as inputs

1. n: the number of nodes; ave_k: the average node degree; and diam: the desired diameter for same-voltage level and the node degree distribution types

• dgln: discrete generalized log-normal distribution

• dpl: discrete power-law distribution

2. the transformer line specs between different-voltage levels: type: k-stars, parameters c and gamma for the transformer degree distribution.

Example

# Define the voltage levels (Node count, Avg Degree, Diameter, Distribution Type)
level_specs = [
    {'n': 50,  'avg_k': 3.5, 'diam': 10, 'dist_type': 'dgln'},    # (Log-Normal)
    {'n': 150, 'avg_k': 2.5, 'diam': 15, 'dist_type': 'dpl'},     # (Power Law)
    {'n': 300, 'avg_k': 2.0, 'diam': 20, 'dist_type': 'poisson'}  # (Poisson)
]
# Define connections between levels (k-stars model)
connection_specs = {
    (0, 1): {'type': 'k-stars', 'c': 0.174, 'gamma': 4.15},
    (1, 2): {'type': 'k-stars', 'c': 0.15, 'gamma': 4.15}
}
# Initialize Configurator
configurator = InputConfigurator(seed=100)
# Generating Input Parameters
params = configurator.create_params(level_specs, connection_specs)

Module Contents

class powergrid_synth.transmission.input_configurator.InputConfigurator(seed=None)

Generate detailed input sequences for PowerGridGenerator from high-level parameters.

This is “operation mode II”, where the user specifies only the number of nodes, average degree, diameter, and distribution type for each voltage level, rather than providing explicit degree sequences. The configurator uses DegreeDistributionOptimizer to fit distribution parameters and then samples degree sequences.

See Section 6 of Aksoy et al. (2018) for the synthetic input generation guidelines.

Parameters:

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

_generate_optimized_degrees(n_nodes, avg_degree, max_degree, dist_type)

Generate a degree sequence by optimizing DGLN or DPL parameters.

First calls DegreeDistributionOptimizer.optimize() to find the distribution parameters matching avg_degree and max_degree, then samples n_nodes degrees from the resulting PDF.

Parameters:

• n_nodes (int) – Number of nodes in the same-voltage subgraph.

• avg_degree (float) – Target average degree \(\bar{d}\).

• max_degree (int) – Maximum degree \(d_{\max}\) (PDF support is 1..max_degree).

• dist_type (str) – 'dgln' for generalized log-normal or 'dpl' for power law.

Returns:

Sampled degree sequence of length n_nodes.

Return type:

list of int

_generate_poisson_degrees(n_nodes, avg_degree)

Generate a degree sequence from a Poisson distribution.

Parameters:

• n_nodes (int) – Number of nodes.

• avg_degree (float) – Mean of the Poisson distribution \(\lambda = \bar{d}\).

Returns:

Sampled degree sequence of length n_nodes.

Return type:

list of int

_generate_transformer_simple(n_nodes, prob)

Generate binary transformer degrees (simple probabilistic model).

Each node independently gets transformer degree 0 or 1 with probability 1 - prob and prob, respectively.

Parameters:

• n_nodes (int) – Number of nodes.

• prob (float) – Probability that a node participates in a transformer edge.

Returns:

Transformer degree list (0 or 1 per node).

Return type:

list of int

_generate_transformer_stars(n_i, n_j, c=0.174, gamma=4.15)

Generate transformer degrees using the disjoint k-stars model.

Follows Section 6.2 of Aksoy et al. (2018):

1. Number of star centres: \(h(n_i, n_j) = c \cdot \min(n_i, n_j)\) with \(c \approx 0.174\).

2. Star sizes sampled from a discrete power law \(P(k) \propto k^{-\gamma}\) with \(\gamma \approx 4.15\).

3. Each star is randomly assigned a centre in level i or j.

4. Degree lists are padded with zeros and shuffled.

Parameters:

• n_i (int) – Number of nodes in the two voltage levels.

• n_j (int) – Number of nodes in the two voltage levels.

• c (float, optional) – Coefficient for the number of active star centres. Default is 0.174 (paper optimum).

• gamma (float, optional) – Power-law exponent for star sizes. Default is 4.15 (paper optimum, Section 6.2).

Returns:

(t_i, t_j) — transformer degree sequences for levels i and j, each of length n_i and n_j respectively.

Return type:

tuple of (list of int, list of int)

create_params(levels, inter_connections)

Generate the full parameter set for PowerGridGenerator.generate_grid().

Parameters:

• levels (list of dict) –

  One dict per voltage level with keys:

  • 'n' (int): number of nodes.

  • 'avg_k' (float): target average degree.

  • 'diam' (int): target diameter.

  • 'dist_type' (str): 'dgln', 'dpl', or 'poisson'.

  • 'max_k' (int, optional): maximum degree (default: min(n - 1, 50)). For 'dpl' the paper suggests \(d_{\max} \approx 1.517\,n^{1/4}\); for 'dgln' \(\bar{d} \approx 2.425 \pm 0.185\) is consistent across subgraphs (Section 6.1 of Aksoy et al., 2018).

• inter_connections (dict) –

  Mapping (i, j) -> config for transformer connections. Config is either:

  • {'type': 'k-stars', 'c': 0.174, 'gamma': 4.15}

  • {'type': 'simple', 'p_i_j': float, 'p_j_i': float}

Returns:

Keys 'degrees_by_level', 'diameters_by_level', and 'transformer_degrees', ready to be unpacked into PowerGridGenerator.generate_grid().

Return type:

dict