Components

Components are objects representing different elements of the network stored as edges in the network graph. A differentiation is made in PyDHN between branch and edge components (see here) and between ideal and real components. These categorizations are used to speed up the hydraulic convergence, currently based on a modified loop method. The difference between ideal and real components is that the former enforce a setpoint, such as a certain mass flow rate, while the latter define a relationship between pressure losses and mass flow.

Component

The class Component provides a blueprint for all component classes and defines the main methods that are used during simulations. Each component has its own attributes, stored as a dictionary within the property _attrs. By default, in addition to all the attributes that are enforced as mandatory inputs, kwargs are also stored there:

>>> from pydhn.components import Component
>>> comp = Component(test_attr=5)
>>> print(comp._attrs['test_attr'])
5

Attributes however are not meant to be accessed by directly calling _attrs, but with the built-it __getitem__() method:

>>> from pydhn.components import Component
>>> comp = Component(test_attr=5)
>>> print(comp['test_attr'])
5

and can be changed via the set() method:

>>> from pydhn.components import Component
>>> comp = Component(test_attr=5)
>>> comp.set('test_attr', 10)
>>> print(comp['test_attr'])
10

In addition, the properties _type, with the unique name of the component type, _class (either "branch_component" or "leaf_component") and _is_ideal (either True or False) should be specified when creating a new component class:

>>> from pydhn.components import Component
>>> # Create custom class
>>> class MyComp(Component):
...     def __init__(self, **kwargs):
...         super(MyComp, self).__init__()
...         # Component class and type
...         self._class = "branch_component"
...         self._type = "my_custom_component"
...         self._is_ideal = True
...         # Add new inputs
...         self._attrs.update(kwargs)
...
>>> # Instantiate a MyComp object
>>> my_comp = MyComp()
>>> # Print component_type
>>> print(my_comp['component_type'])
my_custom_component
>>> # Print component_class
>>> print(my_comp['component_class'])
branch_component
>>> # Print is_ideal
>>> print(my_comp['is_ideal'])
True

More complex logic can also be implemented by modifying the method _run_control_logic(), which defines return rules for one or more attributes:

>>> from pydhn.components import Component
>>>
>>> # Create custom class
>>> class MyComp(Component):
...     def __init__(self, test_value, **kwargs):
...         super(MyComp, self).__init__()
...         # Component class and type
...         self._class = "branch_component"
...         self._type = "my_custom_component"
...         self._is_ideal = True
...         # Add new inputs
...         input_dict = {
...            "test_value": test_value
...         }
...         self._attrs.update(input_dict)
...         self._attrs.update(kwargs)
...
...     # Implement the _run_control_logic method
...     def _run_control_logic(self, key):
...         if key == "test_value":
...             return self._attrs["test_value"]**2
...         return None
...
>>> # Instantiate a MyComp object
>>> my_comp = MyComp(test_value=5)
>>> # Print test_value
>>> print(my_comp._run_control_logic('test_value'))
25
>>> # Check that the original value was not modified
>>> print(my_comp._attrs['test_value'])
5

Finally, for each component two private methods defining the functioning during simulations need to be implemented: _compute_delta_p() and _compute_temperatures().

Pipe

Component type	Component class	Is ideal
base_pipe	branch_component	False

Pipe is the base implementation for steady-state pipes. It has the following main attributes:

Input	Symbol	Documentation	Default	Unit
diameter	$D_p$	D_PIPES	0.0204	$m$
length	$L_p$	L_PIPES	1.0	$m$
roughness	$ϵ$	ROUGHNESS	0.045	$mm$
depth	$\delta$	DEPTH	1.0	$m$
k_insulation	$k_{ins}$	K_INSULATION	0.026	$W/(m·K)$
insulation_thickness	$t_{ins}$	INSULATION_THICKNESS	0.034	$m$
k_internal_pipe	$k_{ip}$	K_INTERNAL_PIPE	45.0	$W/(m·K)$
internal_pipe_thickness	$t_{ip}$	INTERNAL_PIPE_THICKNESS	0.023	$m$
k_casing	$k_{cas}$	K_CASING	0.4	$W/(m·K)$
casing_thickness	$t_{cas}$	CASING_THICKNESS	0.003	$m$
discretization	$-$	DISCRETIZATION	10	$m$

