BoreholeDesign API Reference

geoloop.geoloopcore.boreholedesign.BoreholeDesign

COAXIAL `class-attribute` `instance-attribute`

COAXIAL: str = 'COAXIAL'

Configuration type for coaxial pipes.

UTUBE `class-attribute` `instance-attribute`

UTUBE: str = 'UTUBE'

Configuration type for U-tube pipes.

init

__init__(
    type: str,
    H: float,
    D: float,
    r_b: float,
    r_in: list[float],
    r_out: list[float],
    k_p: float | list[float],
    k_g: float | list[float],
    pos: list[list[float]] = [[0.0, 0.0], [0.0, 0.0]],
    J: int = 3,
    nInlets: int = 1,
    m_flow: float = 1.0,
    T_f: float = 10.0,
    fluid_str: str = "Water",
    fluid_percent: float = 100.0,
    epsilon: float = 1e-06,
    z_k_g: list[float] | None = None,
    ncalcsegments: int = 1,
    insu_z: float = 0.0,
    insu_dr: float = 0.0,
    insu_k: float = 0.03,
    N: int = 1,
    M: int = 1,
    R: float = 3.0,
    inclination_start: float = 0.0,
    inclination_end: float = 0.0,
    num_tiltedsegments: int = 1,
) -> None

Initialize a borehole design with geometry, pipe configuration, and material properties.

Parameters:

Name	Type	Description	Default
`type`	`(COAXIAL, UTUBE)`	Borehole configuration type.	`"COAXIAL"`
`H`	`float`	Borehole length (m).	required
`D`	`float`	Buried depth of borehole top (m).	required
`r_b`	`float`	Borehole radius (m).	required
`r_in`	`array_like`	Inner radii of pipe(s) (m).	required
`r_out`	`array_like`	Outer radii of pipe(s) (m).	required
`k_p`	`float or array_like`	Thermal conductivity of the pipe material (W/m·K).	required
`k_g`	`float or array_like`	Grout thermal conductivity. If array-like, depth-dependent values must be supplied along with `z_k_g`.	required
`pos`	`tuple of float`	Radial position of pipe(s) for UTUBE layouts. Ignored for COAXIAL.	`[[0.0, 0.0], [0.0, 0.0]]`
`J`	`int`	Number of segments used in `pygfunction` internal pipe discretization.	`3`
`nInlets`	`int`	Number of inlet pipes (UTUBE).	`1`
`m_flow`	`float`	Mass flow rate of circulating fluid (kg/s).	`1.0`
`T_f`	`float`	Initial fluid temperature (°C).	`10.0`
`fluid_str`	`(Water, MPG, MEG, MMA, MEA)`	Fluid type for hydraulic and thermal properties.	`"Water"`
`fluid_percent`	`float`	Percentage of the working fluid relative to water.	`100.0`
`epsilon`	`float`	Pipe roughness for hydraulic calculations (m).	`1e-06`
`z_k_g`	`array_like`	Depth breakpoints corresponding to grout thermal conductivities.	`None`
`ncalcsegments`	`int`	Number of vertical discretization segments for thermal calculations.	`1`
`insu_z`	`float`	Depth up to which outlet pipes are insulated (m).	`0.0`
`insu_dr`	`float`	Fraction of pipe wall thickness that is insulated.	`0.0`
`insu_k`	`float`	Insulation thermal conductivity (W/m·K).	`0.03`
`N`	`int`	Total nr of boreholes in borehole field for PYGFIELD models.	`1`
`M`	`int`	Boreholes per side of the borehole field for PYGFIELD models (only equally sided fields are supported).	`1`
`R`	`float`	Borefield radius or spacing parameter.	`3.0`
`inclination_start`	`float`	Start angle of borehole inclination (degrees).	`0.0`
`inclination_end`	`float`	End angle of borehole inclination (degrees).	`0.0`
`num_tiltedsegments`	`int`	Number of segments for inclined/tilted borehole discretization.	`1`

Notes

The thermal resistance of insulated pipes is computed in getR_p.
Depth-dependent grout conductivity is evaluated via StratInterpolator.
A CustomPipe or CoaxialPipe object is created automatically.

get_r_p

get_r_p(z: ndarray) -> list[np.ndarray]

Compute pipe thermal resistance at specific depths.

Insulation is applied only to outlet pipes (i.e., pipes with index >= nInlets) and only for depths shallower than insu_z.

Parameters:

Name	Type	Description	Default
`z`	`array_like of float`	Depth values (m) at which pipe resistances are evaluated.	required

Returns:

Type	Description
`list of ndarray`	List containing pipe resistances for each depth. Each entry contains an array of size `n_p`.

get_k_g

get_k_g(
    zstart: Sequence[float], zend: Sequence[float]
) -> np.ndarray

Interpolate grout conductivity for a list of vertical intervals.

Parameters:

Name	Type	Description	Default
`zstart`	`sequence of float`	Lower bounds of intervals.	required
`zend`	`sequence of float`	Upper bounds of intervals.	required

Returns:

Type	Description
`ndarray`	Grout conductivity per interval.

get_custom_pipe

get_custom_pipe() -> CustomPipe

Construct and return the appropriate pipe model instance (CoaxialPipe or CustomPipe).

Returns:

Type	Description
`CoaxialPipe \| CustomPipe`	Constructed pipe representation compatible with the rest of the code.

from_config `classmethod`

from_config(config: SingleRunConfig) -> BoreholeDesign

