pedon.soil module

Soil sample class and pedotransfer functions.

class pedon.soil.Soil(name: str, model: SoilModel | None = None, sample: SoilSample | None = None, source: Literal['HYDRUS', 'VS2D', 'Staring_2001', 'Staring_2018', 'Clapp', 'Rawls'] | None = None, description: str | None = None)

Bases: object

A class representing soil properties and models.

name

The name identifier for the soil.

Type:

str

model

The soil model instance containing hydraulic parameters, by default None.

Type:

SoilModel | None, optional

sample

The soil sample data associated with this soil, by default None.

Type:

SoilSample | None, optional

source

The data source for the soil parameters (e.g., ‘HYDRUS’, ‘Staring_2018’), by default None.

Type:

str | None, optional

description

A text description of the soil type, by default None.

Type:

str | None, optional

description: str | None = None
from_name(sm: type[SoilModel] | SoilModel | Literal['Genuchten', 'Brooks', 'Brunswick', 'Panday', 'Gardner', 'Rucker', 'Haverkamp', 'Fredlund', 'Kosugi', 'Campbell', 'Kool', 'GenuchtenGardner', 'Gerke'], source: Literal['HYDRUS', 'VS2D', 'Staring_2001', 'Staring_2018', 'Clapp', 'Rawls'] | None = None) → Self

Load soil parameters from a CSV database by soil name and model type.

Available sources include HYDRUS, VS2D, Staring_2001, Staring_2018, Rawls and Clapp.

References

Rawls, W. J., Brakensiek, D. L., & Saxton, K. E. (1982). Estimation of Soil Water Properties. Transactions of the ASAE, 25(5), 1316–1320. doi: 10.13031/2013.33720

Clapp, R. B., & Hornberger, G. M. (1978). Empirical equations for some soil hydraulic properties. Water Resources Research, 14(4), 601–604. doi: 10.1029/WR014i004p00601

Carsel, R. F. and Parrish, R. S. (1988). Developing Joint Probability Distributions of Soil Water Retention Characteristics. Water Resources Research, 24(5), 755–769. doi: 10.1029/WR024i005p00755

Šimůnek, J., van Genuchten, M. Th., & Šejna, M. (2008). Development and applications of the HYDRUS and STANMOD software packages and related codes. Vadose Zone Journal, 7(2), 587–600. doi: 10.2136/vzj2007.0077

Healy, R. W. (1990). Simulation of Solute Transport in Variably Saturated Porous Media with Supplemental Information on Modifications to the U.S. Geological Survey Computer Program VS2D. Water-Resources Investigations Report, U.S. Geological Survey, Denver, CO. Report 90-4025. doi: 10.3133/wri904025

Wösten, J. H. M., Veerman, G. J., de Groot, W. J. M., & Stolte, J. (2001). Waterretentie- en Doorlatendheidskarakteristieken van Boven- en Ondergronden in Nederland: De Staringreeks. Alterra, Report 153, Wageningen, The Netherlands. url: https://edepot.wur.nl/43272

Heinen, M., Bakker, G., & Wösten, J. H. M. (2020). Waterretentie- en Doorlatendheidskarakteristieken van Boven- en Ondergronden in Nederland: De Staringreeks; (Update 2018). Wageningen Environmental Research, Report 2978, Wageningen, The Netherlands. doi: 10.18174/512761

from_staring(year: Literal['2001', '2018'] = '2018') → Self

Load soil parameters from the Staring series database.

static list_names(sm: type[SoilModel] | SoilModel | Literal['Genuchten', 'Brooks', 'Brunswick', 'Panday', 'Gardner', 'Rucker', 'Haverkamp', 'Fredlund', 'Kosugi', 'Campbell', 'Kool', 'GenuchtenGardner', 'Gerke']) → list[str]

Return a list of available soil names for a given soil model.

model: SoilModel | None = None
name: str
sample: SoilSample | None = None
source: Literal['HYDRUS', 'VS2D', 'Staring_2001', 'Staring_2018', 'Clapp', 'Rawls'] | None = None
class pedon.soil.SoilSample(sand_p: float | None = None, silt_p: float | None = None, clay_p: float | None = None, rho: float | None = None, th33: float | None = None, th1500: float | None = None, om_p: float | None = None, m50: float | None = None, d10: float | None = None, d20: float | None = None, h: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None, k: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None, theta: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None)

Bases: object

A container for measured soil properties and in-situ soil hydraulic data.

Class provides convenience routines to predict hydraulic parameters using a range of pedotransfer functions and empirical models.

sand_p

Sand fraction in percent (%).

Type:

float | None

silt_p

Silt fraction in percent (%).

Type:

float | None

clay_p

