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
//! RBF kernel functions

/// Radial basis function kernel types
#[derive(Debug, Clone, Copy)]
pub enum RBFKernel {
    /// Thin plate spline: φ(r²) = 0.5·r²·ln(r²)
    ///
    /// Used in Diaw et al. for nuclear physics surrogate modeling.
    /// Exact interpolation of training data with good smoothness.
    ThinPlateSpline,

    /// Gaussian: φ(r) = exp(-ε²r²)
    ///
    /// Popular general-purpose kernel. Requires shape parameter ε.
    Gaussian {
        /// Shape parameter controlling kernel width.
        epsilon: f64,
    },

    /// Multiquadric: φ(r) = √(1 + ε²r²)
    ///
    /// Good for scattered data interpolation.
    Multiquadric {
        /// Shape parameter.
        epsilon: f64,
    },

    /// Inverse multiquadric: φ(r) = 1/√(1 + ε²r²)
    ///
    /// Produces smoother interpolants than multiquadric.
    InverseMultiquadric {
        /// Shape parameter.
        epsilon: f64,
    },

    /// Cubic: φ(r) = r³
    ///
    /// Simple kernel for 1D/2D interpolation.
    Cubic,

    /// Quintic: φ(r) = r⁵
    ///
    /// Higher-order smoothness than cubic.
    Quintic,
}

impl RBFKernel {
    /// Evaluate kernel at distance r
    #[must_use]
    pub fn eval(&self, r: f64) -> f64 {
        match self {
            Self::ThinPlateSpline => {
                if r < 1e-14 {
                    0.0 // Limit as r → 0
                } else {
                    let r2 = r * r;
                    0.5 * r2 * r2.ln()
                }
            }
            Self::Gaussian { epsilon } => {
                let er = epsilon * r;
                (-er * er).exp()
            }
            Self::Multiquadric { epsilon } => {
                let er2 = (epsilon * r).powi(2);
                (1.0 + er2).sqrt()
            }
            Self::InverseMultiquadric { epsilon } => {
                let er2 = (epsilon * r).powi(2);
                1.0 / (1.0 + er2).sqrt()
            }
            Self::Cubic => r.powi(3),
            Self::Quintic => r.powi(5),
        }
    }

    /// Name of the kernel
    #[must_use]
    pub fn name(&self) -> &str {
        match self {
            Self::ThinPlateSpline => "ThinPlateSpline",
            Self::Gaussian { .. } => "Gaussian",
            Self::Multiquadric { .. } => "Multiquadric",
            Self::InverseMultiquadric { .. } => "InverseMultiquadric",
            Self::Cubic => "Cubic",
            Self::Quintic => "Quintic",
        }
    }
}

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

    #[test]
    fn test_tps_kernel_at_zero() {
        let kernel = RBFKernel::ThinPlateSpline;
        assert_eq!(kernel.eval(0.0), 0.0);
    }

    #[test]
    fn test_tps_kernel_nonzero() {
        let kernel = RBFKernel::ThinPlateSpline;
        let r = 2.0;
        let expected = 0.5 * 4.0 * (4.0_f64).ln(); // 0.5 * r² * ln(r²)
        assert!((kernel.eval(r) - expected).abs() < 1e-12);
    }

    #[test]
    fn test_gaussian_kernel() {
        let kernel = RBFKernel::Gaussian { epsilon: 1.0 };
        assert!((kernel.eval(0.0) - 1.0).abs() < 1e-14);
        assert!((kernel.eval(1.0) - (-1.0_f64).exp()).abs() < 1e-14);
    }

    #[test]
    fn test_multiquadric_kernel() {
        let kernel = RBFKernel::Multiquadric { epsilon: 1.0 };
        assert!((kernel.eval(0.0) - 1.0).abs() < 1e-14);
        assert!((kernel.eval(1.0) - 2.0_f64.sqrt()).abs() < 1e-14);
    }

    #[test]
    fn test_cubic_kernel() {
        let kernel = RBFKernel::Cubic;
        assert_eq!(kernel.eval(0.0), 0.0);
        assert_eq!(kernel.eval(2.0), 8.0);
    }

    #[test]
    fn test_inverse_multiquadric_kernel() {
        let kernel = RBFKernel::InverseMultiquadric { epsilon: 1.0 };
        assert!((kernel.eval(0.0) - 1.0).abs() < 1e-14);
        assert!((kernel.eval(1.0) - (1.0 / 2.0_f64.sqrt())).abs() < 1e-14);
    }

    #[test]
    fn test_quintic_kernel() {
        let kernel = RBFKernel::Quintic;
        assert_eq!(kernel.eval(0.0), 0.0);
        assert_eq!(kernel.eval(2.0), 32.0);
    }

    #[test]
    fn test_kernel_names() {
        assert_eq!(RBFKernel::ThinPlateSpline.name(), "ThinPlateSpline");
        assert_eq!(RBFKernel::Gaussian { epsilon: 0.5 }.name(), "Gaussian");
        assert_eq!(
            RBFKernel::Multiquadric { epsilon: 1.0 }.name(),
            "Multiquadric"
        );
        assert_eq!(
            RBFKernel::InverseMultiquadric { epsilon: 1.0 }.name(),
            "InverseMultiquadric"
        );
        assert_eq!(RBFKernel::Cubic.name(), "Cubic");
        assert_eq!(RBFKernel::Quintic.name(), "Quintic");
    }

    #[test]
    fn test_tps_kernel_near_zero() {
        let kernel = RBFKernel::ThinPlateSpline;
        assert_eq!(kernel.eval(1e-15), 0.0);
    }
}