quadsv.kernels

Kernel matrix construction and spectral properties.

class quadsv.kernels.Kernel(n: int, method: str = 'gaussian', **kwargs)

Bases: ABC

Abstract base class for spatial kernels.

Handles dense, sparse, and implicit (operator-based) kernels. Implements a dual-mode system that switches between explicit (dense) and implicit (sparse) computation based on problem size.

n

Number of observations (samples).

Type:

int

method

The kernel method (‘gaussian’, ‘matern’, ‘moran’, ‘graph_laplacian’, ‘car’).

Type:

str

is_implicit

If True, uses sparse solver for implicit kernels (N > 5000). If False, uses dense matrix operations.

Type:

bool

params

Additional kernel parameters (bandwidth, nu, rho, etc.).

Type:

dict

__init__(n: int, method: str = 'gaussian', **kwargs) → None

Initialize the Kernel.

Parameters:

• n (int) – Number of observations.

• method (str, default 'gaussian') – Kernel method to use.

• **kwargs (dict) – Additional kernel-specific parameters.

realization() → ndarray

Return the realized (N, N) kernel matrix.

Returns:

Dense (N, N) kernel matrix.

Return type:

np.ndarray

Warning

If is_implicit is True, this forces expensive dense inversion of the precision matrix. Use xtKx() and trace() for implicit kernels instead.

eigenvalues(k: int | None = None) → ndarray

Compute the k largest eigenvalues of the kernel matrix.

Parameters:

k (int, optional) – Number of largest eigenvalues to return. If None, returns all.

Returns:

Eigenvalues sorted in descending order, shape (k,) or (n,).

Return type:

np.ndarray

xtKx(x: ndarray | spmatrix) → float | ndarray

Efficiently compute the quadratic form x^T K x.

Handles both single vectors and batches. Uses implicit solvers for large N (implicit_threshold) to avoid dense matrix operations. Supports sparse input matrices without densification.

Parameters:

x (np.ndarray or scipy.sparse matrix) – Input vector of shape (N,) or batch of vectors (N, M). Can be dense numpy array or sparse matrix (CSC/CSR format).

Returns:

Quadratic form value(s). Scalar if input was 1D, shape (M,) if input was 2D.

Return type:

float or np.ndarray

Notes

For implicit kernels, uses sparse solve instead of matrix inversion. For sparse input, maintains sparsity throughout computation where possible.

trace() → float

Compute the trace of the kernel matrix Tr(K).

For implicit kernels, uses Hutchinson’s trick with random vectors for efficient O(N) estimation instead of O(N³) eigendecomposition.

Returns:

Trace of the kernel matrix.

Return type:

float

square_trace() → float

Compute the trace of the squared kernel Tr(K²).

Used for variance estimation in statistical tests. For implicit kernels, uses Hutchinson’s trick for efficient O(N) estimation.

Returns:

Trace of K squared.

Return type:

float

__getstate__()

Custom pickling behavior: exclude unpicklable SuperLU objects.

__setstate__(state)

Restore state and ensure _lu is reset to None.

class quadsv.kernels.SpatialKernel(data: ndarray, mode: str = 'coords', method: str = 'matern', **kwargs)

Bases: Kernel

Concrete implementation of Spatial Kernel.

Can be built from raw coordinates OR from precomputed matrices.

data

Raw data (coordinates or matrix) used to construct the kernel.

Type:

np.ndarray

mode

How the kernel was initialized.

Type:

{‘coords’, ‘precomputed’, ‘precomputed_inverse’}

__init__(data: ndarray, mode: str = 'coords', method: str = 'matern', **kwargs) → None

Internal constructor. Use .from_coordinates() or .from_matrix() instead.

Parameters:

• data (np.ndarray) – Input data (coordinates or kernel matrix).

• mode ({'coords', 'precomputed', 'precomputed_inverse'}, default 'coords') – Interpretation of the data.

• method (str, default 'matern') – Kernel method to use.

• **kwargs (dict) – Additional kernel parameters.

classmethod from_coordinates(coords: ndarray, method: str = 'matern', **kwargs) → SpatialKernel

Build kernel from spatial coordinates.

Parameters:

• coords (np.ndarray) – Array of spatial coordinates, shape (N, D).

• method (str, default 'matern') – Kernel method. Must be one of ‘gaussian’, ‘matern’, ‘moran’, ‘graph_laplacian’, ‘car’.

• **kwargs (dict) – Additional kernel parameters (bandwidth, nu, rho, k_neighbors, etc.).

Returns:

Initialized kernel object.

Return type:

SpatialKernel

Examples

>>> coords = np.random.randn(100, 2)
>>> kernel = SpatialKernel.from_coordinates(coords, method='gaussian', bandwidth=1.0)

classmethod from_matrix(matrix: ndarray | spmatrix, is_inverse: bool = False, method: str = 'precomputed', **kwargs) → SpatialKernel

Build kernel from a precomputed kernel matrix or its inverse.

Parameters:

• matrix (np.ndarray or scipy.sparse matrix) – Kernel matrix (N, N) or its inverse (precision matrix).

• is_inverse (bool, default False) – If True, matrix is treated as the inverse (precision) matrix K^-1.

• method (str, default 'precomputed') – The logical kernel method (e.g., ‘car’ for precision matrices).

• **kwargs (dict) – Additional parameters.

Returns:

Initialized kernel object.

Return type:

SpatialKernel

Examples

>>> K = np.array([[2, -1], [-1, 2]])  # kernel matrix
>>> kernel = SpatialKernel.from_matrix(K, is_inverse=False)