primal-barracuda 0.4.0

barraCuda — BARrier-free Rust Abstracted Cross-platform Unified Dimensional Algebra. Vendor-agnostic GPU compute via WGSL.
Documentation
// SPDX-License-Identifier: AGPL-3.0-or-later
//! CPU reference implementations for batched element-wise ops.
//!
//! Used for tests and validation against GPU results.

/// Hargreaves-Samani ET₀ (CPU reference) — FAO-56 Eq. 52
#[must_use]
pub fn hargreaves_et0_cpu(tmax: f64, tmin: f64, lat_rad: f64, doy: f64) -> f64 {
    use std::f64::consts::PI;
    let two_pi = 2.0 * PI;
    let dr = 0.033f64.mul_add((two_pi * doy / 365.0).cos(), 1.0);
    let decl = 0.409 * (two_pi * doy / 365.0 - 1.39).sin();
    let ws_arg = (-lat_rad.tan() * decl.tan()).clamp(-1.0, 1.0);
    let ws = ws_arg.acos();
    let ra_mj = 37.586
        * dr
        * (ws * lat_rad.sin()).mul_add(decl.sin(), lat_rad.cos() * decl.cos() * ws.sin());
    let ra_mm = ra_mj * 0.408;
    let tmean = (tmax + tmin) * 0.5;
    let td = (tmax - tmin).max(0.0);
    (0.0023 * (tmean + 17.8) * td.sqrt() * ra_mm).max(0.0)
}

/// FAO-56 Eq. 62 Kc climate adjustment (CPU reference)
#[must_use]
pub fn kc_climate_adjust_cpu(kc_table: f64, u2: f64, rh_min: f64, crop_height_m: f64) -> f64 {
    let adj =
        0.04f64.mul_add(u2 - 2.0, -(0.004 * (rh_min - 45.0))) * (crop_height_m / 3.0_f64).powf(0.3);
    (kc_table + adj).max(0.0)
}

/// Van Genuchten θ(h) — soil water content from matric head (CPU reference)
/// θ(h) = `θ_r` + (`θ_s` - `θ_r`) / [1 + (α|h|)^n]^m where m = 1 - 1/n
#[must_use]
pub fn van_genuchten_theta_cpu(theta_r: f64, theta_s: f64, alpha: f64, n: f64, h: f64) -> f64 {
    if h >= 0.0 {
        return theta_s;
    }
    let m = 1.0 - 1.0 / n;
    let alpha_h = alpha * (-h);
    let se = 1.0 / (1.0 + alpha_h.powf(n)).powf(m);
    (theta_s - theta_r).mul_add(se, theta_r)
}

/// Van Genuchten K(h) — hydraulic conductivity (CPU reference)
/// K(h) = `K_s` * `S_e^l` * [1 - (1 - `S_e^(1/m))^m`]^2
#[must_use]
pub fn van_genuchten_k_cpu(
    k_s: f64,
    _theta_r: f64,
    _theta_s: f64,
    alpha: f64,
    n: f64,
    l: f64,
    h: f64,
) -> f64 {
    if h >= 0.0 {
        return k_s;
    }
    let m = 1.0 - 1.0 / n;
    let alpha_h = alpha * (-h);
    let se = 1.0 / (1.0 + alpha_h.powf(n)).powf(m);
    let se_1m = se.powf(1.0 / m);
    let inner = 1.0 - (1.0 - se_1m).powf(m);
    k_s * se.powf(l) * inner * inner
}

/// Thornthwaite monthly ET₀ (CPU reference)
/// ET₀ = 16 * (10*`T_mean/I)^a` * (N/12) * (d/30)
#[must_use]
pub fn thornthwaite_et0_cpu(
    heat_index_i: f64,
    exponent_a: f64,
    daylight_hours_n: f64,
    days_in_month_d: f64,
    t_mean: f64,
) -> f64 {
    if t_mean <= 0.0 {
        return 0.0;
    }
    16.0 * (10.0 * t_mean / heat_index_i.max(0.001)).powf(exponent_a)
        * (daylight_hours_n / 12.0)
        * (days_in_month_d / 30.0)
}

