network

Base class for networks

class Network[source]

Bases: AbstractNetwork

Main class for district heating networks. The underlying structure of the network is a Networkx graph of which edges are different network elements, such as pipes, consumers and producers. The graph is directed and the directions of edges set the reference frame: for example, a negative mass flow indicates that the fluid is flowing in the opposite direction with respect to the edge. Multigraphs are not supported.

The elements in the edges are represented by objects called components, which contain the attributes of the edge and the element-specific functions used in simulations.

The graph underlying a Network object must be connected and have nodes of total degree 2 or 3. Nodes with higher total degree might still work, but not enough testing has been done on this front. The graph is also expected to have a “sandwich” structure, with a supply and a return line containing only branch components and connected only by leaf components. As of now, one of these leaf components has to be the “main” component, where a setpoint pressure difference is enforced. A simple example would look like this:

1---->2---->3---->4
^     |     |     |
|     |     |     |
M    S1    S2    S3
|     |     |     |
|     v     v     v
8<----7<----6<----5

Here, nodes 1-4 are in the supply line, while nodes 5-8 are in the return line. The horizontal edges are branch components, and the vertical edges are leaf components. Among these, M is the main node, for example a heat plant where an array of pumps enforces a pre-defined pressure lift.

__init__()[source]
add_branch_pump(name, start_node, end_node, delta_p=0.0, **kwargs)[source]

Adds a single edge of type “branch_pump” to the directed graph of the network.

add_branch_valve(name, start_node, end_node, kv=0.0, **kwargs)[source]

Adds a single edge of type “base_branch_valve” to the directed graph of the network. For a description of the component see BranchValve.

Parameters:

  • name (Hashable) – The label for the edge.

  • start_node (Hashable) – Starting node of the edge.

  • end_node (Hashable) – Ending node of the edge.

  • kv (TYPE, optional) – DESCRIPTION. For the default value see KV.

  • **kwargs (TYPE) – DESCRIPTION.

add_bypass_pipe(name, start_node, end_node, diameter=0.0372, depth=1.0, k_insulation=0.026, length=1.0, insulation_thickness=0.031, roughness=0.045, k_internal_pipe=45.0, internal_pipe_thickness=0.0052, k_casing=0.4, casing_thickness=0.0054, discretization=10, line=None, **kwargs)[source]

Adds a single edge of type “bypass_pipe” to the directed graph of the network.

add_component(name: Hashable, start_node: Hashable, end_node: Hashable, component: Component, **kwargs) → None[source]

Adds a deepcopy of the input component to the network as an edge between start_node and end_node.

Parameters:

  • name (Hashable) – The label for the edge.

  • start_node (Hashable) – Starting node of the edge.

  • end_node (Hashable) – Ending node of the edge.

  • component (Component) – The component to be added as an edge.

  • **kwargs (dict) – Additional keyword arguments to be passed to the edge addition method.

Returns:

This method does not return any value.

Return type:

None

Examples

>>> from pydhn import Network
>>> from pydhn.components import Pipe
>>> net = Network()
>>> pipe = Pipe(length=10)
>>> net.add_component('pipe_1', 0, 1, pipe)
>>> net[(0, 1)]["length"]
10
add_consumer(name: Hashable, start_node: Hashable, end_node: Hashable, diameter: float = 0.02, mass_flow_min: float = 1e-06, heat_demand: float = 5000.0, design_delta_t: float = -30.0, t_secondary: float = 0.0, setpoint_type_hx: str = 'delta_t', setpoint_type_hx_rev: str = 'delta_t', setpoint_value_hx: float = -30.0, setpoint_value_hx_rev: float = 0.0, power_max_hx: float = nan, t_out_min_hx: float = nan, setpoint_type_hyd: str = 'mass_flow', setpoint_value_hyd: float = 1e-06, control_type: str = 'energy', **kwargs) → None[source]

Adds a single edge of type “base_consumer” to the directed graph of the network. The base consumer is an ideal leaf component with imposed mass flow rate, which can either be specified by the user with the parameter setpoint_value_hyd when the control type is “mass_flow”, or computed from the optional inputs heat_demand and design_delta_t when the control type is “energy”. Imposing a setpoint pressure difference is currently not supported.

For the thermal simulation, the base consumer has 3 different possible setpoint types (setpoint_type_hx):

  • “t_out” imposes a specified outlet temperature (°C)

  • “delta_t” imposes a specified temperature difference (K) between the ending and starting node of the edge of the component

  • “delta_q” imposes a specified energy loss or gain (Wh)

