Gram Matrix Kernels#

2026-09-01

12 min read time

Applies to Linux

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(
exp_t exponent,
math_t gain,
math_t offset
)#

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(
math_t gain,
math_t offset
)#

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)