CustomPipe API Reference

geoloop.geoloopcore.CustomPipe.CustomPipe

Bases: _BasePipe

Pipe model with depth-dependent ambient temperatures.

Supports U-tubes and multi-U-tubes with N inlet pipes and M outlet pipes. Uses pygfunction (Cimmino & Cook, 2022) for thermal resistance networks.

Internal resistances are based on the multipole method of Claesson & Hellström (2011). Fluid properties are obtained via pygfunction.

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 [#Single-Hellstrom1991]. Internal borehole thermal resistances are evaluated using the multipole method of Claesson and Hellstrom [#Single-Claesson2011b].

The effective borehole thermal resistance is evaluated using the method of Cimmino [#Single-Cimmin2019]_. This is valid for any number of pipes.

References

.. [#Cimmino2022] Cimmino, M., & Cook, J.C. (2022). pygfunction 2.2: New features and improvements in accuracy and computational efficiency. In Research Conference Proceedings, IGSHPA Annual Conference 2022 (pp. 45-52). International Ground Source Heat Pump Association. DOI: https://doi.org/10.22488/okstate.22.00001 .. [#Single-Hellstrom1991] 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. .. [#Single-Claesson2011b] Claesson, J., & Hellstrom, G. (2011). Multipole method to calculate borehole thermal resistances in a borehole heat exchanger. HVAC&R Research, 17(6), 895-911. .. [#Single-Cimmin2019] 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.

init

__init__(
    pos,
    r_in,
    r_out,
    borehole,
    k_g,
    k_p,
    J=3,
    nInlets=1,
    m_flow=1.0,
    T_f=10,
    fluid_str="Water",
    percent=100,
    epsilon=1e-06,
    ncalcsegments=1,
    R_p=[],
)

Initialize a custom borehole pipe model and compute its thermal and hydraulic properties.

Parameters

pos : list of (float, float) Pipe coordinates inside the borehole. r_in : float or array_like Inner radius of the pipes (m). r_out : float or array_like Outer radius of the pipes (m). borehole : gt.boreholes.Borehole Borehole geometry object. k_g : float Grout thermal conductivity (W/m·K). k_p : float Pipe thermal conductivity (W/m·K). J : int, optional Number of multipoles per pipe. Default is 3. nInlets : int, optional Number of inlet pipes. Default is 1. m_flow : float, optional Mass flow rate (kg/s). Default is 1.0. T_f : float, optional Inlet fluid temperature (°C). Default is 10. fluid_str : str, optional Fluid type. Default is "Water". percent : float, optional Fluid mixture percentage. Default is 100. epsilon : float, optional Pipe roughness. Default is 1e-6. ncalcsegments : int, optional Number of segments for thermal resistance evaluation. R_p : list or array, optional Precomputed pipe thermal resistances.

Attributes:

Name	Type	Description
`R_p`	`list of float`	Pipe thermal resistances (m·K/W).
`h_f`	`ndarray`	Convective heat transfer coefficient per pipe.
`Rd`	`ndarray`	Δ-circuit thermal resistance per segment.
`R`	`ndarray`	Thermal resistance matrix.
`R1`	`ndarray`	Inverse thermal resistance matrix.
`m_flow_pipe`	`ndarray`	Mass flow per pipe.

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.

create_multi_u_tube

create_multi_u_tube()

Build a standard pygfunction U-tube / multi-U-tube object using depth-independent pipe properties.

Returns:

Type	Description
`SingleUTube or MultipleUTube`	pygfunction pipe object.

update_scaleflow

update_scaleflow(scaleflow: float = 1.0) -> None

Update the flow scaling factor and recalculate convective and thermal resistances.

Parameters:

Name	Type	Description	Default
`scaleflow`	`float`	Scaling multiplier applied to the mass flow rate. Default is 1.0.	`1.0`

Notes

Assumes that k_g and k_s are arrays of length ncalcsegments, allowing depth-dependent thermal properties.

init_thermal_resistances

init_thermal_resistances(
    k_g: ndarray, R_p: list[ndarray]
) -> None

Initialize depth-dependent thermal resistances using provided conductivity and pipe resistance arrays.

This routine is called from the B2G.runsimulation method, in order to generate thermal resistances based on actual segments determined by len(k_g) and len(R_p)

Parameters:

Name	Type	Description	Default
`k_g`	`array_like`	Grout thermal conductivity for each depth segment.	required
`R_p`	`list of array_like`	Pipe thermal resistance values for each segment.	required

update_thermal_resistances

update_thermal_resistances(
    initialize_stored_coeff: bool = False,
) -> None

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.

Its dimension corresponds to ncalcsegments (which is dictated by b2g.py (nx nodes) or b2g_ana (nsegments) and takes into account depth dependent effects of insulation

Parameters:

Name	Type	Description	Default
`initialize_stored_coeff`	`bool`	If True, also reinitialize stored coefficients. Default is False.	`False`

get_Rs

get_Rs(nyear: float, alpha: float = 1e-06) -> float

Approximate long-term borehole resistance Rs using an analytical estimate. Calculate Rs for simple approximation for Tb-T0 = Rs qc

Parameters:

Name	Type	Description	Default
`nyear`	`float`	Duration (years) used to compute the effective thermal resistance.	required
`alpha`	`float`	Soil thermal diffusivity (m²/s). Default is 1e-6.	`1e-06`

Returns:

Type	Description
`float`	Approximate long-term borehole resistance Rs (m·K/W).

get_temperature_depthvar

get_temperature_depthvar(
    T_f_in: float,
    signpower: float | ndarray,
    Rs: ndarray,
    soil_props,
    nsegments: int = 10,
) -> tuple

Compute fully depth-dependent inlet/outlet fluid temperatures, borehole wall temperatures, pipe temperatures, and heat extraction along the borehole.

Parameters:

Name	Type	Description	Default
`T_f_in`	`float`	Inlet fluid temperature (°C).	required
`signpower`	`float`	Sign of the thermal load direction (±1).	required
`Rs`	`array_like`	Long-term borehole resistance values for each segment, based on approximation for Tb-T0 = Rs qc.	required
`soil_props`	`SoilProperties`	Soil properties object.	required
`nsegments`	`int`	Number of depth segments. Default is 10.	`10`

Returns:

Type	Description
`tuple`	(T_f_out, power, Reff, pipe_temps, borehole_temps, segment_heat_flows)

get_temperature_depthvar_power

get_temperature_depthvar_power(
    power: float | ndarray,
    Rs: ndarray,
    soil_props,
    nsegments: int = 10,
) -> tuple

Compute inlet and outlet temperatures to satisfy a prescribed power extraction.

Parameters:

Name	Type	Description	Default
`power`	`float`	Target borehole heat extraction rate (W).	required
`Rs`	`array_like`	Long-term borehole resistance per segment, based on approximation for Tb-T0 = Rs qc.	required
`soil_props`	`SoilProperties`	Soil properties object.	required
`nsegments`	`int`	Number of depth segments. Default is 10.	`10`

Returns:

Type	Description
`tuple`	(T_f_out, T_f_in, Reff, pipe_temps, Tb, qbz)

visualize_pipes

visualize_pipes()

Plot a cross-sectional diagram of the borehole and pipe layout.

Returns:

Type	Description
`Figure`	Figure containing the visualization.