powergrid_synth.distribution

Distribution grid synthesis pipeline (Schweitzer et al. 2017).

Submodules

• powergrid_synth.distribution.distribution_analysis
• powergrid_synth.distribution.distribution_converter
• powergrid_synth.distribution.distribution_input_model
• powergrid_synth.distribution.distribution_params
• powergrid_synth.distribution.distribution_synthesis
• powergrid_synth.distribution.distribution_validation
• powergrid_synth.distribution.synthesize

Package Contents

class powergrid_synth.distribution.BetaParams

Beta distribution parameters (used for fractions).

class powergrid_synth.distribution.CableLibraryEntry

A single cable type in the library.

class powergrid_synth.distribution.CurrentThreshold

Max nominal current threshold for cables far from the source.

class powergrid_synth.distribution.DistributionInputModel(bw_method=None, seed=None)

3-D KDE input model for feeder size and loading.

The model is fitted on reference feeders and then sampled to produce realistic (n_nodes, total_load, total_gen) triples.

Parameters:

• bw_method (str or float, optional) – Bandwidth method passed to scipy.stats.gaussian_kde.

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

_fit_kde(data)

Fit KDE with regularization for near-singular covariance.

Parameters:

data (numpy.ndarray)

Return type:

scipy.stats.gaussian_kde

fit(feeders)

Fit the KDE from a collection of reference feeder graphs.

Each graph must have node attributes P_mw (positive for load, negative for generation).

Parameters:

feeders (sequence of nx.Graph) – Reference feeder graphs.

Return type:

self

fit_from_arrays(n_nodes, total_load, total_gen)

Fit directly from arrays (no graph objects needed).

Parameters:

• n_nodes (array-like of int)

• total_load (array-like of float)

• total_gen (array-like of float)

Return type:

self

pdf(n_nodes, total_load, total_gen)

Evaluate the KDE density at a given point.

Parameters:

• n_nodes (float) – Coordinates in the 3-D input space.

• total_load (float) – Coordinates in the 3-D input space.

• total_gen (float) – Coordinates in the 3-D input space.

Returns:

Estimated probability density.

Return type:

float

sample(n_samples=1)

Draw samples from the fitted input model.

Parameters:

n_samples (int) – Number of samples to draw.

Return type:

list of FeederInputSample

class powergrid_synth.distribution.DistributionSynthParams

All parameters for the Schweitzer distribution feeder generator.

Default values are taken from Table III and the text of Schweitzer et al. (2017).

class powergrid_synth.distribution.ExponentialClip

Exponential clipping function for max cable length: g_max(h) = a * e^(b*h).

class powergrid_synth.distribution.ExponentialParams

Exponential distribution parameters (e.g., I_est / I_nom ratio).

class powergrid_synth.distribution.FeederInputSample

A single draw from the 3-D input model.

class powergrid_synth.distribution.MixtureGammaParams

Mixture of two Gamma distributions for degree assignment.

class powergrid_synth.distribution.MixtureNormalParams

Mixture of two Normal distributions for injection node norm. hop.

class powergrid_synth.distribution.MixturePoissonParams

Mixture of two Poisson distributions for intermediate node hop.

class powergrid_synth.distribution.ModifiedCauchyParams

Modified Cauchy distribution for cable lengths.

class powergrid_synth.distribution.NegBinomParams

Negative Binomial distribution parameters for hop-distance assignment.

class powergrid_synth.distribution.NormalParams

Normal distribution parameters.

class powergrid_synth.distribution.PowerLawClip

Power-law clipping function: g_dmax(h) = a * h^b.

class powergrid_synth.distribution.SchweetzerFeederGenerator(params=None, seed=None)

Generate a single MV radial distribution feeder.

Parameters:

• params (DistributionSynthParams, optional) – All distribution parameters. Defaults to Table III values.

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

_assign_cable_lengths(G)

Assign lengths from modified Cauchy and compute impedance.

Parameters:

G (networkx.Graph)

Return type:

None

_assign_cable_types(G, v_nom_kv)

Assign cable types from the library using I_est / I_nom ratio.

Parameters:

• G (networkx.Graph)

• v_nom_kv (float)

Return type:

None

_assign_injection(G, total_gen_mw)

Assign power injection to a fraction of nodes.

Parameters:

• G (networkx.Graph)

• total_gen_mw (float)

Return type:

None

_assign_intermediate(G)

Mark a fraction of nodes as intermediate (zero load).

Parameters:

G (networkx.Graph)

Return type:

None

