powergrid_synth.distribution.synthesize

One-line distribution feeder synthesis workflow.

This module exposes a single public function synthesize_distribution() that runs the full Schweitzer pipeline — reference loading, parameter fitting, feeder generation, validation, and export — without any intermediate steps.

Two operation modes are supported:

• Mode I – reference-based (mode="reference"): Load an existing distribution network from pandapower, pypowsybl, or a file in any pypowsybl-supported format, extract its statistical parameters, and generate structurally similar synthetic feeders.

• Mode II – default / parametric (mode="default"): Generate feeders using the built-in default parameters from Table III of Schweitzer et al. (2017), or from a user-supplied DistributionSynthParams object.

Example — Mode I (reference-based, pandapower):

from powergrid_synth.distribution.synthesize import synthesize_distribution

feeders = synthesize_distribution(
    mode="reference",
    reference_case="cigre_lv",
    n_feeders=5,
    n_nodes=20,
    total_load_mw=0.5,
    seed=42,
)

Example — Mode I (reference-based, pypowsybl network):

import pypowsybl as pp
net = pp.network.load("/path/to/grid.cgmes")

feeders = synthesize_distribution(
    mode="reference",
    reference_net=net,
    n_feeders=3,
    n_nodes=25,
    total_load_mw=1.0,
    seed=42,
)

Example — Mode II (default parameters):

feeders = synthesize_distribution(
    mode="default",
    n_feeders=10,
    n_nodes=30,
    total_load_mw=0.8,
    seed=42,
)

Module Contents

powergrid_synth.distribution.synthesize._export_feeders(feeders, *, output_dir, output_name, export_formats)

Export feeders using the GridExporter.

Parameters:

• feeders (List[networkx.Graph])

• output_dir (str)

• output_name (str)

• export_formats (Sequence[str])

Return type:

None

powergrid_synth.distribution.synthesize._get_pandapower_dist_case(name)

Load a pandapower built-in distribution network by short name.

Parameters:

name (str)

powergrid_synth.distribution.synthesize._is_pypowsybl_network(obj)

Check if obj is a pypowsybl Network without a hard import.

Return type:

bool

powergrid_synth.distribution.synthesize._load_reference_feeders(*, reference_net=None, reference_file=None, reference_case=None)

Resolve a reference source to a list of feeder graphs.

Priority: reference_net > reference_file > reference_case.

Parameters:

• reference_file (Optional[str])

• reference_case (Optional[str])

Return type:

List[networkx.Graph]

powergrid_synth.distribution.synthesize.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.