Clay fraction in percent (%).

Type:

float | None

rho

Bulk density (g cm^-3).

Type:

float | None

th33

Water content at -33 kPa (cm).

Type:

float | None

th1500

Water content at -1500 kPa (cm).

Type:

float | None

om_p

Organic matter content in percent (%).

Type:

float | None

m50

Median sand fraction (μm).

Type:

float | None

d10

Representative grain diameter from sieve curve (m).

Type:

float | None

d20

Representative grain diameter from sieve curve (m).

Type:

float | None

h

Pressure head measurements (cm).

Type:

FloatArray | None

k

Hydraulic conductivity measurements (m s^-1 or cm d^-1).

Type:

FloatArray | None

theta

Measured volumetric water content (dimensionless).

Type:

FloatArray | None

Notes

  • Verify units before use as different methods expect specific conventions.

  • Methods return soil hydraulic model instances (e.g., Genuchten, Brooks).

  • Some methods make external API calls (rosetta) or use empirical relationships.

clay_p: float | None = None
cosby() → Brooks

Pedotransfer function returning Brooks-Corey parameters.

References

Cooper, E., Blyth, E., Cooper, H., Ellis, R., Pinnington, E., & Dadson, S. J. (2021). Using Data Assimilation to Optimize Pedotransfer Functions Using Field-Scale In Situ Soil Moisture Observations. Hydrology and Earth System Sciences, 25, 2445–2461. doi: 10.5194/hess-25-2445-2021

Cosby, B. J., Hornberger, G. M., Clapp, R. B., & Ginn, T. R. (1984). A Statistical Exploration of the Relationships of Soil Moisture Characteristics to the Physical Properties of Soils. Water Resources Research, 20(6), 682–690. doi: 10.1029/WR020i006p00682

d10: float | None = None
d20: float | None = None
fit(sm: type[SoilModel], pbounds: DataFrame | None = None, weights: float | ndarray[tuple[Any, ...], dtype[float64]] = 1.0, W1: float = 0.1, W2: float | None = None, k_s: float | None = None, silent: bool = True, **kwargs) → SoilModel

Fit the provided SoilModel to the measurements.

Fit the provided SoilModel (e.g., van Genuchten, Brooks-Corey class) to the stored measurements (theta, k, h) using nonlinear least squares. If pbounds is not provided, default parameter bounds are retrieved for the requested model name. The objective combines water retention and log10(k) errors; weighting terms W1 and W2 control the relative contribution of k. Returns a model instance with optimized parameters.

Parameters:

  • sm (Type[SoilModel]) – The soil model class to fit (e.g., Genuchten, Brooks).

  • pbounds (DataFrame | None, optional) – DataFrame with parameter bounds and initial values. If None, defaults are used based on the model name. Expected columns: ‘p_ini’, ‘p_min’, ‘p_max’.

  • weights (FloatArray | float, optional) – Weights for the objective function. Can be a single float (applied to all) or an array of length N+M (N for theta, M-N for k). Default is 1.0.

  • W1 (float, optional) – Scaling factor for the k error in the objective function. Default is 0.1.

  • W2 (float | None, optional) – Additional scaling factor for the k error. If None, it is computed to balance the contributions of theta and k errors based on their magnitudes and weights.

  • k_s (float | None, optional) – If provided, this value of saturated hydraulic conductivity will be fixed during optimization. This means that the relative hydraulic conductivity curve will be estimated.

  • silent (bool, optional) – If False, prints the optimization result. Default is True.

  • kwargs (dict, optional) – Additional keyword arguments to pass to the scipy.optimize.least_squares function.

Notes

  • Requires theta and k (and optionally h) to be set.

  • If k_s is provided it will be fixed during optimization.

  • Input/outputs and bounds are expected in the units used by the soil model.

References

van Genuchten, M. Th., Leij, F. J., & Yates, S. R. (1991). The RETC Code for Quantifying the Hydraulic Functions. Version 1.0. U.S. Salinity Laboratory, USDA, ARS, Riverside, CA. EPA Report 600/2-91/065. url: https://cfpub.epa.gov/si/si_public_record_report.cfm?dirEntryId=130162

from_staring(name: str, year: str = '2018') → Self

Get properties and measurements from Staring series.

References

Wösten, J. H. M., Veerman, G. J., de Groot, W. J. M., & Stolte, J. (2001). Waterretentie- en Doorlatendheidskarakteristieken van Boven- en Ondergronden in Nederland: De Staringreeks. Alterra, Report 153, Wageningen, The Netherlands. url: https://edepot.wur.nl/43272

