ptfkit.saxton2006

def calc_conductivity_saxton2006(
    *,
    theta: float | ArrayLike,
    theta_s: float | ArrayLike,
    saturated_conductivity: float | ArrayLike,
    conductivity_lambda: float | ArrayLike,
    out: NDArray[floating] | None = None,
) -> floating | NDArray[floating]:
    """Estimate unsaturated hydraulic conductivity from water content.

    Arguments:
        theta: Volumetric water content. (m^3/m^3)
        theta_s: Saturated volumetric water content. (m^3/m^3)
        saturated_conductivity: Saturated hydraulic conductivity of the matric soil. (mm/h)
        conductivity_lambda: Inverse of retention exponent B. (dimensionless)
        out: Optional output arrays for in-place calculation.

    Returns:
        conductivity: Unsaturated hydraulic conductivity at the supplied water content. (mm/h)

    Models:
        $k(h)$: Campbell unsaturated conductivity model

    Notes:
        Prediction target: Unsaturated hydraulic conductivity of the matric soil.

    Warning:
        The equation does not include residual water content.

    """
    return _call(
        _calc_ptf_saxton2006_conductivity,
        theta,
        theta_s,
        saturated_conductivity,
        conductivity_lambda,
        out=out,
    )

def calc_density_adjustment_saxton2006(
    *,
    normal_density: float | ArrayLike,
    theta_s: float | ArrayLike,
    theta_33: float | ArrayLike,
    density_factor: float | ArrayLike,
    out: Saxton2006DensityResult[NDArray[floating]] | None = None,
) -> Saxton2006DensityResult[floating] | Saxton2006DensityResult[NDArray[floating]]:
    r"""Adjust Saxton and Rawls water characteristics for soil density.

    Arguments:
        normal_density: Normal dry bulk density estimated by the base model. (g/cm^3)
        theta_s: Saturated water content at normal density. (m^3/m^3)
        theta_33: Water content at 33 kPa and normal density. (m^3/m^3)
        density_factor: Multiplicative adjustment to normal density. (dimensionless)
        out: Optional output arrays for in-place calculation.

    Returns:
        Saxton2006DensityResult: Results grouped by result attributes.

    Models:
        $h(\theta)$: Density adjustment to the point estimates

    Notes:
        Prediction target: Density-adjusted saturation and 33 kPa water contents.
        The source limits the saturation-minus-33 kPa difference to at least 0.005 m^3/m^3.

    Warning:
        The source recommends density factors only from 0.9 to 1.3.

    """
    values = _call(
        _calc_ptf_saxton2006_density,
        normal_density,
        theta_s,
        theta_33,
        density_factor,
        out=out,
    )

    return Saxton2006DensityResult(*values)

def calc_gravel_adjustment_saxton2006(
    *,
    gravel_weight_fraction: float | ArrayLike,
    matric_density: float | ArrayLike,
    plant_available_water: float | ArrayLike,
    saturated_conductivity: float | ArrayLike,
    out: Saxton2006GravelResult[NDArray[floating]] | None = None,
) -> Saxton2006GravelResult[floating] | Saxton2006GravelResult[NDArray[floating]]:
    r"""Adjust matric-soil properties for gravel content.

    Arguments:
        gravel_weight_fraction: Gravel mass fraction of the bulk soil. (g/g)
        matric_density: Dry bulk density of the fine-earth matric soil. (g/cm^3)
        plant_available_water: Plant-available water of the matric soil. (m^3/m^3)
        saturated_conductivity: Saturated hydraulic conductivity of the matric soil. (mm/h)
        out: Optional output arrays for in-place calculation.

    Returns:
        Saxton2006GravelResult: Results grouped by result attributes.

    Models:
        $h(\theta)$: Gravel reduction of plant-available water
        $k(h)$: Peck-Watson conductivity reduction

    Notes:
        Prediction target: Gravel volume, bulk density, available water, and saturated conductivity.
        Gravel comprises particles larger than 2 mm.
        Gravel density is fixed at 2.65 g/cm^3 in the source equations.

    Warning:
        The conductivity correction does not represent extra macropores sometimes found in gravelly
            soils.

    """
    values = _call(
        _calc_ptf_saxton2006_gravel,
        gravel_weight_fraction,
        matric_density,
        plant_available_water,
        saturated_conductivity,
        out=out,
    )

    return Saxton2006GravelResult(*values)

