Networks Module¶

class pygfunction.networks.Network(boreholes, pipes, bore_connectivity=None, m_flow_network=None, cp_f=None, nSegments=None, segment_ratios=None)¶

Bases: object

Class for networks of boreholes with series, parallel, and mixed connections between the boreholes.

Contains information regarding the physical dimensions and thermal characteristics of the pipes and the grout material in each borehole, the topology of the connections between boreholes, as well as methods to evaluate fluid temperatures and heat extraction rates based on the work of Cimmino (2018, 2019, 2024) [1], [2], [3].

Attributes:

boreholeslist of Borehole objects: List of boreholes included in the bore field.
pipeslist of pipe objects: List of pipes included in the bore field.
bore_connectivitylist, optional: Index of fluid inlet into each borehole. -1 corresponds to a borehole connected to the bore field inlet. If this parameter is not provided, parallel connections between boreholes is used. Default is None.
m_flow_networkfloat or array, optional: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits. This parameter is used to initialize the coefficients if it is provided. Default is None.
cp_ffloat, optional: Fluid specific isobaric heat capacity (in J/kg.degC). This parameter is used to initialize the coefficients if it is provided. Default is None.
nSegmentsint, optional: Number of line segments used per borehole. This parameter is used to initialize the coefficients if it is provided. Default is None.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Notes

The expected array shapes of input parameters and outputs are documented for each class method. nInlets and nOutlets are the number of inlets and outlets to the network, and both correspond to the number of parallel circuits. nTotalSegments is the sum of the number of discretized segments along every borehole. nBoreholes is the total number of boreholes in the network.

References

