carm.properties package

Submodules

carm.properties.borehole module

Borehole heat exchanger types module.

Defines the geometry, mesh, thermal properties, and fluid dynamics for all supported BHE configurations: single U-tube, double U-tube, coaxial, and helical pipes. The class hierarchy is:

BoreholeProperties ├── Utube │ ├── SingleUtube │ └── DoubleUtube ├── Coaxial └── Helical

class carm.properties.borehole.BoreholeGeometry

Bases: object

Geometric parameters of the borehole. D_irrigation and perf_fraction parameters must be set as None if

grout variable properties are not taken into account.

Note: the irrigation system is feasible only with shallow helical heat exchangers.

Lbore

Active borehole length [m].

Type:

float

D0

Borehole diameter [m].

Type:

float

D_irrigation

Irrigation pipe diameter [m].

Type:

None | float = None

perf_fraction

Irrigation pipe perforation fraction [-].

Type:

None | float = None

Lbore: float

D0: float

D_irrigation: None | float

perf_fraction: None | float

property r0: float

class carm.properties.borehole.BoreholeMesh

Bases: object

Axial discretization of the borehole.

m_mesh

Number of axial mesh elements along the borehole.

Type:

int

m_mesh: int

class carm.properties.borehole.BoreholeThermalProperties

Bases: object

Thermal properties of the borehole filling material (grout). The user must define whether he wants to define equivalent properties or grout stratification.

cp_0

Specific heat capacity [J / (kg K)].

Type:

float | None

rho_0

Density [kg/m³].

Type:

float | None

k0

Thermal conductivity [W / (m K)].

Type:

float | None

stratification

Grout layering as a sequence of (k, cp, rho, thickness) tuples. The sum of layer thicknesses must equal the borehole discretized length. Stratification is set as None by default.

Type:

Sequence[tuple[float, float, float, float]] | None

soil_type

Soil type string. This is set as None by default. If accounting for time variable properties, it must be set as ‘sand’, ‘loam’, or ‘clay’ and the correct properties must be given as input.

Type:

str

cp_0: float | None = None

rho_0: float | None = None

k0: float | None = None

stratification: Sequence[tuple[float, float, float, float]] | None = None

soil_type: str | None = None

class carm.properties.borehole.BoreholeProperties

Bases: object

Base class for all BHE configurations.

Assembles geometry, mesh, thermal properties, and fluid into a single object. Computes derived quantities (dz, mesh-shaped property arrays) shared by all BHE types.

geom

Borehole geometric parameters.

Type:

BoreholeGeometry

mesh

Axial discretization settings.

Type:

BoreholeMesh

thermalprops

Thermal properties of the grout.

Type:

BoreholeThermalProperties

fluid

Thermophysical properties of the heat carrier fluid.

Type:

Fluid

Lbore

Active borehole length [m].

Type:

float

D0

Borehole diameter [m].

Type:

float

m_mesh

Number of axial mesh elements.

Type:

int

dz

Axial mesh element size [m].

Type:

float

cp_0

Specific heat capacity array, shape (m_mesh, 1) [J / (kg K)].

Type:

NDArray

rho_0

Density array, shape (m_mesh, 1) [kg/m³].

Type:

NDArray

k0

Thermal conductivity array, shape (m_mesh, 1) [W / (m K)].

Type:

NDArray

class carm.properties.borehole.Utube

Bases: BoreholeProperties

Base class for U-tube BHE configurations (single and double).

Extends BoreholeProperties with pipe geometry, grout cross-sectional areas (shell and core), thermal capacitances, and axial resistances.

pipe_thick

Pipe wall thickness [m].

Type:

float

pipe_spacing

Centre-to-centre spacing between pipes [m].

Type:

float

Dpi

Inner pipe diameter [m].

Type:

float

n_pipes

Number of pipes (2 for single U-tube, 4 for double U-tube).

Type:

int

S_shell

Cross-sectional area of the grout shell region [m²].

Type:

float

S_core

Cross-sectional area of the grout core region [m²].

Type:

float

C_shell

Thermal capacitance of the shell, shape (m_mesh, 1) [J/K].

Type:

NDArray

C_core

