gprx 0.2.0

Gaussian process regression in Rust: exact GPR, sparse GPR (VFE), and SVGP.
Documentation
//! Runtime policies: distance cache, Cholesky buffer, kernel `exp`, and
//! jitter. Every model reads the ones it uses.

use crate::error::GprError;

/// Records whether [`crate::Gpr`] caches training distances between kernel builds.
///
/// [`Self::Cached`] (the default) fills the distances once per fit and reuses
/// them while `X` is unchanged: isotropic fits store an `n×n`
/// squared-Euclidean matrix, ARD fits also store raw `(Δx_d)²` as
/// `n × (n·d)`. [`Self::Uncached`] recomputes them from `X` on every kernel
/// build. A kernel that does not read distances (standalone Linear,
/// Constant, White) never allocates the cache. Squared distances the caller
/// supplies are not a cache: a model keeps them whatever the policy, and a
/// fill is called once per fit.
///
/// # Examples
///
/// ```rust
/// use gprx::kernel::{KernelSpec, RbfKernel};
/// use gprx::{DistanceCachePolicy, GaussianLikelihood, Gpr};
///
/// # fn main() -> Result<(), gprx::GprError> {
/// let kernel = KernelSpec::from(RbfKernel::new(1.0)?);
/// let gpr = Gpr::new(kernel, GaussianLikelihood::new(0.1)?);
/// assert_eq!(gpr.distance_cache_policy(), DistanceCachePolicy::Cached);
/// let gpr = gpr.with_prefer_memory();
/// assert_eq!(gpr.distance_cache_policy(), DistanceCachePolicy::Uncached);
/// let _fitted = gpr.fit(&[0.0, 1.0], 2, 1, &[0.0, 1.0]).map_err(|(_, e)| e)?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
#[non_exhaustive]
pub enum DistanceCachePolicy {
    /// Fills distances once per fit and reuses them (the speed pole).
    #[default]
    Cached,
    /// Recomputes distances from `X` on every kernel build (the memory pole).
    Uncached,
}

/// Records where the gradient matrix `W = ααᵀ - K⁻¹` lives during a fit.
///
/// [`Self::Retain`] (the default) keeps a dedicated `n×n` `W`, so the
/// Cholesky factor stays in place and optimizers that report changed
/// parameters rebuild only the touched kernel leaves. [`Self::Reuse`]
/// overwrites the factor with `W` and refactors afterwards; it saves one
/// `n×n` matrix and always rebuilds the full kernel.
///
/// # Examples
///
/// ```rust
/// use gprx::kernel::{KernelSpec, RbfKernel};
/// use gprx::{CholeskyBuffer, GaussianLikelihood, Gpr};
///
/// # fn main() -> Result<(), gprx::GprError> {
/// let kernel = KernelSpec::from(RbfKernel::new(1.0)?);
/// let gpr = Gpr::new(kernel, GaussianLikelihood::new(0.1)?);
/// assert_eq!(gpr.cholesky_buffer(), CholeskyBuffer::Retain);
/// let gpr = gpr.with_prefer_memory();
/// assert_eq!(gpr.cholesky_buffer(), CholeskyBuffer::Reuse);
/// let _fitted = gpr.fit(&[0.0, 1.0], 2, 1, &[0.0, 1.0]).map_err(|(_, e)| e)?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub enum CholeskyBuffer {
    /// Keeps a dedicated `W` (the speed pole).
    #[default]
    Retain,
    /// Overwrites the factor with `W`, then refactors (the memory pole).
    Reuse,
}

/// Records which kernel `exp` a model evaluates with.
///
/// [`crate::Gpr`], [`crate::Sgpr`], and [`crate::Svgp`] take it through
/// `with_math`.
/// [`Self::Accurate`] (the default) is language `exp` and SIMD `exp` ([`crate::Accurate`]).
/// [`Self::FastApprox`] is the polynomial ([`crate::FastApprox`]); fit and predict use the
/// same one. Hyperparameter `exp(θ)` is unchanged.
///
/// # Examples
///
/// ```rust
/// use gprx::kernel::{KernelSpec, RbfKernel};
/// use gprx::{GaussianLikelihood, Gpr, KernelExp};
///
/// # fn main() -> Result<(), gprx::GprError> {
/// assert_eq!(KernelExp::default(), KernelExp::Accurate);
/// let gpr = Gpr::new(
///     KernelSpec::from(RbfKernel::new(1.0)?),
///     GaussianLikelihood::new(0.1)?,
/// )
/// .with_math(KernelExp::FastApprox);
/// assert_eq!(gpr.math(), KernelExp::FastApprox);
/// let _fitted = gpr.fit(&[0.0, 1.0], 2, 1, &[0.0, 1.0]).map_err(|(_, e)| e)?;
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
#[non_exhaustive]
pub enum KernelExp {
    /// Uses the exact language `exp` and SIMD `exp`.
    #[default]
    Accurate,
    /// Uses the degree-7 polynomial `exp`.
    FastApprox,
}