coefficients_borehole_heat_extraction_rate(m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Build coefficient matrices to evaluate heat extraction rates of all boreholes segments.

Returns coefficients for the relation:

\[\mathbf{Q_b} = \mathbf{a_{in}} T_{f,network,in} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

a_in(nTotalSegments, 1,) array: Array of coefficients for inlet fluid temperature.
a_b(nTotalSegments, nTotalSegments,) array: Array of coefficients for borehole wall temperatures.

coefficients_fluid_heat_extraction_rate(m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Build coefficient matrices to evaluate heat extraction rates of all boreholes.

Returns coefficients for the relation:

\[\mathbf{Q_f} = \mathbf{a_{in}} T_{f,network,in} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

a_in(nBoreholes, 1,) array: Array of coefficients for inlet fluid temperature.
a_b(nBoreholes, nTotalSegments,) array: Array of coefficients for borehole wall temperatures.

coefficients_inlet_temperature(m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Build coefficient matrices to evaluate intlet fluid temperatures of all boreholes.

Returns coefficients for the relation:

\[\mathbf{T_{f,borehole,in}} = \mathbf{a_{in}} T_{f,network,in} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

a_in(nBoreholes, 1,) array: Array of coefficients for inlet fluid temperature.
a_b(nBoreholes, nTotalSegments,) array: Array of coefficients for borehole wall temperatures.

coefficients_network_heat_extraction_rate(m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Build coefficient matrices to evaluate total heat extraction rate of the network.

Returns coefficients for the relation:

\[\mathbf{Q_network} = \mathbf{a_{in}} T_{f,network,in} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

a_in(1, 1,) array: Array of coefficients for inlet fluid temperature.
a_b(1, nTotalSegments,) array: Array of coefficients for borehole wall temperatures.

coefficients_network_inlet_temperature(m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Build coefficient matrices to evaluate inlet fluid temperature of the network.

Returns coefficients for the relation:

\[\mathbf{T_{f,network,in}} = \mathbf{a_{q,f}} Q_{f} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

a_qf(1, 1,) array: Array of coefficients for total heat extraction rate.
a_b(1, nTotalSegments,) array: Array of coefficients for borehole wall temperatures.

coefficients_network_outlet_temperature(m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Build coefficient matrices to evaluate outlet fluid temperature of the network.

Returns coefficients for the relation:

\[\mathbf{T_{f,network,out}} = \mathbf{a_{in}} T_{f,network,in} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

a_in(1, 1,) array: Array of coefficients for inlet fluid temperature.
a_b(1, nTotalSegments,) array: Array of coefficients for borehole wall temperatures.

coefficients_outlet_temperature(m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Build coefficient matrices to evaluate outlet fluid temperatures of all boreholes.

Returns coefficients for the relation:

\[\mathbf{T_{f,borehole,out}} = \mathbf{a_{in}} T_{f,network,in} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

a_in(nBoreholes, 1,) array: Array of coefficients for inlet fluid temperature.
a_b(nBoreholes, nTotalSegments,) array: Array of coefficients for borehole wall temperatures.

Constructs the ‘Network’ class from static parameters.

Parameters:

boreholeslist of Borehole objects

List of boreholes included in the bore field.

pipe_type_strstr

Should be one of ‘COAXIAL_ANNULAR_IN’, ‘COAXIAL_ANNULAR_OUT’, ‘DOUBLE_UTUBE_PARALLEL’, ‘DOUBLE_UTUBE_SERIES’, or ‘SINGLE_UTUBE’.

poslist of tuples

Position (x, y) (in meters) of the pipes inside the borehole.

r_infloat

Inner radius (in meters) of the U-Tube pipes.

r_outfloat

Outer radius (in meters) of the U-Tube pipes.

k_sfloat

Soil thermal conductivity (in W/m-K).

k_gfloat

Grout thermal conductivity (in W/m-K).

k_pfloat, tuple, or (2,) array

Pipe thermal conductivity (in W/m-K).

m_flow_networkfloat

Fluid mass flow rate into the network of boreholes (in kg/s).

epsilonfloat

Pipe roughness (in meters).

fluid_str: str

The mixer for this application should be one of:

‘Water’ - Complete water solution

‘MEG’ - Ethylene glycol mixed with water

‘MPG’ - Propylene glycol mixed with water

‘MEA’ - Ethanol mixed with water

‘MMA’ - Methanol mixed with water

fluid_concentration_pct: float

Mass fraction of the mixing fluid added to water (in %). Lower bound = 0. Upper bound is dependent on the mixture.

fluid_temperature: float, optional

Temperature used for evaluating fluid properties (in degC). Default is 20.

reversible_flowbool, optional

True to treat a negative mass flow rate as the reversal of flow direction within the borehole. If False, the direction of flow is not reversed when the mass flow rate is negative, and the absolute value is used for calculations. Default is True.

bore_connectivitylist, optional

Index of fluid inlet into each borehole. -1 corresponds to a borehole connected to the bore field inlet. If this parameter is not provided, parallel connections between boreholes is used. Default is None.

Jint, optional

Number of multipoles per pipe to evaluate the thermal resistances. J=1 or J=2 usually gives sufficient accuracy. J=0 corresponds to the line source approximation. Default is 2.

Returns:

Network‘Network’ object.: The network.

get_borehole_heat_extraction_rate(T_f_in, T_b, m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Returns the heat extraction rates of all boreholes.

Parameters:

T_f_infloat or (1,) array: Inlet fluid temperatures into network (in Celsius).
T_bfloat or (nTotalSegments,) array: Borehole wall temperatures (in Celsius). If a float is supplied, the same temperature is applied to all segments of all boreholes.
m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

Q_b(nTotalSegments,) array: Heat extraction rates along each borehole segment (in Watts).

get_fluid_heat_extraction_rate(T_f_in, T_b, m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Returns the total heat extraction rates of all boreholes.

Parameters:

T_f_infloat or (1,) array: Inlet fluid temperatures into network (in Celsius).
T_bfloat or (nTotalSegments,) array: Borehole wall temperatures (in Celsius). If a float is supplied, the same temperature is applied to all segments of all boreholes.
m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

Q_f(nBoreholes,) array: Total heat extraction rates from each borehole (in Watts).

get_inlet_temperature(T_f_in, T_b, m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Returns the inlet fluid temperatures of all boreholes.

Parameters:

T_f_infloat or (1,) array: Inlet fluid temperatures into network (in Celsius).
T_bfloat or (nTotalSegments,) array: Borehole wall temperatures (in Celsius). If a float is supplied, the same temperature is applied to all segments of all boreholes.
m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

T_f_in(nBoreholes,) array: Inlet fluid temperature (in Celsius) into each borehole.

get_network_heat_extraction_rate(T_f_in, T_b, m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Returns the total heat extraction rate of the network.

Parameters:

T_f_infloat or (1,) array: Inlet fluid temperatures into network (in Celsius).
T_bfloat or (nTotalSegments,) array: Borehole wall temperatures (in Celsius). If a float is supplied, the same temperature is applied to all segments of all boreholes.
m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

Q_tfloat or (1,) array: Heat extraction rate of the network (in Watts). The returned type corresponds to the type of the parameter Tin.

get_network_inlet_temperature(Q_t, T_b, m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Returns the inlet fluid temperature of the network.

Parameters:

Q_tfloat or (1,) array: Total heat extraction rate from the network (in Watts).
T_bfloat or (nTotalSegments,) array: Borehole wall temperatures (in Celsius). If a float is supplied, the same temperature is applied to all segments of all boreholes.
m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

T_f_infloat or (1,) array: Inlet fluid temperature (in Celsius) into the network. The returned type corresponds to the type of the parameter Qt.

get_network_outlet_temperature(T_f_in, T_b, m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Returns the outlet fluid temperature of the network.

Parameters:

T_f_infloat or (1,) array: Inlet fluid temperatures into network (in Celsius).
T_bfloat or (nTotalSegments,) array: Borehole wall temperatures (in Celsius). If a float is supplied, the same temperature is applied to all segments of all boreholes.
m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

T_f_outfloat or (1,) array: Outlet fluid temperature (in Celsius) from the network. The returned type corresponds to the type of the parameter Tin.

get_outlet_temperature(T_f_in, T_b, m_flow_network, cp_f, nSegments, segment_ratios=None)¶

Returns the outlet fluid temperatures of all boreholes.

Parameters:

T_f_infloat or (1,) array: Inlet fluid temperatures into network (in Celsius).
T_bfloat or (nTotalSegments,) array: Borehole wall temperatures (in Celsius). If a float is supplied, the same temperature is applied to all segments of all boreholes.
m_flow_networkfloat or (nInlets,) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).
nSegmentsint or list: Number of borehole segments for each borehole. If an int is supplied, all boreholes are considered to have the same number of segments.
segment_ratios
(nSegments,) array or list of (nSegments[i],) arrays, optional: Ratio of the borehole length represented by each segment. The sum of ratios must be equal to 1. If segment_ratios==None, segments of equal lengths are considered. Default is None.

Returns:

T_f_out(nBoreholes,) array: Outlet fluid temperatures (in Celsius) from each borehole.

pygfunction.networks.network_thermal_resistance(network, m_flow_network, cp_f)¶

Evaluate the effective bore field thermal resistance.

As proposed in Cimmino (2018, 2019) [1], [2].

Parameters:

networknetwork object: Model of the network.
m_flow_networkfloat or (nInlets, ) array: Total mass flow rate into the network or inlet mass flow rates into each circuit of the network (in kg/s). If a float is supplied, the total mass flow rate is split equally into all circuits.
cp_ffloat: Fluid specific isobaric heat capacity (in J/kg.degC).

Returns:

R_fieldfloat: Effective bore field thermal resistance (m.K/W).

Networks Module¶

Table of Contents

Previous topic

Next topic

This Page