Thermal capacitance of the core, shape (m_mesh, 1) [J/K].

Type:

NDArray

C_fluid

Thermal capacitance of the fluid per pipe element [J/K].

Type:

float

R_axial_shell

Axial thermal resistance of the shell, shape (m_mesh, 1) [K/W].

Type:

NDArray

R_axial_core

Axial thermal resistance of the core, shape (m_mesh, 1) [K/W].

Type:

NDArray

class carm.properties.borehole.SingleUtube

Bases: Utube

Single U-tube BHE configuration (2 pipes).

Extends Utube with pipe-to-grout and grout-to-ground resistances specific to the single U-tube layout.

Rp0

Pipe-to-grout thermal resistance [K m / W].

Type:

float

RppB

Grout-to-ground thermal resistance [K m / W].

Type:

float

n_equations

Number of nodal equations in the discretized system (6).

Type:

int

Rp0_dz

Rp0 normalized by dz [K/W].

Type:

float

RppB_dz

RppB normalized by dz [K/W].

Type:

float

crossing_time_calculation(mw_tot)

Compute the fluid transit time through the U-tube.

Parameters:

mw_tot (NDArray) – Total mass flow rate [kg/s].

Returns:

Time for the fluid to travel the full U-tube length (2 × Lbore) [s].

Return type:

NDArray

Examples

>>> mw_tot = np.full(n_steps, 2)
>>> t = bhe.crossing_time_calculation(mw_tot=mw_tot)

class carm.properties.borehole.DoubleUtube

Bases: Utube

Double U-tube BHE configuration (4 pipes).

Extends Utube with an additional pipe-to-pipe resistance and support for series (S) or parallel (P) pipe connection.

connection

Pipe connection mode: 'S' for series, 'P' for parallel.

Type:

str

Rp0

Pipe-to-grout thermal resistance [K m / W].

Type:

float

RppB

Grout-to-ground thermal resistance [K m / W].

Type:

float

RppA

Pipe-to-pipe thermal resistance [K m / W].

Type:

float

n_equations

Number of nodal equations in the discretized system (10).

Type:

int

Rp0_dz

Rp0 normalized by dz [K/W].

Type:

float

RppB_dz

RppB normalized by dz [K/W].

Type:

float

RppA_dz

RppA normalized by dz [K/W].

Type:

float

crossing_time_calculation(mw_tot)

Compute the fluid transit time through the double U-tube.

Accounts for series (full flow in each pipe) vs. parallel (half flow in each pipe) connection.

Parameters:

mw_tot (NDArray) – Total mass flow rate [kg/s].

Returns:

Fluid transit time [s].

Return type:

NDArray

class carm.properties.borehole.Coaxial

Bases: BoreholeProperties

Coaxial pipe BHE configuration.

Two concentric pipes: inner pipe (1) and annular outer pipe (2). Flow direction is set by supply_and_return.

Dp1i

Inner diameter of pipe 1 (inner pipe) [m].

Type:

float

Dp2i

Inner diameter of pipe 2 (outer annulus) [m].

Type:

float

pipe1_thick

Wall thickness of pipe 1 [m].

Type:

float

pipe2_thick

Wall thickness of pipe 2 [m].

Type:

float

k_pipe1

Thermal conductivity of the pipe 1 material [W / (m K)].

Type:

float

k_pipe2

Thermal conductivity of the pipe 2 material [W / (m K)].

Type:

float

supply_and_return

Flow direction: '1_2' (supply in pipe 1) or '2_1' (supply in pipe 2).

Type:

str

n_equations

Number of nodal equations in the discretized system (5).

Type:

int

De

Hydraulic diameter of the annular region [m].

Type:

float

S_shell

Cross-sectional area of the grout annulus [m²].

Type:

float

R_cond1

Conductive resistance of pipe 1 wall [K/W].

Type:

float

R_cond2

Conductive resistance of pipe 2 wall [K/W].

Type:

float

R_shell

Conductive resistance of the grout annulus [K/W].

Type:

float

R_pipes1

Conductive resistance of stationary fluid in pipe 1, used when mw=0 [K/W].

Type:

float

R_pipes2

