Pedon Package Structure

Martin Vonk (2025)

Overview

pedon is a Python package for analyzing unsaturated soil hydraulic properties. It provides an integrated framework that combines:

1. Soil Hydraulic Models - parametric descriptions of water retention and conductivity

2. Parameter Databases - pre-computed parameters from established sources (HYDRUS, VS2D, Staring)

3. Pedotransfer Functions - empirical relationships to estimate parameters from easily measured soil properties

4. Fitting Routines - direct parameter estimation from laboratory measurements

This notebook introduces the three core classes that form the foundation of pedon: Soil, SoilModel, and SoilSample.

import inspect
import sys

import pedon as pe

The Three Core Classes

pedon is built around three main classes:

1. ``SoilModel`` - represents a soil hydraulic model (e.g., van Genuchten, Brooks-Corey)

2. ``SoilSample`` - holds measured or estimated soil properties (e.g., grain size, water content, conductivity)

3. ``Soil`` - combines a SoilModel with metadata (name, source, description)

Exploring the Soil Class

The Soil class is the primary container for soil hydraulic information. Its attributes are:

# main class
# containing both SoilModel and SoilSample
pe.Soil.__annotations__

{'name': str,
 'model': pedon.soilmodel.SoilModel | None,
 'sample': pedon.soil.SoilSample | None,
 'source': str | None,
 'description': str | None}

Available Soil Models

pedon provides multiple soil model formulations from the literature. Each model represents the relationship between pressure head (h), water content (θ), and hydraulic conductivity (K):

# classes for soil models
soilmodels = [
    cls_name
    for cls_name, cls_obj in inspect.getmembers(sys.modules["pedon.soilmodel"])
    if inspect.isclass(cls_obj)
]
soilmodels

['Brooks',
 'Fredlund',
 'Gardner',
 'Genuchten',
 'GenuchtenGardner',
 'Haverkamp',
 'Panday',
 'Protocol',
 'Rucker',
 'SoilModel']

The SoilSample Class

The SoilSample class stores measured or observable soil properties. It can contain:

From soil composition:

• sand_p, silt_p, clay_p - grain size distribution (%)

• rho - bulk density (g/cm³)

• om_p - organic matter content (%)

• m50 - median sand grain diameter (μm)

From direct measurements (laboratory or field):

• h - pressure head values (cm)

• theta - corresponding water content measurements (-)

• k - corresponding hydraulic conductivity measurements (cm/d or m/s)

The SoilSample can be used with various functions to estimate soil hydraulic parameters through pedotransfer functions or curve fitting.

# Show all attributes of SoilSample class
print("SoilSample attributes:")
for attr, dtype in pe.SoilSample.__annotations__.items():
    print(f"  {attr}: {dtype}")

SoilSample attributes:
  sand_p: float | None
  silt_p: float | None
  clay_p: float | None
  rho: float | None
  th33: float | None
  th1500: float | None
  om_p: float | None
  m50: float | None
  d10: float | None
  d20: float | None
  h: numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] | None
  k: numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] | None
  theta: numpy.ndarray[tuple[typing.Any, ...], numpy.dtype[numpy.float64]] | None

Workflow Overview

The typical workflow in pedon could follow this pattern:

1. Create a ``SoilSample`` - from measured properties or existing data

2. Estimate parameters - using pedotransfer functions, HYPAGS, or other methods

3. Get a ``SoilModel`` - with parameters that describe water retention and conductivity

4. Use the model - evaluate properties at any pressure head, or export to external tools

In the following notebooks, you’ll learn how to work with each of these components and integrate them into your soil analysis workflows.