pub struct WhiteKernel { /* private fields */ }Expand description
Evaluates the white (nugget) kernel σw² on the training diagonal and zero elsewhere.
The optimizer parameter is θ = log(σw²). Cross-covariance is identically
zero. Observation noise belongs in crate::GaussianLikelihood; do not
also add a large white kernel, which double-counts noise. Cholesky jitter
is a separate numerical stabilizer.
§Examples
use faer::Mat;
use gprx::Interval;
use gprx::kernel::{Triangle, WhiteKernel};
// Parameter: `θ = log(σw²)`; the bounds are on `σw²`.
let k = WhiteKernel::new(0.05)?;
assert!((k.variance() - 0.05).abs() < 1e-12);
let same = WhiteKernel::from_log_variance(k.log_variance())?;
assert!((same.variance() - 0.05).abs() < 1e-12);
let mut k = k.with_bounds(Interval::new(1e-4, 1.0)?)?;
assert!((k.bounds().hi() - 1.0).abs() < 1e-12);
let mut theta = vec![0.0; k.num_params()];
k.get_params(&mut theta)?;
k.set_params(&[0.1_f64.ln()])?; // σw² = 0.1
// `dist` (squared distances) and `x` (coordinates) only give the shape.
let dist = Mat::<f64>::zeros(3, 3);
let x = Mat::from_fn(3, 1, |i, _| i as f64);
let mut gram = Mat::<f64>::zeros(3, 3);
k.apply(dist.as_ref(), gram.as_mut(), Triangle::Full)?;
assert!((gram[(1, 1)] - 0.1).abs() < 1e-12);
assert!(gram[(1, 0)].abs() < 1e-12);
k.apply_points(x.as_ref(), gram.as_mut(), Triangle::Lower)?;
// Train × query is zero.
let xs = Mat::from_fn(1, 1, |_, _| 0.5);
let mut k_cross = Mat::<f64>::zeros(3, 1);
k.apply_cross(Mat::<f64>::zeros(3, 1).as_ref(), k_cross.as_mut())?;
k.apply_cross_points(x.as_ref(), xs.as_ref(), k_cross.as_mut())?;
let mut diag = [0.0; 3];
k.fill_diag(&mut diag);
// ∂K/∂θ and ∂²K/∂θ² are `σw²` on the diagonal, from either view; the
// coordinate derivative is zero.
let mut d_k = Mat::<f64>::zeros(3, 3);
k.grad(dist.as_ref(), d_k.as_mut(), 0, Triangle::Lower)?;
k.grad_points(x.as_ref(), d_k.as_mut(), 0, Triangle::Lower)?;
let mut d2_k = Mat::<f64>::zeros(3, 3);
k.hess(dist.as_ref(), d2_k.as_mut(), 0, 0, Triangle::Lower)?;
k.hess_points(x.as_ref(), d2_k.as_mut(), 0, 0, Triangle::Lower)?;
let mut d_x = Mat::<f64>::zeros(3, 1);
k.grad_wrt_coord_dim(x.as_ref(), xs.as_ref(), d_x.as_mut(), 0)?;Implementations§
Source§impl WhiteKernel
impl WhiteKernel
Sourcepub fn new(variance: f64) -> Result<Self, GprError>
pub fn new(variance: f64) -> Result<Self, GprError>
Builds a white kernel from a positive finite variance σw².
§Errors
Returns GprError::InvalidHyperparameter if variance is not finite
or not strictly positive, or GprError::InvalidInterval if it is
not inside Interval::DEFAULT_POSITIVE, the bounds a new leaf
starts with.
See the example on WhiteKernel.
Sourcepub fn from_log_variance(log_variance: f64) -> Result<Self, GprError>
pub fn from_log_variance(log_variance: f64) -> Result<Self, GprError>
Builds a white kernel from θ = log(σw²).
§Errors
Returns GprError::InvalidHyperparameter if θ is not finite, if
exp(θ) overflows, or if exp(θ) underflows to zero, or
GprError::InvalidInterval if exp(θ) is not inside
Interval::DEFAULT_POSITIVE.
See the example on WhiteKernel.
Sourcepub fn variance(&self) -> f64
pub fn variance(&self) -> f64
Returns σw² = exp(θ).
See the example on WhiteKernel.
Sourcepub fn log_variance(&self) -> f64
pub fn log_variance(&self) -> f64
Returns θ = log(σw²).
See the example on WhiteKernel.
Sourcepub fn bounds(&self) -> Interval
pub fn bounds(&self) -> Interval
Returns the open interval on σw².
See the example on WhiteKernel.
Sourcepub fn with_bounds(self, interval: Interval) -> Result<Self, IntervalError>
pub fn with_bounds(self, interval: Interval) -> Result<Self, IntervalError>
Rebuilds this kernel with a new interval on σw².
§Errors
Returns crate::IntervalError if the current σw² is not strictly
inside interval.
See the example on WhiteKernel.
Sourcepub fn num_params(&self) -> usize
pub fn num_params(&self) -> usize
Returns the number of optimizer parameters (always 1).
See the example on WhiteKernel.
Sourcepub fn get_params(&self, out: &mut [f64]) -> Result<(), GprError>
pub fn get_params(&self, out: &mut [f64]) -> Result<(), GprError>
Writes θ into a length-1 slice.
§Errors
Returns GprError::LengthMismatch if out is not length 1.
See the example on WhiteKernel.
Sourcepub fn set_params(&mut self, params: &[f64]) -> Result<(), GprError>
pub fn set_params(&mut self, params: &[f64]) -> Result<(), GprError>
Replaces θ from a length-1 slice.
§Errors
Returns GprError::LengthMismatch if params is not length 1,
GprError::InvalidHyperparameter if the new θ is invalid, or
GprError::InvalidInterval if the new σw² is not inside
Self::bounds.
See the example on WhiteKernel.
Sourcepub fn apply<T: KernelScalar>(
&self,
dist: MatRef<'_, T>,
out: MatMut<'_, T>,
uplo: Triangle,
) -> Result<(), GprError>
pub fn apply<T: KernelScalar>( &self, dist: MatRef<'_, T>, out: MatMut<'_, T>, uplo: Triangle, ) -> Result<(), GprError>
Writes σw² on the diagonal of out and zero off-diagonal.
Duplicate training points still get the nugget only on i = j, not
from a zero distance. dist is used only for shape checks.
§Errors
Returns GprError::ShapeMismatch if dist is not square or out is not
its shape, or GprError::EmptyInput if they are empty.
See the example on WhiteKernel.
Sourcepub fn apply_cross<T: KernelScalar>(
&self,
dist: MatRef<'_, T>,
out: MatMut<'_, T>,
) -> Result<(), GprError>
pub fn apply_cross<T: KernelScalar>( &self, dist: MatRef<'_, T>, out: MatMut<'_, T>, ) -> Result<(), GprError>
Writes a zero rectangular cross-covariance.
§Errors
Returns GprError::ShapeMismatch if out is not the shape of dist, or
GprError::EmptyInput if they are empty.
See the example on WhiteKernel.
Sourcepub fn apply_points<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
out: MatMut<'_, T>,
uplo: Triangle,
) -> Result<(), GprError>
pub fn apply_points<T: KernelScalar>( &self, x: MatRef<'_, T>, out: MatMut<'_, T>, uplo: Triangle, ) -> Result<(), GprError>
Writes the square white kernel from the number of rows of x.
§Errors
Returns GprError::EmptyInput if x has no row or no column, or
GprError::ShapeMismatch if out is not n×n.
See the example on WhiteKernel.
Sourcepub fn apply_cross_points<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
xs: MatRef<'_, T>,
out: MatMut<'_, T>,
) -> Result<(), GprError>
pub fn apply_cross_points<T: KernelScalar>( &self, x: MatRef<'_, T>, xs: MatRef<'_, T>, out: MatMut<'_, T>, ) -> Result<(), GprError>
Writes a zero rectangular cross-covariance from coordinates.
§Errors
Returns GprError::EmptyInput if x or xs has no row or no column, or
GprError::ShapeMismatch if out is not x.nrows() × xs.nrows().
See the example on WhiteKernel.
Sourcepub fn fill_diag<T: KernelScalar>(&self, out: &mut [T])
pub fn fill_diag<T: KernelScalar>(&self, out: &mut [T])
Writes the diagonal k(x, x) = σw² into out.
See the example on WhiteKernel.
Sourcepub fn grad<T: KernelScalar>(
&self,
dist: MatRef<'_, T>,
d_k: MatMut<'_, T>,
param_idx: usize,
uplo: Triangle,
) -> Result<(), GprError>
pub fn grad<T: KernelScalar>( &self, dist: MatRef<'_, T>, d_k: MatMut<'_, T>, param_idx: usize, uplo: Triangle, ) -> Result<(), GprError>
Writes ∂K/∂θ for θ = log(σw²) (σw² on the diagonal).
§Errors
Returns GprError::IndexOutOfRange if param_idx is not 0, or
the same shape errors as Self::apply.
See the example on WhiteKernel.
Sourcepub fn grad_points<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
d_k: MatMut<'_, T>,
param_idx: usize,
uplo: Triangle,
) -> Result<(), GprError>
pub fn grad_points<T: KernelScalar>( &self, x: MatRef<'_, T>, d_k: MatMut<'_, T>, param_idx: usize, uplo: Triangle, ) -> Result<(), GprError>
Writes ∂K/∂θ from coordinates.
x is used only for shape.
§Errors
Same as Self::grad, with x in place of dist.
See the example on WhiteKernel.
Sourcepub fn hess<T: KernelScalar>(
&self,
dist: MatRef<'_, T>,
d2_k: MatMut<'_, T>,
i: usize,
j: usize,
uplo: Triangle,
) -> Result<(), GprError>
pub fn hess<T: KernelScalar>( &self, dist: MatRef<'_, T>, d2_k: MatMut<'_, T>, i: usize, j: usize, uplo: Triangle, ) -> Result<(), GprError>
Writes ∂²K/∂θ² for θ = log(σw²) (σw² on the diagonal).
§Errors
Returns GprError::IndexOutOfRange if i or j is not 0, or
the same shape errors as Self::apply.
See the example on WhiteKernel.
Sourcepub fn hess_points<T: KernelScalar>(
&self,
x: MatRef<'_, T>,
d2_k: MatMut<'_, T>,
i: usize,
j: usize,
uplo: Triangle,
) -> Result<(), GprError>
pub fn hess_points<T: KernelScalar>( &self, x: MatRef<'_, T>, d2_k: MatMut<'_, T>, i: usize, j: usize, uplo: Triangle, ) -> Result<(), GprError>
Writes ∂²K/∂θ² from coordinates.
x is used only for shape.
§Errors
Same as Self::hess, with x in place of dist.
See the example on WhiteKernel.
Sourcepub fn grad_wrt_coord_dim<T: KernelScalar>(
&self,
x1: MatRef<'_, T>,
x2: MatRef<'_, T>,
d_k: MatMut<'_, T>,
dim: usize,
) -> Result<(), GprError>
pub fn grad_wrt_coord_dim<T: KernelScalar>( &self, x1: MatRef<'_, T>, x2: MatRef<'_, T>, d_k: MatMut<'_, T>, dim: usize, ) -> Result<(), GprError>
Writes the zero coordinate derivative of a white kernel.
Cross-covariance is identically zero, and the square diagonal does not depend on coordinates.
§Errors
Returns GprError::EmptyInput if a view is empty,
GprError::DimensionMismatch if x1 and x2 have different column
counts, GprError::IndexOutOfRange if dim is not a column, or
GprError::ShapeMismatch if d_k is not x1.nrows() × x2.nrows().
See the example on WhiteKernel.
Trait Implementations§
Source§impl<C: PointUse> Add<DistanceKernel<C>> for WhiteKernel
impl<C: PointUse> Add<DistanceKernel<C>> for WhiteKernel
Source§type Output = DistanceKernel<C>
type Output = DistanceKernel<C>
+ operator.Source§impl<C: PointUse> Add<WhiteKernel> for DistanceKernel<C>
impl<C: PointUse> Add<WhiteKernel> for DistanceKernel<C>
Source§type Output = DistanceKernel<C>
type Output = DistanceKernel<C>
+ operator.Source§impl Clone for WhiteKernel
impl Clone for WhiteKernel
impl Copy for WhiteKernel
Source§impl Debug for WhiteKernel
impl Debug for WhiteKernel
Source§impl From<WhiteKernel> for KernelSpec
impl From<WhiteKernel> for KernelSpec
Source§fn from(kernel: WhiteKernel) -> Self
fn from(kernel: WhiteKernel) -> Self
Source§impl<C: PointUse> Mul<DistanceKernel<C>> for WhiteKernel
impl<C: PointUse> Mul<DistanceKernel<C>> for WhiteKernel
Source§type Output = DistanceKernel<C>
type Output = DistanceKernel<C>
* operator.Source§impl<C: PointUse> Mul<WhiteKernel> for DistanceKernel<C>
impl<C: PointUse> Mul<WhiteKernel> for DistanceKernel<C>
Source§type Output = DistanceKernel<C>
type Output = DistanceKernel<C>
* operator.Source§impl PartialEq for WhiteKernel
impl PartialEq for WhiteKernel
impl StructuralPartialEq for WhiteKernel
Auto Trait Implementations§
impl Freeze for WhiteKernel
impl RefUnwindSafe for WhiteKernel
impl Send for WhiteKernel
impl Sync for WhiteKernel
impl Unpin for WhiteKernel
impl UnsafeUnpin for WhiteKernel
impl UnwindSafe for WhiteKernel
Blanket Implementations§
impl<T> Boilerplate for T
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> DistributionExt for Twhere
T: ?Sized,
impl<T> DistributionExt for Twhere
T: ?Sized,
impl<T, U> Imply<T> for U
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more