Conductive resistance of stationary fluid in the annulus, used when mw=0 [K/W].

Type:

float

R_axial_shell

Axial conductive resistance of the grout shell [K/W].

Type:

float

C_shell

Thermal capacitance of the grout shell [J/K].

Type:

float

C_fluid1

Thermal capacitance of the fluid in pipe 1 [J/K].

Type:

float

C_fluid2

Thermal capacitance of the fluid in the annulus [J/K].

Type:

float

crossing_time_calculation(mw_tot)

Compute fluid transit times for both flow paths in the coaxial BHE.

Parameters:

mw_tot (NDArray) – Total mass flow rate [kg/s].

Returns:

crossing_time – Transit time through pipes [s].

Return type:

NDArray

class carm.properties.borehole.Helical

Bases: BoreholeProperties

Helical pipe BHE configuration.

A helical coil wound inside the borehole. The geometry is parameterized by the helix radius, pipe diameter, and number of turns.

Dpi1

Inner pipe 1 diameter (straight tube) [m].

Type:

float

Dpi2

Inner pipe 2 diameter (helical tube) [m].

Type:

float

rih

Inner helix radius (centre of pipe to borehole axis) [m].

Type:

float

pipe_thick

Pipe wall thickness [m].

Type:

float

N

Number of helix turns.

Type:

int

P

Helix pitch [m].

Type:

float

supply_and_return

Flow direction: '1_2' (supply in pipe 1) or '2_1' (supply in pipe 2).

Type:

str

Lp2tot

Total length helical pipe [m].

Type:

float

k_pipe

Thermal conductivity of the pipe material [W / (m K)].

Type:

float

n_equations

Number of nodal equations in the discretized system (6).

Type:

int

F

Turn density (turns per metre) [1/m].

Type:

float

S_shell

Cross-sectional area of the outer grout annulus [m²].

Type:

float

S_core

Cross-sectional area of the inner grout core [m²].

Type:

float

C_shell

Thermal capacitance of the shell, shape (m_mesh, 1) [J/K].

Type:

NDArray

C_shell_middle

Thermal capacitance of the node between pipe 2 and shell, shape (m_mesh, 1) [J/K]

Type:

NDArray

C_core

Thermal capacitance of the core, shape (m_mesh, 1) [J/K].

Type:

NDArray

C_fluid1

Thermal capacitance of the supply fluid [J/K].

Type:

float

C_fluid2

Thermal capacitance of the return fluid [J/K].

Type:

float

crossing_time_calculation(mw_tot)

Compute the fluid transit time through the helical pipe.

Parameters:

mw_tot (NDArray) – Total mass flow rate [kg/s].

Returns:

Fluid transit time [s].

Return type:

NDArray

carm.properties.ground module

Ground properties module.

Defines the geometry, mesh, and thermophysical properties of the ground domain surrounding the borehole. Supports heterogeneous stratification via a layer-by-layer property averaging scheme.

class carm.properties.ground.GroundGeometry

Bases: object

Geometric parameters of the ground domain.

D0

Borehole diameter [m].

Type:

float

L

Active borehole length (middle ground region) [m].

Type:

float

L_sup

Length of the upper ground region [m].

Type:

float

L_inf

Length of the lower ground region [m].

Type:

float

rn

Outer radius of the radial discretization [m]. Required for single-borehole mode; None in multi-borehole mode (where r_eq from the Voronoi decomposition is used instead).

Type:

float or None

r0

Borehole radius, derived as D0 / 2 [m].

Type:

float

D0: float

L: float

L_sup: float

L_inf: float

rn: float | None

property r0: float

class carm.properties.ground.GroundMesh

Bases: object

Discretization parameters for the ground domain.

n_mesh

Number of radial mesh elements.

Type:

int

m_mesh

Number of axial mesh elements in the middle (active) region.

Type:

int

m_mesh_sup

Number of axial mesh elements in the upper region.

Type:

int

m_mesh_inf

Number of axial mesh elements in the lower region.

Type:

int

f

Radial expansion factor for the mesh (default 1.2). Controls how rapidly cell thickness increases moving outward from the borehole.

Type:

float

n_mesh: int

m_mesh: int

m_mesh_sup: int

