Pipes Module

class pygfunction.pipes.Coaxial(pos, r_in, r_out, borehole, k_s, k_g, R_ff, R_fp, J=2)

Bases: SingleUTube

Class for coaxial boreholes.

Contains information regarding the physical dimensions and thermal characteristics of the pipes and the grout material, as well as methods to evaluate fluid temperatures and heat extraction rates based on the work of Hellstrom [1]. Internal borehole thermal resistances are evaluated using the multipole method of Claesson and Hellstrom [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 borehole, and both are equal to 1 for a coaxial borehole. nSegments is the number of discretized segments along the borehole. nPipes is the number of pipes (i.e. the number of U-tubes) in the borehole, equal to 1. nDepths is the number of depths at which temperatures are evaluated.

The effective borehole thermal resistance is evaluated using the method of Cimmino [3]. This is valid for any number of pipes.

References

[1]

Hellstrom, G. (1991). Ground heat storage. Thermal Analyses of Duct Storage Systems I: Theory. PhD Thesis. University of Lund, Department of Mathematical Physics. Lund, Sweden.

[2]

Claesson, J., & Hellstrom, G. (2011). Multipole method to calculate borehole thermal resistances in a borehole heat exchanger. HVAC&R Research, 17(6), 895-911.

[3]

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:

postuple

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

r_in(2,) array

Inner radii (in meters) of the coaxial pipes. The first element of the array corresponds to the inlet pipe.

r_out(2,) array

Outer radii (in meters) of the coaxial pipes. The first element of the array corresponds to the inlet pipe.

boreholeBorehole object

Borehole class object of the borehole containing the U-Tube.

k_sfloat

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

k_gfloat

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

R_fffloat

Fluid to fluid thermal resistance of the inner pipe to the outer pipe (in m-K/W).

R_fpfloat

Fluid to outer pipe wall thermal resistance of the outer pipe in contact with the grout (in m-K/W).

Jint, optional

Number of multipoles per pipe to evaluate the thermal resistances. Default is 2.

nPipesint

Number of U-Tubes, equals to 1.

nInletsint

Total number of pipe inlets, equals to 1.

nOutletsint

Total number of pipe outlets, equals to 1.

coefficients_borehole_heat_extraction_rate(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate heat extraction rates.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nSegments, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nSegments, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_fluid_heat_extraction_rate(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate heat extraction rates.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_inlet_temperature(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate inlet fluid temperature.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_outlet_temperature(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate outlet fluid temperature.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_temperature(z, m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate fluid temperatures at a depth (z).

Returns coefficients for the relation:

\[\mathbf{T_f}(z) = \mathbf{a_{in}} \mathbf{T_{f,in}} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

zfloat or (nDepths,) array

Depths (in meters) to evaluate the fluid temperature coefficients.

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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

(2*nPipes, nInlets,) array, or (nDepths, 2*nPipes, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b

(2*nPipes, nSegments,) array, or (nDepths, 2*nPipes, nSegments,) array

Array of coefficients for borehole wall temperatures.

effective_borehole_thermal_resistance(m_flow_borehole, cp_f)

Evaluate the effective borehole thermal resistance, defined by:

\[ \begin{align}\begin{aligned}\frac{Q_b}{H} = \frac{T^*_b - \bar{T}_f}{R^*_b}\\\bar{T}_f = \frac{1}{2}(T_{f,in} + T_{f,out})\end{aligned}\end{align} \]

where \(Q_b\) is the borehole heat extraction rate (in Watts), \(H\) is the borehole length, \(T^*_b\) is the effective borehole wall temperature, \(R^*_b\) is the effective borehole thermal resistance, \(T_{f,in}\) is the inlet fluid temperature, and \(T_{f,out}\) is the outlet fluid temperature.

Parameters:

m_flow_boreholefloat

Fluid mass flow rate (in kg/s) into the borehole.

cp_ffloat

Fluid specific isobaric heat capacity (in J/kg.K)

Returns:

R_bfloat

Effective borehole thermal resistance (in m.K/W).

get_borehole_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the heat extraction rates of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_bfloat or (nSegments,) array

Heat extraction rates along each borehole segment (in Watts). The returned type corresponds to the type of the parameter T_b.

get_fluid_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the heat extraction rates of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_ffloat or (nOutlets,) array

Heat extraction rates from each fluid circuit (in Watts). The returned type corresponds to the type of the parameter T_f_in.

get_inlet_temperature(Q_f, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the inlet fluid temperatures of the borehole.

Parameters:

Q_ffloat or (nInlets,) array

Heat extraction from the fluid circuits (in Watts).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_infloat or (nOutlets,) array

Inlet fluid temperatures (in Celsius) into each inlet pipe. The returned type corresponds to the type of the parameter Q_f.

get_outlet_temperature(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the outlet fluid temperatures of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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 (nOutlets,) array

Outlet fluid temperatures (in Celsius) from each outlet pipe. The returned type corresponds to the type of the parameter T_f_in.

get_temperature(z, T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the fluid temperatures of the borehole at a depth (z).

Parameters:

zfloat or (nDepths,) array

Depths (in meters) to evaluate the fluid temperatures.

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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(2*nPipes,) or (nDepths, 2*nPipes,) array

Fluid temperature (in Celsius) in each pipe. The returned shape depends on the type of the parameter z.

get_total_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the total heat extraction rate of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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

Total net heat extraction rate of the borehole (in Watts).

local_borehole_thermal_resistance()

Evaluate the local (cross-sectional) borehole thermal resistance, defined by:

\[Q'_b(z) = \frac{T_b(z) - \bar{T}_f(z)}{R_b}\]

where \(Q'_b(z)\) is the borehole heat extraction rate per unit depth at a depth \((z)\), \(T_b(z)\) is the borehole wall temperature, \(\bar{T}_f(z)\) is the arithmetic mean fluid temperature and \(R_b\) is the local borehole thermal resistance.

Returns:

R_bfloat

Local borehole thermal resistance (in m.K/W).

update_thermal_resistances(R_ff, R_fp)

Update the delta-circuit of thermal resistances.

This methods updates the values of the delta-circuit thermal resistances based on the provided fluid to fluid and fluid to outer pipe wall thermal resistances.

Parameters:

R_fffloat

Fluid to fluid thermal resistance of the inner pipe to the outer pipe (in m-K/W).

R_fpfloat

Fluid to outer pipe wall thermal resistance of the outer pipe in contact with the grout (in m-K/W).

visualize_pipes()

Plot the cross-section view of the borehole.

Returns:

figfigure

Figure object (matplotlib).

class pygfunction.pipes.IndependentMultipleUTube(pos, r_in, r_out, borehole, k_s, k_g, R_fp, nPipes, J=2)

Bases: MultipleUTube

Class for multiple U-Tube boreholes with independent U-tubes.

Contains information regarding the physical dimensions and thermal characteristics of the pipes and the grout material, as well as methods to evaluate fluid temperatures and heat extraction rates based on the work of Cimmino [4], [5] for boreholes with any number of U-tubes. Internal borehole thermal resistances are evaluated using the multipole method of Claesson and Hellstrom [6].

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 borehole, and both are equal to the number of pipes. nSegments is the number of discretized segments along the borehole. nPipes is the number of pipes (i.e. the number of U-tubes) in the borehole. nDepths is the number of depths at which temperatures are evaluated.

References

[4]

Cimmino, M. (2016). Fluid and borehole wall temperature profiles in vertical geothermal boreholes with multiple U-tubes. Renewable Energy, 96, 137-147.

[5]

Cimmino, M. (2024). g-Functions for fields of series- and parallel-connected boreholes with variable fluid mass flow rate and reversible flow direction. Renewable Energy, 228, 120661.

[6]

Claesson, J., & Hellstrom, G. (2011). Multipole method to calculate borehole thermal resistances in a borehole heat exchanger. HVAC&R Research, 17(6), 895-911.

Attributes:

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.

boreholeBorehole object

Borehole class object of the borehole containing the U-Tube.

k_sfloat

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

k_gfloat

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

R_fpfloat

Fluid to outer pipe wall thermal resistance (m-K/W).

Jint, optional

Number of multipoles per pipe to evaluate the thermal resistances. Default is 2.

nPipesint

Number of U-Tubes.

nInletsint

Total number of pipe inlets, equals to nPipes.

nOutletsint

Total number of pipe outlets, equals to nPipes.

coefficients_borehole_heat_extraction_rate(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate heat extraction rates.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nSegments, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nSegments, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_fluid_heat_extraction_rate(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate heat extraction rates.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_inlet_temperature(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate inlet fluid temperature.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_outlet_temperature(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate outlet fluid temperature.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_temperature(z, m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate fluid temperatures at a depth (z).

Returns coefficients for the relation:

\[\mathbf{T_f}(z) = \mathbf{a_{in}} \mathbf{T_{f,in}} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

zfloat or (nDepths,) array

Depths (in meters) to evaluate the fluid temperature coefficients.

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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

(2*nPipes, nInlets,) array, or (nDepths, 2*nPipes, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b

(2*nPipes, nSegments,) array, or (nDepths, 2*nPipes, nSegments,) array

Array of coefficients for borehole wall temperatures.

effective_borehole_thermal_resistance(m_flow_borehole, cp_f)

Evaluate the effective borehole thermal resistance, defined by:

\[ \begin{align}\begin{aligned}\frac{Q_b}{H} = \frac{T^*_b - \bar{T}_f}{R^*_b}\\\bar{T}_f = \frac{1}{2}(T_{f,in} + T_{f,out})\end{aligned}\end{align} \]

where \(Q_b\) is the borehole heat extraction rate (in Watts), \(H\) is the borehole length, \(T^*_b\) is the effective borehole wall temperature, \(R^*_b\) is the effective borehole thermal resistance, \(T_{f,in}\) is the inlet fluid temperature, and \(T_{f,out}\) is the outlet fluid temperature.

Parameters:

m_flow_boreholefloat

Fluid mass flow rate (in kg/s) into the borehole.

cp_ffloat

Fluid specific isobaric heat capacity (in J/kg.K)

Returns:

R_bfloat

Effective borehole thermal resistance (in m.K/W).

get_borehole_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the heat extraction rates of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_bfloat or (nSegments,) array

Heat extraction rates along each borehole segment (in Watts). The returned type corresponds to the type of the parameter T_b.

get_fluid_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the heat extraction rates of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_ffloat or (nOutlets,) array

Heat extraction rates from each fluid circuit (in Watts). The returned type corresponds to the type of the parameter T_f_in.

get_inlet_temperature(Q_f, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the inlet fluid temperatures of the borehole.

Parameters:

Q_ffloat or (nInlets,) array

Heat extraction from the fluid circuits (in Watts).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_infloat or (nOutlets,) array

Inlet fluid temperatures (in Celsius) into each inlet pipe. The returned type corresponds to the type of the parameter Q_f.

get_outlet_temperature(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the outlet fluid temperatures of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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 (nOutlets,) array

Outlet fluid temperatures (in Celsius) from each outlet pipe. The returned type corresponds to the type of the parameter T_f_in.

get_temperature(z, T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the fluid temperatures of the borehole at a depth (z).

Parameters:

zfloat or (nDepths,) array

Depths (in meters) to evaluate the fluid temperatures.

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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(2*nPipes,) or (nDepths, 2*nPipes,) array

Fluid temperature (in Celsius) in each pipe. The returned shape depends on the type of the parameter z.

get_total_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the total heat extraction rate of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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

Total net heat extraction rate of the borehole (in Watts).

local_borehole_thermal_resistance()

Evaluate the local (cross-sectional) borehole thermal resistance, defined by:

\[Q'_b(z) = \frac{T_b(z) - \bar{T}_f(z)}{R_b}\]

where \(Q'_b(z)\) is the borehole heat extraction rate per unit depth at a depth \((z)\), \(T_b(z)\) is the borehole wall temperature, \(\bar{T}_f(z)\) is the arithmetic mean fluid temperature and \(R_b\) is the local borehole thermal resistance.

Returns:

R_bfloat

Local borehole thermal resistance (in m.K/W).

update_thermal_resistances(R_fp)

Update the delta-circuit of thermal resistances.

This methods updates the values of the delta-circuit thermal resistances based on the provided fluid to outer pipe wall thermal resistance.

Parameters:

R_fpfloat

Fluid to outer pipe wall thermal resistance (m-K/W).

visualize_pipes()

Plot the cross-section view of the borehole.

Returns:

figfigure

Figure object (matplotlib).

class pygfunction.pipes.MultipleUTube(pos, r_in, r_out, borehole, k_s, k_g, R_fp, nPipes, config='parallel', J=2)

Bases: _BasePipe

Class for multiple U-Tube boreholes.

Contains information regarding the physical dimensions and thermal characteristics of the pipes and the grout material, as well as methods to evaluate fluid temperatures and heat extraction rates based on the work of Cimmino [7], [8] for boreholes with any number of U-tubes. Internal borehole thermal resistances are evaluated using the multipole method of Claesson and Hellstrom [9].

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 borehole, and both are equal to 1 for a multiple U-tube borehole. nSegments is the number of discretized segments along the borehole. nPipes is the number of pipes (i.e. the number of U-tubes) in the borehole. nDepths is the number of depths at which temperatures are evaluated.

The effective borehole thermal resistance is evaluated using the method of Cimmino [10]. This is valid for any number of pipes.

References

[7]

Cimmino, M. (2016). Fluid and borehole wall temperature profiles in vertical geothermal boreholes with multiple U-tubes. Renewable Energy, 96, 137-147.

[8]

Cimmino, M. (2024). g-Functions for fields of series- and parallel-connected boreholes with variable fluid mass flow rate and reversible flow direction. Renewable Energy, 228, 120661.

[9]

Claesson, J., & Hellstrom, G. (2011). Multipole method to calculate borehole thermal resistances in a borehole heat exchanger. HVAC&R Research, 17(6), 895-911.

[10]

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:

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.

boreholeBorehole object

Borehole class object of the borehole containing the U-Tube.

k_sfloat

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

k_gfloat

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

R_fpfloat

Fluid to outer pipe wall thermal resistance (m-K/W).

Jint, optional

Number of multipoles per pipe to evaluate the thermal resistances. Default is 2.

nPipesint

Number of U-Tubes.

configstr, defaults to ‘parallel’

Configuration of the U-Tube pipes:

‘parallel’ : U-tubes are connected in parallel. ‘series’ : U-tubes are connected in series.

nInletsint

Total number of pipe inlets, equals to 1.

nOutletsint

Total number of pipe outlets, equals to 1.

coefficients_borehole_heat_extraction_rate(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate heat extraction rates.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nSegments, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nSegments, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_fluid_heat_extraction_rate(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate heat extraction rates.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_inlet_temperature(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate inlet fluid temperature.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_outlet_temperature(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate outlet fluid temperature.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_temperature(z, m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate fluid temperatures at a depth (z).

Returns coefficients for the relation:

\[\mathbf{T_f}(z) = \mathbf{a_{in}} \mathbf{T_{f,in}} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

zfloat or (nDepths,) array

Depths (in meters) to evaluate the fluid temperature coefficients.

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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

(2*nPipes, nInlets,) array, or (nDepths, 2*nPipes, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b

(2*nPipes, nSegments,) array, or (nDepths, 2*nPipes, nSegments,) array

Array of coefficients for borehole wall temperatures.

effective_borehole_thermal_resistance(m_flow_borehole, cp_f)

Evaluate the effective borehole thermal resistance, defined by:

\[ \begin{align}\begin{aligned}\frac{Q_b}{H} = \frac{T^*_b - \bar{T}_f}{R^*_b}\\\bar{T}_f = \frac{1}{2}(T_{f,in} + T_{f,out})\end{aligned}\end{align} \]

where \(Q_b\) is the borehole heat extraction rate (in Watts), \(H\) is the borehole length, \(T^*_b\) is the effective borehole wall temperature, \(R^*_b\) is the effective borehole thermal resistance, \(T_{f,in}\) is the inlet fluid temperature, and \(T_{f,out}\) is the outlet fluid temperature.

Parameters:

m_flow_boreholefloat

Fluid mass flow rate (in kg/s) into the borehole.

cp_ffloat

Fluid specific isobaric heat capacity (in J/kg.K)

Returns:

R_bfloat

Effective borehole thermal resistance (in m.K/W).

get_borehole_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the heat extraction rates of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_bfloat or (nSegments,) array

Heat extraction rates along each borehole segment (in Watts). The returned type corresponds to the type of the parameter T_b.

get_fluid_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the heat extraction rates of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_ffloat or (nOutlets,) array

Heat extraction rates from each fluid circuit (in Watts). The returned type corresponds to the type of the parameter T_f_in.

get_inlet_temperature(Q_f, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the inlet fluid temperatures of the borehole.

Parameters:

Q_ffloat or (nInlets,) array

Heat extraction from the fluid circuits (in Watts).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_infloat or (nOutlets,) array

Inlet fluid temperatures (in Celsius) into each inlet pipe. The returned type corresponds to the type of the parameter Q_f.

get_outlet_temperature(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the outlet fluid temperatures of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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 (nOutlets,) array

Outlet fluid temperatures (in Celsius) from each outlet pipe. The returned type corresponds to the type of the parameter T_f_in.

get_temperature(z, T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the fluid temperatures of the borehole at a depth (z).

Parameters:

zfloat or (nDepths,) array

Depths (in meters) to evaluate the fluid temperatures.

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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(2*nPipes,) or (nDepths, 2*nPipes,) array

Fluid temperature (in Celsius) in each pipe. The returned shape depends on the type of the parameter z.

get_total_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the total heat extraction rate of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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

Total net heat extraction rate of the borehole (in Watts).

local_borehole_thermal_resistance()

Evaluate the local (cross-sectional) borehole thermal resistance, defined by:

\[Q'_b(z) = \frac{T_b(z) - \bar{T}_f(z)}{R_b}\]

where \(Q'_b(z)\) is the borehole heat extraction rate per unit depth at a depth \((z)\), \(T_b(z)\) is the borehole wall temperature, \(\bar{T}_f(z)\) is the arithmetic mean fluid temperature and \(R_b\) is the local borehole thermal resistance.

Returns:

R_bfloat

Local borehole thermal resistance (in m.K/W).

update_thermal_resistances(R_fp)

Update the delta-circuit of thermal resistances.

This methods updates the values of the delta-circuit thermal resistances based on the provided fluid to outer pipe wall thermal resistance.

Parameters:

R_fpfloat

Fluid to outer pipe wall thermal resistance (m-K/W).

visualize_pipes()

Plot the cross-section view of the borehole.

Returns:

figfigure

Figure object (matplotlib).

class pygfunction.pipes.SingleUTube(pos, r_in, r_out, borehole, k_s, k_g, R_fp, J=2)

Bases: _BasePipe

Class for single U-Tube boreholes.

Contains information regarding the physical dimensions and thermal characteristics of the pipes and the grout material, as well as methods to evaluate fluid temperatures and heat extraction rates based on the work of Hellstrom [11]. Internal borehole thermal resistances are evaluated using the multipole method of Claesson and Hellstrom [12].

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 borehole, and both are equal to 1 for a single U-tube borehole. nSegments is the number of discretized segments along the borehole. nPipes is the number of pipes (i.e. the number of U-tubes) in the borehole, equal to 1. nDepths is the number of depths at which temperatures are evaluated.

The effective borehole thermal resistance is evaluated using the method of Cimmino [13]. This is valid for any number of pipes.

References

[11]

Hellstrom, G. (1991). Ground heat storage. Thermal Analyses of Duct Storage Systems I: Theory. PhD Thesis. University of Lund, Department of Mathematical Physics. Lund, Sweden.

[12]

Claesson, J., & Hellstrom, G. (2011). Multipole method to calculate borehole thermal resistances in a borehole heat exchanger. HVAC&R Research, 17(6), 895-911.

[13]

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:

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.

boreholeBorehole object

Borehole class object of the borehole containing the U-Tube.

k_sfloat

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

k_gfloat

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

R_fpfloat

Fluid to outer pipe wall thermal resistance (m-K/W).

Jint, optional

Number of multipoles per pipe to evaluate the thermal resistances. Default is 2.

nPipesint

Number of U-Tubes, equals to 1.

nInletsint

Total number of pipe inlets, equals to 1.

nOutletsint

Total number of pipe outlets, equals to 1.

coefficients_borehole_heat_extraction_rate(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate heat extraction rates.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nSegments, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nSegments, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_fluid_heat_extraction_rate(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate heat extraction rates.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_inlet_temperature(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate inlet fluid temperature.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_outlet_temperature(m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate outlet fluid temperature.

Returns coefficients for the relation:

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

Parameters:

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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(nOutlets, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b(nOutlets, nSegments,) array

Array of coefficients for borehole wall temperatures.

coefficients_temperature(z, m_flow_borehole, cp_f, nSegments, segment_ratios=None)

Build coefficient matrices to evaluate fluid temperatures at a depth (z).

Returns coefficients for the relation:

\[\mathbf{T_f}(z) = \mathbf{a_{in}} \mathbf{T_{f,in}} + \mathbf{a_{b}} \mathbf{T_b}\]

Parameters:

zfloat or (nDepths,) array

Depths (in meters) to evaluate the fluid temperature coefficients.

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rate (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

nSegmentsint

Number of borehole segments.

segment_ratios(nSegments,) array, 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

(2*nPipes, nInlets,) array, or (nDepths, 2*nPipes, nInlets,) array

Array of coefficients for inlet fluid temperature.

a_b

(2*nPipes, nSegments,) array, or (nDepths, 2*nPipes, nSegments,) array

Array of coefficients for borehole wall temperatures.

effective_borehole_thermal_resistance(m_flow_borehole, cp_f)

Evaluate the effective borehole thermal resistance, defined by:

\[ \begin{align}\begin{aligned}\frac{Q_b}{H} = \frac{T^*_b - \bar{T}_f}{R^*_b}\\\bar{T}_f = \frac{1}{2}(T_{f,in} + T_{f,out})\end{aligned}\end{align} \]

where \(Q_b\) is the borehole heat extraction rate (in Watts), \(H\) is the borehole length, \(T^*_b\) is the effective borehole wall temperature, \(R^*_b\) is the effective borehole thermal resistance, \(T_{f,in}\) is the inlet fluid temperature, and \(T_{f,out}\) is the outlet fluid temperature.

Parameters:

m_flow_boreholefloat

Fluid mass flow rate (in kg/s) into the borehole.

cp_ffloat

Fluid specific isobaric heat capacity (in J/kg.K)

Returns:

R_bfloat

Effective borehole thermal resistance (in m.K/W).

get_borehole_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the heat extraction rates of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_bfloat or (nSegments,) array

Heat extraction rates along each borehole segment (in Watts). The returned type corresponds to the type of the parameter T_b.

get_fluid_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the heat extraction rates of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_ffloat or (nOutlets,) array

Heat extraction rates from each fluid circuit (in Watts). The returned type corresponds to the type of the parameter T_f_in.

get_inlet_temperature(Q_f, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the inlet fluid temperatures of the borehole.

Parameters:

Q_ffloat or (nInlets,) array

Heat extraction from the fluid circuits (in Watts).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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_infloat or (nOutlets,) array

Inlet fluid temperatures (in Celsius) into each inlet pipe. The returned type corresponds to the type of the parameter Q_f.

get_outlet_temperature(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the outlet fluid temperatures of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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 (nOutlets,) array

Outlet fluid temperatures (in Celsius) from each outlet pipe. The returned type corresponds to the type of the parameter T_f_in.

get_temperature(z, T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the fluid temperatures of the borehole at a depth (z).

Parameters:

zfloat or (nDepths,) array

Depths (in meters) to evaluate the fluid temperatures.

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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(2*nPipes,) or (nDepths, 2*nPipes,) array

Fluid temperature (in Celsius) in each pipe. The returned shape depends on the type of the parameter z.

get_total_heat_extraction_rate(T_f_in, T_b, m_flow_borehole, cp_f, segment_ratios=None)

Returns the total heat extraction rate of the borehole.

Parameters:

T_f_infloat or (nInlets,) array

Inlet fluid temperatures (in Celsius).

T_bfloat or (nSegments,) array

Borehole wall temperatures (in Celsius).

m_flow_boreholefloat or (nInlets,) array

Inlet mass flow rates (in kg/s) into the borehole.

cp_ffloat or (nInlets,) array

Fluid specific isobaric heat capacity (in J/kg.degC).

segment_ratios(nSegments,) array, 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

Total net heat extraction rate of the borehole (in Watts).

local_borehole_thermal_resistance()

Evaluate the local (cross-sectional) borehole thermal resistance, defined by:

\[Q'_b(z) = \frac{T_b(z) - \bar{T}_f(z)}{R_b}\]

where \(Q'_b(z)\) is the borehole heat extraction rate per unit depth at a depth \((z)\), \(T_b(z)\) is the borehole wall temperature, \(\bar{T}_f(z)\) is the arithmetic mean fluid temperature and \(R_b\) is the local borehole thermal resistance.

Returns:

R_bfloat

Local borehole thermal resistance (in m.K/W).

update_thermal_resistances(R_fp)

Update the delta-circuit of thermal resistances.

This methods updates the values of the delta-circuit thermal resistances based on the provided fluid to outer pipe wall thermal resistance.

Parameters:

R_fpfloat

Fluid to outer pipe wall thermal resistance (m-K/W).

visualize_pipes()

Plot the cross-section view of the borehole.

Returns:

figfigure

Figure object (matplotlib).

pygfunction.pipes.borehole_thermal_resistance(pipe, m_flow_borehole, cp_f)

Evaluate the effective borehole thermal resistance, defined by:

\[ \begin{align}\begin{aligned}\frac{Q_b}{H} = \frac{T^*_b - \bar{T}_f}{R^*_b}\\\bar{T}_f = \frac{1}{2}(T_{f,in} + T_{f,out})\end{aligned}\end{align} \]

where \(Q_b\) is the borehole heat extraction rate (in Watts), \(H\) is the borehole length, \(T^*_b\) is the effective borehole wall temperature, \(R^*_b\) is the effective borehole thermal resistance, \(T_{f,in}\) is the inlet fluid temperature, and \(T_{f,out}\) is the outlet fluid temperature.

Parameters:

pipepipe object

Model for pipes inside the borehole.

m_flow_boreholefloat

Fluid mass flow rate (in kg/s) into the borehole.

cp_ffloat

Fluid specific isobaric heat capacity (in J/kg.K)

Returns:

R_bfloat

Effective borehole thermal resistance (m.K/W).

Notes

The effective borehole thermal resistance is evaluated using the method of Cimmino [14]. This is valid for any number of pipes.

References

[14]

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.

pygfunction.pipes.conduction_thermal_resistance_circular_pipe(r_in, r_out, k_p)

Evaluate the conduction thermal resistance for circular pipes.

Parameters:

r_infloat

Inner radius of the pipes (in meters).

r_outfloat

Outer radius of the pipes (in meters).

k_pfloat

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

Returns:

R_pfloat

Conduction thermal resistance (in m-K/W).

pygfunction.pipes.convective_heat_transfer_coefficient_circular_pipe(m_flow_pipe, r_in, mu_f, rho_f, k_f, cp_f, epsilon)

Evaluate the convective heat transfer coefficient for circular pipes.

The Nusselt number must first be determined to find the convection coefficient. Determination of the Nusselt number in turbulent flow is done by calling _Nusselt_number_turbulent_flow(). An analytical solution for constant pipe wall surface temperature is used for laminar flow.

Since _Nusselt_number_turbulent_flow() is only valid for Re > 3000. and to avoid dicontinuities in the values of the convective heat transfer coefficient near the onset of the turbulence region (approximately Re = 2300.), linear interpolation is used over the range 2300 < Re < 4000 for the evaluation of the Nusselt number.

This approach was verified by Gnielinski (2013) [15].

Parameters:

m_flow_pipefloat

Fluid mass flow rate (in kg/s) into the pipe.

r_infloat

Inner radius of the pipe (in meters).

mu_ffloat

Fluid dynamic viscosity (in kg/m-s).

rho_ffloat

Fluid density (in kg/m3).

k_ffloat

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

cp_ffloat

Fluid specific heat capacity (in J/kg-K).

epsilonfloat

Pipe roughness (in meters).

Returns:

h_fluidfloat

Convective heat transfer coefficient (in W/m2-K).

References

[15] (1,2)

Gnielinski, V. (2013). On heat transfer in tubes. International Journal of Heat and Mass Transfer, 63, 134–140. https://doi.org/10.1016/j.ijheatmasstransfer.2013.04.015

pygfunction.pipes.convective_heat_transfer_coefficient_concentric_annulus(m_flow_pipe, r_a_in, r_a_out, mu_f, rho_f, k_f, cp_f, epsilon)

Evaluate the inner and outer convective heat transfer coefficient for the annulus region of a concentric pipe.

Grundmann (2016) referenced Hellström (1991) [19] in the discussion about inner and outer convection coefficients in an annulus region of a concentric pipe arrangement.

The following is valid for \(Re < 2300\) and \(0.1 \leq Pr \leq 1000\) :

\[\text{Nu}_{a,in} = 3.66 + 1.2(r^*)^{-0.8}\]

\[\text{Nu}_{a,out} = 3.66 + 1.2(r^*)^{0.5}\]

where \(r^* = r_{a,in} / r_{a,out}\) is the ratio of the inner over the outer annulus radius (Çengel and Ghajar 2015, pg. 476).

Cengel and Ghajar (2015) [17] state that inner and outer Nusselt numbers are approximately equivalent for turbulent flow. They additionally state that Gnielinski _Nusselt_number_turbulent_flow() can be used for turbulent flow. Linear interpolation is used over the range 2300 < Re < 4000 for the evaluation of the Nusselt number, as proposed by Gnielinski (2013) [15].

Parameters:

m_flow_pipe: float

Fluid mass flow rate (in kg/s) into the pipe.

r_a_in: float

Pipe annulus inner radius (in meters).

r_a_out: float

Pipe annulus outer radius (in meters).

mu_ffloat

Fluid dynamic viscosity (in kg/m-s).

rho_ffloat

Fluid density (in kg/m3).

k_ffloat

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

cp_ffloat

Fluid specific heat capacity (in J/kg-K).

epsilonfloat

Pipe roughness (in meters).

Returns:

h_fluid_a_in: float

Convective heat transfer coefficient of the inner pipe annulus region (in W/m2-K).

h_fluid_a_out: float

Convective heat transfer coefficient of the outer pipe annulus region (in W/m2-K).

References

[16]

Grundmann, R. (2016) Improved design methods for ground heat exchangers. Oklahoma State University, M.S. Thesis.

[17]

Çengel, Y.A., & Ghajar, A.J. (2015). Heat and mass transfer: fundamentals & applications (Fifth edition.). McGraw-Hill.

pygfunction.pipes.fluid_friction_factor_circular_pipe(m_flow_pipe, r_in, mu_f, rho_f, epsilon, tol=1e-06)

Evaluate the Darcy-Weisbach friction factor.

Parameters:

m_flow_pipefloat

Fluid mass flow rate (in kg/s) into the pipe.

r_infloat

Inner radius of the pipes (in meters).

mu_ffloat

Fluid dynamic viscosity (in kg/m-s).

rho_ffloat

Fluid density (in kg/m3).

epsilonfloat

Pipe roughness (in meters).

tolfloat

Relative convergence tolerance on Darcy friction factor. Default is 1.0e-6.

Returns:

fDarcyfloat

Darcy friction factor.

pygfunction.pipes.multipole(pos, r_out, r_b, k_s, k_g, R_fp, T_b, q_p, J, x_T=array([], dtype=float64), y_T=array([], dtype=float64), eps=1e-05, it_max=100)

Multipole method to calculate borehole thermal resistances in a borehole heat exchanger.

Adapted from the work of Claesson and Hellstrom [18].

Parameters:

poslist

List of positions (x,y) (in meters) of pipes around the center of the borehole.

r_outfloat or array

Outer radius of the pipes (in meters).

r_bfloat

Borehole radius (in meters).

k_sfloat

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

k_gfloat

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

R_fpfloat or array

Fluid-to-outer-pipe-wall thermal resistance (in m-K/W).

Jint

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.

q_parray

Thermal energy flows (in W/m) from pipes.

T_bfloat

Average borehole wall temperature (in degC).

epsfloat, optional

Iteration relative accuracy. Default is 1e-5.

it_maxint, optional

Maximum number of iterations. Default is 100.

x_Tarray, optional

x-coordinates (in meters) to calculate temperatures. Default is np.empty(0).

y_Tarray, optional

y-coordinates (in meters) to calculate temperatures. Default is np.empty(0).

Returns:

T_farray

Fluid temperatures (in degC) in the pipes.

Tarray

Requested temperatures (in degC).

itint

Total number of iterations

eps_maxfloat

Maximum error.

References

[18]

Claesson, J., & Hellstrom, G. (2011). Multipole method to calculate borehole thermal resistances in a borehole heat exchanger. HVAC&R Research, 17(6), 895-911.

pygfunction.pipes.thermal_resistances(pos, r_out, r_b, k_s, k_g, R_fp, J=2)

Evaluate thermal resistances and delta-circuit thermal resistances.

This function evaluates the thermal resistances and delta-circuit thermal resistances between pipes in a borehole using the multipole method [20]. Thermal resistances are defined by:

\[\mathbf{T_f} - T_b = \mathbf{R} \cdot \mathbf{Q_{p}}\]

Delta-circuit thermal resistances are defined by:

\[ \begin{align}\begin{aligned}q_{p,i,j} = \frac{T_{f,i} - T_{f,j}}{R^\Delta_{i,j}}\\q_{p,i,i} = \frac{T_{f,i} - T_b}{R^\Delta_{i,i}}\end{aligned}\end{align} \]

Parameters:

poslist

List of positions (x,y) (in meters) of pipes around the center of the borehole.

r_outfloat or array

Outer radius of the pipes (in meters).

r_bfloat

Borehole radius (in meters).

k_sfloat

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

k_gfloat

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

R_fpfloat or array

Fluid-to-outer-pipe-wall thermal resistance (in m-K/W).

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 [19]. Default is 2.

Returns:

Rarray

Thermal resistances (in m-K/W).

Rdarray

Delta-circuit thermal resistances (in m-K/W).

References

[19] (1,2)

Hellstrom, G. (1991). Ground heat storage. Thermal Analyses of Duct Storage Systems I: Theory. PhD Thesis. University of Lund, Department of Mathematical Physics. Lund, Sweden.

[20]

Claesson, J., & Hellstrom, G. (2011). Multipole method to calculate borehole thermal resistances in a borehole heat exchanger. HVAC&R Research, 17(6), 895-911.

Examples

>>> pos = [(-0.06, 0.), (0.06, 0.)]
>>> R, Rd = gt.pipes.thermal_resistances(pos, 0.01, 0.075, 2., 1., 0.1,
                                         J=0)
R = [[ 0.36648149, -0.04855895],
     [-0.04855895,  0.36648149]]
Rd = [[ 0.31792254, -2.71733044],
      [-2.71733044,  0.31792254]]