Variable Grout Properties

The SoilMoisture class updates grout thermal conductivity, volumetric heat capacity, and density over time as a function of volumetric water content, to account for irrigation-driven moisture changes around the borehole.

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}}

When to use it

SoilMoisture is only instantiated when water_input is provided in EnvironmentalTimeSeries. In that case, D_irrigation and perf_fraction must also be set on BoreholeGeometry, since they define the irrigation pipe surface area used in the water balance:

A_irr = pi * borehole.D_irrigation * borehole.perf_fraction * borehole.Lbore

Field-level update

Properties are recomputed once per timestep at the field level, not once per borehole. All boreholes share the same grout composition and receive the same irrigation input; the evaporation term uses the mean heat flux across the field rather than a per-borehole value:

q = np.mean(self.q_nbhes[step - 1])

Sensitivity of the water content to the per-borehole heat flux (as opposed to the field average) was verified to be negligible over the operating range (0–10 kW).

Example

from carm import BoreholeGeometry, BoreholeThermalProperties

geom = BoreholeGeometry(
    Lbore=30, D0=0.5,
    D_irrigation=0.030, perf_fraction=0.5,
)
thermalprops = BoreholeThermalProperties(
    cp_0=796.14, rho_0=1587.09, k0=1.0, soil_type="sand",
)

Note

rho_0 above is the dry soil density, required when water_input is active. For simulations without irrigation, use the density at residual water content instead.