m_mesh_inf: int

f: float

class carm.properties.ground.GroundProperties

Bases: object

Thermophysical and discretization properties of the ground domain.

Computes layer-averaged thermal properties from the stratigraphic input, then derives all radial/axial resistances and capacitances used in the global system matrix.

geom

Geometric parameters of the ground domain.

Type:

GroundGeometry

mesh

Discretization settings.

Type:

GroundMesh

Tg

Undisturbed ground temperature [°C].

Type:

float

stratification

Ground layering as a sequence of (k, cp, rho, thickness) tuples. The sum of layer thicknesses must equal the total discretized length.

Type:

Sequence[tuple[float, float, float, float]]

k

Layer-averaged thermal conductivity, shape (n_cells, 1) [W / (m K)].

Type:

NDArray

cp

Layer-averaged specific heat capacity, shape (n_cells, 1) [J / (kg K)].

Type:

NDArray

rho

Layer-averaged density, shape (n_cells, 1) [kg/m³].

Type:

NDArray

k_mean

Mean thermal conductivity over the active (middle) region [W / (m K)].

Type:

float

cp_mean

Mean specific heat capacity over the active region [J / (kg K)].

Type:

float

rho_mean

Mean density over the active region [kg/m³].

Type:

float

radius

Radial cell boundary positions, shape (1, n_mesh + 1) [m].

Type:

NDArray

rm

Barycentric radii for resistance calculations, shape (1, n_mesh + 2) [m].

Type:

NDArray

C_ground

Radial thermal capacitances, shape (m_mesh, n_mesh) [J/K].

Type:

NDArray

R_ground

Radial thermal resistances, shape (m_mesh, n_mesh + 1) [K/W].

Type:

NDArray

R_axial

Axial thermal resistances in the middle region, shape (m_mesh, n_mesh) [K/W].

Type:

NDArray

R_sup

Axial thermal resistances in the upper region, shape (m_mesh_sup,) [K/W].

Type:

NDArray

C_sup

Axial thermal capacitances in the upper region, shape (m_mesh_sup,) [J/K].

Type:

NDArray

R_inf

Axial thermal resistances in the lower region, shape (m_mesh_inf,) [K/W].

Type:

NDArray

C_inf

Axial thermal capacitances in the lower region, shape (m_mesh_inf,) [J/K].

Type:

NDArray

carm.properties.soil_moisture module

Soil mositure module.

Empirical equations are here implemented to account for water content in porous means. This module provides insights on borehole proprieties variability against water content.

class carm.properties.soil_moisture.SoilMoisture

Bases: object

Soil moisture and thermophysical properties module.

Computes borehole thermophysical properties (thermal conductivity, specific heat capacity, density) as a function of volumetric water content, using Chung-Horton (1987) for thermal conductivity, de Vries (1963) for volumetric heat capacity, and a mass-weighted average for density.

loss_factor

Fraction of water volume lost by drainage at each timestep [-].

Type:

float

w_rho

Density of water [kg/m³].

Type:

float

w_latent

Latent heat of vaporization of water [J/kg].

Type:

float

SOIL_PARAMS

Tabulated parameters for sand, loam, and clay soil types. Each entry contains: b1, b2, b3 (Chung-Horton), theta_s, theta_r (Rawls et al.), xs (solid volume fraction), x0 (organic matter fraction).

Type:

dict

water_input

Water flux time series [m/s].

Type:

NDArray

rho_dry

Dry soil density [kg/m³].

Type:

float

b1_loc

Chung-Horton parameter b1 for the selected soil type [W/(m K)].

Type:

float

b2_loc

Chung-Horton parameter b2 for the selected soil type [W/(m K)].

Type:

float

b3_loc

Chung-Horton parameter b3 for the selected soil type [W/(m K)].

Type:

float

theta_s_loc

Saturated volumetric water content for the selected soil type [-].

Type:

float

theta_r_loc

Residual volumetric water content for the selected soil type [-].

Type:

float

xs_loc

Solid volume fraction for the selected soil type [-].

Type:

float

x0_loc

Organic matter volume fraction for the selected soil type [-].

Type:

float

Wvol_prev

Water volume at the previous timestep [m³].