/// Makkink (1957) ET₀ — radiation-based, Netherlands standard (CPU reference)
/// ET₀ = 0.61 * (Δ/(Δ+γ)) * Rs/λ − 0.12
#[must_use]
pub fn makkink_et0_cpu(rs_mj: f64, t_mean: f64, elevation: f64) -> f64 {
    let p = 101.3 * (0.0065f64.mul_add(-elevation, 293.0) / 293.0).powf(5.26);
    let gamma = 0.000665 * p;
    let e_t = 0.6108 * (17.27 * t_mean / (t_mean + 237.3)).exp();
    let delta = 4098.0 * e_t / (t_mean + 237.3_f64).powi(2);
    let lambda = 2.45;
    (0.61 * (delta / (delta + gamma)) * rs_mj / lambda - 0.12).max(0.0)
}

/// Turc (1961) ET₀ — radiation + temperature, humid climates (CPU reference)
/// ET₀ = 0.013 * (T/(T+15)) * (`Rs_cal` + 50) * `C_rh`
#[must_use]
pub fn turc_et0_cpu(rs_mj: f64, t_mean: f64, rh_mean: f64) -> f64 {
    let rs_cal = rs_mj * 23.8846;
    let c_rh = if rh_mean < 50.0 {
        1.0 + (50.0 - rh_mean) / 70.0
    } else {
        1.0
    };
    (0.013 * (t_mean / (t_mean + 15.0)) * (rs_cal + 50.0) * c_rh).max(0.0)
}

/// Hamon (1963) ET₀ — temperature + daylength only (CPU reference).
///
/// PET (mm/day) = 13.97 × D² × Pt
/// where D = `daylight_hours` / 12, Pt = 4.95 × exp(0.062 × T) / 100
/// (Pt approximates saturated vapor density in g/cm³; 13.97 = 0.55 × 25.4
/// converts the original inches/day to mm/day.)
///
/// Reference: Hamon (1963), "Estimating potential evapotranspiration", ASCE.
#[must_use]
pub fn hamon_et0_cpu(t_mean: f64, daylight_hours: f64) -> f64 {
    let d_ratio = daylight_hours / 12.0;
    let pt = 4.95 * (0.062 * t_mean).exp() / 100.0;
    (13.97 * d_ratio * d_ratio * pt).max(0.0)
}

/// SCS-CN Runoff (USDA TR-55) (CPU reference)
/// Q = (P − Ia)² / (P − Ia + S), S = 25400/CN − 254, Ia = `Ia_ratio` × S
#[must_use]
pub(crate) fn scs_cn_runoff_cpu(p: f64, cn: f64, ia_ratio: f64) -> f64 {
    if p <= 0.0 || cn <= 0.0 {
        return 0.0;
    }
    let s = 25400.0 / cn - 254.0;
    let ia = ia_ratio * s;
    if p <= ia {
        return 0.0;
    }
    let pe = p - ia;
    pe * pe / (pe + s)
}

/// Stewart (1977) yield-water function (CPU reference)
/// `Ya/Ym` = 1 − Ky × (1 − `ETa/ETc`)
#[must_use]
pub(crate) fn stewart_yield_water_cpu(ky: f64, eta_etc_ratio: f64) -> f64 {
    ky.mul_add(-(1.0 - eta_etc_ratio), 1.0)
}

/// Blaney-Criddle (1950) ET₀ (CPU reference)
/// ET₀ = p × (0.46 × T + 8.13) where p = `daylight_hours` / 43.80
#[must_use]
pub(crate) fn blaney_criddle_et0_cpu(t_mean: f64, daylight_hours: f64) -> f64 {
    let p = daylight_hours / 43.80;
    (p * 0.46f64.mul_add(t_mean, 8.13)).max(0.0)
}

