one-indexed-vec 0.2.0

A one-based (1-indexed) wrapper around Vec<T>: element at position N is accessed via vec[N].
Documentation
//! Probability distributions and their PDFs / CDFs.
//!
//! These are free functions because they take scalar parameters, not `Vec1`.

/// Standard normal PDF: `φ(x) = exp(-x²/2) / √(2π)`.
///
/// ```rust
/// use one_indexed_vec::stats::distribution::normal_pdf;
/// let p = normal_pdf(0.0, 0.0, 1.0);
/// assert!((p - 0.3989422804).abs() < 1e-6);
/// ```
pub fn normal_pdf(x: f64, mu: f64, sigma: f64) -> f64 {
    assert!(sigma > 0.0, "normal_pdf: sigma must be > 0");
    let z = (x - mu) / sigma;
    libm::exp(-0.5 * z * z) / (sigma * libm::sqrt(2.0 * core::f64::consts::PI))
}

/// Standard normal CDF: `Φ(x)` via the Abramowitz–Stegun approximation.
///
/// ```rust
/// use one_indexed_vec::stats::distribution::normal_cdf;
/// let p = normal_cdf(0.0, 0.0, 1.0);
/// assert!((p - 0.5).abs() < 1e-6);
/// ```
pub fn normal_cdf(x: f64, mu: f64, sigma: f64) -> f64 {
    assert!(sigma > 0.0, "normal_cdf: sigma must be > 0");
    let z = (x - mu) / (sigma * libm::sqrt(2.0));
    0.5 * (1.0 + erf(z))
}

/// Error function approximation (Abramowitz & Stegun 7.1.26).
fn erf(x: f64) -> f64 {
    let sign = if x < 0.0 { -1.0 } else { 1.0 };
    let x = x.abs();
    let t = 1.0 / (1.0 + 0.3275911 * x);
    let y = 1.0
        - (((((1.061405429 * t - 1.453152027) * t) + 1.421413741) * t - 0.284496736) * t
            + 0.254829592)
            * t
            * libm::exp(-x * x);
    sign * y
}

/// Exponential PDF: `λ · exp(-λ x)` for `x >= 0`.
pub fn exponential_pdf(x: f64, lambda: f64) -> f64 {
    assert!(lambda > 0.0, "exponential_pdf: lambda must be > 0");
    if x < 0.0 { 0.0 } else { lambda * libm::exp(-lambda * x) }
}

/// Exponential CDF: `1 - exp(-λ x)` for `x >= 0`.
pub fn exponential_cdf(x: f64, lambda: f64) -> f64 {
    assert!(lambda > 0.0, "exponential_cdf: lambda must be > 0");
    if x < 0.0 { 0.0 } else { 1.0 - libm::exp(-lambda * x) }
}

/// Uniform PDF on `[a, b]`.
pub fn uniform_pdf(x: f64, a: f64, b: f64) -> f64 {
    assert!(a < b, "uniform_pdf: a must be < b");
    if x < a || x > b { 0.0 } else { 1.0 / (b - a) }
}

/// Uniform CDF on `[a, b]`.
pub fn uniform_cdf(x: f64, a: f64, b: f64) -> f64 {
    assert!(a < b, "uniform_cdf: a must be < b");
    if x < a {
        0.0
    } else if x > b {
        1.0
    } else {
        (x - a) / (b - a)
    }
}

/// Standard normal quantile (inverse CDF) via Beasley-Springer-Moro.
///
/// ```rust
/// use one_indexed_vec::stats::distribution::normal_quantile;
/// let q = normal_quantile(0.5, 0.0, 1.0);
/// assert!(q.abs() < 1e-6);
/// ```
pub fn normal_quantile(p: f64, mu: f64, sigma: f64) -> f64 {
    assert!(sigma > 0.0, "normal_quantile: sigma must be > 0");
    assert!(p > 0.0 && p < 1.0, "normal_quantile: p must be in (0, 1)");
    // Rational approximation for the inverse normal CDF
    let t = if p < 0.5 {
        libm::sqrt(-2.0 * libm::log(p))
    } else {
        libm::sqrt(-2.0 * libm::log(1.0 - p))
    };
    let c0 = 2.515517;
    let c1 = 0.802853;
    let c2 = 0.010328;
    let d1 = 1.432788;
    let d2 = 0.189269;
    let d3 = 0.001308;
    let num = c0 + c1 * t + c2 * t * t;
    let den = 1.0 + d1 * t + d2 * t * t + d3 * t * t * t;
    let z = t - num / den;
    let z = if p < 0.5 { -z } else { z };
    mu + sigma * z
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn normal_pdf_peak() {
        let p = normal_pdf(0.0, 0.0, 1.0);
        assert!((p - 0.3989422804).abs() < 1e-6);
    }

    #[test]
    fn normal_cdf_center() {
        let p = normal_cdf(0.0, 0.0, 1.0);
        assert!((p - 0.5).abs() < 1e-6);
    }

    #[test]
    fn normal_cdf_tail() {
        let p = normal_cdf(-10.0, 0.0, 1.0);
        assert!(p < 1e-6);
    }

    #[test]
    fn exponential_pdf_basic() {
        let p = exponential_pdf(0.0, 1.0);
        assert!((p - 1.0).abs() < 1e-10);
    }

    #[test]
    fn exponential_cdf_basic() {
        let p = exponential_cdf(1.0, 1.0);
        assert!((p - (1.0 - (-1.0f64).exp())).abs() < 1e-10);
    }

    #[test]
    fn uniform_pdf_cdf() {
        assert!((uniform_pdf(0.5, 0.0, 1.0) - 1.0).abs() < 1e-10);
        assert!((uniform_cdf(0.5, 0.0, 1.0) - 0.5).abs() < 1e-10);
    }

    #[test]
    fn normal_quantile_median() {
        let q = normal_quantile(0.5, 0.0, 1.0);
        assert!(q.abs() < 1e-3);
    }

    #[test]
    fn normal_quantile_upper() {
        let q = normal_quantile(0.975, 0.0, 1.0);
        assert!((q - 1.96).abs() < 0.01);
    }
}