abstract_network

Base class for networks

class AbstractNetwork(caching: bool = True)

Bases: object

Abstract class for DHNs. It incorporates common methods and utilities to different possible graph representations of DHNs.

__init__(caching: bool = True)

add_edge(name: Hashable, start_node: Hashable, end_node: Hashable, **kwargs) → None

Adds a single edge to the directed graph of the network.

Parameters:

• name (Hashable) – Unique name or ID of the edge.

• start_node (Hashable) – Name of the start node.

• end_node (Hashable) – Name of the end node.

• **kwargs – Additional attributes of the node.

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node(0)
>>> net.add_node(1)
>>> net.add_edge((0, 1), 0, 1)
>>> edges = net.edges()
>>> edges
array([[0, 1]])

add_node(name: Hashable, x: float | None = None, y: float | None = None, z: float | None = 0, temperature: float = 50.0, **kwargs) → None

Adds a single node to the directed graph of the network.

Parameters:

• name (Hashable) – Unique name or ID of the node.

• x (float, optional) – X coordinate of the node for plotting. The default is None.

• y (float, optional) – Y coordinate of the node for plotting. The default is None.

• z (float, optional) – Z coordinate of the node, used to compute hydrostatic pressure. The default is 0.

• temperature (float, optional) – Initial node temperature. The default is TEMPERATURE.

• **kwargs – Additional attributes of the node.

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node(0)
>>> net.add_node(1)
>>> net.add_node(2)
>>> nodes, _ = net.nodes()
>>> nodes
array([0, 1, 2])

property adjacency_matrix: array

Returns the adjacency matrix of the network.

Returns:

The adjacency matrix of the network graph as 2D Numpy array of integers.

Return type:

ndarray

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_edge("Pipe 0-1", "Node 0", "Node 1")
>>> net.adjacency_matrix
array([[0, 1],
       [0, 0]], dtype=int32)

property caching: bool

Returns the status of self._caching. If True, the outputs of some computations, such as for example the adjacency matric, will be cached, allowing for faster simulations.

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork(caching=True)
>>> net._caching
True

copy() → T

Returns a deep copy of the class.

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net_2 = net.copy()

property cycle_matrix

Returns the cycle matrix of the network graph computed using Networkx and converted into a Numpy array. The cycle matrix only includes cycles from a basis and it is computed from the undirected graph. Edges in a cycle with opposite direction are given an entry of -1 in the matrix.

Returns:

The cycle matrix of the network graph as 2D Numpy array of integers.

Return type:

ndarray

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_node("Node 2")
>>> net.add_edge("Pipe 0-1", "Node 0", "Node 1")
>>> net.add_edge("Pipe 1-2", "Node 1", "Node 2")
>>> net.add_edge("Pipe 2-0", "Node 2", "Node 0")
>>> net.cycle_matrix 
array([[ -1., -1.,  1.]])

edges(data: Iterable | None = None, mask: array | None = None) → List[array]

Returns a list of arrays where the first one contains the edge names and the followings ones contain the requested edge data. The values in the arrays follow the order of edges in the class. The order of data arrays follows the order in which they appear in the iterable.

Parameters:

• data (Optional[Iterable], optional) – Names of the attributes to return. If the iterable is a string, a single attribute with the name matching the string is returned. The default is None.

• mask (Optional[np.array], optional) – Array of the indices of edges that should be returned. The indices follow the order of nodes in the network graph.. The default is None.

Returns:

List containing the arrays with node names and those with the values of the requested attributes.

Return type:

list

Examples

>>> from pydhn.classes import Network
>>> net = Network()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_node("Node 2")
>>> net.add_pipe("Pipe 0-1", "Node 0", "Node 1", color="Blue")
>>> net.add_pipe("Pipe 1-2", "Node 1", "Node 2")
>>> net.add_pipe("Pipe 2-0", "Node 2", "Node 0", color="Red")
>>> edges, colors = net.edges("color")
>>> edges
array([['Node 0', 'Node 1'],
       ['Node 1', 'Node 2'],
       ['Node 2', 'Node 0']], dtype='<U6')
>>> colors
array(['Blue', 'nan', 'Red'], dtype='<U32')

get_edges_attribute_array(attribute: str) → array

Returns an array containing the values of the specified attribute for each edge of the network graph. The values follow the order of edges in the class as returned by the method .edges().

Parameters:

attribute (str) – Name of the attribute to get.

Returns:

arr – Array containing the values of the requested attribute for each edge. The values follow the order of edges in the class.

Return type:

Array

Examples

>>> from pydhn.classes import Network
>>> net = Network()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_node("Node 2")
>>> net.add_pipe("Pipe 0-1", "Node 0", "Node 1", color="Blue")
>>> net.add_pipe("Pipe 1-2", "Node 1", "Node 2")
>>> net.add_pipe("Pipe 2-0", "Node 2", "Node 0", color="Red")
>>> edges = net.edges()
>>> edges
array([['Node 0', 'Node 1'],
       ['Node 1', 'Node 2'],
       ['Node 2', 'Node 0']], dtype='<U6')