/// Runs `$body` with the type alias `$M` bound to the [`crate::KernelMath`]
/// type of `$mode`. The body is monomorphized once per mode, as a generic
/// `M` parameter was before.
macro_rules! with_kernel_exp {
    ($mode:expr, $M:ident => $body:expr) => {
        match $mode {
            $crate::policy::KernelExp::Accurate => {
                type $M = $crate::math::Accurate;
                $body
            }
            $crate::policy::KernelExp::FastApprox => {
                type $M = $crate::math::FastApprox;
                $body
            }
        }
    };
}
pub(crate) use with_kernel_exp;

/// Represents the numerical Cholesky stabilizer, distinct from observation noise.
///
/// The first factorization always tries `A = K + σn² I` with no extra
/// diagonal. [`Self::Fixed`] retries once with that `j` if the first factor
/// fails. [`Self::Adaptive`] retries with `initial`, then
/// `initial * multiplier` on each later attempt, stopping at `max_retries`
/// or when `j` would exceed `max_jitter`. A successful retry factors
/// `A + j I`; this crate does not iteratively refine back to `A`.
/// Observation noise stays on [`GaussianLikelihood`](crate::GaussianLikelihood).
///
/// The default is [`Self::fixed`]`(0.0)`: no retry, matching an unregularized
/// factor. [`GprError::CholeskyFailed::jitter`] is the last `j` that was
/// tried (`0.0` when the unregularized factor was the only attempt).
///
/// # Errors
///
/// Constructors return [`GprError::InvalidConfig`] if a value is
/// non-finite or outside the domain below.
///
/// # Examples
///
/// ```rust
/// use gprx::kernel::{KernelSpec, RbfKernel};
/// use gprx::{GaussianLikelihood, Gpr, JitterPolicy};
///
/// # fn main() -> Result<(), gprx::GprError> {
/// let gpr = Gpr::new(
///     KernelSpec::from(RbfKernel::new(1.0)?),
///     GaussianLikelihood::new(0.1)?,
/// )
/// .with_jitter_policy(JitterPolicy::adaptive(1e-10, 10.0, 5, 1e-3)?);
/// let _fitted = gpr.fit(&[0.0, 1.0], 2, 1, &[0.0, 1.0]).map_err(|(_, e)| e)?;
///
/// // The default is one attempt with no jitter.
/// assert_eq!(JitterPolicy::default(), JitterPolicy::fixed(0.0)?);
///
/// // Read the settings back by matching the variants.
/// let fixed = JitterPolicy::fixed(1e-6)?;
/// assert!(matches!(fixed, JitterPolicy::Fixed(_)));
/// if let JitterPolicy::Fixed(fixed) = fixed {
///     assert_eq!(fixed.jitter(), 1e-6);
/// }
/// if let JitterPolicy::Adaptive(adaptive) = JitterPolicy::adaptive(1e-10, 10.0, 5, 1e-3)? {
///     assert_eq!(adaptive.initial(), 1e-10);
///     assert_eq!(adaptive.multiplier(), 10.0);
///     assert_eq!(adaptive.max_retries(), 5);
///     assert_eq!(adaptive.max_jitter(), 1e-3);
/// }
///
/// // A negative jitter is refused.
/// assert!(matches!(
///     JitterPolicy::fixed(-1.0),
///     Err(gprx::GprError::InvalidConfig { .. })
/// ));
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Copy, Debug, PartialEq)]
#[non_exhaustive]
pub enum JitterPolicy {
    /// Retries the failed factor once with this non-negative `j` on the diagonal.
    Fixed(FixedJitter),
    /// Retries with a growing `j` after the unregularized factor fails.
    Adaptive(AdaptiveJitter),
}

/// Represents the non-negative diagonal offset for [`JitterPolicy::Fixed`].
///
/// Built by [`JitterPolicy::fixed`].
///
/// See the example on [`JitterPolicy`].
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct FixedJitter {
    jitter: f64,
}

/// Represents the growing diagonal offsets for [`JitterPolicy::Adaptive`].
///
/// Built by [`JitterPolicy::adaptive`].
///
/// See the example on [`JitterPolicy`].
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct AdaptiveJitter {
    initial: f64,
    multiplier: f64,
    max_retries: usize,
    max_jitter: f64,
}

impl AdaptiveJitter {
    /// `adaptive(1e-8, 10, 5, 1e-3)`, the sparse `K_mm` default.
    pub(crate) const K_MM_DEFAULT: Self = Self {
        initial: 1e-8,
        multiplier: 10.0,
        max_retries: 5,
        max_jitter: 1e-3,
    };
}

