soil_heat.liebethal_and_folken

A collection of Python functions that implement every numbered equation from Liebethal & Foken (2006) Evaluation of six parameterization approaches for the ground heat flux.

Each public function is named after the paper section and equation number for easy cross‑referencing. Helper utilities for finite‑difference gradients and unit handling are provided at the end of the module.

References

Liebethal, C., & Foken, T. (2006). Evaluation of six parameterization approaches for the ground heat flux. Theoretical and Applied Climatology. DOI:10.1007/s00704‑005‑0234‑0

Functions

`reference_ground_heat_flux`(→ numpy.ndarray)	Compute the reference ground‑heat flux G₀,M using the
`ground_heat_flux_pr`(→ numpy.ndarray)	Estimate ground heat flux as a fixed fraction of net radiation
`ground_heat_flux_lr`(→ numpy.ndarray)	Estimate ground heat flux using a linear regression against net
`ur_coefficients`(→ Tuple[numpy.ndarray, numpy.ndarray])	Compute the parameters A and B for the universal net-radiation
`ground_heat_flux_ur`(→ numpy.ndarray)	Estimate ground heat flux using the universal net-radiation
`surface_temp_amplitude`(→ float)	Estimate the diurnal surface-temperature amplitude (ΔT_s) from
`phi_from_soil_moisture`(→ float)	Calculate the empirical parameter φ based on soil moisture content
`ground_heat_flux_sh`(→ numpy.ndarray)	Estimate ground heat flux from the sensible heat flux (H)
`ground_heat_flux_sm`(→ numpy.ndarray)	Estimate surface ground heat flux using the "simple measurement"
`active_layer_thickness`(→ float)	Calculate the thickness of the active soil layer (δz) for the
`ground_heat_flux_fr`(→ numpy.ndarray)	Estimate ground heat flux using the two-layer force-restore method

Module Contents

soil_heat.liebethal_and_folken.reference_ground_heat_flux(temp_profile: numpy.ndarray, depths: Sequence[float], times: Sequence[float], cv: float, thermal_conductivity: float, gradient_depth: float = 0.2) → numpy.ndarray[source]

Compute the reference ground‑heat flux G₀,M using the gradient method combined with calorimetry for heat storage (Liebethal & Foken 2006, Eq. 1).

The method combines the conductive heat flux at a reference depth with the rate of change of heat stored in the soil layer above that depth.

\[G_{0,M}(t) = -\lambda \frac{\partial T}{\partial z} \bigg|_{z=0.2m} + \int_{z=0}^{0.2m} c_v \frac{\partial T}{\partial t} dz\]

Parameters:

temp_profile (numpy.ndarray) – A 2D array of soil temperatures (°C or K) with shape (n_depths, n_times).
depths (Sequence[float]) – A sequence of measurement depths in meters (positive downward), corresponding to the rows of temp_profile.
times (Sequence[float]) – A sequence of time stamps in seconds (e.g., Unix timestamps), corresponding to the columns of temp_profile.
cv (float) – Volumetric heat capacity of the soil (J m⁻³ K⁻¹). Assumed to be constant with depth.
thermal_conductivity (float) – Soil thermal conductivity λ (W m⁻¹ K⁻¹). Assumed to be constant with depth.
gradient_depth (float, optional) – The depth (m) at which the vertical temperature gradient is evaluated, by default 0.20 m.

Returns:

A 1D array of the instantaneous ground‑heat flux G₀,M (W m⁻²) at the surface for each time step. Positive values indicate downward flux.

Return type:

numpy.ndarray

Raises:

ValueError – If temp_profile shape does not match the lengths of depths and times.

soil_heat.liebethal_and_folken.ground_heat_flux_pr(qs: numpy.ndarray, p: float) → numpy.ndarray[source]

Estimate ground heat flux as a fixed fraction of net radiation (Liebethal & Foken 2006, Eq. 2).

This is a simple empirical relationship where the ground heat flux is assumed to be a constant proportion of the net radiation at the surface.

\[G_{0,PR}(t) = -p \cdot Q^*_s(t)\]

Parameters:

qs (numpy.ndarray) – Time series of net radiation (W m⁻²). Positive values are typically downward.
p (float) – The fraction of net radiation that is partitioned into ground heat flux (dimensionless, typically 0 < p < 1).

Returns:

Time series of the estimated ground heat flux G₀,PR (W m⁻²).

Return type:

numpy.ndarray

soil_heat.liebethal_and_folken.ground_heat_flux_lr(qs: numpy.ndarray, a: float, b: float, lag_steps: int = 0) → numpy.ndarray[source]

