Getting Started
Source code: GitHub repository
Installation
From PyPI
pip install powergridsynth
From source (development mode)
Clone the repository:
git clone https://github.com/cookbook-ms/Chung_Lu_Chain-synthesizer.git
cd Chung_Lu_Chain-synthesizer
Create and activate a virtual environment (e.g. with
uv):
uv venv powergrid
source powergrid/bin/activate
Install in editable mode with development dependencies:
uv pip install -e ".[dev]"
For one-call synthesis, converters, exporters, and power-flow integrations, install the optional extras as well:
uv pip install -e ".[dev,export]"
Core dependencies: numpy, scipy, networkx, matplotlib, pandas.
Optional export/power-flow dependencies: pandapower, numba, lightsim2grid, pypowsybl, pypowsybl-jupyter.
Transmission Grid Synthesis
Quick Start
The high-level synthesize() function runs the entire CLC transmission pipeline in one call:
from powergrid_synth import synthesize
# Mode I — clone an existing grid's statistical profile
grid = synthesize(
mode="reference",
reference_case="case118",
seed=42,
export_formats=["json", "cgmes", "matpower"],
)
# Mode II — fully synthetic from user-specified parameters
grid = 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,
export_formats=["json", "matpower"],
)
See examples/transmission/Synthesize.ipynb for a full walkthrough.
Step-by-Step Usage
For fine-grained control over each pipeline stage:
from powergrid_synth import (
InputConfigurator, PowerGridGenerator, BusTypeAllocator,
CapacityAllocator, LoadAllocator, GenerationDispatcher,
TransmissionLineAllocator, GridVisualizer,
)
# 1. Configure voltage levels and inter-level connections
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},
}
config = InputConfigurator(seed=42)
params = config.create_params(level_specs, connection_specs)
# 2. Generate topology (CLC model)
gen = PowerGridGenerator(seed=42)
grid = gen.generate_grid(
degrees_by_level=params['degrees_by_level'],
diameters_by_level=params['diameters_by_level'],
transformer_degrees=params['transformer_degrees'],
)
# 3. Assign bus types, generation/load, dispatch, and line parameters
BusTypeAllocator(grid).allocate()
CapacityAllocator(grid).allocate()
LoadAllocator(grid).allocate()
GenerationDispatcher(grid).dispatch()
TransmissionLineAllocator(grid).allocate()
# 4. Visualize
GridVisualizer().plot_grid(grid, layout='yifan_hu', title="Synthetic Grid")
Synthesis Pipeline
Step |
Module |
Method |
|---|---|---|
1. Topology generation |
|
CLC graph model with prescribed degree distribution and diameter per voltage level; k-stars inter-level transformer model |
2. Bus-type assignment |
|
Entropy-based AIS optimisation reproducing empirical 2-D joint distribution of bus types and node degrees |
3. Generation capacity |
|
Exponential/extreme-value sampling with capacity–degree correlation via 2-D PMF table |
4. Load allocation |
|
Empirical 2-D probability table matching load–degree joint distribution; reactive loads via power-factor model |
5. Generation dispatch |
|
Three-category partitioning with 2-D bin matching and iterative balancing |
6. Transmission lines |
|
LogNormal impedance magnitudes, Lévy-stable line angles, DCPF-based swapping, exponential gauge-ratio assignment |
Modules
Module |
Description |
|---|---|
|
Main orchestrator — |
|
Backbone setup and spatial-box assignment (Algorithm 1) |
|
Intra-level edge creation via CLC model (Algorithm 2) |
|
Inter-level connections via k-stars model (Algorithm 3) |
|
High-level specification → detailed input parameters |
|
Optimises distribution parameters (DGLN α,β / Power-Law γ) to match target average degree |
|
AIS-based Generator / Load / Connection bus-type assignment |
|
Generation capacity (Pg_max) allocation |
|
Active-power load (Pl) and reactive-power load (Ql) allocation |
|
Dispatch factor (α) assignment and generation–load balancing |
|
Branch impedance (R, X) and thermal capacity (F_max) allocation |
|
Lightweight DC power-flow solver |
|
Pre-computed empirical statistics for NYISO, WECC reference systems |
Distribution Grid Synthesis
Quick Start
The high-level synthesize_distribution() function generates realistic radial MV/LV feeders in one call:
from powergrid_synth import synthesize_distribution
# Mode I — fit parameters from a reference distribution network
feeders = synthesize_distribution(
mode="reference",
reference_case="cigre_lv",
n_feeders=5,
n_nodes=20,
total_load_mw=0.5,
seed=42,
output_dir="output",
export_formats=["json"],
)
# Mode II — use default Table III parameters (no reference needed)
feeders = synthesize_distribution(
mode="default",
n_feeders=10,
n_nodes=30,
total_load_mw=0.8,
seed=7,
)
See examples/distribution/DistributionSynth.ipynb and examples/distribution/DistributionSynthFromRef.ipynb for detailed walkthroughs.
Synthesis Pipeline
Step |
Description |
|---|---|
1. Tree topology |
Random radial tree generation with branching and hop-count constraints |
2. Cable types |
Assign cable types from a realistic catalogue (weighted by frequency) |
3. Cable lengths |
Sample cable lengths from a Cauchy distribution fitted to reference data |
4. Loads |
Distribute total load across buses |
5. Generation |
Assign distributed generation (PV, etc.) to buses |
Modules
Module |
Description |
|---|---|
|
|
|
|
|
|
|
|
|
Input configuration and validation |
|
Structural and electrical validation of generated feeders |
|
|
Testing
pytest tests/ -v
Building Documentation
cd docs
make html