Usage

To use Soil Heat in a project:

import soil_heat

FAO-56 Soil Heat Flux

The fao56_soil_heat_flux module implements methods from the FAO-56 paper and the ASCE Standardized Reference ET equation.

Daily Soil Heat Flux

For daily time steps, soil heat flux is often assumed to be zero for a grass reference surface:

from soil_heat import soil_heat_flux_daily

g_daily = soil_heat_flux_daily()
print(f"Daily G: {g_daily} MJ m-2 day-1")

Monthly Soil Heat Flux

When both the previous and next month’s mean air temperatures are available:

from soil_heat import soil_heat_flux_monthly

# Temps for March and May
t_mar, t_may = 14.1, 18.8
g_apr = soil_heat_flux_monthly(t_mar, t_may)
print(f"April G: {g_apr:.3f} MJ m-2 day-1")

Hourly Soil Heat Flux

For hourly or sub-daily periods, G is estimated as a fraction of net radiation (Rn):

from soil_heat import soil_heat_flux_hourly

rn = 2.5  # MJ m-2 hr-1
g_hourly = soil_heat_flux_hourly(rn, is_daytime=True)
print(f"Hourly G: {g_hourly} MJ m-2 hr-1")

Storage Calculations

The storage_calculations module provides methods to estimate energy storage in the soil and canopy.

Soil Heat Storage

Using the change-in-storage approach for a soil layer:

import pandas as pd
import numpy as np
from soil_heat import compute_soil_storage_integrated

# Create sample data
index = pd.date_range("2023-01-01", periods=2, freq="15T")
df = pd.DataFrame({
    "T5cm": [10.0, 10.5],
    "VWC5cm": [0.25, 0.26]
}, index=index)

# Compute storage flux (W/m2)
s_soil = compute_soil_storage_integrated(df, col_T5="T5cm", col_VWC5="VWC5cm")
print(s_soil)

Canopy Heat Storage

Estimating heat storage within biomass:

from soil_heat import compute_canopy_storage

# Sample data with canopy temperature
df["T_CANOPY"] = [15.0, 16.0]

s_canopy = compute_canopy_storage(df, col_irt="T_CANOPY", crop_type="alfalfa")
print(s_canopy)

Soil Thermal Properties and Advanced Flux (Johansen)

The johansen module provides sophisticated models for soil thermal properties and heat flux.

Thermal Properties

Estimating volumetric heat capacity and thermal conductivity from water content:

import numpy as np
from soil_heat import volumetric_heat_capacity, thermal_conductivity_johansen

theta = 0.25  # m3/m3
cv = volumetric_heat_capacity(theta)
lam = thermal_conductivity_johansen(theta)

print(f"Heat Capacity: {cv:.2e} J m-3 K-1")
print(f"Conductivity: {lam:.3f} W m-1 K-1")

Surface Heat Flux from Gradient and Storage

The method_gradient_plus_storage function estimates surface ground heat flux (G0) by combining a conductive flux at a reference depth with calorimetric storage in the layers above:

import pandas as pd
from soil_heat import method_gradient_plus_storage, DEPTHS_CM

# Prepare sample temperature and water content dataframes
index = pd.date_range("2023-01-01", periods=10, freq="h")
ts = pd.DataFrame({d: np.linspace(10, 15, 10) for d in DEPTHS_CM}, index=index)
swc = pd.DataFrame({d: [0.2]*10 for d in DEPTHS_CM}, index=index)

# Estimate surface G0 using 10 cm as the reference depth
g0 = method_gradient_plus_storage(ts, swc, ref_depth_idx=2)
print(g0.head())