Heinen, M., Bakker, G., & Wösten, J. H. M. (2020). Waterretentie- en Doorlatendheidskarakteristieken van Boven- en Ondergronden in Nederland: De Staringreeks; (Update 2018). Wageningen Environmental Research, Report 2978, Wageningen, The Netherlands. doi: 10.18174/512761

h: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None
hodnett(ph: float = 5.8, cec: float = 15.0) → Genuchten

Pedotransfer function for tropical soils.

Implements the continuous pedotransfer function from Hodnett & Tomasella (2002) calibrated exclusively on tropical soils from the IGBP-DIS database. This PTF relies on Organic Carbon (OC), not Organic Matter (OM). This method converts the om_p to OC using a factor 1.724. Note that the k_s is not estimated by this PTF and is set to NaN.

Parameters:

  • ph (float, optional) – Soil pH in water. Default is 5.8 (mean of the calibration dataset).

  • cec (float, optional) – Cation Exchange Capacity (cmol kg^-1). Default is 15.0 (mean of the calibration dataset).

References

Hodnett, M. G., & Tomasella, J. (2002). Marked differences between van Genuchten soil water-retention parameters for temperate and tropical soils: a new water-retention pedo-transfer functions developed for tropical soils. Geoderma, 108(3-4), 155–180. doi: 10.1016/S0016-7061(02)00105-2

hypags() → Genuchten

Estimate van Genuchten parameters using the HYPAGS method.

Implements the Kozeny-Carman-based parameterization from Peche & Houben (2023, 2024) to derive van Genuchten parameters and characteristic grain-size metrics from hydraulic conductivity and/or grain size inputs.

The routine: - Accepts k (hydraulic conductivity), d10, or d20 as input (at least one required) - Iteratively estimates effective porosity (ne), d50, and d60 - Computes van Genuchten alpha and n parameters with bootstrap-derived errors - Returns a Genuchten model with k_s, theta_r, theta_s, alpha, and n

Notes

  • Grain diameters should be in meters; k in m s^-1

  • Input values outside empirically supported ranges trigger warnings

  • theta_r is estimated from k; theta_s equals effective porosity (ne)

Returns:

Van Genuchten soil model with estimated parameters.

Return type:

Genuchten

References

Peche, A., Houben, G., & Altfelder, S. (2024). Approximation of van Genuchten Parameter Ranges from Hydraulic Conductivity Data. Groundwater, 62(3), 469-479. doi: 10.1111/gwat.13365

Peche, A., & Houben, G. J. (2023). Estimating characteristic grain sizes and effective porosity from hydraulic conductivity data. Groundwater, 61(4), 574-585. doi: 10.1111/gwat.13266

k: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None
m50: float | None = None
om_p: float | None = None
rawls(cecc: float | None = None) → Brooks

Estimate Brooks-Corey parameters using the Rawls & Brakensiek method.

cecc: Cation Exchange Capacity of clay (cmol kg^-1). Required if rho is not provided.

References

Rawls, W. J., & Brakensiek, D. L. (1989). Estimation of Soil Water Retention and Hydraulic Properties. In: Morel-Seytoux, H. J. (eds) Unsaturated Flow in Hydrologic Modeling: Theory and Practice. Springer Netherlands, Dordrecht, pp. 275–300. doi: 10.1007/978-94-009-2352-2_10

rho: float | None = None
rosetta(version: Literal[1, 2, 3] = 3) → Genuchten

Pedotransfer function using the Rosetta API.

References

Schaap, M. G., Leij, F. J., & van Genuchten, M. Th. (2001). Rosetta: A Computer Program for Estimating Soil Hydraulic Parameters with Hierarchical Pedotransfer Functions. Journal of Hydrology, 251(3–4), 163–176. doi: 10.1016/S0022-1694(01)00466-8

Zhang, Y., & Schaap, M. G. (2017). Weighted recalibration of the Rosetta pedotransfer model with improved estimates of hydraulic parameter distributions and summary statistics (Rosetta3). Journal of Hydrology, 547, 39–53. doi: 10.1016/j.jhydrol.2017.01.004

sand_p: float | None = None
saxton(df: float = 1.0) → Brooks

Pedotransfer function returning Brooks-Corey parameters.

Implements the equations from Saxton and Rawls (2006) which estimate soil water characteristics from soil texture and organic matter.

Parameters:

df (float, optional) – Density adjustment factor (normally between 0.9 and 1.3) to account for compaction or loosening. Default is 1.0 (normal density).

References

Saxton, K. E., Rawls, W. J., Romberger, J. S., & Papendick, R. I. (1986). Estimating generalized soil-water characteristics from texture. Soil Science Society of America Journal, 50(4), 1031–1036. doi: 10.2136/sssaj1986.03615995005000040039x