Estimate ground heat flux using a linear regression against net radiation, with an optional time lag (Liebethal & Foken 2006, Eq. 3).

\[G_{0,LR}(t) = a \cdot Q^*_s(t + \Delta t_G) + b\]

Parameters:

qs (numpy.ndarray) – Time series of net radiation (W m⁻²).
a (float) – The slope of the linear regression (dimensionless).
b (float) – The intercept of the linear regression (W m⁻²).
lag_steps (int, optional) – The integer time lag (number of array elements) to apply to the net radiation series. A positive value advances the series (e.g., qs[t+lag] is used for G[t]), by default 0.

Returns:

Time series of the estimated ground heat flux G₀,LR (W m⁻²).

Return type:

numpy.ndarray

soil_heat.liebethal_and_folken.ur_coefficients(delta_ts: float | numpy.ndarray) → Tuple[numpy.ndarray, numpy.ndarray][source]

Compute the parameters A and B for the universal net-radiation parameterization, based on the diurnal surface temperature amplitude (Liebethal & Foken 2006, Eq. 5 & 6).

\[A = 0.0074 \cdot \Delta T_s + 0.088 B = 1729 \cdot \Delta T_s + 65013\]

Parameters:: delta_ts (float or numpy.ndarray) – The diurnal amplitude of the surface temperature (K or °C).
Returns:: A tuple containing the computed parameters (A, B). - A is dimensionless. - B is in seconds.
Return type:: Tuple[numpy.ndarray, numpy.ndarray]

soil_heat.liebethal_and_folken.ground_heat_flux_ur(qs: numpy.ndarray, times_sec: numpy.ndarray, delta_ts: float) → numpy.ndarray[source]

Estimate ground heat flux using the universal net-radiation parameterization by Santanello & Friedl (2003), as cited in Liebethal & Foken (2006, Eq. 4).

This method modulates the fraction of net radiation partitioned to ground heat flux with a cosine function of the time of day.

\[G_{0,UR}(t) = -A \cdot \cos\left(\frac{2\pi (t + 10800)}{B}\right) \cdot Q^*_s(t)\]

Parameters:

qs (numpy.ndarray) – Time series of net radiation (W m⁻²).
times_sec (numpy.ndarray) – Time stamps in seconds relative to solar noon. Positive values indicate the afternoon.
delta_ts (float) – The diurnal amplitude of the surface temperature (K or °C).

Returns:

Time series of the estimated ground heat flux G₀,UR (W m⁻²).

Return type:

numpy.ndarray

soil_heat.liebethal_and_folken.surface_temp_amplitude(delta_t1: float, delta_t2: float, z1: float, z2: float) → float[source]

Estimate the diurnal surface-temperature amplitude (ΔT_s) from temperature amplitudes measured at two different soil depths (Liebethal & Foken 2006, Eq. 8).

This method assumes an exponential decay of the temperature wave amplitude with depth.

\[\Delta T_s = \Delta T_1 + \Delta T_2 \cdot \exp\left(\frac{z_2}{z_2 - z_1}\right)\]

Parameters:

delta_t1 (float) – Diurnal temperature amplitude (K or °C) measured at depth z1.
delta_t2 (float) – Diurnal temperature amplitude (K or °C) measured at depth z2.
z1 (float) – The shallower depth in meters (positive downward).
z2 (float) – The deeper depth in meters (positive downward).

Returns:

The estimated diurnal surface-temperature amplitude ΔT_s (K or °C).

Return type:

float

Raises:

ValueError – If z2 is not greater than z1.

soil_heat.liebethal_and_folken.phi_from_soil_moisture(theta_0_10: float, a_phi: float = 9.62, b_phi: float = 0.402) → float[source]

Calculate the empirical parameter φ based on soil moisture content (Liebethal & Foken 2006, Eq. 10).

\[\phi = a_\phi \cdot \theta_{0-10} + b_\phi\]

Parameters:

theta_0_10 (float) – Average volumetric soil moisture content in the top 10 cm (m³ m⁻³).
a_phi (float, optional) – Empirical coefficient, by default 9.62.
b_phi (float, optional) – Empirical coefficient, by default 0.402.

Returns:

The dimensionless parameter φ.

Return type:

float

soil_heat.liebethal_and_folken.ground_heat_flux_sh(h: numpy.ndarray, phase_g0: Sequence[float], phase_h: Sequence[float], u_mean: float, phi: float, omega: float = 2 * np.pi / 86400.0) → numpy.ndarray[source]

Estimate ground heat flux from the sensible heat flux (H) (Liebethal & Foken 2006, Eq. 9).