Hydraulics

The base Pipe implements the following formula to compute pressure losses:

$$\mathrm{\Delta }p=\frac{L_p{f}_D}{4{\pi }^2\rho {\left(\frac{D_p}{2}\right)}^5}|\dot{m}|\dot{m}$$

Plus eventually the hydrostatic pressure:

$$\rho g\mathrm{\Delta }z$$

The friction factor $f_D$ is computed as a function of the Reynolds number $Re$. For laminar flow ($Re\le 2300$) the friction factor is computed as:

$$f_D=\frac{64}{Re}$$

For turbulent flow ($Re\ge 4000$) Haaland equation is used:

$$f_D={\{1.8{\log }_{10}[{\left(\frac{ϵ}{3.7D_p}\right)}^{1.11}+\frac{6.9}{Re}]\}}^{-2}$$

Finally, for the transition regimen ($2320<Re<4000$), the relationship given in [HaZa21] is used.

Thermal

The base Pipe implements a simple steady-state model. The outlet temperature, limited by the soil temperature ${\theta }_s$, is computed as:

$${\theta }_{out}=max\{{\theta }_s,{\theta }_{in}-\frac{Q}{\dot{m}{c}_p}\}$$

The thermal losses $Q$ (Wh) are computed as:

$$Q=\frac{{\theta }_{in}-{\theta }_s}{R_{0,1}+R_{1,2}+R_{2,3}+R_{conv}+R_s}{L}_p-\frac{\dot{m}}{\rho }|\mathrm{\Delta }{p}_{fr}|$$

where $\mathrm{\Delta }{p}_{fr}$ is the frictional component of the pressure loss and $R_{ip}$, $R_{ins}$ and $R_{cas}$ are the thermal resistances of the internal pipe, insulation, casing respectively:

$$\begin{array}{rlrlr}{R}_{ip}=\frac{\ln \frac{r_1}{r_0}}{2\pi k_{ip}}& & R_{ins}=\frac{\ln \frac{r_2}{r_1}}{2\pi k_{ins}}& & R_{cas}=\frac{\ln \frac{r_3}{r_2}}{2\pi k_{cas}}\end{array}$$

And:

$$R_{conv}=\frac{1}{2\pi r_{0}h}$$

$$h=\frac{k_{f}Nu}{2r_0}$$

Finally, $R_s$ is the thermal resistance of the soil computed as:

