geometric_kernels.kernels.karhunen_loeve

This module provides the MaternKarhunenLoeveKernel kernel, the basic kernel for discrete spectrum spaces, subclasses of DiscreteSpectrumSpace.

Module Contents

class geometric_kernels.kernels.karhunen_loeve.MaternKarhunenLoeveKernel(space, num_levels, normalize=True)

Bases: geometric_kernels.kernels.base.BaseGeometricKernel

This class approximates Matérn kernel by its truncated Mercer decomposition, in terms of the eigenfunctions & eigenvalues of the Laplacian on the space.

\[k(x, x') = \sum_{l=0}^{L-1} S(\sqrt\lambda_l) \sum_{s=1}^{d_l} f_{ls}(x) f_{ls}(x'),\]

where \(\lambda_l\) and \(f_{ls}(\cdot)\) are the eigenvalues and eigenfunctions of the Laplacian such that \(\Delta f_{ls} = \lambda_l f_{ls}\), and \(S(\cdot)\) is the spectrum of the Matérn kernel. The eigenvalues and eigenfunctions belong to the DiscreteSpectrumSpace instance.

We denote

\[G_l(\cdot, \cdot') = \sum_{s=1}^{d_l} f_{ls}(\cdot) f_{ls}(\cdot')\]

and term the sets \([f_{ls}]_{s=1}^{d_l}\) “levels”.

For many spaces, like the sphere, we can employ addition theorems to efficiently compute \(G_l(\cdot, \cdot')\) without calculating the individual \(f_{ls}(\cdot)\). Note that \(\lambda_l\) are not required to be unique: it is possible that for some \(l,l'\), \(\lambda_l = \lambda_{l'}\). In other words, the “levels” do not necessarily correspond to full eigenspaces. A level may even correspond to a single eigenfunction.

Note

A brief introduction into the theory behind MaternKarhunenLoeveKernel can be found in this & this documentation pages.

Parameters:

• space (geometric_kernels.spaces.DiscreteSpectrumSpace) – The space to define the kernel upon.

• num_levels (int) – Number of levels to include in the summation.

• normalize (bool) – Whether to normalize kernel to have unit average variance.

K(params, X, X2=None, **kwargs)

Compute the cross-covariance matrix between two batches of vectors of inputs, or batches of matrices of inputs, depending on the space.

Parameters:

• params –

  A dict of kernel parameters, typically containing two keys: “lengthscale” for length scale and “nu” for smoothness.

  The types of values in the params dict determine the output type and the backend used for the internal computations, see the warning below for more details.

  Note

  The values params[“lengthscale”] and params[“nu”] are typically (1,)-shaped arrays of the suitable backend. This serves to point at the backend to be used for internal computations.

  In some cases, for example, when the kernel is ProductGeometricKernel, the values of params may be (s,)-shaped arrays instead, where s is the number of factors.

  Note

  Finite values of params[“nu”] typically correspond to the generalized (geometric) Matérn kernels.

  Infinite params[“nu”] typically corresponds to the heat kernel (a.k.a. diffusion kernel, generalized squared exponential kernel, generalized Gaussian kernel, generalized RBF kernel). Although it is often considered to be a separate entity, we treat the heat kernel as a member of the Matérn family, with smoothness parameter equal to infinity.

• X (lab.Numeric) – A batch of N inputs, each of which is a vector or a matrix, depending on how the elements of the self.space are represented.

• X2 (beartype.typing.Optional[lab.Numeric]) –

  A batch of M inputs, each of which is a vector or a matrix, depending on how the elements of the self.space are represented.

  X2=None sets X2=X1.

  Defaults to None.

Returns:

The N x M cross-covariance matrix.

Return type:

lab.Numeric

Warning

The types of values in the params dict determine the backend used for internal computations and the output type.

Even if, say, geometric_kernels.jax is imported but the values in the params dict are NumPy arrays, the output type will be a NumPy array, and NumPy will be used for internal computations. To get a JAX array as an output and use JAX for internal computations, all the values in the params dict must be JAX arrays.

K_diag(params, X, **kwargs)

Returns the diagonal of the covariance matrix self.K(params, X, X), typically in a more efficient way than actually computing the full covariance matrix with self.K(params, X, X) and then extracting its diagonal.

Parameters:

• params – Same as for K().

• X (lab.Numeric) – A batch of N inputs, each of which is a vector or a matrix, depending on how the elements of the self.space are represented.

Returns:

The N-dimensional vector representing the diagonal of the covariance matrix self.K(params, X, X).

Return type:

lab.Numeric

eigenvalues(params, normalize=None)

Eigenvalues of the kernel.

Parameters:

• params (beartype.typing.Dict[str, lab.Numeric]) – Parameters of the kernel. Must contain keys “lengthscale” and “nu”. The shapes of params[“lengthscale”] and params[“nu”] are (1,).

• normalize (beartype.typing.Optional[bool]) –

  Whether to normalize kernel to have unit average variance. If None, uses self.normalize to decide.

  Defaults to None.

Returns:

An [L, 1]-shaped array.

Return type:

lab.Numeric

init_params()

Initializes the dict of the trainable parameters of the kernel.

Returns dict(nu=np.array([np.inf]), lengthscale=np.array([1.0])).

This dict can be modified and is passed around into such methods as K() or K_diag(), as the params argument.

Note

The values in the returned dict are always of the NumPy array type. Thus, if you want to use some other backend for internal computations when calling K() or K_diag(), you need to replace the values with the analogs typed as arrays of the desired backend.

Return type:

beartype.typing.Dict[str, lab.NPNumeric]

property eigenfunctions: geometric_kernels.spaces.eigenfunctions.Eigenfunctions

Eigenfunctions of the kernel.

Return type:

geometric_kernels.spaces.eigenfunctions.Eigenfunctions

property eigenvalues_laplacian: lab.Numeric

Eigenvalues of the Laplacian.

Return type:

lab.Numeric

property space: geometric_kernels.spaces.DiscreteSpectrumSpace

The space on which the kernel is defined.

Return type:

geometric_kernels.spaces.DiscreteSpectrumSpace