GridTopology

class pomato.grid.GridTopology

GridTopology of POMATO

This module provides the grid functionality to POMATO. And is initialized as an attribute to the POMATO instance when data is (successfully) loaded.

This includes:

• Calculation of the ptdf matrix (power transfer distribution factor), used in linear power flow analysis.

• Calculation of the lodf matrix (load outage distribution factor), to account for contingencies.

• Validation of the input topology based on the nodes and lines data. This includes verification of the chosen slacks/reference nodes and setting of multiple slacks if needed. Also providing the information about which nodes should be balanced through which slack.

• Validation of possible contingencies. This means that lines that disconnect nodes or groups of nodes cannot be considered as a contingency.

• A selection of methods that allow for contingency analysis by obtaining N-1 ptdf matrices by lines, outages or with a sensitivity filter.

This module is initialized solely with nodes and lines data. It purposely does not contain additional data or results, as analysis tasks line power flow calculation are done in respective modules ResultProcessing, GridModel or FBMCModule. This module solely provides the tools for this analysis and the corresponding means of validation to provide a robust experience. The main functionality of contingency analysis is embedded in create_filtered_n_1_ptdf() which reappears in similar form in the other contingency related as well.

The initialization does the following:

• set nodes/lines as attributes.

• check if slacks are set.

• calculate ptdf (and psdf) matrix.

• check if topology contains radial lines/nodes, remove from contingency.

• calculate lodf matrix.

Parameters:

nodesDataFrame

Nodes data, initialized as attribute of GridTopology.

linesDataFrame

Lines data, initialized as attribute of GridTopology.

Attributes:

nodesDataFrame

Nodes table, which .

linesDataFrame

Lines table from data.

ptdfnp.ndarray

ptdf (power transfer distribution factor) matrix \((L \times N)\).

psdfnp.ndarray

psdf (phase shifting distribution factor) matrix \((L \times L)\).

lodfnp.ndarray

N-1 lodf (load outage distribution factor) matrix \((L \times L)\).

contingency_groupsdict

Dictionary that indicates which group of lines is outate, when a line is considered a contingency.

Methods

add_number_of_systems()	Add number of systems to lines dataframe, i.e. how many systems a line is part of.
calculate_parameters(nodes, lines)
check_grid_topology()	Check grid topology for radial nodes and lines.
check_slack()	Check slack configuration from input data.
create_contingency_groups([option])	Create contingency groups i.e. contingencies that occur together.
create_filtered_n_1_ptdf([sensitivity, ...])	Create a N-1 ptdf/info containing all lines under outages with significant impact.
create_incidence_matrix()	Create incidence matrix from lines and nodes attributes.
create_lodf(lines, outages)	Creates load outages distribution factor (lodf) for lines under outages.
create_n_1_lodf_matrix()	Create N-1 LODF matrix.
create_n_1_ptdf_cbco(lines, outage)	Create N-1 ptdf for lines and one specific outage.
create_n_1_ptdf_outage(outages)	Create N-1 ptdf for all lines under a specific outages.
create_psdf_matrix()	Calculate psdf (phase-shifting distribution matrix, LxLL).
create_ptdf_matrix()	Create ptdf matrix.
create_susceptance_matrices()	Create Line (Bl) and Node (Bn) susceptance matrix.
lodf_filter(line[, sensitivity, as_index])	Return outages that impact the specified line with more that the specified sensitivity.
shift_phase_on_line(phase_shift)	Shifts the phase on line l by angle a (in rad).
slack_zones()	Return nodes that are balanced through each slack.

Attributes

numpy_settings

add_number_of_systems()

Add number of systems to lines dataframe, i.e. how many systems a line is part of.

check_grid_topology()

Check grid topology for radial nodes and lines.

Based on the topology, implicitly available in the ptdf matrix, this method find radial lines/nodes and sets the contingency attribute of the grid.lines accordingly.

If a radial line, or a line connecting a radial node, outs it disconnects the network. This means, that the disconnected node(s) cannot be balanced though the slack. Mathematically this causes a division by zero in the lodf matrix calculation.

check_slack()

Check slack configuration from input data.

By checking the components of the network, i.e. the Node-to-Node incidence matrix. For Each component it is checked if a slack is defined, and if not the first node will be set as a slack. Therefore, each subnetwork will be balanced.

create_contingency_groups(option='double_lines')

Create contingency groups i.e. contingencies that occur together.

This can be done by evaluating high lodf values or by topology, i.e. double lines are affected. However, contingency groups still cannot disconnect the network.

Parameters:

option(float, string), optional

Rule of what outages are grouped. Options are: double_lines (default), by value or none.

create_filtered_n_1_ptdf(sensitivity=0.05, short_term_rating_factor=1, long_term_rating_factor=1)

Create a N-1 ptdf/info containing all lines under outages with significant impact.

Create a ptdf that covers the N-0 ptdf (with the outage indicated as basecase in the return DataFrame) and additionally for each line the ptdf that considers outages with significant impact based on the method lodf_filter(). The methods returns a DataFrame with the resulting ptdf matrix including information which lines/outages make up each row.

