powergrid_synth.transmission.synthesize

Complete power-grid synthesis workflow.

This module exposes a single public function synthesize() that runs the full CLC pipeline — topology generation, bus-type assignment, generation/load allocation, dispatch, transmission-line parameterization, and export — without any intermediate visualisation.

Two operation modes are supported:

• Mode I – reference-based (mode="reference"): Load an existing power grid from pandapower, pypowsybl, or a file in any pypowsybl-supported format (CGMES, XIIDM, MATPOWER, PSS/E, etc.), extract its topological parameters, and generate a structurally similar synthetic clone.

• Mode II – synthetic (mode="synthetic"): Build a grid entirely from user-specified voltage-level specifications (node counts, average degrees, diameters, degree distributions) and inter-level connection parameters.

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

from powergrid_synth.synthesize import synthesize

synthesize(
    mode="reference",
    reference_case="case118",
    seed=42,
    output_dir="output",
    export_formats=["json", "cgmes"],
)

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

synthesize(
    mode="reference",
    reference_case="ieee118",
    seed=42,
    output_dir="output",
    export_formats=["json", "cgmes"],
)

Example — Mode I (reference-based, file path):

synthesize(
    mode="reference",
    reference_file="path/to/grid.xiidm",
    seed=42,
    output_dir="output",
    export_formats=["json", "cgmes"],
)

Example — Mode II (fully synthetic):

from powergrid_synth.synthesize import synthesize

synthesize(
    mode="synthetic",
    level_specs=[
        {"n": 50,  "avg_k": 3.5, "diam": 10, "dist_type": "dgln"},
        {"n": 150, "avg_k": 2.5, "diam": 15, "dist_type": "dpl"},
        {"n": 300, "avg_k": 2.0, "diam": 20, "dist_type": "poisson"},
    ],
    connection_specs={
        (0, 1): {"type": "k-stars", "c": 0.174, "gamma": 4.15},
        (1, 2): {"type": "k-stars", "c": 0.15,  "gamma": 4.15},
    },
    seed=42,
    output_dir="output",
    export_formats=["json", "matpower"],
)

Module Contents

powergrid_synth.transmission.synthesize._get_pypowsybl_builtins()

Return a mapping of short names to pypowsybl built-in network factories.

Return type:

Dict[str, object]

powergrid_synth.transmission.synthesize._is_pypowsybl_network(obj)

Check if obj is a pypowsybl Network without requiring the import.

Return type:

bool

powergrid_synth.transmission.synthesize._load_reference(*, reference_net=None, reference_file=None, reference_case=None)

Resolve a reference grid to a NetworkX graph.

Priority: reference_net > reference_file > reference_case.

Parameters:

• reference_file (Optional[str])

• reference_case (Optional[str])

Return type:

networkx.Graph

powergrid_synth.transmission.synthesize.synthesize(*, mode, reference_case=None, reference_net=None, reference_file=None, level_specs=None, connection_specs=None, seed=None, keep_lcc=True, entropy_model=0, bus_type_ratio=None, ref_sys_id=1, loading_level='H', refine_topology=False, base_kv_map=None, output_dir='output', output_name='synthetic_grid', export_formats=('json',))

Run the full CLC synthesis pipeline and export the result.

Parameters:

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

  Selects the operation mode.

  • "reference" — extract topology parameters from an existing pandapower network (Mode I).

  • "synthetic" — generate topology from user-provided level / connection specs (Mode II).

• reference_case (str, optional) – Name of a built-in network. Supports both pandapower case names (e.g. "case118") and pypowsybl IEEE names (e.g. "ieee14", "ieee118"). Ignored if reference_net or reference_file is given.

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

• reference_file (str, optional) – Path to a grid file in any pypowsybl-supported format (CGMES, XIIDM, MATPOWER, IEEE-CDF, PSS/E, UCTE, etc.). Takes precedence over reference_case.

• level_specs (list of dict, optional) – Voltage-level specifications for Mode II. Each dict must have keys "n" (int), "avg_k" (float), "diam" (int), and "dist_type" ("dgln" | "dpl" | "poisson"). Optionally "max_k" (int).

• connection_specs (dict, optional) – Transformer connection specs for Mode II. Maps (level_i, level_j) tuples to dicts with "type" ("k-stars" | "simple") and parameters "c", "gamma".

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

• keep_lcc (bool) – If True (default), keep only the largest connected component after topology generation.

• entropy_model (int) – Bus-type entropy model — 0 (standard) or 1 (weighted).

• bus_type_ratio (list of float, optional) – Target [Gen%, Load%, Conn%] ratios. If None, default ratios based on network size are used.

• ref_sys_id (int) – Reference system for statistical tables (0–3).

• loading_level (str) – Load level — "D" (deterministic), "L" (light), "M" (medium), "H" (heavy, default).

• refine_topology (bool) – If True, the transmission allocator may add/remove edges to improve DCPF convergence.

• base_kv_map (dict, optional) – Custom {level_index: kV} mapping. If None and mode="reference", the mapping is extracted from the reference grid.

• output_dir (str) – Directory for exported files (created if needed).

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

• export_formats (sequence of str) – One or more format names to export. Supported: "json", "excel", "sqlite", "pickle", "xiidm", "cgmes", "matpower", "psse".

Returns:

The fully parameterised synthetic grid (a PowerGridGraph).

Return type:

nx.Graph

Raises:

ValueError – If mode is not "reference" or "synthetic", or if required arguments for the chosen mode are missing.