$$\begin{array}{r}{R}_s=\{\begin{array}{ll}\frac{\ln (\frac{2\delta }{r_3})}{2\pi k_s},& \text{if }\delta >3r_0\\ \frac{\ln (x+\sqrt{x^2-1})}{2\pi k_s},& \text{otherwise}\end{array}\end{array}$$

$$x=\delta /r_3$$

For the thermal simulation, base Pipes can be discretized in segments of a given length for increasing the accuracy at the cost of computational speed.

Lagrangian Pipe

Component type	Component class	Is ideal
lagrangian_pipe	branch_component	False

LagrangianPipe is the implementation of a dynamic pipe based on the Lagrangian approach described in [DeAl19]. It has the following main attributes:

Input	Symbol	Documentation	Default	Unit
diameter	$D_p$	D_PIPES	0.0204	$m$
length	$L_p$	L_PIPES	1.0	$m$
roughness	$ϵ$	ROUGHNESS	0.045	$mm$
depth	$\delta$	DEPTH	1.0	$m$
k_insulation	$k_{ins}$	K_INSULATION	0.026	$W/(m·K)$
insulation_thickness	$t_{ins}$	INSULATION_THICKNESS	0.034	$m$
k_internal_pipe	$k_{ip}$	K_INTERNAL_PIPE	45.0	$W/(m·K)$
internal_pipe_thickness	$t_{ip}$	INTERNAL_PIPE_THICKNESS	0.023	$m$
k_casing	$k_{cas}$	K_CASING	0.4	$W/(m·K)$
casing_thickness	$t_{cas}$	CASING_THICKNESS	0.003	$m$
rho_wall	${\rho }_p$	RHO_INTERNAL_PIPE	940.0	$kg/m^3$
cp_wall	$c{p}_p$	CP_INTERNAL_PIPE	2000.0	$J/(kg·K)$
h_ext	$h_{ext}$	H_EXT	0.0	$W/(m^2·K)$
stepsize	$\mathrm{\Delta }s$	STEPSIZE	5.0	$s$

Each pipe is initialized with a single volume of fluid at a temperature of 50.0 °C. At each time-step, a new volume is inserted in the pipe, pushing all existing volumes.

Hydraulics

The Lagrangian Pipe implements the same hydraulics of the Pipe class described here

Thermal

The equations used for the thermal simulation in the LagrangianPipe class are described in detail in [DeAl19]. The outlet temperature is computed as the weighted average between the volumes exiting the pipe. If the mass flow is zero, the outlet temperature is the temperature at the outlet section of the pipe. Currently, the function used to compute the temperatures is not vectorized, so the simulation loop will call the method _compute_temperatures() for each element of this tipe separately using a for loop.

Note

The stepsize is defined for each pipe separately and there is no mechanism in place to check that all dynamic components share the same stepsize.

The component keeps an internal memory of the moving volumes of fluid and their temperatures:

>>> from pydhn.components import LagrangianPipe
>>> from pydhn import ConstantWater
>>> from pydhn import Soil
>>> comp = LagrangianPipe(length=100)
>>> fluid = ConstantWater()
>>> soil = Soil()
>>> # Print list of internal volumes
>>> print(comp._volumes)
[0.03268513]
>>> # Print list of internal temperatures
>>> print(comp._temperatures)
[50.]
>>> # Set a mass flow of 1 kg/s
>>> comp.set("mass_flow", 1.)
>>> # Simulate one time-step with inlet temperature of 45°C
>>> _ = comp._compute_temperatures(fluid=fluid, soil=soil, t_in=45)
>>> # Print list of internal volumes
>>> print(comp._volumes)
[0.00505051 0.02763462]
>>> # Print list of internal temperatures
>>> print(comp._temperatures)
[45.        49.9998273]

Producer

Component type	Component class	Is ideal
base_producer	leaf_component	True

Producer models a simple heat source where hydraulics and thermal setpoints are enforced. It has the following main attributes:

Input	Symbol	Documentation	Default	Unit
static_pressure	$p_s$	STATIC_PRESSURE	nan	$Pa$
setpoint_type_hx	$-$	SETPOINT_TYPE_HX_PROD	t_out	$-$
setpoint_value_hx	${\theta }_{out}$ or $\mathrm{\Delta }T$ or $Q$	SETPOINT_VALUE_HX_PROD	80.0	$°C$ or $K$ or $Wh$
setpoint_type_hx_rev	$-$	SETPOINT_TYPE_HX_PROD_REV	delta_t	$-$
setpoint_value_hx_rev	${\theta }_{out}$ or $\mathrm{\Delta }T$ or $Q$	SETPOINT_VALUE_HX_PROD_REV	0.0	$°C$ or $K$ or $Wh$
power_max_hx	$Q_{max}$	POWER_MAX_HX	nan	$Wh$
t_out_min_hx	${\theta }_{min}$	T_OUT_MIN	nan	$°C$
setpoint_type_hyd	$-$	SETPOINT_TYPE_HYD_PROD	pressure	$-$
setpoint_value_hyd	$\mathrm{\Delta }{p}_{set}$ or ${\dot{m}}_{set}$	SETPOINT_VALUE_HYD_PROD	-1000000.0	$Pa$ or $kg/s$

Commonly, one producer is used as the “main” component, enforcing a differential pressure to the network (using a 'pressure' setpoint), while the other producers, if present, have an imposed mass flow.

Hydraulics

The base producer has two modes of operations: either the mass flow $\dot{m}$ (kg/s) or pressure difference $\mathrm{\Delta }p$ (Pa) can be imposed. This is done by setting the relevant setpoint_type_hyd, respectively 'mass_flow' or 'pressure'.

Note

A negative pressure difference indicates a pressure lift along the positive direction of the edge.

>>> from pydhn.components import Producer
>>> from pydhn import ConstantWater
>>> comp = Producer(setpoint_type_hyd='pressure', setpoint_value_hyd=-50000)
>>> fluid = ConstantWater()
>>> delta_p, mdot = comp._compute_delta_p(fluid)
>>> print(delta_p)
-50000

Thermal

The base producer can enforce three different types of setpoints for the thermal simulation depending on the value given to setpoint_type_hx the outlet temperature 't_out', the injected energy 'delta_q' or the temperature difference 'delta_t'. The value of the chosen setpoint is then given by setpoint_value_hx. Regardless of the setpoint type, a limitation can be further imposed by limiting the outlet temperature - specifying a value for t_out_min_hx - or the maximum power - specifying a value for power_max_hx.

Warning

power_max_hx comes from an old version of PyDHN where time-steps were assumed to be hourly. What it is actually limiting is the energy and not the power of the heat source, according to the formula:

$${\theta }_{out}=min\{{\theta }_{set},\frac{Q_{max}}{\dot{m}{c}_p}+{\theta }_{in}\}$$

This behaviour will change in a future version.

Note

While the base producer allows different types of setpoints, it is advisable to use at least one 't_out', as in most cases the solver might not converge in the absence of a fixed nodal temperature in the network.

setpoint_type_hx_rev and setpoint_value_hx_rev are used to specify what should happen in case of reverse flow (IE: negative mass flow). The values and usage are the same as the setpoint_type_hx and setpoint_value_hx.

>>> from pydhn.components import Producer
>>> from pydhn import ConstantWater
>>> from pydhn import Soil
>>> comp = Producer(setpoint_type_hx='t_out', setpoint_value_hx=70,
...                 setpoint_type_hx_rev='delta_t', setpoint_value_hx_rev=0.)
>>> fluid = ConstantWater()
>>> soil = Soil()
>>> # Set a mass flow of 10 kg/s
>>> comp.set("mass_flow", 10)
>>> # Simulate one time-step with inlet temperature of 45°C
>>> t_out = comp._compute_temperatures(fluid=fluid, soil=soil, t_in=45)[1]
>>> # Print the outlet temperature
>>> print(t_out)
70.0
>>> # Set a mass flow of -1 kg/s
>>> comp.set("mass_flow", -1)
>>> # Simulate one time-step with inlet temperature of 45°C
>>> t_out = comp._compute_temperatures(fluid=fluid, soil=soil, t_in=45)[1]
>>> # Print the outlet temperature
>>> print(t_out)
45.0

Consumer

Component type	Component class	Is ideal
base_consumer	leaf_component	True

Consumer models a simple consumer where hydraulics and thermal setpoints are enforced. It has the following main attributes:

Input	Symbol	Documentation	Default	Unit
setpoint_type_hx	$-$	SETPOINT_TYPE_HX_PROD	t_out	$-$
setpoint_value_hx	${\theta }_{out}$ or $\mathrm{\Delta }T$ or $Q$	SETPOINT_VALUE_HX_PROD	80.0	$°C$ or $K$ or $Wh$
setpoint_type_hx_rev	$-$	SETPOINT_TYPE_HX_PROD_REV	delta_t	$-$
setpoint_value_hx_rev	${\theta }_{out}$ or $\mathrm{\Delta }T$ or $Q$	SETPOINT_VALUE_HX_PROD_REV	0.0	$°C$ or $K$ or $Wh$
power_max_hx	$Q_{max}$	POWER_MAX_HX	nan	$Wh$
t_out_min_hx	${\theta }_{min}$	T_OUT_MIN	nan	$°C$
setpoint_type_hyd	$-$	SETPOINT_TYPE_HYD_PROD	pressure	$-$
setpoint_value_hyd	$\mathrm{\Delta }{p}_{set}$ or ${\dot{m}}_{set}$	SETPOINT_VALUE_HYD_PROD	-1000000.0	$Pa$ or $kg/s$
control_type	$-$	CONTROL_TYPE_CONS	energy	$-$
design_delta_t	$\mathrm{\Delta }{T}_{des}$	DT_DESIGN	-30.0	$K$
heat_demand	$Q_{dem}$	HEAT_DEMAND	5000.0	$Wh$

Hydraulics

The base consumer has two possible control types that can be selected by setting the argument control_type as either 'mass_flow' or 'energy'. The former behaves exactly like the hydraulic implementation of Producer class described here.

Warning

Note that selecting 'mass_flow' as control_type also allows to use the differential pressure as setpoint. Furthermore, it requires to se the additional attribute setpoint_type_hyd, that can again be 'mass_flow'. This is indeed confusing and will be changed in a future version.

The control type 'energy' imposes again a mass flow setpoint, with the difference that the value is computed from the heat_demand and design_delta_t values as:

$${\dot{m}}_{set}=-\frac{Q_{dem}}{c_p\mathrm{\Delta }{T}_{des}}$$

Note

Note that the signs of $Q_{dem}$ and $\mathrm{\Delta }{T}_{des}$ have to generally be opposite: the demand is normally positive, as it is the energy requested, while the temperature difference is negative, as it represent the (expected) difference between the outlet and inlet temperature of the heat exchanger.

>>> from pydhn.components import Consumer
>>> from pydhn import ConstantWater
>>> comp = Consumer(control_type='energy', heat_demand=5000.,
...                 design_delta_t=-30.)
>>> # Check the hydraulic setpoint value
>>> comp['setpoint_value_hyd'] # it should be 5000/(30*4182) = 0.03985
0.03985333970986769

Thermal

The Consumer class implements the same method for _compute_temperatures() of the Producer class described here. Commonly, the consumers are given setpoint_type_hx as either delta_t or delta_q.

Note

Consumer has the additional argument heat_demand, but this is only used to compute the mass flow setpoint in case control_type is set to 'energy': it has no influence on the thermal simulation.

Branch Valve

Component type	Component class	Is ideal
base_branch_valve	branch_component	False

BranchValve implements a valve controlled by the flow coefficient $K_v$. The model assumes no temperature changes in the fluid across the valve. It has the following main attributes:

Input	Symbol	Documentation	Default	Unit
kv	$K_v$	KV	0.0	$m^3/h$

Hydraulics

The base valve implementation computes the pressure loss according to the following formula:

$$\mathrm{\Delta }p=\frac{1.296\cdot {10}^9}{\rho K_v^2}|\dot{m}|\dot{m}$$

Thermal

The base valve does not introduce any heat loss, and the outlet temperature is equal to the inlet temperature.

Branch Pump

Component type	Component class	Is ideal
branch_pump	branch_component	True

BranchPump implements a branch pump imposing a certain $\mathrm{\Delta }p$. The model assumes no temperature changes in the fluid across the pump. It has the following main attributes:

Input	Symbol	Documentation	Default	Unit
setpoint_value_hyd	$\mathrm{\Delta }p$	-	0.0	$Pa$

Hydraulics

The base pump imposes the $\mathrm{\Delta }p$ value specified by the attribute setpoint_type_hyd regardless of the mass flow.

Thermal

The branch pump does not introduce any heat loss, and the outlet temperature is equal to the inlet temperature.

Bypass Pipe

Component type	Component class	Is ideal
base_bypass_pipe	leaf_component	False

BypassPipe is the implementation of Pipe as a leaf component. It has the following main attributes:

Input	Symbol	Documentation	Default	Unit
diameter	$D_p$	D_BYPASS	0.0372	$m$
length	$L_p$	L_BYPASS_PIPES	1.0	$m$
roughness	$ϵ$	ROUGHNESS	0.045	$mm$
depth	$\delta$	DEPTH	1.0	$m$
k_insulation	$k_{ins}$	K_INSULATION	0.026	$W/(m·K)$
insulation_thickness	$t_{ins}$	BYPASS_INSULATION_THICKNESS	0.031	$m$
k_internal_pipe	$k_{ip}$	K_INTERNAL_PIPE	45.0	$W/(m·K)$
internal_pipe_thickness	$t_{ip}$	INTERNAL_BYPASS_THICKNESS	0.0052	$m$
k_casing	$k_{cas}$	K_CASING	0.4	$W/(m·K)$
casing_thickness	$t_{cas}$	BYPASS_CASING_THICKNESS	0.0054	$m$
discretization	$-$	DISCRETIZATION	10	$m$

Hydraulics

See here.

Thermal

See here.