use crate::error::GprError;
use crate::kernel::{
ConstantKernel, CustomKernel, LinearKernel, MaternArdKernel, MaternKernel, PeriodicKernel,
RationalQuadraticArdKernel, RationalQuadraticKernel, RbfArdKernel, RbfKernel, WhiteKernel,
};
use crate::param::Interval;
use super::leaf_params::LeafParams;
use super::tree::{NoSupply, Supply};
use std::ops::{Add, Mul};
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ParameterBinding {
pub index: usize,
pub leaf_id: usize,
pub local_index: usize,
}
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub enum KernelSpec<S: Supply = NoSupply> {
Rbf(RbfKernel),
RbfArd(RbfArdKernel),
Matern(MaternKernel),
MaternArd(MaternArdKernel),
Periodic(PeriodicKernel),
RationalQuadratic(RationalQuadraticKernel),
RationalQuadraticArd(RationalQuadraticArdKernel),
Constant(ConstantKernel),
Linear(LinearKernel),
White(WhiteKernel),
Custom(CustomKernel),
Sum(Box<KernelSpec<S>>, Box<KernelSpec<S>>),
Product(Box<KernelSpec<S>>, Box<KernelSpec<S>>),
#[doc(hidden)]
Supplied(S),
}
impl From<RbfKernel> for KernelSpec {
fn from(kernel: RbfKernel) -> Self {
Self::Rbf(kernel)
}
}
impl From<RbfArdKernel> for KernelSpec {
fn from(kernel: RbfArdKernel) -> Self {
Self::RbfArd(kernel)
}
}
impl From<MaternKernel> for KernelSpec {
fn from(kernel: MaternKernel) -> Self {
Self::Matern(kernel)
}
}
impl From<MaternArdKernel> for KernelSpec {
fn from(kernel: MaternArdKernel) -> Self {
Self::MaternArd(kernel)
}
}
impl From<PeriodicKernel> for KernelSpec {
fn from(kernel: PeriodicKernel) -> Self {
Self::Periodic(kernel)
}
}
impl From<RationalQuadraticKernel> for KernelSpec {
fn from(kernel: RationalQuadraticKernel) -> Self {
Self::RationalQuadratic(kernel)
}
}
impl From<RationalQuadraticArdKernel> for KernelSpec {
fn from(kernel: RationalQuadraticArdKernel) -> Self {
Self::RationalQuadraticArd(kernel)
}
}
impl From<ConstantKernel> for KernelSpec {
fn from(kernel: ConstantKernel) -> Self {
Self::Constant(kernel)
}
}
impl From<LinearKernel> for KernelSpec {
fn from(kernel: LinearKernel) -> Self {
Self::Linear(kernel)
}
}
impl From<WhiteKernel> for KernelSpec {
fn from(kernel: WhiteKernel) -> Self {
Self::White(kernel)
}
}
impl From<CustomKernel> for KernelSpec {
fn from(kernel: CustomKernel) -> Self {
Self::Custom(kernel)
}
}
impl<S: Supply> Add for KernelSpec<S> {
type Output = Self;
fn add(self, rhs: Self) -> Self {
Self::Sum(Box::new(self), Box::new(rhs))
}
}
impl<S: Supply> Mul for KernelSpec<S> {
type Output = Self;
fn mul(self, rhs: Self) -> Self {
Self::Product(Box::new(self), Box::new(rhs))
}
}
impl KernelSpec {
pub fn custom<K>(term: K) -> Self
where
K: super::KernelTerm<f64>
+ super::KernelTerm<f32>
+ Clone
+ std::fmt::Debug
+ Send
+ Sync
+ 'static,
{
Self::Custom(CustomKernel::new(term))
}
pub(crate) fn widen<S: Supply>(self) -> KernelSpec<S> {
match self {
Self::Rbf(leaf) => KernelSpec::Rbf(leaf),
Self::RbfArd(leaf) => KernelSpec::RbfArd(leaf),
Self::Matern(leaf) => KernelSpec::Matern(leaf),
Self::MaternArd(leaf) => KernelSpec::MaternArd(leaf),
Self::Periodic(leaf) => KernelSpec::Periodic(leaf),
Self::RationalQuadratic(leaf) => KernelSpec::RationalQuadratic(leaf),
Self::RationalQuadraticArd(leaf) => KernelSpec::RationalQuadraticArd(leaf),
Self::Constant(leaf) => KernelSpec::Constant(leaf),
Self::Linear(leaf) => KernelSpec::Linear(leaf),
Self::White(leaf) => KernelSpec::White(leaf),
Self::Custom(leaf) => KernelSpec::Custom(leaf),
Self::Sum(left, right) => {
KernelSpec::Sum(Box::new(left.widen()), Box::new(right.widen()))
}
Self::Product(left, right) => {
KernelSpec::Product(Box::new(left.widen()), Box::new(right.widen()))
}
Self::Supplied(never) => match never {},
}
}
}
impl<S: Supply> KernelSpec<S> {
pub fn num_params(&self) -> usize {
match self {
Self::Rbf(leaf) => leaf.num_params(),
Self::RbfArd(leaf) => leaf.num_params(),
Self::Matern(leaf) => leaf.num_params(),
Self::MaternArd(leaf) => leaf.num_params(),
Self::Periodic(leaf) => leaf.num_params(),
Self::RationalQuadratic(leaf) => leaf.num_params(),
Self::RationalQuadraticArd(leaf) => leaf.num_params(),
Self::Constant(leaf) => leaf.num_params(),
Self::Linear(leaf) => leaf.num_params(),
Self::White(leaf) => leaf.num_params(),
Self::Custom(leaf) => leaf.num_params(),
Self::Supplied(leaf) => S::spec(leaf).leaf.leaf_num_params(),
Self::Sum(left, right) | Self::Product(left, right) => {
left.num_params() + right.num_params()
}
}
}
pub fn get_params(&self, out: &mut [f64]) -> Result<(), GprError> {
crate::data::require_count(out.len(), self.num_params(), "kernel parameters")?;
let mut offset = 0;
self.write_params(out, &mut offset)
}
pub fn set_params(&mut self, params: &[f64]) -> Result<(), GprError> {
crate::data::require_count(params.len(), self.num_params(), "kernel parameters")?;
let mut next = self.clone();
let mut offset = 0;
next.apply_params(params, &mut offset)?;
*self = next;
Ok(())
}
pub(crate) fn set_params_in_place(
&mut self,
params: &[f64],
prev: &[f64],
) -> Result<(), GprError> {
crate::data::require_count(params.len(), self.num_params(), "kernel parameters")?;
let mut offset = 0;
if let Err(err) = self.apply_params(params, &mut offset) {
let mut offset = 0;
let _ = self.apply_params(prev, &mut offset);
return Err(err);
}
Ok(())
}
pub fn parameter_bindings(&self) -> Vec<ParameterBinding> {
let mut out = Vec::new();
let mut index = 0;
let mut leaf_id = 0;
self.collect_bindings(&mut out, &mut index, &mut leaf_id);
out
}
pub fn compile(&self) -> crate::kernel::CompiledKernel<f64, S> {
crate::kernel::CompiledKernel::<f64, S>::from_spec(self)
}
pub fn compile_as<T>(&self) -> crate::kernel::CompiledKernel<T, S>
where
T: crate::kernel::KernelScalar,
{
crate::kernel::CompiledKernel::<T, S>::from_spec(self)
}
fn write_params(&self, out: &mut [f64], offset: &mut usize) -> Result<(), GprError> {
match self {
Self::Rbf(leaf) => leaf.write_leaf_params(out, offset),
Self::RbfArd(leaf) => leaf.write_leaf_params(out, offset),
Self::Matern(leaf) => leaf.write_leaf_params(out, offset),
Self::MaternArd(leaf) => leaf.write_leaf_params(out, offset),
Self::Periodic(leaf) => leaf.write_leaf_params(out, offset),
Self::RationalQuadratic(leaf) => leaf.write_leaf_params(out, offset),
Self::RationalQuadraticArd(leaf) => leaf.write_leaf_params(out, offset),
Self::Constant(leaf) => leaf.write_leaf_params(out, offset),
Self::Linear(leaf) => leaf.write_leaf_params(out, offset),
Self::White(leaf) => leaf.write_leaf_params(out, offset),
Self::Custom(leaf) => leaf.write_leaf_params(out, offset),
Self::Supplied(leaf) => S::spec(leaf).leaf.write_leaf_params(out, offset),
Self::Sum(left, right) | Self::Product(left, right) => {
left.write_params(out, offset)?;
right.write_params(out, offset)
}
}
}
pub(crate) fn write_intervals(
&self,
out: &mut [Interval],
offset: &mut usize,
) -> Result<(), GprError> {
match self {
Self::Rbf(leaf) => leaf.write_leaf_intervals(out, offset),
Self::RbfArd(leaf) => leaf.write_leaf_intervals(out, offset),
Self::Matern(leaf) => leaf.write_leaf_intervals(out, offset),
Self::MaternArd(leaf) => leaf.write_leaf_intervals(out, offset),
Self::Periodic(leaf) => leaf.write_leaf_intervals(out, offset),
Self::RationalQuadratic(leaf) => leaf.write_leaf_intervals(out, offset),
Self::RationalQuadraticArd(leaf) => leaf.write_leaf_intervals(out, offset),
Self::Constant(leaf) => leaf.write_leaf_intervals(out, offset),
Self::Linear(leaf) => leaf.write_leaf_intervals(out, offset),
Self::White(leaf) => leaf.write_leaf_intervals(out, offset),
Self::Custom(leaf) => leaf.write_leaf_intervals(out, offset),
Self::Supplied(leaf) => S::spec(leaf).leaf.write_leaf_intervals(out, offset),
Self::Sum(left, right) | Self::Product(left, right) => {
left.write_intervals(out, offset)?;
right.write_intervals(out, offset)
}
}
}
fn apply_params(&mut self, params: &[f64], offset: &mut usize) -> Result<(), GprError> {
match self {
Self::Rbf(leaf) => leaf.apply_leaf_params(params, offset),
Self::RbfArd(leaf) => leaf.apply_leaf_params(params, offset),
Self::Matern(leaf) => leaf.apply_leaf_params(params, offset),
Self::MaternArd(leaf) => leaf.apply_leaf_params(params, offset),
Self::Periodic(leaf) => leaf.apply_leaf_params(params, offset),
Self::RationalQuadratic(leaf) => leaf.apply_leaf_params(params, offset),
Self::RationalQuadraticArd(leaf) => leaf.apply_leaf_params(params, offset),
Self::Constant(leaf) => leaf.apply_leaf_params(params, offset),
Self::Linear(leaf) => leaf.apply_leaf_params(params, offset),
Self::White(leaf) => leaf.apply_leaf_params(params, offset),
Self::Custom(leaf) => leaf.apply_leaf_params(params, offset),
Self::Supplied(leaf) => S::spec_mut(leaf).leaf.apply_leaf_params(params, offset),
Self::Sum(left, right) | Self::Product(left, right) => {
left.apply_params(params, offset)?;
right.apply_params(params, offset)
}
}
}
fn collect_bindings(
&self,
out: &mut Vec<ParameterBinding>,
index: &mut usize,
leaf_id: &mut usize,
) {
match self {
Self::Rbf(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::RbfArd(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::Matern(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::MaternArd(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::Periodic(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::RationalQuadratic(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::RationalQuadraticArd(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::Constant(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::Linear(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::White(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::Custom(leaf) => {
push_leaf_bindings(out, index, leaf_id, leaf.num_params());
}
Self::Supplied(leaf) => {
push_leaf_bindings(out, index, leaf_id, S::spec(leaf).leaf.leaf_num_params());
}
Self::Sum(left, right) | Self::Product(left, right) => {
left.collect_bindings(out, index, leaf_id);
right.collect_bindings(out, index, leaf_id);
}
}
}
}
fn push_leaf_bindings(
out: &mut Vec<ParameterBinding>,
index: &mut usize,
leaf_id: &mut usize,
n_params: usize,
) {
let id = *leaf_id;
*leaf_id += 1;
for local_index in 0..n_params {
out.push(ParameterBinding {
index: *index,
leaf_id: id,
local_index,
});
*index += 1;
}
}
#[cfg(test)]
mod tests {
use super::KernelSpec;
use crate::kernel::{
ConstantKernel, MaternArdKernel, MaternKernel, MaternNu, PeriodicKernel,
RationalQuadraticArdKernel, RationalQuadraticKernel, RbfArdKernel, RbfKernel, WhiteKernel,
};
const TOL: f64 = 1e-12;
use crate::test_check::assert_close;
fn rbf(ell: f64) -> KernelSpec {
KernelSpec::from(RbfKernel::new(ell).expect("valid"))
}
#[test]
fn sum_flattens_params_left_to_right() {
let mut spec = (rbf(1.0) + rbf(2.0)) + rbf(3.0);
assert_eq!(spec.num_params(), 3);
let mut params = [0.0; 3];
spec.get_params(&mut params).expect("len 3");
assert_close(params[0], 1.0_f64.ln(), TOL);
assert_close(params[1], 2.0_f64.ln(), TOL);
assert_close(params[2], 3.0_f64.ln(), TOL);
params[1] = 4.0_f64.ln();
spec.set_params(¶ms).expect("len 3");
spec.get_params(&mut params).expect("len 3");
assert_close(params[1], 4.0_f64.ln(), TOL);
match spec.compile() {
crate::kernel::CompiledKernel::Sum(terms) => assert_eq!(terms.len(), 3),
other => panic!("expected flattened sum, got {other:?}"),
}
}
#[test]
fn product_keeps_sum_nested() {
let spec = rbf(1.0) * (rbf(2.0) + rbf(3.0));
match spec.compile() {
crate::kernel::CompiledKernel::Product(factors) => {
assert_eq!(factors.len(), 2);
assert!(matches!(factors[1], crate::kernel::CompiledKernel::Sum(_)));
}
other => panic!("expected product, got {other:?}"),
}
}
#[test]
fn product_flattens_three_factors() {
let spec = (rbf(1.0) * rbf(2.0)) * rbf(3.0);
match spec.compile() {
crate::kernel::CompiledKernel::Product(factors) => assert_eq!(factors.len(), 3),
other => panic!("expected flattened product, got {other:?}"),
}
}
#[test]
fn constant_times_rbf_then_rbf_flattens_like_sklearn() {
let spec = KernelSpec::from(ConstantKernel::new(1.5).expect("valid")) * rbf(1.0) + rbf(2.0);
assert_eq!(spec.num_params(), 3);
let mut params = [0.0; 3];
spec.get_params(&mut params).expect("len 3");
assert_close(params[0], 1.5_f64.ln(), TOL);
assert_close(params[1], 1.0_f64.ln(), TOL);
assert_close(params[2], 2.0_f64.ln(), TOL);
match spec.compile() {
crate::kernel::CompiledKernel::Sum(terms) => {
assert_eq!(terms.len(), 2);
assert!(matches!(
terms[0],
crate::kernel::CompiledKernel::Product(_)
));
}
other => panic!("expected sum of product and rbf, got {other:?}"),
}
}
#[test]
fn set_params_is_atomic() {
let mut spec = rbf(1.0) + rbf(2.0);
let before = spec.clone();
assert!(spec.set_params(&[0.0, f64::INFINITY]).is_err());
assert_eq!(spec, before);
}
#[test]
fn bindings_follow_leaves() {
let spec = rbf(1.0) + rbf(2.0);
let b = spec.parameter_bindings();
assert_eq!(b.len(), 2);
assert_eq!(b[0].leaf_id, 0);
assert_eq!(b[1].leaf_id, 1);
assert_eq!(b[0].local_index, 0);
assert_eq!(b[1].index, 1);
}
#[test]
fn ard_flattens_per_dimension_params() {
let mut spec = KernelSpec::from(RbfArdKernel::new(&[1.0, 2.0]).expect("valid"));
assert_eq!(spec.num_params(), 2);
let mut params = [0.0; 2];
spec.get_params(&mut params).expect("len 2");
assert_close(params[0], 1.0_f64.ln(), TOL);
assert_close(params[1], 2.0_f64.ln(), TOL);
params[1] = 3.0_f64.ln();
spec.set_params(¶ms).expect("len 2");
spec.get_params(&mut params).expect("len 2");
assert_close(params[1], 3.0_f64.ln(), TOL);
let b = spec.parameter_bindings();
assert_eq!(b.len(), 2);
assert_eq!(b[0].leaf_id, 0);
assert_eq!(b[1].leaf_id, 0);
assert_eq!(b[1].local_index, 1);
match spec.compile() {
crate::kernel::CompiledKernel::RbfArd(leaf) => assert_eq!(leaf.num_params(), 2),
other => panic!("expected ARD RBF, got {other:?}"),
}
}
#[test]
fn constant_and_white_flatten_with_rbf() {
let spec = rbf(1.0)
+ KernelSpec::from(ConstantKernel::new(2.0).expect("valid"))
+ KernelSpec::from(WhiteKernel::new(0.1).expect("valid"));
assert_eq!(spec.num_params(), 3);
let mut params = [0.0; 3];
spec.get_params(&mut params).expect("len 3");
assert_close(params[1], 2.0_f64.ln(), TOL);
assert_close(params[2], 0.1_f64.ln(), TOL);
let compiled = spec.compile();
assert_eq!(compiled.num_params(), 3);
assert_eq!(
compiled.coord_mode().expect("compat"),
crate::kernel::compiled::CoordMode::Dist
);
}
#[test]
fn matern_and_matern_ard_flatten() {
let iso = KernelSpec::from(MaternKernel::new(1.5, MaternNu::ThreeHalves).expect("valid"));
assert_eq!(iso.num_params(), 1);
let mut params = [0.0];
iso.get_params(&mut params).expect("len 1");
assert_close(params[0], 1.5_f64.ln(), TOL);
let mut ard =
KernelSpec::from(MaternArdKernel::new(&[1.0, 2.0], MaternNu::Half).expect("valid"));
assert_eq!(ard.num_params(), 2);
let mut ard_params = [0.0; 2];
ard.get_params(&mut ard_params).expect("len 2");
assert_close(ard_params[1], 2.0_f64.ln(), TOL);
ard_params[1] = 3.0_f64.ln();
ard.set_params(&ard_params).expect("len 2");
match ard.compile() {
crate::kernel::CompiledKernel::MaternArd(leaf) => {
assert_eq!(leaf.num_params(), 2);
assert_eq!(leaf.nu(), MaternNu::Half);
}
other => panic!("expected ARD Matern, got {other:?}"),
}
}
#[test]
fn periodic_flattens_lengthscale_then_period() {
let mut spec = KernelSpec::from(PeriodicKernel::new(1.5, 4.0).expect("valid"));
assert_eq!(spec.num_params(), 2);
let mut params = [0.0; 2];
spec.get_params(&mut params).expect("len 2");
assert_close(params[0], 1.5_f64.ln(), TOL);
assert_close(params[1], 4.0_f64.ln(), TOL);
params[1] = 2.0_f64.ln();
spec.set_params(¶ms).expect("len 2");
let b = spec.parameter_bindings();
assert_eq!(b.len(), 2);
assert_eq!(b[0].leaf_id, 0);
assert_eq!(b[1].local_index, 1);
match spec.compile() {
crate::kernel::CompiledKernel::Periodic(leaf) => {
assert_close(leaf.period(), 2.0, TOL);
}
other => panic!("expected Periodic, got {other:?}"),
}
assert_eq!(
spec.compile().coord_mode().expect("compat"),
crate::kernel::compiled::CoordMode::Dist
);
}
#[test]
fn rational_quadratic_flattens_iso_and_ard() {
let mut iso = KernelSpec::from(RationalQuadraticKernel::new(1.5, 0.8).expect("valid"));
assert_eq!(iso.num_params(), 2);
let mut params = [0.0; 2];
iso.get_params(&mut params).expect("len 2");
assert_close(params[0], 1.5_f64.ln(), TOL);
assert_close(params[1], 0.8_f64.ln(), TOL);
params[1] = 2.0_f64.ln();
iso.set_params(¶ms).expect("len 2");
match iso.compile() {
crate::kernel::CompiledKernel::RationalQuadratic(leaf) => {
assert_close(leaf.alpha(), 2.0, TOL);
}
other => panic!("expected RQ, got {other:?}"),
}
assert_eq!(
iso.compile().coord_mode().expect("compat"),
crate::kernel::compiled::CoordMode::Dist
);
let mut ard =
KernelSpec::from(RationalQuadraticArdKernel::new(&[1.0, 2.0], 0.5).expect("valid"));
assert_eq!(ard.num_params(), 3);
let mut ard_params = [0.0; 3];
ard.get_params(&mut ard_params).expect("len 3");
assert_close(ard_params[2], 0.5_f64.ln(), TOL);
ard_params[2] = 1.25_f64.ln();
ard.set_params(&ard_params).expect("len 3");
match ard.compile() {
crate::kernel::CompiledKernel::RationalQuadraticArd(leaf) => {
assert_eq!(leaf.num_params(), 3);
assert_close(leaf.alpha(), 1.25, TOL);
}
other => panic!("expected ARD RQ, got {other:?}"),
}
assert_eq!(
ard.compile().coord_mode().expect("compat"),
crate::kernel::compiled::CoordMode::Points
);
}
}