Saxton, K. E., & Rawls, W. J. (2006). Soil Water Characteristic Estimates by Texture and Organic Matter for Hydrologic Solutions. Soil Science Society of America Journal, 70(5), 1569–1578. doi: 10.2136/sssaj2005.0117

silt_p: float | None = None
th1500: float | None = None
th33: float | None = None
theta: float | ndarray[tuple[Any, ...], dtype[float64]] | None = None
toth(topsoil: bool = False) → Genuchten

Pedotransfer function returning Mualem-van Genuchten parameters.

Implements the continuous pedotransfer functions from Tóth et al. (2015) based on the EU-HYDI database. Uses Eq (21) for the Moisture Retention Characteristic and Eq (16) for Saturated Hydraulic Conductivity.

Parameters:

topsoil (bool, optional) – If True, applies the topsoil adjustment to the pedotransfer function. Default is False.

Returns:

Van Genuchten soil model with estimated parameters.

Return type:

Genuchten

References

Tóth, B., Weynants, M., Nemes, A., Makó, A., Bilas, G., & Tóth, G. (2015). New generation of hydraulic pedotransfer functions for Europe. European Journal of Soil Science, 66(1), 226–238. doi: 10.1111/ejss.12192

vereecken() → Genuchten

Pedotransfer function returning van Genuchten parameters.

Implements the classic continuous pedotransfer functions from Vereecken et al. (1989) (Table 7) to estimate soil moisture retention parameters from texture, bulk density, and carbon content, combined with the saturated hydraulic conductivity (k_s) regression from Vereecken et al. (1990).

The Vereecken PTF relies on Organic Carbon (OC) in %. This method converts om_p to OC using the standard 1.724 factor.

Warning: This method brute-forces a Gardner-calibrated k_s into a standard Mualem-van Genuchten model framework. The resulting unsaturated conductivity curve will follow Mualem-van Genuchten’s format, not Vereecken’s 1990 Gardner function. Adjust accordingly when interpreting results or comparing to original Vereecken curves.

References

Vereecken, H., Maes, J., Feyen, J., & Darius, P. (1989). Estimating the soil moisture retention characteristic from texture, bulk density, and carbon content. Soil Science, 148(6), 389–403. doi: 10.1097/00010694-198912000-00001

Vereecken, H., Maes, J., & Feyen, J. (1990). Estimating Unsaturated Hydraulic Conductivity from Easily Measured Soil Properties. Soil Science, 149(1), 1–12. doi: 10.1097/00010694-199001000-00001

weynants() → Genuchten

Pedotransfer function returning Mualem-van Genuchten parameters.

The Weynants PTF relies on Organic Carbon (OC), not Organic Matter (OM). This method converts the om_p to OC using a factor 1.724.

References

Weynants, M., Vereecken, H., & Javaux, M. (2009). Revisiting Vereecken Pedotransfer Functions: Introducing a Closed-Form Hydraulic Model. Vadose Zone Journal, 8(1), 86–95. doi: 10.2136/vzj2008.0062

Vereecken, H., Maes, J., Feyen, J., & Darius, P. (1989). Estimating the soil moisture retention characteristic from texture, bulk density, and carbon content. Soil Science, 148(6), 389–403. doi: 10.1097/00010694-198912000-00001

wosten(topsoil: bool = False) → Genuchten

Pedotransfer function for general soils.

Sometimes also referred to as HYPRES: HYdraulic PRoperties of European Soils

Parameters:

topsoil (bool, optional) – If True, applies the topsoil adjustment to the pedotransfer function. Default is False.

References

Wösten, J. H. M., Nemes, A., Lilly, A., & Le Bas, C. (1999). Development and use of a database of hydraulic properties of European soils. Geoderma, 90, 169–185. doi: 10.1016/S0016-7061(98)00132-3

wosten_clay() → Genuchten

Pedotransfer function for clay soils.

References

Wösten, J. H. M., Veerman, G. J., de Groot, W. J. M., & Stolte, J. (2001). Waterretentie- en Doorlatendheidskarakteristieken van Boven- en Ondergronden in Nederland: De Staringreeks. Alterra, Report 153, Wageningen, The Netherlands. url: https://edepot.wur.nl/43272

wosten_sand(topsoil: bool = False) → Genuchten

Pedotransfer function for sandy soils.

Parameters:

topsoil (bool, optional) – If True, applies the topsoil adjustment to the pedotransfer function. Default is False.

References

Wösten, J. H. M., Veerman, G. J., de Groot, W. J. M., & Stolte, J. (2001). Waterretentie- en Doorlatendheidskarakteristieken van Boven- en Ondergronden in Nederland: De Staringreeks. Alterra, Report 153, Wageningen, The Netherlands. url: https://edepot.wur.nl/43272