Regardless of the setpoint type chosen, the setpoint value is given by setpoint_value_hx.

In case reverse flow is expected, the parameters setpoint_type_hx_rev and setpoint_value_hx_rev should also be specified to control the behaviour of the component in such cases.

Parameters:

  • name (Hashable) – The label for the edge.

  • start_node (Hashable) – Starting node of the edge.

  • end_node (Hashable) – Ending node of the edge.

  • diameter (float, optional) – Internal diameter of the heat exchanger (m). This parameter is not currently used, as singular pressure losses are not implemented. The default is 0.02.

  • mass_flow_min (float, optional) – Minimum mass flow allowed through the consumer (kg/s). Setting this parameter enforces a minimum mass flow even if the heat demand is 0. The default is 1e-06.

  • heat_demand (float, optional) – Heat demand of the consumer (Wh), only used to compute the imposed mass flow when the control type is set to “energy”. A positive heat demand means that the consumer wants energy from the network. This parameter does not control the actual amount of energy exchanged. The default is 5000.0.

  • design_delta_t (float, optional) – Expected temperature difference through the heat exchanger of the consumer (K), only used to compute the imposed mass flow when the control type is set to “energy”. A positive temperature difference means that the consumer is expected to reduce the inlet temperature by that value. This parameter does not control the actual temperature difference during the thermal simulation. The default is -30.0.

  • t_secondary (float, optional) – Temperature of the secondary system (°C). This parameter is not currently used. The default is 0.0.

  • setpoint_type_hx (str, optional) – Type of setpoint for the thermal simulation in case of forward flow. Possible values are “t_out”, “delta_t” and “delta_q”. The default is delta_t.

  • setpoint_type_hx_rev (str, optional) – Type of setpoint for the thermal simulation in case of reverse flow. Possible values are “t_out”, “delta_t” and “delta_q”. The default is delta_t.

  • setpoint_value_hx (float, optional) – Setpoint value of the chosen setpoint type for the thermal simulation in case of forward flow. The default is -30.0.

  • setpoint_value_hx_rev (float, optional) – Setpoint value of the chosen setpoint type for the thermal simulation in case of reverse flow. The default is 0.0.

  • power_max_hx (float, optional) – Maximum power of the heat exchanger, which currently correspond to the maximum energy that can be exchanged during one simulation step (Wh). If set, it limits the heat exchange enforced by the defined setpoints, which are not anymore guaranteed to be reached. The default is nan.

  • t_out_min_hx (float, optional) – Minimum outlet temperature (°C). If set, it limits the outlet temperature resulting from the simulation with the defined setpoints, which are not anymore guaranteed to be reached. The default is nan.

  • setpoint_type_hyd (str, optional) – Hydraulic setpoint type. Currently, the only supported option is “mass_flow”. The default is mass_flow.

  • setpoint_value_hyd (float, optional) – Setpoint value of the chosen setpoint type for the hydraulic simulation. Currently, the only supported hydraulic setpoint type is mass flow (kg/s). The default is 1e-06.

  • control_type (str, optional) – How to compute the imposed mass flow. It can be either “mass_flow”, to impose the value of setpoint_value_hyd, or “energy”, to compute the mass flow from the expected energy_demand and design_delta_t. The default is energy.

  • **kwargs (dict) – Additional keyword arguments.

Returns:

This method does not return any value.

Return type:

None

Examples

>>> from pydhn import Network
>>> net = Network()
>>> net.add_node(0, z=0)
>>> net.add_node(1, z=0)
>>> net.add_consumer('cons_1', 0, 1, control_type='energy')
>>> net[(0, 1)]["control_type"]
'energy'
add_lagrangian_pipe(name: Hashable, start_node: Hashable, end_node: Hashable, diameter: float = 0.0204, depth: float = 1.0, k_insulation: float = 0.026, insulation_thickness: float = 0.034, length: float = 1.0, roughness: float = 0.045, k_internal_pipe: float = 45.0, internal_pipe_thickness: float = 0.023, k_casing: float = 0.4, casing_thickness: float = 0.003, rho_wall: float = 940.0, cp_wall: float = 2000.0, h_ext: float = 0.0, stepsize: float = 5.0, line=None, **kwargs) → None[source]