/// Pedotransfer polynomial — Horner form (CPU reference)
/// y = a0 + x*(a1 + x*(a2 + x*(a3 + x*(a4 + x*a5))))
#[must_use]
pub fn pedotransfer_polynomial_cpu(
    a0: f64,
    a1: f64,
    a2: f64,
    a3: f64,
    a4: f64,
    a5: f64,
    x: f64,
) -> f64 {
    a5.mul_add(x, a4)
        .mul_add(x, a3)
        .mul_add(x, a2)
        .mul_add(x, a1)
        .mul_add(x, a0)
}

/// FAO-56 Penman-Monteith ET₀ (CPU reference)
pub(crate) fn fao56_et0_cpu(
    tmax: f64,
    tmin: f64,
    rh_max: f64,
    rh_min: f64,
    wind_2m: f64,
    rs: f64,
    elevation: f64,
    lat: f64,
    doy: u32,
) -> f64 {
    use std::f64::consts::PI;

    let tmean = f64::midpoint(tmax, tmin);

    // Atmospheric pressure (FAO-56 Eq. 7)
    let p = 101.3 * (0.0065f64.mul_add(-elevation, 293.0) / 293.0).powf(5.26);

    // Psychrometric constant
    let gamma = 0.000665 * p;

    // Saturation vapour pressure
    let e_tmax = 0.6108 * (17.27 * tmax / (tmax + 237.3)).exp();
    let e_tmin = 0.6108 * (17.27 * tmin / (tmin + 237.3)).exp();
    let es = f64::midpoint(e_tmax, e_tmin);

    // Actual vapour pressure
    let ea = f64::midpoint(e_tmin * rh_max / 100.0, e_tmax * rh_min / 100.0);

    // Slope of saturation vapour pressure curve
    let e_tmean = 0.6108 * (17.27 * tmean / (tmean + 237.3)).exp();
    let delta = 4098.0 * e_tmean / (tmean + 237.3).powi(2);

    // Extraterrestrial radiation
    let lat_rad = lat.to_radians();
    let dr = 0.033f64.mul_add((2.0 * PI * doy as f64 / 365.0).cos(), 1.0);
    let decl = 0.409 * (2.0 * PI * doy as f64 / 365.0 - 1.39).sin();

    let tan_lat = lat_rad.tan();
    let tan_decl = decl.tan();
    let ws_arg = -tan_lat * tan_decl;
    let ws = if ws_arg.abs() > 1.0 {
        PI
    } else {
        ws_arg.acos()
    };

    let gsc = 0.0820;
    let ra = 24.0 * 60.0 / PI
        * gsc
        * dr
        * (ws * lat_rad.sin()).mul_add(decl.sin(), lat_rad.cos() * decl.cos() * ws.sin());

    // Clear-sky radiation
    let rso = 0.00002f64.mul_add(elevation, 0.75) * ra;

    // Net shortwave radiation
    let rns = (1.0 - 0.23) * rs;

    // Net longwave radiation
    let sigma = 4.903e-9; // Stefan-Boltzmann constant
    let tmax_k = tmax + 273.16;
    let tmin_k = tmin + 273.16;
    let rnl = sigma * (tmax_k.powi(4) + tmin_k.powi(4)) / 2.0
        * 0.14f64.mul_add(-ea.sqrt(), 0.34)
        * (1.35 * rs / rso.max(0.001) - 0.35);

    // Net radiation
    let rn = rns - rnl;

    // FAO-56 Penman-Monteith equation
    let numerator =
        (0.408 * delta).mul_add(rn, gamma * 900.0 / (tmean + 273.0) * wind_2m * (es - ea));
    let denominator = delta + gamma * 0.34f64.mul_add(wind_2m, 1.0);

    numerator / denominator
}

/// Water balance daily update (CPU reference)
pub(crate) fn water_balance_cpu(
    dr_prev: f64,
    precip: f64,
    irrig: f64,
    etc: f64,
    taw: f64,
    raw: f64,
) -> f64 {
    // Stress coefficient
    let ks = if dr_prev > raw {
        ((taw - dr_prev) / (taw - raw)).max(0.0)
    } else {
        1.0
    };

    // Adjusted ETc
    let etc_adj = ks * etc;

    // New depletion
    let dr_new = dr_prev - precip - irrig + etc_adj;
    dr_new.clamp(0.0, taw)
}