Graph Theoretic Model

Geographic Graph

A class for geographic graph corresponding to a multilayer network.

Geographic graph is a unique concept in this project. Due to the fact that there is no duplicated intra-nodes in different layers, all the intra-edges can be included in one simple graph (without parallel edge). Furthermore, inter-nodes represent transformers in power systems, so they are geographical points. That is, all the nodes and edges in a planar graph have geographical attributes.

class mgrid.graph.geographic.GeoGraph(dg=None)

Bases: networkx.classes.digraph.DiGraph

Multilayer network as a planar graph.

Note

DiGraph from networkx is inherited, in order to modify terminals of edges directly. The order of edge terminals returned by Graph class is not consistent.

inter_nodes

information on inter-nodes.

name	dtype	definition
name (index)	object	name in planar graph
upper	int64	connected upper layer
lower	int64	connected lower layer

Type

DataFrame

layers

integer indices of all the layers.

Type

Set[int]

df_layers

information on layers.

name	dtype	definition
idx (index)	int	integer indices of layers
name	object	layer names

Type

DataFrame

__init__(dg=None)

Init an empty directed graph or from existing directed graph.

Parameters

dg (Optional[DiGraph]) – an existing directed graph. Default to be None.

add_inter_node(name, upper=True)

Specify a planar node as inter-node with an adjacent layer.

Sometimes, one terminal of an inter-edge is an isolated node in some layer, then it will not be recognised as an inter-node. It must be specified manually.

Warning

Upper layer has a smaller integer index.

Parameters

• name (str) – name of the inter-node.

• upper (Optional[bool]) – whether the other terminal of the corresponding inter-edge is on upper layer.

find_layer(node)

Find layer(s) of a given node.

Note

• It is assumed that there is no isolated planar node, or its layer must be specified by node attribute.

• If an inter-node is isolated in some layer, only the other layer will be returned.

Parameters

node (str) – name of a planar node or an inter-node.

Return type

Tuple[int, int]

Returns

Integer indices of upper and lower layers.

classmethod from_edgelist(df, source, target, element=None)

Init a planar graph from an edgelist dataframe.

Parameters

• df (DataFrame) –

  an edgelist with at least three columns.

  name	dtype	definition
  layer	int	to which layer an intra-edge belongs
  element (optional)	object	model for intra-edge

• source (str) – column name indicating sources of edges.

• target (str) – column name indicating targets of edges.

• element (Optional[str]) – column name indicating models for delivery element.

Returns

A PlanarGraph when the dataframe have essential columns.

property intra_nodes

Gather all the intra-nodes in a dataframe.

Return type

DataFrame

Returns

Information on intra-nodes.

name	dtype	definition
name (index)	object	node name
layer	int64	to which layer the node belongs

layer_edges(layer)

Gather all the edges and edge attributes in one layer.

Parameters

layer (int) – integer index of a layer.

Return type

Set[tuple]

Returns

An edgelist for those in one layer.

layer_graph(layer)

Build a directed graph for one layer.

Note

Inter-nodes are not distinguished in different layers.

Parameters

layer (int) – integer index of a layer.

Return type

DiGraph

Returns

A directed graph representing a given layer.

Supra Graph

Class for multilayer network in supra-graph format.

class mgrid.graph.supra.SupraGraph(dg=None)

Bases: networkx.classes.digraph.DiGraph

Multilayer network as a supra graph.

Supra-graph is way to represent a multilayer network in one graph. Especially, intra-edges and inter-edges exist at the same time. See [bianconi2018multilayer] for details.

Note

Any terminal pair of inter-edges is replica nodes. In planar graph, the inter-edge is contracted, so such two replica nodes are represented by one node. So they are called inter-nodes. Nodes in another kind only exist in one layer, and there is nothing in another lay related to them.

Warning

It is impossible to modify SupraGraph for now, and it is frozen using networkx.

intra_edges

correspondence between intra-edges in planar graph and in multilayer graph.

name	dtype	definition
source_original (index)	object	target in planar graph
target_original (index)	object	target in planar graph
source	object	current source bus
target	object	current target bus

Type

DataFrame

inter_edges

correspondence between inter-nodes in planar graph and inter-edges in multilayer graph.

name	dtype	definition
node (index)	object	name in planar graph
upper	int64	integer index of upper layer
lower	int64	integer index of lower layer
source	object	source node in supra graph
target	object	target node in supra graph

Type

DataFrame

__init__(dg=None)

Init an empty directed graph or existing directed graph.

Note

It is essential to have the option for empty graph, or some built-in networkx function will not work. Don’t know why.

Parameters

dg (Optional[DiGraph]) – an existing directed graph. Default to be None.

property nodes_new

Gather information on terminals of inter-edges.

Return type

DataFrame

Returns

Correspondance between original nodes, layers and buses for terminals of inter-edges.

name	dtype	definition
origin (index)	object	node in geographic graph
layer (index)	int64	to which layer the node belongs
bus	object	node name in supra graph