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 boreholes, 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) 1, 2.

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

1(1,2): Cimmino, M. (2018). g-Functions for bore fields with mixed parallel and series connections considering the axial fluid temperature variations. Proceedings of the IGSHPA Sweden Research Track 2018. Stockholm, Sweden. pp. 262-270.
2(1,2): Cimmino, M. (2019). Semi-analytical method for g-function calculation of bore fields with series- and parallel-connected boreholes. Science and Technology for the Built Environment, 25 (8), 1007-1022.

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.

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 intlet 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.

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).