Skip to main content

Crate gprx

Crate gprx 

Source
Expand description

Gaussian process regression in Rust: exact GPR, sparse GPR (VFE), and SVGP.

Gpr is the trainer. Gpr::fit consumes Gpr<Lbfgs> and returns FittedGpr. Gpr::with_optimizer swaps in NelderMead, TrustRegion, or FastSimulatedAnnealing. Gpr<Fixed>::factor factors at the current θ without a search. Training X is column-major: n points and d features packed as feature 0 for all rows, then feature 1, and so on. Observation noise lives in GaussianLikelihood. kernel::WhiteKernel is opt-in composition; using both at large values double-counts noise.

Depend on crates.io with gprx = "0.2". The 0.2.0 contract (tag v0.2.0) is the default-feature public API: Gpr, Sgpr, and Svgp, online updates, supplied squared distances (kernel::ScalarDistance, kernel::ArdDistance), and directory save/load. A 0.x minor may break that API; the changelog lists what 0.2.0 changed from 0.1.0. The MSRV is 1.88. The internals module (bench-internals, insert-stages) is outside semantic versioning.

Distance fills and lower-triangle kernel writes run on the process-wide Rayon thread pool, which the linear-algebra backend shares. There is no parallel on/off flag and no n_jobs setter on Gpr. Set RAYON_NUM_THREADS before the process starts, or call rayon::ThreadPoolBuilder::new().num_threads(n).build_global() before the first Gpr::fit / FittedGpr::predict. One worker (RAYON_NUM_THREADS=1) is sequential. The global pool can be initialized only once. A factor or solve of n rows and k columns (the training Cholesky factor and the n-column solve that forms the gradient matrix ααᵀ − A⁻¹ have k = n; a predict or covariance solve has one column per query point) runs the linear-algebra backend on min(pool, n / 64, n · k / 16384, k / 12) workers, at least one, so a 1024 × 100 solve does not start 16 workers. Kernel fills still use the full pool.

§Examples

use gprx::kernel::{KernelSpec, RbfKernel};
use gprx::{GaussianLikelihood, Gpr};

let kernel = KernelSpec::from(RbfKernel::new(1.0)?);
let likelihood = GaussianLikelihood::new(0.1)?;
let gpr = Gpr::new(kernel, likelihood);
let fitted = gpr.fit(&[0.0, 1.0], 2, 1, &[0.0, 1.0]).map_err(|(_, e)| e)?;
let pred = fitted.predict(&[0.5], 1, 1)?;
assert_eq!(pred.mean.len(), 1);

Re-exports§

pub use persist::FORMAT_VERSION;
pub use persist::LoadedGpr;
pub use persist::LoadedSgpr;
pub use persist::LoadedSvgp;
pub use persist::PersistRegistry;

Modules§

kernel
Describes kernel leaves and composition (KernelSpec / CompiledKernel).
persist
Saves and loads fitted models as a directory of config.json and model.safetensors.
transform
Transforms input (X) and target (y).

Structs§

Accurate
Selects the exact language exp and SIMD exp for kernel evaluation.
Adam
Represents the mini-batch Adam used by crate::Svgp<Adam>::fit.
AdaptiveJitter
Represents the growing diagonal offsets for JitterPolicy::Adaptive.
BoundedParam
Represents a user-unit parameter that cannot sit on or outside its Interval.
DoublePrecision
Uses f64 for stored factors and for refinement.
FastApprox
Selects the polynomial exp for kernel evaluation.
FastSimulatedAnnealing
Represents fast simulated annealing with a Cauchy generating distribution.
FittedGpr
Stores a fitted Exact GPR: L, α, the training data, kernel, and transforms.
FittedSgpr
Represents the factored collapsed variational SGPR at the θ used by Sgpr::fit or Sgpr<Fixed>::factor.
FittedSvgp
Represents the factored stochastic variational GPR at the θ used by crate::Svgp<Fixed>::factor or crate::Svgp<crate::Adam>::fit.
Fixed
Represents no hyperparameter search: the model keeps the θ it was built with.
FixedInducing
Keeps inducing coordinates fixed during Sgpr::fit.
FixedJitter
Represents the non-negative diagonal offset for JitterPolicy::Fixed.
FreeInducing
Optimizes inducing coordinates jointly with kernel and likelihood θ.
GaussianLikelihood
Represents the Gaussian likelihood with observation noise variance σn².
Gpr
Trains an Exact GPR from a kernel, a likelihood, transforms, an optimizer, and a recompute strategy.
InducingId
Represents the stable identity of one inducing point on OnlineSgpr.
Interval
Represents the finite open interval (lo, hi) with lo < hi.
Lbfgs
Searches hyperparameters with limited-memory BFGS.
MixedPrecision
Factors in f32 and refines the predict α in f64.
NelderMead
Searches hyperparameters with Nelder–Mead.
OnlineGpr
Stores an online Exact GPR after FittedGpr::into_online: LDLT factor, tail insert, and delete.
OnlineSgpr
Represents the online collapsed variational SGPR after FittedSgpr::into_online.
OptResult
Represents the result of Optimizer::minimize.
PointId
Represents the stable identity of one training point on crate::OnlineGpr or crate::OnlineSgpr.
PredictOptions
Represents the options of a prediction.
Prediction
Represents the predictive mean and (diagonal) variance at the query points.
PredictiveCovariance
Represents the predictive mean and query–query covariance at the query points.
PromoteStorage
Represents the residual r = y − Aα from the saved f32 matrix promoted to f64.
ReevaluateKernel
Represents the residual r = y − Aα from a fresh f64 kernel evaluation.
Sgpr
Represents the trainer for collapsed variational SGPR at an inducing set the caller chooses.
SinglePrecision
Uses f32 for stored factors and keeps that factorization as-is.
Svgp
Represents the trainer for stochastic variational GPR at an inducing set the caller chooses.
TrustRegion
Searches hyperparameters with a trust-region method and the Steihaug conjugate-gradient subproblem.

Enums§

BoundaryPolicy
Selects how FastSimulatedAnnealing folds a proposed coordinate back into an open parameter interval.
CholeskyBuffer
Records where the gradient matrix W = ααᵀ - K⁻¹ lives during a fit.
CholeskyStage
Names the stage at which a Cholesky factorization failed (GprError::CholeskyFailed).
DistanceCachePolicy
Records whether crate::Gpr caches training distances between kernel builds.
GprError
Reports a recoverable failure from a gprx operation.
IntervalError
Reports why an Interval or BoundedParam could not be constructed.
JitterPolicy
Represents the numerical Cholesky stabilizer, distinct from observation noise.
KernelExp
Records which kernel exp a model evaluates with.
PersistErrorKind
Names the part of a save or load that failed (GprError::PersistFailed).
SlotErrorKind
Names what is wrong with how a call’s crate::kernel::DistanceSources match the slots of the kernel (GprError::DistanceSlot).
VarianceKind
Records which predictive variance Prediction reports.

Traits§

Differentiable
Represents the first-order objective.
GpScalar
Represents a model precision: DoublePrecision, SinglePrecision, or a MixedPrecision.
IncrementalObjective
Represents the partial kernel rebuild from changed parameter indices.
KernelMath
Represents the kernel exp mode: Accurate or FastApprox.
Objective
Represents the optimizer-facing scalar objective (value only).
Optimizer
Represents the hyperparameter optimizer.
PrecisionPolicy
Selects storage and residual-refinement scalar types for GP computations.
ResidualFormula
Describes how MixedPrecision builds the refinement residual r = y − Aα.
TwiceDifferentiable
Represents the second-order objective.