Utilities

This section covers the kernel objects used for defining filters and other helper functions.

Kernel Objects

class VFKernel(R, Q, D)

Vector Fitting Kernel representation.

A dataclass to store the components of a rational kernel approximation obtained from Vector Fitting.

classmethod from_dict(data)

Loads kernel data from a dictionary.

Parameters:

data (dict) – A dictionary containing the kernel parameters, typically loaded from a JSON file. It should have ‘poles’ and ‘d’ keys.

Returns:

A new instance of the VFKernel class.

Return type:

VFKernel

D

Direct term (offset) of shape (n_dims,).

Q

Poles vector of shape (n_poles,).

R

Residue matrix of shape (n_poles, n_dims).

class ChebyKernel(C, spectrum_bound)

Stores Chebyshev polynomial approximations for one or more kernels.

classmethod from_dict(data)

Loads kernel data from a dictionary.

classmethod from_function(f, order, spectrum_bound, n_samples=None, sampling='chebyshev', min_lambda=0.0, rtol=1e-12, adaptive=False, max_order=500, target_error=1e-10)

Creates a ChebyKernel by fitting a vectorized function.

Parameters:

• f (Callable[[np.ndarray], np.ndarray]) – The vectorized function to approximate.

• order (int) – Order of the Chebyshev polynomial to fit.

• spectrum_bound (float) – Upper bound of the function’s domain.

• n_samples (int, optional) – Number of sample points (only used for non-Chebyshev sampling).

• sampling (str, default 'chebyshev') – Sampling strategy: ‘chebyshev’ (optimal), ‘linear’, ‘quadratic’, ‘logarithmic’.

• min_lambda (float, default 0.0) – Lower bound of the sampling range.

• rtol (float, default 1e-12) – Relative tolerance for truncating negligible coefficients.

• adaptive (bool, default False) – If True, automatically determines optimal order to achieve target_error.

• max_order (int, default 500) – Maximum order for adaptive mode.

• target_error (float, default 1e-10) – Target approximation error for adaptive mode.

classmethod from_function_on_graph(L, f, order, **kwargs)

Creates a ChebyKernel fitted to a graph’s spectrum.

evaluate(x)

Evaluates the Chebyshev approximation at given points.

C

Coefficient matrix of shape (order + 1, n_dims).

spectrum_bound

Shared upper spectrum bound for all kernels.

Helper Functions

impulse(lap, n=0, n_timesteps=1)

Generates a Dirac impulse signal at a specified vertex.

Parameters:

• lap (csc_matrix) – Graph Laplacian defining the number of vertices.

• n (int) – Index of the vertex where the impulse is applied.

• n_timesteps (int) – Number of time steps (columns) in the resulting signal.

Returns:

1D array (n_vertices,) if n_timesteps=1, otherwise 2D array (n_vertices, n_timesteps) with 1.0 at index n and 0.0 elsewhere.

Return type:

ndarray

estimate_spectral_bound(L)

Estimates the largest eigenvalue (spectral bound) of a matrix.

This is typically used to find the domain [0, lambda_max] for Chebyshev polynomial approximations.

Parameters:

L (csc_matrix) – The matrix (e.g., Graph Laplacian) for which to estimate the bound.

Returns:

An estimate of the largest eigenvalue, scaled by 1.01 for safety.

Return type:

float