This method relates the ground heat flux to the sensible heat flux through a phase-shifted and scaled relationship.

\[G_{0,SH}(t) = -\frac{\phi}{\sqrt{\bar{u}}} \frac{\cos(\omega t + \varphi(G_0))} {\cos(\omega t + \varphi(H))} H(t)\]

Parameters:

h (numpy.ndarray) – Time series of sensible heat flux (W m⁻²).
phase_g0 (Sequence[float]) – Phase lags of the ground heat flux, φ(G₀), in radians. Must have the same length as h.
phase_h (Sequence[float]) – Phase lags of the sensible heat flux, φ(H), in radians. Must have the same length as h.
u_mean (float) – Mean horizontal wind speed during the daytime (m s⁻¹).
phi (float) – An empirical dimensionless parameter, often derived from soil moisture via phi_from_soil_moisture.
omega (float, optional) – The diurnal angular frequency (rad s⁻¹), by default 2π/86400.

Returns:

Time series of the estimated ground heat flux G₀,SH (W m⁻²).

Return type:

numpy.ndarray

Raises:

ValueError – If the length of phase arrays does not match the length of h.

soil_heat.liebethal_and_folken.ground_heat_flux_sm(gp: numpy.ndarray, t1: numpy.ndarray, delta_t: numpy.ndarray, cv: float, zp: float, dt_seconds: float) → numpy.ndarray[source]

Estimate surface ground heat flux using the “simple measurement” parameterization, correcting a heat flux plate measurement with a storage term (Liebethal & Foken 2006, Eq. 11).

\[G_{0,SM}(t) = G_p(t) + c_v z_p \left( \frac{dT_1}{dt} + \frac{1}{2} \frac{d(\Delta T)}{dt} \right)\]

Parameters:

gp (numpy.ndarray) – Heat flux plate measurements at depth zp (W m⁻²).
t1 (numpy.ndarray) – Soil temperature at 0.01 m depth (K or °C).
delta_t (numpy.ndarray) – Temperature difference T(0.01 m) - T(zp) (K).
cv (float) – Volumetric heat capacity of the soil (J m⁻³ K⁻¹).
zp (float) – Depth of the heat flux plate (m, positive downward).
dt_seconds (float) – The constant time step between consecutive samples (s).

Returns:

Time series of the estimated ground heat flux G₀,SM (W m⁻²). The first element will be NaN due to the backward difference.

Return type:

numpy.ndarray

soil_heat.liebethal_and_folken.active_layer_thickness(lambda_: float, cv: float, omega: float = 2 * np.pi / 86400) → float[source]

Calculate the thickness of the active soil layer (δz) for the force-restore method (Liebethal & Foken 2006, Eq. 13).

\[\delta_z = \sqrt{\frac{\lambda}{2 c_v \omega}}\]

Parameters:

lambda (float) – Soil thermal conductivity (W m⁻¹ K⁻¹).
cv (float) – Volumetric heat capacity of the soil (J m⁻³ K⁻¹).
omega (float, optional) – The diurnal angular frequency (rad s⁻¹), by default 2π/86400.

Returns:

The thickness of the active soil layer δz (m).

Return type:

float

soil_heat.liebethal_and_folken.ground_heat_flux_fr(tg: numpy.ndarray, tg_avg: float, cv: float, lambda_: float, delta_z: float | None = None, times: numpy.ndarray | None = None) → numpy.ndarray[source]

Estimate ground heat flux using the two-layer force-restore method (Liebethal & Foken 2006, Eq. 12).

\[G_{0,FR}(t) = -\delta_z c_v \frac{dT_g}{dt} + \sqrt{\lambda \omega c_v} \left( \frac{1}{\omega}\frac{dT_g}{dt} + (T_g - \bar{T_g}) \right)\]

Parameters:

tg (numpy.ndarray) – Time series of the upper (surface) layer temperature, Tg(t) (K).
tg_avg (float) – The long-term average or “restoring” temperature, T̄g (K).
cv (float) – Volumetric heat capacity of the soil (J m⁻³ K⁻¹).
lambda (float) – Soil thermal conductivity λ (W m⁻¹ K⁻¹).
delta_z (float, optional) – Thickness of the active soil layer δz (m). If None, it is calculated internally using active_layer_thickness, by default None.
times (numpy.ndarray, optional) – Time stamps in seconds corresponding to tg. Required for calculating the time derivative. If None, assumes a uniform time step of 1 second, by default None.

Returns:

Time series of the estimated ground heat flux G₀,FR (W m⁻²).

Return type:

numpy.ndarray