impl Default for JitterPolicy {
    fn default() -> Self {
        Self::Fixed(FixedJitter { jitter: 0.0 })
    }
}

impl JitterPolicy {
    /// Builds a single retry offset `j ≥ 0`.
    ///
    /// # Errors
    ///
    /// Returns [`GprError::InvalidConfig`] if `jitter` is not finite
    /// or is negative.
    ///
    /// See the example on [`JitterPolicy`].
    pub fn fixed(jitter: f64) -> Result<Self, GprError> {
        if !jitter.is_finite() || jitter < 0.0 {
            return Err(GprError::InvalidConfig {
                reason: format!("jitter must be finite and non-negative, got {jitter}"),
            });
        }
        Ok(Self::Fixed(FixedJitter { jitter }))
    }

    /// Builds a growing retry sequence after an unregularized factor fails.
    ///
    /// `initial` must be positive, `multiplier` must be greater than 1,
    /// `max_retries` must be at least 1, and `max_jitter` must be at least
    /// `initial`.
    ///
    /// # Errors
    ///
    /// Returns [`GprError::InvalidConfig`] if a value is non-finite
    /// or outside that domain.
    ///
    /// See the example on [`JitterPolicy`].
    pub fn adaptive(
        initial: f64,
        multiplier: f64,
        max_retries: usize,
        max_jitter: f64,
    ) -> Result<Self, GprError> {
        if !initial.is_finite() || initial <= 0.0 {
            return Err(GprError::InvalidConfig {
                reason: format!(
                    "adaptive initial jitter must be finite and positive, got {initial}"
                ),
            });
        }
        if !multiplier.is_finite() || multiplier <= 1.0 {
            return Err(GprError::InvalidConfig {
                reason: format!(
                    "adaptive jitter multiplier must be finite and greater than 1, got {multiplier}"
                ),
            });
        }
        if max_retries < 1 {
            return Err(GprError::InvalidConfig {
                reason: "adaptive jitter max_retries must be at least 1".to_owned(),
            });
        }
        if !max_jitter.is_finite() || max_jitter < initial {
            return Err(GprError::InvalidConfig {
                reason: format!(
                    "adaptive max_jitter must be finite and at least initial ({initial}), got {max_jitter}"
                ),
            });
        }
        Ok(Self::Adaptive(AdaptiveJitter {
            initial,
            multiplier,
            max_retries,
            max_jitter,
        }))
    }

    pub(crate) fn retry_jitters(self) -> RetryJitters {
        match self {
            Self::Fixed(fixed) => {
                if fixed.jitter > 0.0 {
                    RetryJitters {
                        next: Some(fixed.jitter),
                        multiplier: 1.0,
                        remaining: 1,
                        max_jitter: fixed.jitter,
                    }
                } else {
                    RetryJitters {
                        next: None,
                        multiplier: 1.0,
                        remaining: 0,
                        max_jitter: 0.0,
                    }
                }
            }
            Self::Adaptive(adaptive) => RetryJitters {
                next: Some(adaptive.initial),
                multiplier: adaptive.multiplier,
                remaining: adaptive.max_retries,
                max_jitter: adaptive.max_jitter,
            },
        }
    }
}

impl FixedJitter {
    /// Returns the retry offset `j`.
    ///
    /// See the example on [`JitterPolicy`].
    pub fn jitter(&self) -> f64 {
        self.jitter
    }
}

impl AdaptiveJitter {
    /// Returns the first retry offset.
    ///
    /// See the example on [`JitterPolicy`].
    pub fn initial(&self) -> f64 {
        self.initial
    }

    /// Returns the factor applied after each failed retry.
    ///
    /// See the example on [`JitterPolicy`].
    pub fn multiplier(&self) -> f64 {
        self.multiplier
    }

    /// Returns the maximum number of jittered attempts.
    ///
    /// See the example on [`JitterPolicy`].
    pub fn max_retries(&self) -> usize {
        self.max_retries
    }

    /// Returns the largest retry offset that may be tried.
    ///
    /// See the example on [`JitterPolicy`].
    pub fn max_jitter(&self) -> f64 {
        self.max_jitter
    }
}

pub(crate) struct RetryJitters {
    next: Option<f64>,
    multiplier: f64,
    remaining: usize,
    max_jitter: f64,
}

impl Iterator for RetryJitters {
    type Item = f64;

    fn next(&mut self) -> Option<f64> {
        if self.remaining == 0 {
            return None;
        }
        let j = self.next?;
        if j > self.max_jitter {
            return None;
        }
        self.remaining -= 1;
        let grown = j * self.multiplier;
        self.next = if grown.is_finite() { Some(grown) } else { None };
        Some(j)
    }
}