Type:

float

Wvol_r

Residual water volume at the current timestep [m³].

Type:

float

Wvol_loss

Water volume lost by drainage at the current timestep [m³].

Type:

float

Wvol_evap

Water volume lost by evaporation at the current timestep [m³].

Type:

float

W_content

Volumetric water content at the current timestep [-].

Type:

float

loss_factor = 0.1

w_rho = 1000.0

w_latent = 2250000.0

SOIL_PARAMS = {'clay': {'b1': -0.197, 'b2': -0.962, 'b3': 2.521, 'theta_r': 0.09, 'theta_s': 0.385, 'x0': 0.024, 'xs': 0.591}, 'loam': {'b1': 0.243, 'b2': 0.393, 'b3': 1.534, 'theta_r': 0.027, 'theta_s': 0.434, 'x0': 0.018, 'xs': 0.548}, 'sand': {'b1': 0.228, 'b2': -2.406, 'b3': 4.909, 'theta_r': 0.02, 'theta_s': 0.417, 'x0': 0.012, 'xs': 0.571}}

Module contents

class carm.properties.SoilMoisture

Bases: object

Soil moisture and thermophysical properties module.

Computes borehole thermophysical properties (thermal conductivity, specific heat capacity, density) as a function of volumetric water content, using Chung-Horton (1987) for thermal conductivity, de Vries (1963) for volumetric heat capacity, and a mass-weighted average for density.

loss_factor

Fraction of water volume lost by drainage at each timestep [-].

Type:

float

w_rho

Density of water [kg/m³].

Type:

float

w_latent

Latent heat of vaporization of water [J/kg].

Type:

float

SOIL_PARAMS

Tabulated parameters for sand, loam, and clay soil types. Each entry contains: b1, b2, b3 (Chung-Horton), theta_s, theta_r (Rawls et al.), xs (solid volume fraction), x0 (organic matter fraction).

Type:

dict

water_input

Water flux time series [m/s].

Type:

NDArray

rho_dry

Dry soil density [kg/m³].

Type:

float

b1_loc

Chung-Horton parameter b1 for the selected soil type [W/(m K)].

Type:

float

b2_loc

Chung-Horton parameter b2 for the selected soil type [W/(m K)].

Type:

float

b3_loc

Chung-Horton parameter b3 for the selected soil type [W/(m K)].

Type:

float

theta_s_loc

Saturated volumetric water content for the selected soil type [-].

Type:

float

theta_r_loc

Residual volumetric water content for the selected soil type [-].

Type:

float

xs_loc

Solid volume fraction for the selected soil type [-].

Type:

float

x0_loc

Organic matter volume fraction for the selected soil type [-].

Type:

float

Wvol_prev

Water volume at the previous timestep [m³].

Type:

float

Wvol_r

Residual water volume at the current timestep [m³].

Type:

float

Wvol_loss

Water volume lost by drainage at the current timestep [m³].

Type:

float

Wvol_evap

Water volume lost by evaporation at the current timestep [m³].

Type:

float

W_content

Volumetric water content at the current timestep [-].

Type:

float

loss_factor = 0.1

w_rho = 1000.0

w_latent = 2250000.0

SOIL_PARAMS = {'clay': {'b1': -0.197, 'b2': -0.962, 'b3': 2.521, 'theta_r': 0.09, 'theta_s': 0.385, 'x0': 0.024, 'xs': 0.591}, 'loam': {'b1': 0.243, 'b2': 0.393, 'b3': 1.534, 'theta_r': 0.027, 'theta_s': 0.434, 'x0': 0.018, 'xs': 0.548}, 'sand': {'b1': 0.228, 'b2': -2.406, 'b3': 4.909, 'theta_r': 0.02, 'theta_s': 0.417, 'x0': 0.012, 'xs': 0.571}}

class carm.properties.GroundProperties

Bases: object

Thermophysical and discretization properties of the ground domain.

Computes layer-averaged thermal properties from the stratigraphic input, then derives all radial/axial resistances and capacitances used in the global system matrix.

geom

Geometric parameters of the ground domain.

Type:

GroundGeometry

mesh

Discretization settings.

Type:

