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.jsonandmodel.safetensors. - transform
- Transforms input (
X) and target (y).
Structs§
- Accurate
- Selects the exact language
expand SIMDexpfor kernel evaluation. - Adam
- Represents the mini-batch Adam used by
crate::Svgp<Adam>::fit. - Adaptive
Jitter - Represents the growing diagonal offsets for
JitterPolicy::Adaptive. - Bounded
Param - Represents a user-unit parameter that cannot sit on or outside its
Interval. - Double
Precision - Uses
f64for stored factors and for refinement. - Fast
Approx - Selects the polynomial
expfor kernel evaluation. - Fast
Simulated Annealing - Represents fast simulated annealing with a Cauchy generating distribution.
- Fitted
Gpr - Stores a fitted Exact GPR:
L,α, the training data, kernel, and transforms. - Fitted
Sgpr - Represents the factored collapsed variational SGPR at the
θused bySgpr::fitorSgpr<Fixed>::factor. - Fitted
Svgp - Represents the factored stochastic variational GPR at the
θused bycrate::Svgp<Fixed>::factororcrate::Svgp<crate::Adam>::fit. - Fixed
- Represents no hyperparameter search: the model keeps the
θit was built with. - Fixed
Inducing - Keeps inducing coordinates fixed during
Sgpr::fit. - Fixed
Jitter - Represents the non-negative diagonal offset for
JitterPolicy::Fixed. - Free
Inducing - Optimizes inducing coordinates jointly with kernel and likelihood
θ. - Gaussian
Likelihood - 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.
- Inducing
Id - Represents the stable identity of one inducing point on
OnlineSgpr. - Interval
- Represents the finite open interval
(lo, hi)withlo < hi. - Lbfgs
- Searches hyperparameters with limited-memory BFGS.
- Mixed
Precision - Factors in
f32and refines the predictαinf64. - Nelder
Mead - Searches hyperparameters with Nelder–Mead.
- Online
Gpr - Stores an online Exact GPR after
FittedGpr::into_online: LDLT factor, tail insert, and delete. - Online
Sgpr - 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::OnlineGprorcrate::OnlineSgpr. - Predict
Options - Represents the options of a prediction.
- Prediction
- Represents the predictive mean and (diagonal) variance at the query points.
- Predictive
Covariance - Represents the predictive mean and query–query covariance at the query points.
- Promote
Storage - Represents the residual
r = y − Aαfrom the savedf32matrix promoted tof64. - Reevaluate
Kernel - Represents the residual
r = y − Aαfrom a freshf64kernel evaluation. - Sgpr
- Represents the trainer for collapsed variational SGPR at an inducing set the caller chooses.
- Single
Precision - Uses
f32for stored factors and keeps that factorization as-is. - Svgp
- Represents the trainer for stochastic variational GPR at an inducing set the caller chooses.
- Trust
Region - Searches hyperparameters with a trust-region method and the Steihaug conjugate-gradient subproblem.
Enums§
- Boundary
Policy - Selects how
FastSimulatedAnnealingfolds a proposed coordinate back into an open parameter interval. - Cholesky
Buffer - Records where the gradient matrix
W = ααᵀ - K⁻¹lives during a fit. - Cholesky
Stage - Names the stage at which a Cholesky factorization failed
(
GprError::CholeskyFailed). - Distance
Cache Policy - Records whether
crate::Gprcaches training distances between kernel builds. - GprError
- Reports a recoverable failure from a gprx operation.
- Interval
Error - Reports why an
IntervalorBoundedParamcould not be constructed. - Jitter
Policy - Represents the numerical Cholesky stabilizer, distinct from observation noise.
- Kernel
Exp - Records which kernel
expa model evaluates with. - Persist
Error Kind - Names the part of a save or load that failed (
GprError::PersistFailed). - Slot
Error Kind - Names what is wrong with how a call’s
crate::kernel::DistanceSources match the slots of the kernel (GprError::DistanceSlot). - Variance
Kind - Records which predictive variance
Predictionreports.
Traits§
- Differentiable
- Represents the first-order objective.
- GpScalar
- Represents a model precision:
DoublePrecision,SinglePrecision, or aMixedPrecision. - Incremental
Objective - Represents the partial kernel rebuild from changed parameter indices.
- Kernel
Math - Represents the kernel
expmode:AccurateorFastApprox. - Objective
- Represents the optimizer-facing scalar objective (
valueonly). - Optimizer
- Represents the hyperparameter optimizer.
- Precision
Policy - Selects storage and residual-refinement scalar types for GP computations.
- Residual
Formula - Describes how
MixedPrecisionbuilds the refinement residualr = y − Aα. - Twice
Differentiable - Represents the second-order objective.