_assign_load(G, total_load_mw)

Assign positive load to all remaining (non-intermediate, non-inj) nodes.

Parameters:

• G (networkx.Graph)

• total_load_mw (float)

Return type:

None

_assign_node_properties(G, total_load_mw, total_gen_mw)

Assign intermediate / injection / load node types and powers.

Parameters:

• G (networkx.Graph)

• total_load_mw (float)

• total_gen_mw (float)

Return type:

None

_compute_downstream_power(G)

Compute total downstream apparent power for each node.

Returns dict mapping node → downstream S (MVA).

Parameters:

G (networkx.Graph)

Return type:

Dict[int, float]

_connect_nodes(G)

Connect nodes into a radial tree using bimodal-Gamma degrees.

Parameters:

G (networkx.Graph)

Return type:

None

_fill_hop_gaps(G)

Compress hop distances so every level from 0 to max has ≥1 node.

Gaps are removed by decrementing hop values above each gap, ensuring a contiguous sequence of hop levels.

Parameters:

G (networkx.Graph)

Return type:

None

_generate_nodes(G, n_nodes)

Create n_nodes nodes with hop-distance and power-factor attrs.

Parameters:

• G (networkx.Graph)

• n_nodes (int)

Return type:

None

_pick_cable_by_capacity(i_nom_target, h, library, threshold)

Pick cable from library closest to target I_nom, respecting threshold.

Parameters:

• i_nom_target (float)

• h (int)

• library (List[powergrid_synth.distribution.distribution_params.CableLibraryEntry])

Return type:

powergrid_synth.distribution.distribution_params.CableLibraryEntry

generate_feeder(n_nodes, total_load_mw, total_gen_mw=0.0, v_nom_kv=10.0, assign_cable_types=True, assign_cable_lengths=True)

Generate a complete MV distribution feeder.

Parameters:

• n_nodes (int) – Total number of nodes in the feeder (including source and root).

• total_load_mw (float) – Total real-power load (MW) to be distributed across load buses.

• total_gen_mw (float, optional) – Total real-power generation/injection (MW). Default 0.

• v_nom_kv (float, optional) – Nominal MV voltage in kV. Default 10.

• assign_cable_types (bool, optional) – Whether to run Step 4 (cable type assignment). Default True.

• assign_cable_lengths (bool, optional) – Whether to run Step 5 (cable length and impedance assignment). Default True.

Returns:

Annotated graph with node attributes (h, P_mw, Q_mvar, pf, node_type) and, when enabled, edge attributes (cable_type, length_km, r_ohm, x_ohm, max_i_ka, I_est_ka).

Return type:

nx.Graph

class powergrid_synth.distribution.TLocationScaleParams

t-Location-Scale distribution for load deviation from uniform.

powergrid_synth.distribution.compare_feeders(synthetic, reference)

Compare synthetic and reference feeders via KL-divergence.

Returns a dict mapping distribution name → KL divergence value.

Parameters:

• synthetic (networkx.Graph)

• reference (networkx.Graph)

Return type:

Dict[str, float]

powergrid_synth.distribution.compute_emergent_properties(G)

Compute emergent (aggregate) properties of a feeder.

Returns a dict with:

• n_nodes : total number of nodes

• n_edges : total number of edges

• max_hop : maximum hop distance

• mean_degree : mean node degree

• total_load_mw : sum of positive P

• total_gen_mw : sum of negative P (absolute)

• frac_intermediate : fraction of intermediate nodes

• frac_injection : fraction of injection nodes

• mean_length_km : mean cable length

• max_length_km : maximum cable length

• total_length_km : total cable length

Parameters:

G (networkx.Graph)

Return type:

Dict[str, float]

powergrid_synth.distribution.feeder_summary(feeders)

Return a summary dict for each feeder graph.

Parameters:

feeders (sequence of nx.Graph) – Feeder graphs produced by pandapower_to_feeders().

Returns:

One dict per feeder with keys n_nodes, n_edges, max_hop, is_tree, total_load_mw, total_gen_mw, node_types.

Return type:

list[dict]

powergrid_synth.distribution.fit_params_from_feeders(feeders)

Fit all Schweitzer parameters from a collection of reference feeders.

Parameters:

feeders (sequence of nx.Graph) – Reference distribution feeder graphs, each annotated with h, P_mw, node_type, length_km attributes.

Returns:

Fitted parameter set ready for SchweetzerFeederGenerator.

Return type:

DistributionSynthParams

