Gram Matrix Kernels#
2026-09-01
12 min read time
Gram matrix kernels evaluate the Hermitian matrix of inner products between two vector sets, and are used to build kernel-based methods such as polynomial, tanh, and RBF kernels.
#include <cuvs/distance/grammian.hpp>
namespace cuvs::distance::kernels
Gram Matrix Kernels#
-
template<typename math_t>
class GramMatrixBase# - #include <grammian.hpp>
Base class for general Gram matrices A Gram matrix is the Hermitian matrix of inner probucts G_ik = <x_i, x_k> Here, the inner product is evaluated for all elements from vectors sets X1, and X2.
To be more precise, on exit the output buffer will store:
if is_row_major == true: out[j+k*n1] = <x1_j, x2_k>,
if is_row_major == false: out[j*n2 + k] = <x1_j, x2_k>, where x1_j is the j-th vector from the x1 set and x2_k is the k-th vector from the x2 set.
Subclassed by cuvs::distance::kernels::PolynomialKernel< math_t, exp_t >, cuvs::distance::kernels::RBFKernel< math_t >, cuvs::distance::kernels::TanhKernel< math_t >
Public Functions
- void operator()(
- raft::resources const &handle,
- dense_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1 = nullptr,
- math_t *norm_x2 = nullptr
Convenience function to evaluate the Gram matrix for two vector sets. Vector sets are provided in Matrix format
- Parameters:
handle – [in] raft handle
x1 – [in] dense device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – optional L2-norm of x1’s rows for computation within RBF.
norm_x2 – optional L2-norm of x2’s rows for computation within RBF.
- void operator()(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1 = nullptr,
- math_t *norm_x2 = nullptr
Convenience function to evaluate the Gram matrix for two vector sets. Vector sets are provided in Matrix format
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – optional L2-norm of x1’s rows for computation within RBF.
norm_x2 – optional L2-norm of x2’s rows for computation within RBF.
- void operator()(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- csr_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1 = nullptr,
- math_t *norm_x2 = nullptr
Convenience function to evaluate the Gram matrix for two vector sets. Vector sets are provided in Matrix format
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] csr device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – optional L2-norm of x1’s rows for computation within RBF.
norm_x2 – optional L2-norm of x2’s rows for computation within RBF.
- virtual void evaluate(
- raft::resources const &handle,
- dense_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate the Gram matrix for two vector sets using simple dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] dense device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate the Gram matrix for two vector sets using simple dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- csr_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate the Gram matrix for two vector sets using simple dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] csr device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- const math_t *x1,
- int n1,
- int n_cols,
- const math_t *x2,
- int n2,
- math_t *out,
- bool is_row_major,
- cudaStream_t stream,
- int ld1,
- int ld2,
- int ld_out
Evaluate the Gram matrix for two vector sets using simple dot product.
- Parameters:
x1 – [in] device array of vectors, size [n1*n_cols]
n1 – [in] number vectors in x1
n_cols – [in] number of columns (features) in x1 and x2
x2 – [in] device array of vectors, size [n2*n_cols]
n2 – [in] number vectors in x2
out – [out] device buffer to store the Gram matrix, size [n1*n2]
is_row_major – [in] whether the input and output matrices are in row major format
stream – [in] cuda stream
ld1 – leading dimension of x1 (usually it is n1)
ld2 – leading dimension of x2 (usually it is n2)
ld_out – leading dimension of out (usually it is n1)
- void operator()(
- const math_t *x1,
- int n1,
- int n_cols,
- const math_t *x2,
- int n2,
- math_t *out,
- bool is_row_major,
- cudaStream_t stream,
- int ld1 = 0,
- int ld2 = 0,
- int ld_out = 0
Convenience function to evaluate the Gram matrix for two vector sets.
- Parameters:
x1 – [in] device array of vectors, size [n1*n_cols]
n1 – [in] number vectors in x1
n_cols – [in] number of columns (features) in x1 and x2
x2 – [in] device array of vectors, size [n2*n_cols]
n2 – [in] number vectors in x2
out – [out] device buffer to store the Gram matrix, size [n1*n2]
is_row_major – [in] whether the input and output matrices are in row major format
stream – [in] cuda stream
ld1 – leading dimension of x1
ld2 – leading dimension of x2
ld_out – leading dimension of out
-
template<typename math_t>
class KernelFactory#
-
template<typename math_t, typename exp_t>
class PolynomialKernel : public cuvs::distance::kernels::GramMatrixBase<math_t># - #include <grammian.hpp>
Create a kernel matrix using polynomial kernel function.
Public Functions
- inline PolynomialKernel( )#
Constructs a polynomial kernel object. It evaluates the kernel matrix using the following formula: K_ij = (gain*<x1_i, x2_k> + offset)^exponent
- Template Parameters:
math_t – floating point type
exp_t – type of exponent
- Parameters:
exponent –
gain –
offset –
- virtual void evaluate(
- raft::resources const &handle,
- dense_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using polynomial kernel.
output[i,k] = (gain*<x1_i, x2_k> + offset)^exponent, where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and < , > denotes dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] dense device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using polynomial kernel.
output[i,k] = (gain*<x1_i, x2_k> + offset)^exponent, where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and < , > denotes dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- csr_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using polynomial kernel.
output[i,k] = (gain*<x1_i, x2_k> + offset)^exponent, where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and < , > denotes dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] csr device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- const math_t *x1,
- int n1,
- int n_cols,
- const math_t *x2,
- int n2,
- math_t *out,
- bool is_row_major,
- cudaStream_t stream,
- int ld1,
- int ld2,
- int ld_out
Evaluate the Gram matrix using the legacy interface.
- Parameters:
x1 – [in] device array of vectors, size [n1*n_cols]
n1 – [in] number vectors in x1
n_cols – [in] number of columns (features) in x1 and x2
x2 – [in] device array of vectors, size [n2*n_cols]
n2 – [in] number vectors in x2
out – [out] device buffer to store the Gram matrix, size [n1*n2]
is_row_major – [in] whether the input and output matrices are in row major format
stream – [in] cuda stream
ld1 – leading dimension of x1 (usually it is n1)
ld2 – leading dimension of x2 (usually it is n2)
ld_out – leading dimension of out (usually it is n1)
-
template<typename math_t>
class TanhKernel : public cuvs::distance::kernels::GramMatrixBase<math_t># - #include <grammian.hpp>
Create a kernel matrix using tanh kernel function.
Public Functions
- inline TanhKernel( )#
Constructs a tanh kernel object. It evaluates the kernel matrix using the following formula: K_ij = tanh(gain*<x1_i, x2_k> + offset)
- Template Parameters:
math_t – floating point type
- Parameters:
gain –
offset –
- virtual void evaluate(
- raft::resources const &handle,
- dense_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using tanh kernel.
output_[i + k*n1] = (gain*<x1_i, x2_k> + offset)^exponent, where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and < , > denotes dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] dense device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using tanh kernel.
output_[i + k*n1] = (gain*<x1_i, x2_k> + offset)^exponent, where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and < , > denotes dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- csr_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using tanh kernel.
output_[i + k*n1] = (gain*<x1_i, x2_k> + offset)^exponent, where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and < , > denotes dot product.
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] csr device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – unused.
norm_x2 – unused.
- virtual void evaluate(
- const math_t *x1,
- int n1,
- int n_cols,
- const math_t *x2,
- int n2,
- math_t *out,
- bool is_row_major,
- cudaStream_t stream,
- int ld1,
- int ld2,
- int ld_out
Evaluate the Gram matrix using the legacy interface.
- Parameters:
x1 – [in] device array of vectors, size [n1*n_cols]
n1 – [in] number vectors in x1
n_cols – [in] number of columns (features) in x1 and x2
x2 – [in] device array of vectors, size [n2*n_cols]
n2 – [in] number vectors in x2
out – [out] device buffer to store the Gram matrix, size [n1*n2]
is_row_major – [in] whether the input and output matrices are in row major format
stream – [in] cuda stream
ld1 – leading dimension of x1 (usually it is n1)
ld2 – leading dimension of x2 (usually it is n2)
ld_out – leading dimension of out (usually it is n1)
-
template<typename math_t>
class RBFKernel : public cuvs::distance::kernels::GramMatrixBase<math_t># - #include <grammian.hpp>
Create a kernel matrix using RBF kernel function.
Public Functions
- inline RBFKernel(
- math_t gain
Constructs a RBF kernel object. It evaluates the kernel matrix using the following formula: K_ij = exp(-gain*|x1_i- x2_k|^2)
- Template Parameters:
math_t – floating point type
- Parameters:
gain –
- virtual void evaluate(
- raft::resources const &handle,
- dense_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using RBF kernel.
output_[i + k*n1] = exp(-gain*|x1_i - x2_k|^2), where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and | | euclidean distance.
- Parameters:
handle – [in] raft handle
x1 – [in] dense device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – optional L2-norm of x1’s rows for computation within RBF.
norm_x2 – optional L2-norm of x2’s rows for computation within RBF.
- virtual void evaluate(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- dense_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using RBF kernel.
output_[i + k*n1] = exp(-gain*|x1_i - x2_k|^2), where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and | | euclidean distance.
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] dense device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – optional L2-norm of x1’s rows for computation within RBF.
norm_x2 – optional L2-norm of x2’s rows for computation within RBF.
- virtual void evaluate(
- raft::resources const &handle,
- csr_input_matrix_view_t<math_t> x1,
- csr_input_matrix_view_t<math_t> x2,
- dense_output_matrix_view_t<math_t> out,
- math_t *norm_x1,
- math_t *norm_x2
Evaluate kernel matrix using RBF kernel.
output_[i + k*n1] = exp(-gain*|x1_i - x2_k|^2), where x1_i is the i-th vector from the x1 set, and x2_k is k-th vector in the x2 set, and | | euclidean distance.
- Parameters:
handle – [in] raft handle
x1 – [in] csr device matrix view, size [n1*n_cols]
x2 – [in] csr device matrix view, size [n2*n_cols]
out – [out] dense device matrix view for the Gram matrix, size [n1*n2]
norm_x1 – optional L2-norm of x1’s rows for computation within RBF.
norm_x2 – optional L2-norm of x2’s rows for computation within RBF.
- virtual void evaluate(
- const math_t *x1,
- int n1,
- int n_cols,
- const math_t *x2,
- int n2,
- math_t *out,
- bool is_row_major,
- cudaStream_t stream,
- int ld1,
- int ld2,
- int ld_out
Evaluate the Gram matrix using the legacy interface.
- Parameters:
x1 – [in] device array of vectors, size [n1*n_cols]
n1 – [in] number vectors in x1
n_cols – [in] number of columns (features) in x1 and x2
x2 – [in] device array of vectors, size [n2*n_cols]
n2 – [in] number vectors in x2
out – [out] device buffer to store the Gram matrix, size [n1*n2]
is_row_major – [in] whether the input and output matrices are in row major format
stream – [in] cuda stream
ld1 – leading dimension of x1 (usually it is n1)
ld2 – leading dimension of x2 (usually it is n2)
ld_out – leading dimension of out (usually it is n1)