powergrid_synth.transmission.deg_dist_optimizer

Given the size n and the average degree ave_k, This module returns the degree distribution with optimized distribution parameters for

  • dgln: discrete generalized log-normal — the number \(n_d\) of degree \(d\) nodes

    \[n_d \propto \exp\Big(-\bigg(\frac{\log d}{\alpha}\bigg)^\beta\Big)\]

    for some parameters \(\alpha, \beta\).

  • dpl: discrete power law — a scale-free network where the degree distribution follows a power law

    \[n_d \propto d^{-\gamma}\]

    for some parameter \(\gamma\).

This optimizer is based on Kolda et al. (2014), where users specify target values for average degree and/or maximum degree. See Topology Generation on how to set them.

Module Contents

class powergrid_synth.transmission.deg_dist_optimizer.DegreeDistributionOptimizer(verbose=False)[source]

Find parameters for ideal degree distributions matching target statistics.

Supports two distribution families:

  • dgln (discrete generalized log-normal): \(n_d \propto \exp\!\big(-(\log d / \alpha)^\beta\big)\)

  • dpl (discrete power law): \(n_d \propto d^{-\gamma}\)

The optimizer minimizes a penalty that combines a max-degree probability bound with a squared error on the target average degree, following Kolda et al. (2014) (FEASTPACK).

Ported from MATLAB degdist_param_search.m (Sandia National Labs).

Parameters:

verbose (bool, optional) – If True, print optimization progress. Default is False.

_dgln_pdf(n, alpha, beta)[source]

Compute the discrete generalized log-normal (DGLN) PDF.

\[P(x) \propto \exp\!\Big(-\Big(\frac{\log x}{\alpha}\Big)^\beta\Big), \quad x=1,\dots,n\]
Parameters:

  • n (int) – Maximum degree (support is 1..n).

  • alpha (float) – Scale parameter (> 0).

  • beta (float) – Shape parameter (> 0).

Returns:

Normalized probability vector of length n.

Return type:

numpy.ndarray

_dpl_pdf(n, gamma)[source]

Compute the discrete power-law (DPL) PDF.

\[P(x) \propto x^{-\gamma}, \quad x=1,\dots,n\]
Parameters:

  • n (int) – Maximum degree (support is 1..n).

  • gamma (float) – Power-law exponent (> 0).

Returns:

Normalized probability vector of length n.

Return type:

numpy.ndarray

_objective_func(params, dist_type, max_deg, target_avg, prob_bound)[source]

Objective function for the distribution parameter search.

The score combines two terms:

  1. Max-degree bound penalty: exponential penalty if \(P(d_{\max}) > \text{prob\_bound}\).

  2. Average-degree error: \((\bar{d}_{\text{current}} - \bar{d}_{\text{target}})^2\).

Parameters:

  • params (array-like) – Distribution parameters: (alpha, beta) for DGLN or (gamma,) for DPL.

  • dist_type (str) – 'dgln' or 'dpl'.

  • max_deg (int) – Maximum degree in the support.

  • target_avg (float) – Target average degree.

  • prob_bound (float) – Upper bound on the probability at max_deg.

Returns:

Penalty score (lower is better).

Return type:

float

optimize(target_avg, max_deg, dist_type='dgln', prob_bound=1e-10)[source]

Find distribution parameters matching the target average degree.

Uses Nelder-Mead optimization to minimize _objective_func(). See Kolda et al. (2014) for details.

Parameters:

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

  • max_deg (int) – Maximum degree \(d_{\max}\) (defines the PDF support 1..max_deg).

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

  • prob_bound (float, optional) – Upper bound on \(P(d_{\max})\). Default is 1e-10.

Returns:

  • best_params (numpy.ndarray) – Optimized parameters: (alpha, beta) for DGLN or (gamma,) for DPL.

  • final_pdf (numpy.ndarray) – Normalized PDF evaluated at degrees 1..max_deg.

Return type:

Tuple[numpy.ndarray, numpy.ndarray]