use super::{
Triangle, require_same_shape, require_square_pair, validate_log_positive,
validate_positive_finite, write_square,
};
use crate::error::GprError;
use crate::kernel::KernelScalar;
use crate::param::{BoundedParam, Interval};
use faer::{MatMut, MatRef};
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct WhiteKernel {
variance: BoundedParam,
}
impl WhiteKernel {
pub fn new(variance: f64) -> Result<Self, GprError> {
validate_positive_finite(variance, "white kernel variance")?;
Ok(Self {
variance: BoundedParam::default_positive(variance)?,
})
}
pub fn from_log_variance(log_variance: f64) -> Result<Self, GprError> {
let log_variance = validate_log_positive(log_variance, "white kernel variance")?;
Ok(Self {
variance: BoundedParam::default_positive(log_variance.exp())?,
})
}
pub fn variance(&self) -> f64 {
self.variance.value()
}
pub fn log_variance(&self) -> f64 {
self.variance.ln()
}
pub fn bounds(&self) -> Interval {
self.variance.interval()
}
pub fn with_bounds(self, interval: Interval) -> Result<Self, crate::IntervalError> {
Ok(Self {
variance: self.variance.with_interval(interval)?,
})
}
pub fn num_params(&self) -> usize {
1
}
pub fn get_params(&self, out: &mut [f64]) -> Result<(), GprError> {
crate::data::require_count(out.len(), 1, "white parameter")?;
out[0] = self.variance.ln();
Ok(())
}
pub fn set_params(&mut self, params: &[f64]) -> Result<(), GprError> {
crate::data::require_count(params.len(), 1, "white parameter")?;
let log_variance = validate_log_positive(params[0], "white kernel variance")?;
self.variance = BoundedParam::new(log_variance.exp(), self.variance.interval())?;
Ok(())
}
pub fn apply<T: KernelScalar>(
&self,
dist: MatRef<'_, T>,
out: MatMut<'_, T>,
uplo: Triangle,
) -> Result<(), GprError> {
require_square_pair(dist, out.as_ref())?;
self.write_square(out, uplo)
}
pub fn apply_cross<T: KernelScalar>(
&self,
dist: MatRef<'_, T>,
mut out: MatMut<'_, T>,
) -> Result<(), GprError> {
require_same_shape(dist, out.as_ref())?;
for col in 0..out.ncols() {
for row in 0..out.nrows() {
out[(row, col)] = T::from_f64(0.0);
}
}
Ok(())
}
pub fn apply_points<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
out: MatMut<'_, T>,
uplo: Triangle,
) -> Result<(), GprError> {
require_columns(x)?;
self.apply_rows(x, out, uplo)
}
pub(crate) fn apply_rows<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
out: MatMut<'_, T>,
uplo: Triangle,
) -> Result<(), GprError> {
require_points_square(x, out.as_ref())?;
self.write_square(out, uplo)
}
pub fn apply_cross_points<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
xs: MatRef<'_, T>,
out: MatMut<'_, T>,
) -> Result<(), GprError> {
require_columns(x)?;
require_columns(xs)?;
self.apply_cross_rows(x, xs, out)
}
pub(crate) fn apply_cross_rows<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
xs: MatRef<'_, T>,
mut out: MatMut<'_, T>,
) -> Result<(), GprError> {
require_cross_points(x, xs, out.as_ref())?;
for col in 0..out.ncols() {
for row in 0..out.nrows() {
out[(row, col)] = T::from_f64(0.0);
}
}
Ok(())
}
pub fn fill_diag<T: KernelScalar>(&self, out: &mut [T]) {
out.fill(T::from_f64(self.variance()));
}
pub fn grad<T: KernelScalar>(
&self,
dist: MatRef<'_, T>,
d_k: MatMut<'_, T>,
param_idx: usize,
uplo: Triangle,
) -> Result<(), GprError> {
require_param_idx(param_idx)?;
require_square_pair(dist, d_k.as_ref())?;
self.write_square(d_k, uplo)
}
pub fn grad_points<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
d_k: MatMut<'_, T>,
param_idx: usize,
uplo: Triangle,
) -> Result<(), GprError> {
require_columns(x)?;
self.grad_rows(x, d_k, param_idx, uplo)
}
pub(crate) fn grad_rows<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
d_k: MatMut<'_, T>,
param_idx: usize,
uplo: Triangle,
) -> Result<(), GprError> {
require_param_idx(param_idx)?;
require_points_square(x, d_k.as_ref())?;
self.write_square(d_k, uplo)
}
pub fn hess<T: KernelScalar>(
&self,
dist: MatRef<'_, T>,
d2_k: MatMut<'_, T>,
i: usize,
j: usize,
uplo: Triangle,
) -> Result<(), GprError> {
require_hess_idx(i, j)?;
require_square_pair(dist, d2_k.as_ref())?;
self.write_square(d2_k, uplo)
}
pub fn hess_points<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
d2_k: MatMut<'_, T>,
i: usize,
j: usize,
uplo: Triangle,
) -> Result<(), GprError> {
require_columns(x)?;
self.hess_rows(x, d2_k, i, j, uplo)
}
pub(crate) fn hess_rows<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
d2_k: MatMut<'_, T>,
i: usize,
j: usize,
uplo: Triangle,
) -> Result<(), GprError> {
require_hess_idx(i, j)?;
require_points_square(x, d2_k.as_ref())?;
self.write_square(d2_k, uplo)
}
pub fn grad_wrt_coord_dim<T: KernelScalar>(
&self,
x1: MatRef<'_, T>,
x2: MatRef<'_, T>,
mut d_k: MatMut<'_, T>,
dim: usize,
) -> Result<(), GprError> {
super::require_coord_grad(x1, x2, d_k.as_ref(), dim)?;
for col in 0..d_k.ncols() {
for row in 0..d_k.nrows() {
d_k[(row, col)] = T::from_f64(0.0);
}
}
Ok(())
}
pub(crate) fn hess_wrt_coord_dims<T: KernelScalar>(
&self,
x1: MatRef<'_, T>,
x2: MatRef<'_, T>,
mut d2_k: MatMut<'_, T>,
dim_a: usize,
dim_b: usize,
) -> Result<(), GprError> {
super::require_coord_grad(x1, x2, d2_k.as_ref(), dim_a)?;
super::require_coord_grad(x1, x2, d2_k.as_ref(), dim_b)?;
fill_zero(d2_k.as_mut());
Ok(())
}
pub(crate) fn hess_wrt_coord_mixed<T: KernelScalar>(
&self,
x1: MatRef<'_, T>,
x2: MatRef<'_, T>,
mut d2_k: MatMut<'_, T>,
dim_x1: usize,
dim_x2: usize,
) -> Result<(), GprError> {
super::require_coord_grad(x1, x2, d2_k.as_ref(), dim_x1)?;
super::require_coord_grad(x1, x2, d2_k.as_ref(), dim_x2)?;
fill_zero(d2_k.as_mut());
Ok(())
}
pub(crate) fn hess_theta_coord_dim<T: KernelScalar>(
&self,
x1: MatRef<'_, T>,
x2: MatRef<'_, T>,
mut d2_k: MatMut<'_, T>,
param_idx: usize,
dim: usize,
) -> Result<(), GprError> {
require_param_idx(param_idx)?;
super::require_coord_grad(x1, x2, d2_k.as_ref(), dim)?;
fill_zero(d2_k.as_mut());
Ok(())
}
fn write_square<T: KernelScalar>(
&self,
out: MatMut<'_, T>,
uplo: Triangle,
) -> Result<(), GprError> {
let var = T::from_f64(self.variance());
write_square(out, uplo, |row, col| {
Ok(if row == col { var } else { T::from_f64(0.0) })
})
}
}
fn fill_zero<T: KernelScalar>(mut out: MatMut<'_, T>) {
for col in 0..out.ncols() {
for row in 0..out.nrows() {
out[(row, col)] = T::from_f64(0.0);
}
}
}
fn require_param_idx(param_idx: usize) -> Result<(), GprError> {
if param_idx == 0 {
Ok(())
} else {
Err(GprError::IndexOutOfRange {
reason: "white kernel has a single parameter at index 0".to_owned(),
})
}
}
fn require_hess_idx(i: usize, j: usize) -> Result<(), GprError> {
if i == 0 && j == 0 {
Ok(())
} else {
Err(GprError::IndexOutOfRange {
reason: format!("white kernel has a single parameter; got pair ({i}, {j})"),
})
}
}
fn require_points_square<T: KernelScalar>(
x: MatRef<'_, T>,
out: MatRef<'_, T>,
) -> Result<(), GprError> {
if x.nrows() == 0 {
return Err(GprError::EmptyInput);
}
if out.nrows() != x.nrows() || out.ncols() != x.nrows() {
return Err(GprError::ShapeMismatch {
reason: format!(
"output is {}x{}, expected {}x{}",
out.nrows(),
out.ncols(),
x.nrows(),
x.nrows()
),
});
}
Ok(())
}
fn require_cross_points<T: KernelScalar>(
x: MatRef<'_, T>,
xs: MatRef<'_, T>,
out: MatRef<'_, T>,
) -> Result<(), GprError> {
if x.nrows() == 0 || xs.nrows() == 0 {
return Err(GprError::EmptyInput);
}
if out.nrows() != x.nrows() || out.ncols() != xs.nrows() {
return Err(GprError::ShapeMismatch {
reason: format!(
"output is {}x{}, expected {}x{}",
out.nrows(),
out.ncols(),
x.nrows(),
xs.nrows()
),
});
}
Ok(())
}
fn require_columns<T>(x: MatRef<'_, T>) -> Result<(), GprError> {
if x.ncols() == 0 {
return Err(GprError::EmptyInput);
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::WhiteKernel;
use crate::error::GprError;
use crate::kernel::Triangle;
use faer::{Mat, mat};
const TOL: f64 = 1e-8;
use crate::test_check::{assert_close, assert_lower_close, fill};
fn dummy_dist(n: usize) -> Mat<f64> {
Mat::zeros(n, n)
}
#[test]
fn apply_is_diagonal_even_when_dist_is_zero() {
let kernel = WhiteKernel::new(0.4).expect("valid");
let dist = dummy_dist(3);
let mut k = fill(3, 1.0);
kernel
.apply(dist.as_ref(), k.as_mut(), Triangle::Full)
.expect("shape");
for col in 0..3 {
for row in 0..3 {
let expected = if row == col { 0.4 } else { 0.0 };
assert_close(k[(row, col)], expected, TOL);
assert_close(k[(row, col)], k[(col, row)], TOL);
}
}
}
#[test]
fn lower_matches_full_and_leaves_upper() {
let kernel = WhiteKernel::new(0.2).expect("valid");
let dist = dummy_dist(3);
let mut full = fill(3, 0.0);
kernel
.apply(dist.as_ref(), full.as_mut(), Triangle::Full)
.expect("shape");
let mut lower = fill(3, 42.0);
kernel
.apply(dist.as_ref(), lower.as_mut(), Triangle::Lower)
.expect("shape");
assert_lower_close(lower.as_ref(), full.as_ref(), TOL);
assert_close(lower[(0, 1)], 42.0, TOL);
}
#[test]
fn apply_cross_is_zero() {
let kernel = WhiteKernel::new(1.0).expect("valid");
let dist = mat![[0.0, 0.0], [1.0, 0.0]];
let mut out = fill(2, 9.0);
kernel
.apply_cross(dist.as_ref(), out.as_mut())
.expect("rect");
assert_close(out[(0, 0)], 0.0, TOL);
assert_close(out[(0, 1)], 0.0, TOL);
}
#[test]
fn grad_matches_finite_difference() {
let kernel = WhiteKernel::from_log_variance(-1.0).expect("valid");
let theta = kernel.log_variance();
let h = 1e-6;
let plus = WhiteKernel::from_log_variance(theta + h).expect("valid");
let minus = WhiteKernel::from_log_variance(theta - h).expect("valid");
let dist = dummy_dist(2);
let mut kp = fill(2, 0.0);
let mut km = fill(2, 0.0);
let mut dk = fill(2, 0.0);
plus.apply(dist.as_ref(), kp.as_mut(), Triangle::Full)
.expect("shape");
minus
.apply(dist.as_ref(), km.as_mut(), Triangle::Full)
.expect("shape");
kernel
.grad(dist.as_ref(), dk.as_mut(), 0, Triangle::Full)
.expect("idx 0");
let fd = (kp[(0, 0)] - km[(0, 0)]) / (2.0 * h);
assert_close(dk[(0, 0)], fd, TOL);
assert_close(dk[(0, 1)], 0.0, TOL);
}
#[test]
fn get_set_params_roundtrip() {
let mut kernel = WhiteKernel::new(0.3).expect("valid");
let mut params = [0.0];
kernel.get_params(&mut params).expect("len 1");
assert_close(params[0], 0.3_f64.ln(), TOL);
params[0] = 0.1_f64.ln();
kernel.set_params(¶ms).expect("len 1");
assert_close(kernel.variance(), 0.1, TOL);
}
#[test]
fn rejects_non_positive() {
assert!(matches!(
WhiteKernel::new(0.0),
Err(GprError::InvalidHyperparameter { .. })
));
}
}