Skip to main content

WhiteKernel

Struct WhiteKernel 

Source
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

Source

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.

Source

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.

Source

pub fn variance(&self) -> f64

Returns σw² = exp(θ).

See the example on WhiteKernel.

Source

pub fn log_variance(&self) -> f64

Returns θ = log(σw²).

See the example on WhiteKernel.

Source

pub fn bounds(&self) -> Interval

Returns the open interval on σw².

See the example on WhiteKernel.

Source

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.

Source

pub fn num_params(&self) -> usize

Returns the number of optimizer parameters (always 1).

See the example on WhiteKernel.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn fill_diag<T: KernelScalar>(&self, out: &mut [T])

Writes the diagonal k(x, x) = σw² into out.

See the example on WhiteKernel.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Source§

type Output = DistanceKernel<C>

The resulting type after applying the + operator.
Source§

fn add(self, rhs: DistanceKernel<C>) -> Self::Output

Performs the + operation. Read more
Source§

impl<C: PointUse> Add<WhiteKernel> for DistanceKernel<C>

Source§

type Output = DistanceKernel<C>

The resulting type after applying the + operator.
Source§

fn add(self, rhs: WhiteKernel) -> Self::Output

Performs the + operation. Read more
Source§

impl Clone for WhiteKernel

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Copy for WhiteKernel

Source§

impl Debug for WhiteKernel

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl From<WhiteKernel> for KernelSpec

Source§

fn from(kernel: WhiteKernel) -> Self

Converts to this type from the input type.
Source§

impl<C: PointUse> Mul<DistanceKernel<C>> for WhiteKernel

Source§

type Output = DistanceKernel<C>

The resulting type after applying the * operator.
Source§

fn mul(self, rhs: DistanceKernel<C>) -> Self::Output

Performs the * operation. Read more
Source§

impl<C: PointUse> Mul<WhiteKernel> for DistanceKernel<C>

Source§

type Output = DistanceKernel<C>

The resulting type after applying the * operator.
Source§

fn mul(self, rhs: WhiteKernel) -> Self::Output

Performs the * operation. Read more
Source§

impl PartialEq for WhiteKernel

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for WhiteKernel

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Boilerplate for T
where T: Copy + Send + Sync + Debug + PartialEq + 'static,

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> ByRef<T> for T

Source§

fn by_ref(&self) -> &T

Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DistributionExt for T
where T: ?Sized,

Source§

fn rand<T>(&self, rng: &mut (impl Rng + ?Sized)) -> T
where Self: Distribution<T>,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Imply<T> for U
where T: ?Sized, U: ?Sized,

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> SendAlias for T

Source§

impl<T> SyncAlias for T

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V