ptfkit.ahuja1984

def calc_ptf_ahuja1984(
    *,
    total_porosity: float | ArrayLike,
    theta_33: float | ArrayLike,
    coefficient_b: float | ArrayLike,
    exponent_n: float | ArrayLike,
    out: NDArray[floating] | None = None,
) -> floating | NDArray[floating]:
    """Calculate the pedotransfer function.

    Estimate saturated hydraulic conductivity from total porosity and water content at -33 kPa using
    user-supplied empirical coefficients.

    Arguments:
        total_porosity: Total porosity; in the experiments it was taken as saturated volumetric
            water content. (cm^3/cm^3)
        theta_33: Volumetric soil water content at -33 kPa pressure head. (cm^3/cm^3)
        coefficient_b: Soil-specific empirical coefficient in the generalized Kozeny-Carman
            relation. (cm/h)
        exponent_n: Empirical exponent; the paper evaluates values of 4 and 5 for deriving
            conductivity scaling-factor distributions. (1)
        out: Optional output arrays for in-place calculation.

    Returns:
        k_sat: Saturated hydraulic conductivity. (cm/h)

    Territory:
        Chickasha, Oklahoma, and the Wahiawa Plateau, Oahu, Hawaii, USA

    Models:
        $k(h)$: Saturated hydraulic conductivity

    Notes:
        Prediction target: Saturated hydraulic conductivity from effective porosity, defined as
            total porosity minus volumetric water content at -33 kPa.
        Effective porosity is total_porosity - theta_33; the paper notes that field capacity is not
            a precisely defined soil parameter.
        Soil-core fitted exponents were near 4, whereas the smaller Hawaii field dataset had a
            fitted slope of 1.59 over a narrower effective-porosity range.

    Warning:
        The empirical coefficient B varies with soil type; callers must supply a coefficient
            calibrated for the soil being evaluated.
        Callers must supply the exponent. The paper evaluates both n = 4 and n = 5 and does not
            select one as a unique transferable value.
        total_porosity must be greater than or equal to theta_33.

    """
    return _call(
        _calc_ptf_ahuja1984,
        total_porosity,
        theta_33,
        coefficient_b,
        exponent_n,
        out=out,
    )