def calc_osmotic_potential_saxton2006(
    *,
    electrical_conductivity: float | ArrayLike,
    theta: float | ArrayLike,
    theta_s: float | ArrayLike,
    out: Saxton2006SalinityResult[NDArray[floating]] | None = None,
) -> Saxton2006SalinityResult[floating] | Saxton2006SalinityResult[NDArray[floating]]:
    r"""Estimate saturated and moisture-adjusted osmotic potential.

    Arguments:
        electrical_conductivity: Electrical conductivity of a saturated soil extract. (dS/m)
        theta: Current volumetric water content. (m^3/m^3)
        theta_s: Saturated volumetric water content. (m^3/m^3)
        out: Optional output arrays for in-place calculation.

    Returns:
        Saxton2006SalinityResult: Results grouped by result attributes.

    Models:
        $h(\theta)$: Matric-plus-osmotic tension adjustment

    Notes:
        Prediction target: Osmotic potential from saturated-extract electrical conductivity.
        The moisture adjustment assumes dissolved salt quantity remains near constant as water
            content falls.

    Warning:
        Precipitation, bonding, ionic nutrition, and toxicity can modify actual salinity effects.

    """
    values = _call(
        _calc_ptf_saxton2006_salinity,
        electrical_conductivity,
        theta,
        theta_s,
        out=out,
    )

    return Saxton2006SalinityResult(*values)

def calc_ptf_saxton2006(
    *,
    sand: float | ArrayLike,
    clay: float | ArrayLike,
    organic_matter: float | ArrayLike,
    out: Saxton2006PTFResult[NDArray[floating]] | None = None,
) -> Saxton2006PTFResult[floating] | Saxton2006PTFResult[NDArray[floating]]:
    r"""Estimate soil water characteristics from sand, clay, and organic matter.

    Arguments:
        sand: Sand mass fraction of the fine-earth soil. (g/g)
        clay: Clay mass fraction of the fine-earth soil. (g/g)
        organic_matter: Organic matter content on a mass percentage basis. (% mass)
        out: Optional output arrays for in-place calculation.

    Returns:
        Saxton2006PTFResult: Results grouped by result attributes.

    Models:
        $h(\theta)$: Campbell power function with a linear wet-range segment
        $k(h)$: Campbell unsaturated conductivity model

    Notes:
        Prediction target: Water contents at 1500, 33, and 0 kPa, plant-available water, air-entry
            tension, retention coefficients, normal density, and saturated hydraulic conductivity.
        Sand and clay are decimal mass fractions, while organic matter is a percentage.
        The 1500 and 33 kPa values are also termed wilting point and field capacity.

    Warning:
        Do not apply the regression above 8% organic matter or 60% clay.
        Sand and clay fractions must describe one soil and therefore must sum to at most 1.
        These statistical-average estimates should be calibrated to local measurements when
            available.

    """
    values = _call(
        _calc_ptf_saxton2006,
        sand,
        clay,
        organic_matter,
        out=out,
    )

    return Saxton2006PTFResult(*values)

def calc_tension_dry_saxton2006(
    *,
    theta: float | ArrayLike,
    theta_1500: float | ArrayLike,
    theta_33: float | ArrayLike,
    out: NDArray[floating] | None = None,
) -> floating | NDArray[floating]:
    r"""Estimate matric tension in the 1500 to 33 kPa segment.

    Arguments:
        theta: Volumetric water content. (m^3/m^3)
        theta_1500: Volumetric water content at 1500 kPa. (m^3/m^3)
        theta_33: Volumetric water content at 33 kPa. (m^3/m^3)
        out: Optional output arrays for in-place calculation.

    Returns:
        tension: Matric tension at the supplied water content. (kPa)

    Models:
        $h(\theta)$: Campbell power function

    Notes:
        Prediction target: Matric tension for water content between theta_1500 and theta_33.

    Warning:
        Use only for the 1500 to 33 kPa segment defined by the source.

    """
    return _call(
        _calc_ptf_saxton2006_tension_dry,
        theta,
        theta_1500,
        theta_33,
        out=out,
    )

def calc_tension_wet_saxton2006(
    *,
    theta: float | ArrayLike,
    theta_33: float | ArrayLike,
    theta_s: float | ArrayLike,
    air_entry_tension: float | ArrayLike,
    out: NDArray[floating] | None = None,
) -> floating | NDArray[floating]:
    r"""Estimate matric tension in the 33 kPa to air-entry segment.

    Arguments:
        theta: Volumetric water content. (m^3/m^3)
        theta_33: Volumetric water content at 33 kPa. (m^3/m^3)
        theta_s: Saturated volumetric water content. (m^3/m^3)
        air_entry_tension: Air-entry tension estimated by the base model. (kPa)
        out: Optional output arrays for in-place calculation.

    Returns:
        tension: Matric tension at the supplied water content. (kPa)

    Models:
        $h(\theta)$: Linear wet-range segment

    Notes:
        Prediction target: Matric tension for water content between theta_33 and theta_s.
        At tensions below air entry, Equation 13 fixes water content at theta_s.

    Warning:
        Use only for the 33 kPa to air-entry segment defined by the source.

    """
    return _call(
        _calc_ptf_saxton2006_tension_wet,
        theta,
        theta_33,
        theta_s,
        air_entry_tension,
        out=out,
    )