Adds a component of type “lagrangian_pipe” to the directed graph of the network as an edge between start_node and end_node. The “lagrangian_pipe” branch component is a dynamic pipe type based on the Lagrangian approach. It takes into account the heat capacity of the fluid and internal pipe walls.

Parameters:

  • name (Hashable) – The label for the edge.

  • start_node (Hashable) – Starting node of the edge.

  • end_node (Hashable) – Ending node of the edge.

  • diameter (float, optional) – Internal diameter of the pipe (m). The default is 0.0204.

  • depth (float, optional) – Burying depth of the pipe (m). The default is 1.0.

  • k_insulation (float, optional) – Thermal conductivity of insulation (W/(m·K)). The default is 0.026.

  • insulation_thickness (float, optional) – Thickness of the insulation layer (m). The default is 0.034.

  • length (float, optional) – Length of the pipe (m). The default is 1.0.

  • roughness (float, optional) – Roughness of the internal pipe surface (mm). The default is 0.045.

  • k_internal_pipe (float, optional) – Thermal conductivity of the pipe (W/(m·K)). The default is 45.0.

  • internal_pipe_thickness (float, optional) – Thickness of the pipe (m). The default is 0.023.

  • k_casing (float, optional) – Thermal conductivity of the casing (W/(m·K)). The default is 0.4.

  • casing_thickness (float, optional) – Thickness of the casing (m). The default is 0.003.

  • rho_wall (float, optional) – Density of internal pipe (kg/m³). The default is 940.0.

  • cp_wall (float, optional) – Specific heat capacity of pipe wall (J/(kg·K)). The default is 2000.0.

  • stepsize (float, optional) – Size of a time-step (s). The default is 5.0.

  • h_ext (float, optional) – External heat transfer coefficient (W/(m²·K)). The default is 0.0.

  • line (str, optional) – Either “supply” or “return”. The default is None.

  • **kwargs (dict) – Additional keyword arguments.

Returns:

This method does not return any value.

Return type:

None

Examples

>>> from pydhn import Network
>>> net = Network()
>>> net.add_node(0, z=0)
>>> net.add_node(1, z=0)
>>> net.add_lagrangian_pipe('pipe_1', 0, 1, stepsize=60)
>>> net[(0, 1)]["stepsize"]
60
add_pipe(name: Hashable, start_node: Hashable, end_node: Hashable, diameter: float = 0.0204, depth: float = 1.0, k_insulation: float = 0.026, insulation_thickness: float = 0.034, length: float = 1.0, roughness: float = 0.045, k_internal_pipe: float = 45.0, internal_pipe_thickness: float = 0.023, k_casing: float = 0.4, casing_thickness: float = 0.003, discretization: float = 10, line: str | None = None, **kwargs) → None[source]

Adds a branch component of type “base_pipe” to the directed graph of the network as an edge between start_node and end_node. The “base_pipe” is a steady-state pipe type where volumes of water can be discretized for more accurate results.

Parameters:

  • name (Hashable) – The label for the edge.

  • start_node (Hashable) – Starting node of the edge.

  • end_node (Hashable) – Ending node of the edge.

  • diameter (float, optional) – Internal diameter of the pipe (m). The default is 0.0204.

  • depth (float, optional) – Burying depth of the pipe (m). The default is 1.0.

  • k_insulation (float, optional) – Thermal conductivity of insulation (W/(m·K)). The default is 0.026.

  • insulation_thickness (float, optional) – Thickness of the insulation layer (m). The default is 0.034.

  • length (float, optional) – Length of the pipe (m). The default is 1.0.

  • roughness (float, optional) – Roughness of the internal pipe surface (mm). The default is 0.045.

  • k_internal_pipe (float, optional) – Thermal conductivity of the pipe (W/(m·K)). The default is 45.0.

  • internal_pipe_thickness (float, optional) – Thickness of the pipe (m). The default is 0.023.

  • k_casing (float, optional) – Thermal conductivity of the casing (W/(m·K)). The default is 0.4.

  • casing_thickness (float, optional) – Thickness of the casing (m). The default is 0.003.

  • discretization (float, optional) – Length of segments for discretizing the pipe (m). The default is 10.

  • line (str, optional) – Either “supply” or “return”. The default is None.

  • **kwargs (dict) – Additional keyword arguments.

Returns:

This method does not return any value.

Return type:

None

Examples