>>> values = ["green", "blue", "red"]
>>> net.get_edges_attribute_array("color")
array(['Blue', 'nan', 'Red'], dtype='<U32')

get_edges_with_attribute(attribute: str, value: Any) → array

Returns the name of edges with the speficied attribute value.

Parameters:

• attribute (str) – Name of the attribute to filter.

• value (Any) – Value of the attribute to be searched.

Returns:

Array containing the name of edges where the attribute has the specified value.

Return type:

Array

Examples

>>> from pydhn.classes import Network
>>> net = Network()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_node("Node 2")
>>> net.add_pipe("Pipe 0-1", "Node 0", "Node 1", color="Blue")
>>> net.add_pipe("Pipe 1-2", "Node 1", "Node 2")
>>> net.add_pipe("Pipe 2-0", "Node 2", "Node 0", color="Red")
>>> edges = net.get_edges_with_attribute("color", "Blue")
>>> edges
array(['Pipe 0-1'], dtype='<U8')

get_nodes_attribute_array(attribute: str, fill_missing: Any = 0.0, dtype: type | None = None) → array

Returns an array containing the values of the specified attribute for each node of the network graph. The values follow the order of nodes in the class as returned by the method .nodes().

Parameters:

• attribute (str) – Name of the attribute to get.

• fill_missing (Any, optional) – Value for replacing missing entries. The default is 0.0.

• dtype (Type, optional) – Data type to which the output array should be casted. The default is None.

Returns:

arr – Array containing the values of the requested attribute for each node. The values follow the order of nodes in the class.

Return type:

Array

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node(0, color="blue")
>>> net.add_node(1)
>>> colors = net.get_nodes_attribute_array("color", fill_missing="red")
>>> colors
array(['blue', 'red'], dtype='<U4')

get_nodes_with_attribute(attribute: str, value: Any) → array

Returns the name of nodes with the speficied attribute value.

Parameters:

• attribute (str) – Name of the attribute to filter.

• value (Any) – Value of the attribute to be searched.

Returns:

Array containing the name of nodes where the attribute has the specified value.

Return type:

Array

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node('u', color="blue")
>>> net.add_node('v', color="red")
>>> nodes = net.get_nodes_with_attribute("color","red")
>>> nodes
array(['v'], dtype='<U1')

property incidence_matrix: array

Returns the incidence matrix of the network.

Returns:

The incidence matrix of the network graph as 2D Numpy array of integers.

Return type:

ndarray

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_edge("Pipe 0-1", "Node 0", "Node 1")
>>> net.incidence_matrix
array([[-1.],
       [ 1.]])

load_gml(filename)

load_graph(filename)

property n_edges: int

Returns the number of edges in the network. This property has no setter method, so that it cannot be modified manually.

Returns:

Number of edges in the network graph.

Return type:

int

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_edge("Pipe 0-1", "Node 0", "Node 1")
>>> net.n_edges
1

property n_nodes: int

Returns the number of nodes in the network.

Returns:

Number of nodes in the network graph.

Return type:

int

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.n_nodes
2

nodes(data: Iterable | None = nan, mask: array | None = None) → List[array]

Returns a list of arrays where the first one contains the node names and the followings ones contain the requested node data. The values in the arrays follow the order of nodes in the class. The order of data arrays follows the order in which they appear in the iterable.

Parameters:

• data (Optional[Iterable], optional) – Names of the attributes to return. If the iterable is a string, a single attribute with the name matching the string is returned. The default is np.nan.

• mask (Optional[np.array], optional) – Array of the indices of nodes that should be returned. The indices follow the order of nodes in the network graph. The default is None.

Yields:

Array – Arrays containing the node names and the values for the requested attributes.

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node('u', color="blue", size=10)
>>> net.add_node('v', color="red")
>>> nodes, _ = net.nodes()
>>> nodes
array(['u', 'v'], dtype='<U1')
>>> nodes, color = net.nodes('color')
>>> color
array(['blue', 'red'], dtype='<U4')
>>> nodes, color, size = net.nodes(['color', 'size'])
>>> size
array([10.,  0.])

plot_network(figsize: Tuple[float, float] = (12, 8), plot_edge_labels: bool = False, plot_node_labels: bool = False, **kwargs) → None

Method implementing pydhn.plotting.plot_network. Coordinates x and y must be given for nodes as attributes.

Parameters:

• figsize (Tuple[float, float], optional) – Size of the figure. The default is (12, 8).

• plot_edge_labels (bool, optional) – Wether to plot edge names. The default is False.

• plot_node_labels (bool, optional) – Wether to plot node names. The default is False.

• **kwargs – Keyword arguments for nx.draw_networkx.

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node(0, x=0, y=0)
>>> net.add_node(1, x=1, y=2)
>>> net.add_node(2, x=2, y=0)
>>> net.add_edge('edge 1', 0, 1)
>>> net.add_edge('edge 2', 1, 2)
>>> net.plot_network()