powergrid_synth.distribution.kl_divergence_discrete(p_counts, q_counts, n_bins=None)

Compute KL divergence D_KL(P || Q) for two discrete histograms.

Parameters:

• p_counts (array-like) – Raw counts or probability arrays. They are normalized internally.

• q_counts (array-like) – Raw counts or probability arrays. They are normalized internally.

• n_bins (int, optional) – Re-bin both arrays into n_bins equally spaced bins.

Returns:

KL divergence in nats. Returns inf if Q has zero probability where P is nonzero.

Return type:

float

powergrid_synth.distribution.pandapower_to_feeders(net)

Convert a pandapower network to a list of Schweitzer-format feeder graphs.

Each connected component with at least three nodes is returned as a separate graph annotated with the attributes expected by fit_params_from_feeders() and SchweetzerFeederGenerator:

• Node attributes: h (hop distance from root), P_mw (positive = load, negative = generation), node_type ('load' | 'injection' | 'intermediate'), pf (power factor).

• Edge attributes: length_km (cable length in km).

The function handles lines, transformers, and closed bus–bus switches so that the full connectivity of the pandapower network is captured.

Parameters:

net (pandapowerNet) – A pandapower network object.

Returns:

One feeder graph per connected component (≥ 3 nodes).

Return type:

list[nx.Graph]

powergrid_synth.distribution.pypowsybl_to_feeders(network)

Convert a pypowsybl Network to a list of Schweitzer-format feeder graphs.

This is the pypowsybl counterpart of pandapower_to_feeders(). It extracts buses, lines, two-winding transformers, loads, and generators from the pypowsybl Network and builds annotated feeder graphs suitable for fit_params_from_feeders() and SchweetzerFeederGenerator.

Parameters:

network (pypowsybl.network.Network) – A pypowsybl Network object (loaded from CGMES, XIIDM, MATPOWER, etc.).

Returns:

One feeder graph per connected component (≥ 3 nodes), with the same node/edge attributes as pandapower_to_feeders().

Return type:

list[nx.Graph]

powergrid_synth.distribution.synthesize_distribution(*, mode, reference_case=None, reference_net=None, reference_file=None, params=None, n_feeders=1, n_nodes=20, total_load_mw=0.5, total_gen_mw=0.0, v_nom_kv=10.0, assign_cable_types=True, assign_cable_lengths=True, seed=None, output_dir=None, output_name='synthetic_feeder', export_formats=('json',))

Run the full Schweitzer distribution synthesis pipeline.

Parameters:

• mode ("reference" or "default") –

  Selects the operation mode.

  • "reference" — fit synthesis parameters from an existing distribution network (pandapower, pypowsybl, or file), then generate synthetic feeders with the fitted parameters.

  • "default" — use default Table III parameters (or a user-supplied DistributionSynthParams).

• reference_case (str, optional) – Short name of a built-in distribution network. Currently supported: "cigre_lv", "cigre_mv", or any pandapower factory function name. Ignored when reference_net or reference_file is given.

• reference_net (pandapowerNet or pypowsybl.network.Network, optional) – A pre-loaded network object. Takes precedence over reference_case and reference_file.

• reference_file (str, optional) – Path to a grid file in any pypowsybl-supported format.

• params (DistributionSynthParams, optional) – Custom parameters for mode="default". If None, the built-in defaults from Schweitzer Table III are used.

• n_feeders (int) – Number of synthetic feeders to generate (default 1).

• n_nodes (int) – Number of nodes per feeder (default 20).

• total_load_mw (float) – Total load in MW per feeder (default 0.5).

• total_gen_mw (float) – Total generation in MW per feeder (default 0.0).

• v_nom_kv (float) – Nominal voltage in kV (default 10.0).

• assign_cable_types (bool) – Run Step 4 — cable type assignment (default True).

• assign_cable_lengths (bool) – Run Step 5 — cable length / impedance assignment (default True).

• seed (int, optional) – Random seed for reproducibility.

• output_dir (str, optional) – If given, export feeders to this directory.

• output_name (str) – Base filename (without extension) for exported files.

• export_formats (sequence of str) – Export formats when output_dir is set. Supported: "json", "excel", "sqlite", "pickle".

Returns:

Generated synthetic feeders as annotated NetworkX graphs.

Return type:

list[nx.Graph]

Raises:

ValueError – If mode is invalid or required arguments are missing.

powergrid_synth.distribution.validate_tree(G)

Check structural validity of a feeder and return list of issues.

Parameters:

G (networkx.Graph)

Return type:

List[str]