>>> from pydhn import Network
>>> net = Network()
>>> net.add_node(0, z=0)
>>> net.add_node(1, z=0)
>>> net.add_pipe('pipe_1', 0, 1, length=10)
>>> net[(0, 1)]["length"]
10
add_producer(name, start_node, end_node, static_pressure=nan, setpoint_type_hx='t_out', setpoint_type_hx_rev='delta_t', setpoint_value_hx=80.0, setpoint_value_hx_rev=0.0, power_max_hx=nan, t_out_min=nan, setpoint_type_hyd='pressure', setpoint_value_hyd=-1000000.0, **kwargs)[source]

Adds a single edge of type “base_producer” to the directed graph of the network. The base producer is an ideal leaf component with imposed pressure difference (for the main producer) or mass flow rate (for secondary producers).

For the thermal simulation, the base producer has 3 different possible setpoint types (setpoint_type_hx):

  • “t_out” imposes a specified outlet temperature (°C)

  • “delta_t” imposes a specified temperature difference (K) between

    the ending and starting node of the edge of the component

  • “delta_q” imposes a specified energy loss or gain (Wh)

Regardless of the setpoint type chosen, the setpoint value is given by setpoint_value_hx.

In case reverse flow is expected, the parameters setpoint_type_hx_rev and setpoint_value_hx_rev should also be specified to control the behaviour of the component in such cases.

Parameters:

  • name (Hashable) – The label for the edge.

  • start_node (Hashable) – Starting node of the edge.

  • end_node (Hashable) – Ending node of the edge.

  • static_pressure (float, optional) – The end node of the producer can be used as slack node to impose a pressure value in one node of the network. The pressure in all other nodes will be then computed from the pressure differences in edges resulting from the hydraulic simulation. The default is nan.

  • setpoint_type_hx (str, optional) – Type of setpoint for the thermal simulation in case of forward flow. Possible values are “t_out”, “delta_t” and “delta_q”. The default is t_out.

  • setpoint_type_hx_rev (str, optional) – Type of setpoint for the thermal simulation in case of reverse flow. Possible values are “t_out”, “delta_t” and “delta_q”. The default is delta_t.

  • setpoint_value_hx (float, optional) – Setpoint value of the chosen setpoint type for the thermal simulation in case of forward flow. The default is 80.0.

  • setpoint_value_hx_rev (float, optional) – Setpoint value of the chosen setpoint type for the thermal simulation in case of reverse flow. The default is 0.0.

  • power_max_hx (float, optional) – Maximum power of the heat exchanger, which currently correspond to the maximum energy that can be exchanged during one simulation step (Wh). If set, it limits the heat exchange enforced by the defined setpoints, which are not anymore guaranteed to be reached. The default is nan.

  • t_out_min (float, optional) – Minimum outlet temperature (°C). If set, it limits the outlet temperature resulting from the simulation with the defined setpoints, which are not anymore guaranteed to be reached. The default is nan.

  • setpoint_type_hyd (str, optional) – Hydraulic setpoint type, either “pressure” for imposing a pressure difference (Pa) or “mass_flow” to impose a certain mass flow rate (kg/s). Currently, one (main) producer needs to have a setpoint of type “pressure”, while all the others should have a “mass_flow” setpoint. Having multiple producers with a “pressure” setpoint also works, but the simulation might not converge in complex cases. The default is pressure.

  • setpoint_value_hyd (float, optional) – Setpoint value of the chosen setpoint type for the hydraulic simulation. The default is -1000000.0.

  • **kwargs (dict) – Additional keyword arguments.

Returns:

This method does not return any value.

Return type:

None

Examples

>>> from pydhn import Network
>>> net = Network()
>>> net.add_node(0, z=0)
>>> net.add_node(1, z=0)
>>> net.add_producer('cons_1', 0, 1, setpoint_type_hx='t_out')
>>> net[(0, 1)]["setpoint_type_hx"]
't_out'
property branch_components_mask: array

Returns an array with the indices of all the edges that are eiter in the supply or return line (branch components).

property branch_components_pointer: DiGraph

Returns a view of the network graph with only the branch components. The mask is based on the order of edges in the Networkx graph.

property consumers_cycle_matrix: array

Returns the edge-loop incidence matrix, or cycle matrix, of the network containing loops from the producer to each consumer.

property consumers_mask: array

Returns an array with the indices of all the base consumers.

property consumers_pointer: DiGraph