This methodology is extremely helpful for contingency analysis where the resulting ptdf matrix, and therefore the resulting optimization problem, becomes prohibitive large. We have shown that even a sensitivity of 1% reduces the size of the resulting ptdf matrix by 95%.

See Fast Security-Constrained Optimal Power Flow through Low-Impact and Redundancy Screening for more detailed information.

Parameters:

sensitivityfloat, optional

The sensitivity defines the threshold from which outages are considered critical. A outage that can impact the lineflow, relative to its maximum capacity, more than the sensitivity is considered critical.

Returns:

ptdfDataFrame

Returns DataFrame, each row represents a line (cb, critical branch) under an outage (co, critical outage) with ptdf for each node and the available capacity (ram, remaining available margin) which is equal to the line capacity (but does not have to).

create_incidence_matrix()

Create incidence matrix from lines and nodes attributes.

Returns:

incidencenp.ndarray

Incidence matrix.

create_lodf(lines, outages)

Creates load outages distribution factor (lodf) for lines under outages.

This method creates specific lodf for all lines in argument lines and simultaneous outages in argument outages.

This is calculated by (Bl * A_l * Bhat * A_lc)*(I - Blc * Bhat * A_lc)^-1 as discussed in Fast Security-Constrained Optimal Power Flow through Low-Impact and Redundancy Screening.

Note that the returned array has the dimension lines x outages, therefore the curation of a general lodf matrix, including combined/multiple contingencies is not possible.

Parameters:

lineslist(int), list(string)

List of lines which are affected by the outages.

outageslist(int), list(string)

List of lines that consists the contingency case.

Returns:

lodf

The returned lodf can be used to calculate the contingency ptdf (c_ptdf) from the pre-contingency ptdf (ptdf): c_ptdf = ptdf[lines] + lodf * ptdf[outages, :]

Raises:

ZeroDivisionError

Indicates error in configuration of slack(s) or contingencies.

create_n_1_lodf_matrix()

Create N-1 LODF matrix.

The lodf matrix represents a line to line sensitivity in the case of an outage. In other words, how does the flow on a line distribute on other lines in the case of an outage. This method returns a LxL matrix, representing how each line is affected by the outage of all other lines.

This LODF matrix therefore represents the N-1 case, as only one outage is considered per case. Multiple contingencies have to be explicitly calculated with the more general create_lodf() method.

create_n_1_ptdf_cbco(lines, outage)

Create N-1 ptdf for lines and one specific outage.

Parameters:

linelines.index, int

Line index (DataFrame index or integer).

outageslines.index, int, list(lines.index), list(int)

Line index (DataFrame index or integer).

Returns:

ptdfnp.ndarray

Returns ptdf matrix (1xN) where for a N-dim vector of nodal injections INJ, the dot-product \(PTDF \cdot INJ\) results in the flow on the specified line under the specified outage.

create_n_1_ptdf_outage(outages)

Create N-1 ptdf for all lines under a specific outages.

Parameters:

outageslines.index, int, list(lines.index), list(int)

Line index (DataFrame index or integer).

Returns:

ptdfnp.ndarray

Returns ptdf matrix (LxN) where for a N-dim vector of nodal injections INJ, the dot-product \(PTDF \cdot INJ\) results in the flows on each line under the specified outage.

create_psdf_matrix()

Calculate psdf (phase-shifting distribution matrix, LxLL).

A psdf at position (l,ll) represents the change in power flow on line ll caused by a phase-shift of 1 [rad] on line l.

create_ptdf_matrix()

Create ptdf matrix.

The ptdf matrix represents a note to line sensitivity, essentially a linear mapping of how nodal power injections distribute within the network.

The ptdf matrix is calculated based on the topology and line parameters (i.e. line susceptance).

create_susceptance_matrices()

Create Line (Bl) and Node (Bn) susceptance matrix.

Returns:

line_susceptancenp.ndarray

Line susceptance matrix.

node_susceptancenp.ndarray

Node susceptance matrix.

lodf_filter(line, sensitivity=0.05, as_index=False)

Return outages that impact the specified line with more that the specified sensitivity.

Contingency analysis relies on making sure line capacities are not violated in the case of an outage. This methods returns the lines that, in the worst case of outage, impact the specified line more than the specified sensitivity.

For example this methods returns:

• for a line l, and sensitivity of 5%

• a list of all outages

• which impact line l with more that 5% of its capacity

• in the worst case outage, i.e. when fully loaded.

Parameters:

linelines.index, int

line index (DataFrame index or integer).

sensitivityfloat, optional

The sensitivity defines the threshold

as_indexbool, optional

Bool to indicate whether to return int index.

Returns:

outageslist

list of outages that have a significant (sensitivity) impact on line in case of the worst outage.

shift_phase_on_line(phase_shift)

Shifts the phase on line l by angle a (in rad).

Recalculates the ptdf matrix. This is a static representation of a phase shift rather than a dynamic (and useful one).

Parameters:

phase_shiftdict

dict with line as key, phase shift [rad] as value.

slack_zones()

Return nodes that are balanced through each slack.

In other words, if there are multiple disconnected networks, this returns the informations which node is balanced through which slack.

Returns:

slack_zonesdict(slack, list(node.index))

Dictionary containing slack as keys and list of the nodes indices that are balanced though the slack.