API Reference / algorithms / svm / kernels /

precomputed.py

Precomputed Kernel Matrix implementation.

Classes

PrecomputedKernel

class algorithms.svm.kernels.precomputed.PrecomputedKernel(Kernel)

Precomputed Kernel Matrix for supplying a pre-calculated Gram matrix.

The Precomputed Kernel allows users to provide their own kernel (Gram) matrix rather than having it computed internally. This is useful when the kernel is expensive to compute, when using a custom kernel not available in the library, or when the kernel matrix comes from an external source.
Constructor 
__init__(
    self,
    kernel_matrix: np.ndarray = None,
)

Overview

The usage workflow is:

  1. Compute a kernel matrix K externally (e.g., a custom domain-specific kernel)
  2. Pass the matrix to PrecomputedKernel (either at construction or via set_kernel_matrix)
  3. Call build(X) to associate training indices with the matrix
  4. Use compute(i, j) or compute_matrix() to retrieve kernel values

Theory

A valid kernel matrix K \in \mathbb{R}^{n \times n} must be symmetric and positive semi-definite (Mercer's condition):

K_{ij} = K(x_i, x_j), \quad K = K^T, \quad \forall c: c^T K c \geq 0

Any function K: \mathcal{X} \times \mathcal{X} \to \mathbb{R} satisfying Mercer's theorem can be represented as a precomputed matrix.

Parameters

kernel_matrix
np.ndarray or None = None
Precomputed kernel matrix of shape (n_samples, n_samples). If None, the matrix passed to build() is treated as the kernel matrix itself.

Attributes

n_samples\_
int
Number of samples in the kernel matrix.
n_features\_
int
Number of features (or n_samples when the matrix is used directly).

Notes

Complexity:

  • Lookup: O(1) per pair (direct matrix indexing)
  • Storage: O(n^2) for the full Gram matrix
When to use PrecomputedKernel:
  • When using a domain-specific or custom kernel function
  • When the kernel computation is expensive and should be done once
  • Graph kernels, Wasserstein kernels, or other specialized similarity measures
  • When leveraging external libraries to compute the kernel matrix

References

Scholkopf2002
Schoelkopf, B. and Smola, A.J. (2002). Learning with Kernels: Support Vector Machines, Regularization, Optimization, and Beyond. MIT Press.

See Also

RBFKernel

Gaussian RBF kernel computed on-the-fly.
LinearKernel

Linear kernel for dot-product similarity.

Basic usage with an externally computed kernel matrix:

python 
>>> from tuiml.algorithms.svm.kernels import PrecomputedKernel
>>> import numpy as np
>>>
>>> # Create a simple kernel matrix (linear kernel)
>>> X = np.array([[1, 2], [3, 4], [5, 6]])
>>> K = X @ X.T
>>> kernel = PrecomputedKernel(kernel_matrix=K)
>>> kernel.build(X)
PrecomputedKernel(...)
>>> value = kernel.compute(0, 1)

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return parameter schema.

build (self, X: np.ndarray) -> 'PrecomputedKernel'

Build with training data.

Parameters
X
np.ndarray
Training data or kernel matrix.
Returns
self
PrecomputedKernel
Returns the built instance.
set_kernel_matrix (self, K: np.ndarray) -> 'PrecomputedKernel'

Set or update the kernel matrix.

Parameters
K
np.ndarray of shape (n_samples, n_samples)
Kernel matrix.
Returns
self
PrecomputedKernel
Returns the updated instance.
evaluate (self, x1: np.ndarray, x2: np.ndarray) -> float

Evaluate is not supported for precomputed kernels.

Parameters
x1
np.ndarray
First vector (unused).
x2
np.ndarray
Second vector (unused).
Returns
None
Raises
NotImplementedError
Always raised; use compute(i, j) instead.
compute (self, i: int, j: int) -> float

Get precomputed kernel value.

Parameters
i
int
Index of first instance.
j
int
Index of second instance.
Returns
val
float
K[i, j] from precomputed matrix.
compute_matrix (self) -> np.ndarray

Return a copy of the precomputed kernel matrix.

Returns
K
np.ndarray of shape (n_samples, n_samples)
A copy of the stored Gram matrix.
compute_matrix_cross (self, X1: np.ndarray, X2: np.ndarray) -> np.ndarray

Retrieve sub-matrix from the precomputed kernel matrix by index.

Parameters
X1
np.ndarray of shape (n1,) or (n1, n_features)
If 1-D integer array, treated as row indices into the stored kernel matrix. Otherwise falls back to the base class.
X2
np.ndarray of shape (n2,) or (n2, n_features)
If 1-D integer array, treated as column indices into the stored kernel matrix. Otherwise falls back to the base class.
Returns
K
np.ndarray of shape (n1, n2)
Sub-matrix of the precomputed kernel.
__repr__ (self) -> str

String representation.