Returns a view of the network graph with only the consumers. The mask is based on the order of edges in the Networkx graph.

property cycle_matrix: array

Returns the cycle matrix of the network graph computed using a custom cycle basis. The matrix is computed from the undirected network graph and each entry is 1 if the jth edge is in the ith cycle and their directions match, -1 if their directions oppose, and 0 otherwise.

edges cin 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 import Network
>>> net = Network()
>>> net.add_node("Node 0")
>>> net.add_node("Node 1")
>>> net.add_node("Node 2")
>>> net.add_node("Node 3")
>>> net.add_producer("Prod 0-1", "Node 0", "Node 1")
>>> net.add_pipe("Pipe 1-2", "Node 1", "Node 2", line="supply")
>>> net.add_consumer("Cons 2-3", "Node 2", "Node 3")
>>> net.add_pipe("Pipe 3-0", "Node 3", "Node 0", line="return")
>>> net.cycle_matrix
array([[1., 1., 1., 1.]])
property ideal_components_mask: array

Returns an array with the indices of all the ideal components.

property imposed_mdot_matrix: array

Returns the edge-loop incidence matrix, or cycle matrix, of the network containing only loops from the edges with a mass flow setpoint to the main producer.

property imposed_pumps_mask: array

Returns an array with the indices of all the pumps with imposed rpm.

property imposed_valves_mask: array

Returns an array with the indices of all the valves with imposed kv.

property leaf_components_mask: array

Returns an array with the indices of all the edges that are between the supply and return line (leaf components).

property leaf_components_pointer: DiGraph

Returns a view of the network graph with only the leaf compoents. The mask is based on the order of edges in the Networkx graph.

property main_edge_mask: array

Returns an array with the index of the main edge.

mask(attr, value, condition='equality') → array[source]

Returns an array with the indices of all the edges for which attr is equal to value

property mass_flow_setpoints_mask: array

Returns an array with the indices of all the ideal components with a mass flow setpoint.

property mass_flow_setpoints_pointer: DiGraph

Returns a view of the network graph with only the ideal components with a mass flow setpoint. The mask is based on the order of edges in the Networkx graph.

property n_consumers: int

Returns the number of consumers in the network.

property n_pipes: int

Returns the number of pipes in the network.

property n_producers: int

Returns the number of producers in the network.

property pipes_mask: array

Returns an array with the indices of all the base pipes.

property pipes_pointer: DiGraph

Returns a view of the network graph with only the pipes. The mask is based on the order of edges in the Networkx graph.

property pressure_setpoints_mask: array

Returns an array with the indices of all the ideal components with a pressure setpoint.

property pressure_setpoints_pointer: DiGraph

Returns a view of the network graph with only the ideal components with a pressure setpoint. The mask is based on the order of edges in the Networkx graph.

property producers_mask: array

Returns an array with the indices of all the base producers.

property producers_pointer: DiGraph

Returns a view of the network graph with only the producers. The mask is based on the order of edges in the Networkx graph.

property pumps_mask: array

Returns an array with the indices of all the producers.

property real_components_mask: array

Returns an array with the indices of all the real components.

property return_line_mask: array

Returns an array with the indices of all the edges in the return line.

property return_line_pointer: DiGraph

eturns a view of the network graph with only the components in the return line. The mask is based on the order of edges in the Networkx graph. If the line attribute is missing from at least one branch component, the lines are recomputed and assigned automatically.

run_sanity_checks(verbose=1, check_isomorphism=True)[source]

Runs sanity checks on the Network against common mistakes.

Parameters:

verbose (Bool, optional) – Defines the level of verbosity. The default is 1.

Returns:

errors – Dictionary with the results of the sanity check. A True value means that an error was found during that test.

Return type:

Dict

property secondary_producers_mask: array

Returns an array with the indices of all the secondary producers.

property supply_line_mask: array

Returns an array with the indices of all the edges in the supply line.

property supply_line_pointer: DiGraph

Returns a view of the network graph with only the components in the supply line. The mask is based on the order of edges in the Networkx graph. If the line attribute is missing from at least one branch component, the lines are recomputed and assigned automatically.

to_citysim_xml(filename, climatefile_path, fluid=None, demand_dataframe=None, n_days=365)[source]

Convert and save the Network object to a CitySim XML file. The buildings in the file are modelled as single walls and won’t be simulated.

property valves_mask: array

Returns an array with the indices of all the consumers.