GroundMesh

Tg

Undisturbed ground temperature [°C].

Type:

float

stratification

Ground layering as a sequence of (k, cp, rho, thickness) tuples. The sum of layer thicknesses must equal the total discretized length.

Type:

Sequence[tuple[float, float, float, float]]

k

Layer-averaged thermal conductivity, shape (n_cells, 1) [W / (m K)].

Type:

NDArray

cp

Layer-averaged specific heat capacity, shape (n_cells, 1) [J / (kg K)].

Type:

NDArray

rho

Layer-averaged density, shape (n_cells, 1) [kg/m³].

Type:

NDArray

k_mean

Mean thermal conductivity over the active (middle) region [W / (m K)].

Type:

float

cp_mean

Mean specific heat capacity over the active region [J / (kg K)].

Type:

float

rho_mean

Mean density over the active region [kg/m³].

Type:

float

radius

Radial cell boundary positions, shape (1, n_mesh + 1) [m].

Type:

NDArray

rm

Barycentric radii for resistance calculations, shape (1, n_mesh + 2) [m].

Type:

NDArray

C_ground

Radial thermal capacitances, shape (m_mesh, n_mesh) [J/K].

Type:

NDArray

R_ground

Radial thermal resistances, shape (m_mesh, n_mesh + 1) [K/W].

Type:

NDArray

R_axial

Axial thermal resistances in the middle region, shape (m_mesh, n_mesh) [K/W].

Type:

NDArray

R_sup

Axial thermal resistances in the upper region, shape (m_mesh_sup,) [K/W].

Type:

NDArray

C_sup

Axial thermal capacitances in the upper region, shape (m_mesh_sup,) [J/K].

Type:

NDArray

R_inf

Axial thermal resistances in the lower region, shape (m_mesh_inf,) [K/W].

Type:

NDArray

C_inf

Axial thermal capacitances in the lower region, shape (m_mesh_inf,) [J/K].

Type:

NDArray

class carm.properties.GroundGeometry

Bases: object

Geometric parameters of the ground domain.

D0

Borehole diameter [m].

Type:

float

L

Active borehole length (middle ground region) [m].

Type:

float

L_sup

Length of the upper ground region [m].

Type:

float

L_inf

Length of the lower ground region [m].

Type:

float

rn

Outer radius of the radial discretization [m]. Required for single-borehole mode; None in multi-borehole mode (where r_eq from the Voronoi decomposition is used instead).

Type:

float or None

r0

Borehole radius, derived as D0 / 2 [m].

Type:

float

D0: float

L: float

L_sup: float

L_inf: float

rn: float | None

property r0: float

class carm.properties.GroundMesh

Bases: object

Discretization parameters for the ground domain.

n_mesh

Number of radial mesh elements.

Type:

int

m_mesh

Number of axial mesh elements in the middle (active) region.

Type:

int

m_mesh_sup

Number of axial mesh elements in the upper region.

Type:

int

m_mesh_inf

Number of axial mesh elements in the lower region.

Type:

int

f

Radial expansion factor for the mesh (default 1.2). Controls how rapidly cell thickness increases moving outward from the borehole.

Type:

float

n_mesh: int

m_mesh: int

m_mesh_sup: int

m_mesh_inf: int

f: float

class carm.properties.BoreholeProperties

Bases: object

Base class for all BHE configurations.

Assembles geometry, mesh, thermal properties, and fluid into a single object. Computes derived quantities (dz, mesh-shaped property arrays) shared by all BHE types.

geom

Borehole geometric parameters.

Type:

BoreholeGeometry

mesh

Axial discretization settings.

Type:

BoreholeMesh

thermalprops

Thermal properties of the grout.

Type:

BoreholeThermalProperties

fluid

Thermophysical properties of the heat carrier fluid.

Type:

Fluid

Lbore

Active borehole length [m].

Type:

float

D0

Borehole diameter [m].

Type:

float

m_mesh

Number of axial mesh elements.

Type:

int

dz

Axial mesh element size [m].

Type:

float

cp_0

Specific heat capacity array, shape (m_mesh, 1) [J / (kg K)].

Type:

NDArray

rho_0

