This repository provides a collection of Python modules for soil science applications, emphasizing soil moisture dynamics, infiltration, nutrient cycling, and soil respiration. The routines are designed to leverage Python’s data science and GIS ecosystem, using NumPy, SciPy, and rasterio where relevant. All algorithms strictly follow scientific references to ensure accuracy and reproducibility.
-
Set up a virtual environment:
python -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate`
-
Install dependencies:
pip install -r requirements.txt
A UML diagram showing the module structure and dependencies is available in uml_diagram.md. You can generate a visual diagram from the Mermaid Live Editor by pasting the content of the file.
All inputs and outputs are in SI units unless otherwise noted.
Computes bulk density from particle density and porosity.
from soil_science.physics import bulk_density
bd = bulk_density(particle_density=2650, porosity=0.5) # kg/m^3, unitless
print(f"Bulk Density: {bd} kg/m^3")
# Output: Bulk Density: 1325.0 kg/m^3Simulates soil temperature profile using a finite difference solution to the Fourier heat conduction equation.
import numpy as np
from soil_science.physics import soil_temperature_profile
initial_temp = np.array([15.0, 14.0, 13.0, 12.0, 11.0]) # Celsius
temps = soil_temperature_profile(
initial_temp=initial_temp,
time_steps=10,
delta_t=3600, # seconds
delta_z=0.1, # meters
thermal_diffusivity=1e-6 # m^2/s
)
print("Temperature profile at final time step (°C):")
print(temps[-1, :])Models the soil water retention curve using the van Genuchten equation.
from soil_science.hydrology import soil_water_retention_vg
theta = soil_water_retention_vg(
pressure_head=-1.0, # meters
theta_r=0.05, # m^3/m^3
theta_s=0.45, # m^3/m^3
alpha=0.1, # 1/m
n=1.5 # unitless
)
print(f"Volumetric Water Content: {theta:.3f} m^3/m^3")Implements the Green-Ampt infiltration model.
from soil_science.hydrology import green_ampt_infiltration
f = green_ampt_infiltration(
hydraulic_conductivity=5e-5, # m/s
wetting_front_suction=0.15, # m
initial_moisture_deficit=0.2,# unitless
cumulative_infiltration=0.01 # m
)
print(f"Infiltration Rate: {f:.2e} m/s")Calculates reference evapotranspiration using the FAO-56 Penman-Monteith method.
from soil_science.hydrology import penman_monteith_et
et0 = penman_monteith_et(
net_radiation=15, # MJ/m^2/day
air_temp=20, # °C
vapor_pressure_deficit=1.5, # kPa
aerodynamic_resistance=200, # s/m
surface_resistance=70 # s/m
)
print(f"Reference ET: {et0:.2f} mm/day")Computes the daily soil water balance.
import numpy as np
from soil_science.hydrology import soil_moisture_balance
precip = np.array([10, 0, 5, 0, 20]) # mm
et_ref = np.array([3, 3, 3, 4, 2]) # mm
sm, drainage = soil_moisture_balance(
precip, et_ref, awc=100, initial_soil_moisture=80 # mm for all
)
print("Soil Moisture (mm):", sm)
print("Drainage (mm):", drainage)Calculates soil respiration rate based on Q10 temperature dependence.
from soil_science.biogeochemistry import soil_respiration
resp_rate = soil_respiration(
base_respiration_rate=2.5, # e.g., mg CO2/m^2/hr
soil_temp=25 # °C
)
print(f"Respiration Rate: {resp_rate:.2f} mg CO2/m^2/hr")Estimates net nitrogen mineralization based on CENTURY model principles.
from soil_science.biogeochemistry import nitrogen_mineralization
n_min = nitrogen_mineralization(
soil_organic_carbon=10, # kg C/m^2
soil_temp=25, # °C
soil_moisture=0.5 # m^3/m^3
)
print(f"N Mineralization Rate: {n_min:.4f} kg N/m^2/day")Models the first-order decay of soil organic carbon.
from soil_science.biogeochemistry import soil_carbon_decomposition
c_decomp = soil_carbon_decomposition(
soil_organic_carbon=10, # kg C/m^2
soil_temp=20, # °C
soil_moisture=0.6 # m^3/m^3
)
print(f"C Decomposition Rate: {c_decomp:.4f} kg C/m^2/day")Estimates soil erosion using the Universal Soil Loss Equation (USLE). It can accept NumPy arrays or paths to raster files. The units of the factors must be consistent, and the output unit will be the product of the input units.
import numpy as np
from soil_science.erosion import soil_erosion_usle
# Using NumPy arrays
# Example units for USLE factors:
# R: (MJ * mm) / (ha * hr * year)
# K: (t * ha * hr) / (ha * MJ * mm)
# LS, C, P: unitless
# Resulting A: t / (ha * year)
r = np.full((5, 5), 150)
k = np.full((5, 5), 0.3)
ls = np.full((5, 5), 1.2)
c = np.full((5, 5), 0.2)
p = np.full((5, 5), 1.0)
soil_loss = soil_erosion_usle(r, k, ls, c, p)
print("Average Soil Loss (e.g., t/ha/year):", np.mean(soil_loss))
# This function can also accept file paths to GeoTIFF rasters.This project is licensed under a custom non-commercial license.
- ✅ Free for personal, academic, and research use.
- ❌ Commercial use is strictly prohibited without a separate license.
For commercial licensing inquiries, please contact me at ** s i a d s i m @ g m a i l . c o m **.
Allen, R.G., Pereira, L.S., Raes, D., & Smith, M. (1998). Crop Evapotranspiration — Guidelines for computing crop water requirements. FAO Irrigation and Drainage Paper 56.
Green, W.H. & Ampt, G.A. (1911). Studies on soil physics. The Journal of Agricultural Science, 4(1), 1-24.
Hillel, D. (1998). Environmental Soil Physics. Academic Press.
Lloyd, J. & Taylor, J.A. (1994). On the temperature dependence of soil respiration. Functional Ecology, 8(3), 315-323.
Parton, W.J., Schimel, D.S., Cole, C.V., & Ojima, D.S. (1987). Analysis of factors controlling soil organic matter levels in Great Plains grasslands. Soil Science Society of America Journal, 51(5), 1173-1179.
van Genuchten, M.T. (1980). A closed-form equation for predicting the hydraulic conductivity of unsaturated soils. Soil Science Society of America Journal, 44(5), 892-898.
Wischmeier, W.H., & Smith, D.D. (1978). Predicting rainfall erosion losses. USDA Agriculture Handbook 537.