Create a BoreholeDesign instance from a configuration object.

The configuration object should contain keys consistent with the BoreholeDesign constructor arguments.

Parameters:

Name	Type	Description	Default
`config`	`SingleRunConfig`	Object containing borehole design parameters.	required

Returns:

Type	Description
`BoreholeDesign`	Configured instance.

visualize_pipes

visualize_pipes(filename: str | Path) -> None

Vsualize the borehole design, including pipe layout and create a figure.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Output path for the saved figure.	required

Returns:

Type	Description
`None`

fluid_friction_factor

fluid_friction_factor(
    ipipe: int,
    m_flow_pipe: float,
    mu_f: float,
    rho_f: float,
    epsilon: float,
    tol: float = 1e-06,
) -> tuple[float, float, float]

Evaluate the Darcy-Weisbach friction factor. It calculates the hydraulic diameter D, and the cross_section flow area, depending on the pipe configuration.

Parameters:

Name	Type	Description	Default
`m_flow_pipe`	`float`	Fluid mass flow rate (in kg/s) into the pipe.	required
`mu_f`	`float`	Fluid dynamic viscosity (in kg/m-s).	required
`rho_f`	`float`	Fluid density (in kg/m3).	required
`epsilon`	`float`	Pipe roughness (in meters).	required
`tol`	`float`	Relative convergence tolerance on Darcy friction factor. Default is 1.0e-6.	`1e-06`

Returns:

Name	Type	Description
`fDarcy`	`float`	Darcy friction factor.
`dpdl`	`float`	Pressure loss
`Re`	`float`	Reynolds number.

dploop_nosyphon

dploop_nosyphon(
    tempfluid: ndarray, flowrate: ndarray, effpump: float
) -> tuple[np.ndarray, np.ndarray]

Compute loop pressure drop (no syphon) and pumping power.

Parameters:

Name	Type	Description	Default
`tempfluid`	`ndarray`	Fluid temperature time series (°C).	required
`flowrate`	`ndarray`	Mass flow rate time series (kg/s).	required
`effpump`	`float`	Pump efficiency (0–1).	required

Returns:

Name	Type	Description
`dpsumtime`	`ndarray`	Pressure drop time series (bar).
`qpump`	`ndarray`	Power [W] required to drive the pumping

findflowrate_dploop

findflowrate_dploop(
    dplooptarget: float,
    tempfluid: ndarray,
    flowrate: float,
    effpump: float,
) -> float

Calculate flowrate matching with dplooptarget based on root finding algorithm (brentq is used with a scaling of the given flowrate, in range 0.01-10).

Parameters:

Name	Type	Description	Default
`dplooptarget`	`float`	Target pumping pressure (bar).	required
`tempfluid`	`ndarray`	Fluid temperatures (°C).	required
`flowrate`	`float`	Initial flow rate (kg/s) used as scale reference.	required
`effpump`	`float`	Pump efficiency.	required

Returns:

Type	Description
`float`	Mass flow rate (kg/s) that results in the desired pumping pressure.

root_func_dploop

root_func_dploop(
    mflowscale: float,
    dplooptarget: float,
    tempfluid: ndarray,
    flowrate: float,
    effpump: float,
) -> float

Objective function used by findflowrate_dploop for root finding function.

Parameters:

Name	Type	Description	Default
`mflowscale`	`float`	Scaling factor applied to nominal flow rate.	required
`dplooptarget`	`float`	Target pumping pressure (bar).	required
`tempfluid`	`ndarray`	Fluid temperatures (°C).	required
`flowrate`	`float`	Nominal mass flow rate (kg/s).	required
`effpump`	`float`	Pump efficiency.	required

Returns:

Type	Description
`float`	Difference between actual and target pumping pressure.

calculate_dploop

calculate_dploop(
    T_f: ndarray,
    z: ndarray,
    flowrate: ndarray,
    effpump: float,
) -> tuple[np.ndarray, np.ndarray]

Pumping pressure, pumping power and the Reynolds number are calculated for the in- and outlets in the loop. Assumption is that the flow and temperature are divided equally and symmetrically over the pipes. (i.e. the pipe diameters of respectively the inlet and outlet pipes is the same and the in- and oulet pipes alternate in the pipe design). Re_in, Re_uit are stored over time (Re_in represents the Reynolds number that is the same in all inlets, Re_out represents the Reynolds number that represents all outlets)

Parameters:

Name	Type	Description	Default
`T_f`	`ndarray`	Fluid temperature profile [ntime, nz, npipes] (°C).	required
`z`	`ndarray`	Along hole depth discretization (m).	required
`flowrate`	`ndarray`	Mass flow rate time series (kg/s).	required
`effpump`	`float`	Pump efficiency.	required

Returns:

Name	Type	Description
`dpsumtime`	`ndarray`	Pumping pressure (bar) for each time.
`qpump`	`ndarray`	Pumping power (W) for each time.

BoreholeDesign API Reference

geoloop.geoloopcore.boreholedesign.BoreholeDesign

COAXIAL class-attribute instance-attribute

UTUBE class-attribute instance-attribute

__init__

get_r_p

get_k_g

get_custom_pipe

from_config classmethod

visualize_pipes

fluid_friction_factor

dploop_nosyphon

findflowrate_dploop

root_func_dploop

calculate_dploop

COAXIAL `class-attribute` `instance-attribute`

UTUBE `class-attribute` `instance-attribute`

init

from_config `classmethod`