Rank Nodes

Rank Nodes#

High-level ranking helpers that wrap lower-level network and market scoring functions and return sorted node rankings.

API path: node_ranking.rank_nodes

High-level helpers for producing sorted node rankings.

This module wraps the lower-level score functions from network_scores and market_scores and converts raw score dictionaries into descending [(node, score), ...] rankings.

rank_nodes_by_betweenness(G)[source]#

Rank nodes by betweenness centrality.

This ranking is based on the node-level scores returned by node_ranking.network_scores.compute_node_betweenness_centrality().

Parameters:

G (nx.Graph) – Input network.

Returns:

Sorted (node, score) pairs, where the score is the normalized betweenness centrality from NetworkX.

Return type:

list[tuple[hashable, float]]

rank_nodes_by_degree(G)[source]#

Rank nodes by degree centrality.

This ranking is based on the node-level scores returned by node_ranking.network_scores.compute_node_degree_centrality().

Parameters:

G (nx.Graph) – Input network.

Returns:

Sorted (node, score) pairs, where the score is the normalized degree centrality from NetworkX.

Return type:

list[tuple[hashable, float]]

rank_nodes_by_dispatch_volume(nodes, generators, baseline_result)[source]#

Rank nodes by dispatched generation volume.

This ranking is based on the node-level scores returned by node_ranking.market_scores.dispatch_volume_score().

Parameters:

  • nodes (dict) – Node data keyed by node label.

  • generators (dict) – Generator data keyed by generator id.

  • baseline_result (dict) – Baseline dispatch outputs containing dispatch.

Returns:

Sorted (node, score) pairs.

Return type:

list[tuple[hashable, float]]

rank_nodes_by_gamma_capacity_congestion_score(nodes, generators, lines, baseline_result)[source]#

Rank nodes by gamma-capacity-congestion score.

This ranking is based on the node-level scores returned by node_ranking.market_scores.gamma_capacity_congestion_score().

Parameters:

  • nodes (dict) – Node data keyed by node label.

  • generators (dict) – Generator data keyed by generator id.

  • lines (dict) – Line data keyed by line id.

  • baseline_result (dict) – Baseline dispatch outputs containing gamma, mu_plus, and mu_minus.

Returns:

Sorted (node, score) pairs.

Return type:

list[tuple[hashable, float]]

rank_nodes_by_gamma_capacity_score(nodes, generators, baseline_result)[source]#

Rank nodes by gamma-capacity score.

This ranking is based on the node-level scores returned by node_ranking.market_scores.gamma_capacity_score().

Parameters:

  • nodes (dict) – Node data keyed by node label.

  • generators (dict) – Generator data keyed by generator id.

  • baseline_result (dict) – Baseline dispatch outputs containing gamma.

Returns:

Sorted (node, score) pairs.

Return type:

list[tuple[hashable, float]]

rank_nodes_by_ptdf(ptdf, edges, nodes, mask, G, method='sum', fmax_attr='F_max')[source]#

Rank nodes by PTDF-contribution score.

This is a thin wrapper around node_ranking.network_scores.compute_node_ptdf_contribution_scores(). It computes one PTDF-based score per node and returns the nodes sorted from most to least exposed according to the selected aggregation rule.

Parameters:

  • ptdf (np.ndarray) – PTDF matrix with rows as lines and columns as non-slack buses.

  • edges (list[tuple]) – Edge list in the same order as the PTDF rows.

  • nodes (list[hashable]) – Full node list used when constructing the PTDF.

  • mask (list[int]) – Indices of the non-slack buses corresponding to PTDF columns.

  • G (nx.Graph) – Network graph containing the line attributes used for scoring.

  • method ({"sum", "max", "weighted_sum"}, default="sum") – Aggregation rule used to collapse each PTDF column into a node score.

  • fmax_attr (str, default="F_max") – Edge attribute used as the line-capacity weight for method="weighted_sum".

Returns:

Sorted (node, score) pairs.

Return type:

list[tuple[hashable, float]]

rank_nodes_by_ptdf_stress_score(
ptdf,
nodes,
mask,
generators,
line_margins,
epsilon=1e-06,
)[source]#

Rank nodes by PTDF stress score.

This ranking is based on the node-level scores returned by node_ranking.market_scores.ptdf_stress_score().

Parameters:

  • ptdf (np.ndarray) – PTDF matrix with rows as lines and columns as non-slack buses.

  • nodes (list[hashable]) – Full node list used when constructing the PTDF.

  • mask (list[int]) – Indices of the non-slack buses corresponding to PTDF columns.

  • generators (dict) – Generator data keyed by generator id.

  • line_margins (np.ndarray or list[float]) – Residual margin for each PTDF row / line.

  • epsilon (float, default=1e-6) – Small positive stabilizer added to the denominator.

Returns:

Sorted (node, score) pairs.

Return type:

list[tuple[hashable, float]]

rank_nodes_by_scarcity_score(nodes, baseline_result, VOLL=500.0, cap_lambda=True)[source]#

Rank nodes by load-weighted LMP scarcity score.

This ranking is based on nodal prices, node load, and an optional VOLL cap applied to prices before scoring. It uses the node-level scores returned by node_ranking.market_scores.load_weighted_lmp_score().

Parameters:

  • nodes (dict) – Node data keyed by node label. Each node must provide load.

  • baseline_result (dict) – Baseline dispatch outputs containing lambdas.

  • VOLL (float, default=500.0) – Value of lost load used as the optional price cap.

  • cap_lambda (bool, default=True) – Whether to cap nodal prices at VOLL before scoring.

Returns:

Sorted (node, score) pairs.

Return type:

list[tuple[hashable, float]]

rank_nodes_by_shadow_score(nodes, generators, baseline_result)[source]#

Rank nodes by rent-weighted dispatch score.

This ranking is based on the node-level scores returned by node_ranking.market_scores.rent_weighted_dispatch_score().

Parameters:

  • nodes (dict) – Node data keyed by node label.

  • generators (dict) – Generator data keyed by generator id.

  • baseline_result (dict) – Baseline dispatch outputs containing at least dispatch and lambdas.

Returns:

Sorted (node, score) pairs.

Return type:

list[tuple[hashable, float]]