tensorlogic_sklears_kernels/deep_kernel/
mod.rs

1//! Deep Kernel Learning (DKL).
2//!
3//! This module implements the Deep Kernel Learning architecture of
4//! Wilson et al. (2016). A DKL wraps a classical base kernel
5//! `K_base(·, ·)` with a differentiable feature extractor `g_θ` and
6//! evaluates
7//!
8//! ```text
9//! K_DKL(x, y) = K_base(g_θ(x), g_θ(y)).
10//! ```
11//!
12//! In the v0.2.0 research preview we ship a single reference feature
13//! extractor — an MLP with Xavier/Glorot-normal initialisation (via
14//! SciRS2-Core's seeded RNG) and support for ReLU / Tanh / Identity
15//! activations. The generic [`DeepKernel`] is parameterised by the
16//! extractor and the base kernel, so any other kernel in this crate
17//! (RBF, Linear, Matern, …) plugs in without modification.
18//!
19//! # Relationship to `learned_composition`
20//!
21//! This module is the "nonlinear feature composition" counterpart of
22//! [`crate::learned_composition`]. Where
23//! [`crate::learned_composition::LearnedMixtureKernel`] learns a
24//! softmax-weighted mixture *over* a library of kernels,
25//! [`DeepKernel`] learns a nonlinear feature map that *transforms*
26//! inputs before a single base kernel is applied. The two modules are
27//! intended to be used together for expressive, trainable similarity
28//! metrics.
29//!
30//! # Module layout
31//!
32//! * [`layer`] — [`DenseLayer`] / [`Activation`] primitives.
33//! * [`feature_extractor`] — [`NeuralFeatureMap`] trait and
34//!   [`MLPFeatureExtractor`] reference implementation.
35//! * [`kernel`] — the [`DeepKernel`] wrapper that composes a feature
36//!   map with a base kernel and implements [`crate::Kernel`].
37//! * [`gradient`] — finite-difference verification and an analytical
38//!   gradient path for the RBF-base case.
39//! * [`builder`] — fluent [`DeepKernelBuilder`] for common MLP
40//!   topologies.
41//!
42//! # Gradient semantics
43//!
44//! * **Analytical**: the closed form `∂K_DKL/∂θ` for the
45//!   MLP-extractor + RBF-base case is available via
46//!   [`gradient::rbf_dkl_gradient`] — one forward+backward pass, no
47//!   autodiff.
48//! * **Numerical**: every `DeepKernel<MLPFeatureExtractor, K>` supports
49//!   [`gradient::finite_difference_gradient`] as a correctness check or
50//!   as a stand-in for base kernels whose analytical chain rule has not
51//!   yet been derived.
52//! * **Base-kernel hyperparameters**: gradients w.r.t. e.g. the RBF
53//!   `γ` are **not** produced here — callers should go through
54//!   [`crate::tensor_kernels::RbfKernel::compute_with_gradient`] or a
55//!   future autodiff layer.
56//!
57//! # Example
58//!
59//! ```rust
60//! use tensorlogic_sklears_kernels::{
61//!     deep_kernel::{Activation, DeepKernelBuilder},
62//!     Kernel, RbfKernel, RbfKernelConfig,
63//! };
64//!
65//! let rbf = RbfKernel::new(RbfKernelConfig::new(0.5)).expect("valid gamma");
66//! let dkl = DeepKernelBuilder::new()
67//!     .input_dim(2)
68//!     .hidden_layer(4, Activation::Tanh)
69//!     .output_dim(2, Activation::Identity)
70//!     .seed(42)
71//!     .build(rbf)
72//!     .expect("valid topology");
73//!
74//! let x = vec![0.1, -0.2];
75//! let y = vec![0.3, 0.4];
76//! let _value = dkl.compute(&x, &y).expect("dkl value");
77//! ```
78
79pub mod builder;
80pub mod feature_extractor;
81pub mod gradient;
82pub mod kernel;
83pub mod layer;
84
85#[cfg(test)]
86mod tests;
87
88pub use builder::DeepKernelBuilder;
89pub use feature_extractor::{ForwardCache, LayerCache, MLPFeatureExtractor, NeuralFeatureMap};
90pub use gradient::{finite_difference_gradient, rbf_dkl_gradient};
91pub use kernel::{DeepKernel, DeepKernelSummary, FeatureMapShape};
92pub use layer::{Activation, DenseLayer};
tensorlogic_sklears_kernels/deep_kernel/mod.rs

tensorlogic_sklears_kernels/deep_kernel/
mod.rs