save_gml(filename)

save_graph(filename)

set_edge_attribute(value: Any, name: str, mask: array | None = None) → None

Set the same value as the specified attribute (name) for all edges.

Parameters:

• value (Any) – Value to be set for all edges.

• name (str) – Name of the attribute for which value is set.

• mask (array, optional) – Array of the indices of edges for which the attribute should be set. The order is based on the order of edges in the class as returned by the method .edges().

Examples

>>> import numpy as np
>>> from pydhn.classes import Network
>>> net = Network()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_node("Node 2")
>>> net.add_pipe("Pipe 0-1", "Node 0", "Node 1")
>>> net.add_pipe("Pipe 1-2", "Node 1", "Node 2")
>>> net.add_pipe("Pipe 2-0", "Node 2", "Node 0")
>>> edges = net.edges()
>>> edges
array([['Node 0', 'Node 1'],
       ['Node 1', 'Node 2'],
       ['Node 2', 'Node 0']], dtype='<U6')
>>> net.set_edge_attribute("red", "color")
>>> _, colors = net.edges("color")
>>> colors
array(['red', 'red', 'red'], dtype='<U3')
>>> mask = np.array([0, 2])
>>> net.set_edge_attribute("blue", "color", mask)
>>> _, colors = net.edges("color")
>>> colors
array(['blue', 'red', 'blue'], dtype='<U4')

set_edge_attributes(values: dict | array, name: str, mask: array | None = None) → None

Set the specified attribute in edges. Values can be either a dict mapping edges to values or an iterable which has the same length as the number of edges in the graph. In this case, the order of values must match the order of edges obtained using self.edges()

Parameters:

• values (Union[dict, np.array]) – Either a dict with edge-value pairs or an iterable containing the values ordered as the correspondig edges. If a mask is used, the order should be that of the elements in the mask instead.

• name (str) – Name of the attribute for which values are set.

• mask (array, optional) – Array of the indices of edges for which the attribute should be set. The order is based on the order of edges in the class as returned by the method .edges().

Examples

>>> from pydhn.classes import Network
>>> net = Network()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_node("Node 2")
>>> net.add_pipe("Pipe 0-1", "Node 0", "Node 1")
>>> net.add_pipe("Pipe 1-2", "Node 1", "Node 2")
>>> net.add_pipe("Pipe 2-0", "Node 2", "Node 0")
>>> edges = net.edges()
>>> edges
array([['Node 0', 'Node 1'],
       ['Node 1', 'Node 2'],
       ['Node 2', 'Node 0']], dtype='<U6')
>>> values = ["green", "blue", "red"]
>>> net.set_edge_attributes(values, "color")
>>> _, colors = net.edges("color")
>>> colors
array(['green', 'blue', 'red'], dtype='<U5')
>>> values = {("Node 0", "Node 1"): "purple"}
>>> net.set_edge_attributes(values, "color")
>>> _, colors = net.edges("color")
>>> colors
array(['purple', 'blue', 'red'], dtype='<U6')
>>> mask = np.array([0, 2])
>>> values = ["yellow", "orange"]
>>> net.set_edge_attributes(values, "color", mask)
>>> _, colors = net.edges("color")
>>> colors
array(['yellow', 'blue', 'orange'], dtype='<U6')

set_node_attribute(value: Any, name: str) → None

Set the same value as the specified attribute (name) for all nodes.

Parameters:

• value (Any) – Value to be set for all nodes.

• name (str) – Name of the attribute for which value is set.

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node(0)
>>> net.add_node(1)
>>> net.set_node_attribute("blue", "color")
>>> _, colors = net.nodes("color")
>>> colors
array(['blue', 'blue'], dtype='<U4')

set_node_attributes(values: dict | array, name: str) → None

Set the specified attribute in nodes. Values can be either a dict mapping nodes to values or an iterable which has the same length as the number of nodes in the graph. In this case, the order of values must match the order of nodes obtained using self.nodes()

Parameters:

• values (Union[dict, np.array]) – Either a dict with node-value pairs or an iterable containing the values ordered as the correspondig nodes.

• name (str) – Name of the attribute for which values are set.

Examples

>>> from pydhn.classes import AbstractNetwork
>>> net = AbstractNetwork()
>>> net.add_node(0)
>>> net.add_node(1)
>>> nodes, _ = net.nodes()
>>> nodes
array([0, 1])
>>> values = ["green", "blue"]
>>> net.set_node_attributes(values, "color")
>>> _, colors = net.nodes("color")
>>> colors
array(['green', 'blue'], dtype='<U5')
>>> values = {0: "green", 1: "red"}
>>> net.set_node_attributes(values, "color")
>>> _, colors = net.nodes("color")
>>> colors
array(['green', 'red'], dtype='<U5')

to_geodataframe(target='all')

to_geojson(filename, target='all')

to_linegraph(edge_label='name')

to_nx_graph() → DiGraph