Density array, shape (m_mesh, 1) [kg/m³].

Type:

NDArray

k0

Thermal conductivity array, shape (m_mesh, 1) [W / (m K)].

Type:

NDArray

class carm.properties.BoreholeGeometry

Bases: object

Geometric parameters of the borehole. D_irrigation and perf_fraction parameters must be set as None if

grout variable properties are not taken into account.

Note: the irrigation system is feasible only with shallow helical heat exchangers.

Lbore

Active borehole length [m].

Type:

float

D0

Borehole diameter [m].

Type:

float

D_irrigation

Irrigation pipe diameter [m].

Type:

None | float = None

perf_fraction

Irrigation pipe perforation fraction [-].

Type:

None | float = None

Lbore: float

D0: float

D_irrigation: None | float

perf_fraction: None | float

property r0: float

class carm.properties.BoreholeMesh

Bases: object

Axial discretization of the borehole.

m_mesh

Number of axial mesh elements along the borehole.

Type:

int

m_mesh: int

class carm.properties.BoreholeThermalProperties

Bases: object

Thermal properties of the borehole filling material (grout). The user must define whether he wants to define equivalent properties or grout stratification.

cp_0

Specific heat capacity [J / (kg K)].

Type:

float | None

rho_0

Density [kg/m³].

Type:

float | None

k0

Thermal conductivity [W / (m K)].

Type:

float | None

stratification

Grout layering as a sequence of (k, cp, rho, thickness) tuples. The sum of layer thicknesses must equal the borehole discretized length. Stratification is set as None by default.

Type:

Sequence[tuple[float, float, float, float]] | None

soil_type

Soil type string. This is set as None by default. If accounting for time variable properties, it must be set as ‘sand’, ‘loam’, or ‘clay’ and the correct properties must be given as input.

Type:

str

cp_0: float | None = None

rho_0: float | None = None

k0: float | None = None

stratification: Sequence[tuple[float, float, float, float]] | None = None

soil_type: str | None = None

class carm.properties.SingleUtube

Bases: Utube

Single U-tube BHE configuration (2 pipes).

Extends Utube with pipe-to-grout and grout-to-ground resistances specific to the single U-tube layout.

Rp0

Pipe-to-grout thermal resistance [K m / W].

Type:

float

RppB

Grout-to-ground thermal resistance [K m / W].

Type:

float

n_equations

Number of nodal equations in the discretized system (6).

Type:

int

Rp0_dz

Rp0 normalized by dz [K/W].

Type:

float

RppB_dz

RppB normalized by dz [K/W].

Type:

float

crossing_time_calculation(mw_tot)

Compute the fluid transit time through the U-tube.

Parameters:

mw_tot (NDArray) – Total mass flow rate [kg/s].

Returns:

Time for the fluid to travel the full U-tube length (2 × Lbore) [s].

Return type:

NDArray

Examples

>>> mw_tot = np.full(n_steps, 2)
>>> t = bhe.crossing_time_calculation(mw_tot=mw_tot)

class carm.properties.DoubleUtube

Bases: Utube

Double U-tube BHE configuration (4 pipes).

Extends Utube with an additional pipe-to-pipe resistance and support for series (S) or parallel (P) pipe connection.

connection

Pipe connection mode: 'S' for series, 'P' for parallel.

Type:

str

Rp0

Pipe-to-grout thermal resistance [K m / W].

Type:

float

RppB

Grout-to-ground thermal resistance [K m / W].

Type:

float

RppA

Pipe-to-pipe thermal resistance [K m / W].

Type:

float

n_equations

Number of nodal equations in the discretized system (10).

Type:

int

Rp0_dz

Rp0 normalized by dz [K/W].

Type:

float

RppB_dz

RppB normalized by dz [K/W].

Type:

float

RppA_dz

RppA normalized by dz [K/W].

Type:

float

crossing_time_calculation(mw_tot)

Compute the fluid transit time through the double U-tube.

Accounts for series (full flow in each pipe) vs. parallel (half flow in each pipe) connection.

Parameters:

mw_tot (NDArray) – Total mass flow rate [kg/s].

Returns:

Fluid transit time [s].

Return type:

NDArray

class carm.properties.Coaxial

