Matern¶

class probnum.randprocs.kernels.Matern(input_shape, nu=1.5, *, lengthscales=None)¶

Bases: Kernel, IsotropicMixin

Matérn kernel.

Covariance function defined by

\begin{equation} k_\nu(x_0, x_1) := \frac{2^{1 - \nu}}{\Gamma(\nu)} \left( \sqrt{2 \nu} \lVert x_0 - x_1 \rVert_{\Lambda^{-1}} \right)^\nu K_\nu \left( \sqrt{2 \nu} \lVert x_0 - x_1 \rVert_{\Lambda^{-1}} \right), \end{equation}

where \(K_\nu\) is a modified Bessel function of the second kind and

\[\lVert x_0 - x_1 \rVert_{\Lambda^{-1}}^2 := \sum_{i = 1}^d \frac{(x_{0,i} - x_{1,i})^2}{l_i}.\]

The Matérn kernel generalizes the ExpQuad kernel via its additional parameter \(\nu\) controlling the smoothness of the functions in the associated RKHS. For \(\nu \rightarrow \infty\), the Matérn kernel converges to the ExpQuad kernel. A Gaussian process with Matérn covariance function is \(\lceil \nu \rceil - 1\) times differentiable.

If \(\nu\) is a half-integer, i.e. \(\nu = p + \frac{1}{2}\) for some nonnegative integer \(p\), then the expression for the kernel function simplifies to a product of an exponential and a polynomial

\begin{equation} k_{\nu = p + \frac{1}{2}}(x_0, x_1) = \exp \left( -\sqrt{2 \nu} \lVert x_0 - x_1 \rVert_{\Lambda^{-1}} \right) \frac{p!}{(2p)!} \sum_{i = 0}^p \frac{(p + i)!}{i!(p - i)!} 2^{p - i} \left( \sqrt{2 \nu} \lVert x_0 - x_1 \rVert_{\Lambda^{-1}} \right)^{p - i}. \end{equation}

Parameters

input_shape (Union[int, Integral, integer, Iterable[Union[int, Integral, integer]]]) – Shape of the kernel’s inputs.
nu (Union[int, float, complex, Number, number]) – Hyperparameter \(\nu\) controlling differentiability.
lengthscales (Optional[Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]]) – Lengthscales \(l_i\) along the different input dimensions of the kernel. Describes the input scales on which the process varies. The lengthscales will be broadcast to the input shape of the kernel.

See also

ExpQuad: Exponentiated Quadratic / RBF kernel.
ProductMatern: Product Matern kernel.

Examples

>>> import numpy as np
>>> from probnum.randprocs.kernels import Matern
>>> K = Matern((), nu=2.5, lengthscales=0.1)
>>> xs = np.linspace(0, 1, 3)
>>> K.matrix(xs)
array([[1.00000000e+00, 7.50933789e-04, 3.69569622e-08],
       [7.50933789e-04, 1.00000000e+00, 7.50933789e-04],
       [3.69569622e-08, 7.50933789e-04, 1.00000000e+00]])

Attributes Summary

`input_ndim`	Syntactic sugar for `len(input_shape)`.
`input_shape`	Shape of single, i.e. non-batched, arguments of the covariance function.
`input_size`	Syntactic sugar for the product over the input size.
`is_half_integer`	Indicates whether \(\nu\) is a half-integer.
`lengthscale`	Deprecated.
`lengthscales`	Input lengthscales along the different input dimensions.
`nu`	Smoothness parameter \(\nu\).
`output_ndim`	Syntactic sugar for `len(output_shape)`.
`output_shape`	Shape of single, i.e. non-batched, return values of the covariance function.
`p`	Degree \(p\) of the polynomial part of a Matérn kernel with half-integer smoothness parameter \(\nu = p + \frac{1}{2}\).

Methods Summary

`__call__`(x0, x1)	Evaluate the (cross-)covariance function(s).
`half_integer_coefficients`(p)	Computes the rational coefficients \(c_i\) of the polynomial part of a Matérn kernel with half-integer smoothness parameter \(\nu = p + \frac{1}{2}\).
`matrix`(x0[, x1])	A convenience function for computing a kernel matrix for two sets of inputs.

Attributes Documentation

input_ndim¶: Syntactic sugar for len(input_shape).

input_shape¶: Shape of single, i.e. non-batched, arguments of the covariance function.

input_size¶: Syntactic sugar for the product over the input size.

is_half_integer¶: Indicates whether \(\nu\) is a half-integer.

lengthscale¶: Deprecated.

lengthscales¶: Input lengthscales along the different input dimensions.

nu¶: Smoothness parameter \(\nu\).

output_ndim¶: Syntactic sugar for len(output_shape).

output_shape¶

Shape of single, i.e. non-batched, return values of the covariance function.

If output_shape is (), the Kernel instance represents a single (cross-)covariance function. Otherwise, i.e. if output_shape is non-empty, the Kernel instance represents a tensor of (cross-)covariance functions whose shape is given by output_shape.

p¶

Degree \(p\) of the polynomial part of a Matérn kernel with half-integer smoothness parameter \(\nu = p + \frac{1}{2}\). If \(\nu\) is not a half-integer, this is set to None.

Sample paths of a Gaussian process with this covariance function are \(p\)-times continuously differentiable.

Methods Documentation

__call__(x0, x1)¶

Evaluate the (cross-)covariance function(s).

The evaluation of the (cross-covariance) function(s) is vectorized over the batch shapes of the arguments, applying standard NumPy broadcasting.

Parameters

x0 (ArrayLike) – shape= batch_shape_0 + input_shape – (Batch of) input(s) for the first argument of the Kernel.
x1 (Optional[ArrayLike]) – shape= batch_shape_1 + input_shape – (Batch of) input(s) for the second argument of the Kernel. Can also be set to None, in which case the function will behave as if x1 = x0 (but it is implemented more efficiently).

Returns

shape= bcast_batch_shape + output_shape – The (cross-)covariance function(s) evaluated at (x0, x1). Since the function is vectorized over the batch shapes of the inputs, the output array contains the following entries:

k_x0_x1[batch_idx + output_idx] = k[output_idx](
    x0[batch_idx, ...],
    x1[batch_idx, ...],
)

where we assume that x0 and x1 have been broadcast to a common shape bcast_batch_shape + input_shape, and where output_idx and batch_idx are indices compatible with output_shape and bcast_batch_shape, respectively. By k[output_idx] we refer to the covariance function at index output_idx in the tensor of covariance functions represented by the Kernel instance.

Return type

k_x0_x1

Raises

ValueError – If one of the input shapes is not of the form batch_shape_{0,1} + input_shape.
ValueError – If the inputs can not be broadcast to a common shape.