geometric_kernels.kernels.matern_kernel

Provides MaternGeometricKernel,the geometric Matérn kernel—with the heat kernel as a special case—that just works.

It wraps around different kernels and feature maps, dispatching on the space.

Unless you know exactly what you are doing, use MaternGeometricKernel.

Module Contents

class geometric_kernels.kernels.matern_kernel.MaternGeometricKernel[source]

This class represents a Matérn geometric kernel that “just works”. Unless you really know what you are doing, you should always use this kernel class.

Upon creation, unpacks into a specific geometric kernel based on the provided space, and, optionally, the associated (approximate) feature map.

__new__(space, num=None, normalize=True, return_feature_map=False, **kwargs)[source]

Construct a kernel and (if return_feature_map is True) a feature map on space.

Note

See this page for a brief introduction into feature maps.

Parameters:

  • space (geometric_kernels.spaces.Space) – Space to construct the kernel on.

  • num (int) –

    If provided, controls the “order of approximation” of the kernel. For the discrete spectrum spaces, this means the number of “levels” that go into the truncated series that defines the kernel (for example, these are unique eigenvalues for the Hypersphere or eigenvalues with repetitions for the Graph or for the Mesh). For the non-compact symmetric spaces (NoncompactSymmetricSpace), this is the number of random phases used to construct the kernel.

    If num=None, we use a (hopefully) reasonable default, which is space-dependent.

  • normalize (bool) –

    Normalize the kernel (and the feature map). If normalize=True, then either \(k(x, x) = 1\) for all \(x \in X\), where \(X\) is the space, or \(\int_X k(x, x) d x = 1\), depending on the space.

    Defaults to True.

    Note

    For many kernel methods, \(k(\cdot, \cdot)\) and \(a k(\cdot, \cdot)\) are indistinguishable, whatever the positive constant \(a\) is. For these, it makes sense to use normalize=False to save up some computational overhead. For others, like for the Gaussian process regression, the normalization of the kernel might be important. In these cases, you will typically want to set normalize=True.

  • return_feature_map (bool) –

    If True, return a feature map (needed e.g. for efficient sampling from Gaussian processes) along with the kernel.

    Default is False.

  • **kwargs – Any additional keyword arguments to be passed to the kernel (like key).

Note

For non-compact symmetric spaces, like Hyperbolic or SymmetricPositiveDefiniteMatrices, the key must be provided in **kwargs.

geometric_kernels.kernels.matern_kernel.default_feature_map(*, space=None, num=None, kernel=None)[source]

Constructs the default feature map for the specified space or kernel.

Parameters:

  • space (geometric_kernels.spaces.Space) – A space to construct the feature map on. If provided, kernel must either be omitted or set to None.

  • kernel (geometric_kernels.kernels.base.BaseGeometricKernel) – A kernel to construct the feature map from. If provided, space and num must either be omitted or set to None.

  • num (int) – Controls the number of features (dimensionality of the feature map). If omitted or set to None, the default value for each respective space is used. Must only be provided when constructing a feature map on a space (not from a kernel).

Returns:

Callable which is the respective feature map.

geometric_kernels.kernels.matern_kernel.default_num(space: geometric_kernels.spaces.DiscreteSpectrumSpace) → int[source]
geometric_kernels.kernels.matern_kernel.default_num(space: geometric_kernels.spaces.NoncompactSymmetricSpace) → int

Return the default approximation level for the space.

Parameters:

space – A space.

Returns:

The default approximation level.

Note

This function is organized as an abstract dispatcher plus a set of @overload-decorated implementations, one for each type of spaces.

When followed by an “empty” @dispatch-decorated function of the same name, plum-dispatch changes the default behavior of the @overload decorator, allowing the implementations inside the preceding @overload-decorated functions. This is opposed to the standard behavior when @overload-decorated functions can only provide type signature, while the general implementation should be contained in the function of the same name without an @overload decorator.

The trick is taken from https://beartype.github.io/plum/integration.html.

Note

For dispatching to work, the empty @dispatch-decorated function should follow (not precede) the @overload-decorated implementations in the code.

geometric_kernels.kernels.matern_kernel.feature_map_from_kernel(kernel: geometric_kernels.kernels.karhunen_loeve.MaternKarhunenLoeveKernel)[source]
geometric_kernels.kernels.matern_kernel.feature_map_from_kernel(kernel: geometric_kernels.kernels.feature_map.MaternFeatureMapKernel)

Return the default feature map for the specified kernel kernel.

Parameters:

kernel – A kernel to construct the feature map from.

Returns:

A feature map.

Return type:

feature_maps.FeatureMap

Note

This function is organized as an abstract dispatcher plus a set of @overload-decorated implementations, one for each type of kernels.

When followed by an “empty” @dispatch-decorated function of the same name, plum-dispatch changes the default behavior of the @overload decorator, allowing the implementations inside the preceding @overload-decorated functions. This is opposed to the standard behavior when @overload-decorated functions can only provide type signature, while the general implementation should be contained in the function of the same name without an @overload decorator.

The trick is taken from https://beartype.github.io/plum/integration.html.

Note

For dispatching to work, the empty @dispatch-decorated function should follow (not precede) the @overload-decorated implementations in the code.

geometric_kernels.kernels.matern_kernel.feature_map_from_space(space: geometric_kernels.spaces.DiscreteSpectrumSpace, num: int)[source]
geometric_kernels.kernels.matern_kernel.feature_map_from_space(space: geometric_kernels.spaces.NoncompactSymmetricSpace, num: int)

Return the default feature map for the specified space space and approximation level num.

Parameters:

  • space – A space to construct the feature map on.

  • num – Approximation level.

Returns:

A feature map.

Return type:

feature_maps.FeatureMap

Note

This function is organized as an abstract dispatcher plus a set of @overload-decorated implementations, one for each type of spaces.

When followed by an “empty” @dispatch-decorated function of the same name, plum-dispatch changes the default behavior of the @overload decorator, allowing the implementations inside the preceding @overload-decorated functions. This is opposed to the standard behavior when @overload-decorated functions can only provide type signature, while the general implementation should be contained in the function of the same name without an @overload decorator.

The trick is taken from https://beartype.github.io/plum/integration.html.

Note

For dispatching to work, the empty @dispatch-decorated function should follow (not precede) the @overload-decorated implementations in the code.