Bases: BoreholeProperties

Coaxial pipe BHE configuration.

Two concentric pipes: inner pipe (1) and annular outer pipe (2). Flow direction is set by supply_and_return.

Dp1i

Inner diameter of pipe 1 (inner pipe) [m].

Type:

float

Dp2i

Inner diameter of pipe 2 (outer annulus) [m].

Type:

float

pipe1_thick

Wall thickness of pipe 1 [m].

Type:

float

pipe2_thick

Wall thickness of pipe 2 [m].

Type:

float

k_pipe1

Thermal conductivity of the pipe 1 material [W / (m K)].

Type:

float

k_pipe2

Thermal conductivity of the pipe 2 material [W / (m K)].

Type:

float

supply_and_return

Flow direction: '1_2' (supply in pipe 1) or '2_1' (supply in pipe 2).

Type:

str

n_equations

Number of nodal equations in the discretized system (5).

Type:

int

De

Hydraulic diameter of the annular region [m].

Type:

float

S_shell

Cross-sectional area of the grout annulus [m²].

Type:

float

R_cond1

Conductive resistance of pipe 1 wall [K/W].

Type:

float

R_cond2

Conductive resistance of pipe 2 wall [K/W].

Type:

float

R_shell

Conductive resistance of the grout annulus [K/W].

Type:

float

R_pipes1

Conductive resistance of stationary fluid in pipe 1, used when mw=0 [K/W].

Type:

float

R_pipes2

Conductive resistance of stationary fluid in the annulus, used when mw=0 [K/W].

Type:

float

R_axial_shell

Axial conductive resistance of the grout shell [K/W].

Type:

float

C_shell

Thermal capacitance of the grout shell [J/K].

Type:

float

C_fluid1

Thermal capacitance of the fluid in pipe 1 [J/K].

Type:

float

C_fluid2

Thermal capacitance of the fluid in the annulus [J/K].

Type:

float

crossing_time_calculation(mw_tot)

Compute fluid transit times for both flow paths in the coaxial BHE.

Parameters:

mw_tot (NDArray) – Total mass flow rate [kg/s].

Returns:

crossing_time – Transit time through pipes [s].

Return type:

NDArray

class carm.properties.Helical

Bases: BoreholeProperties

Helical pipe BHE configuration.

A helical coil wound inside the borehole. The geometry is parameterized by the helix radius, pipe diameter, and number of turns.

Dpi1

Inner pipe 1 diameter (straight tube) [m].

Type:

float

Dpi2

Inner pipe 2 diameter (helical tube) [m].

Type:

float

rih

Inner helix radius (centre of pipe to borehole axis) [m].

Type:

float

pipe_thick

Pipe wall thickness [m].

Type:

float

N

Number of helix turns.

Type:

int

P

Helix pitch [m].

Type:

float

supply_and_return

Flow direction: '1_2' (supply in pipe 1) or '2_1' (supply in pipe 2).

Type:

str

Lp2tot

Total length helical pipe [m].

Type:

float

k_pipe

Thermal conductivity of the pipe material [W / (m K)].

Type:

float

n_equations

Number of nodal equations in the discretized system (6).

Type:

int

F

Turn density (turns per metre) [1/m].

Type:

float

S_shell

Cross-sectional area of the outer grout annulus [m²].

Type:

float

S_core

Cross-sectional area of the inner grout core [m²].

Type:

float

C_shell

Thermal capacitance of the shell, shape (m_mesh, 1) [J/K].

Type:

NDArray

C_shell_middle

Thermal capacitance of the node between pipe 2 and shell, shape (m_mesh, 1) [J/K]

Type:

NDArray

C_core

Thermal capacitance of the core, shape (m_mesh, 1) [J/K].

Type:

NDArray

C_fluid1

Thermal capacitance of the supply fluid [J/K].

Type:

float

C_fluid2

Thermal capacitance of the return fluid [J/K].

Type:

float

crossing_time_calculation(mw_tot)

Compute the fluid transit time through the helical pipe.

Parameters:

mw_tot (NDArray) – Total mass flow rate [kg/s].

Returns:

Fluid transit time [s].

Return type:

NDArray