Matern¶

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

Bases: CovarianceFunction, IsotropicMixin

Matérn covariance function.

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 covariance function generalizes the ExpQuad covariance function via its additional parameter \(\nu\) controlling the smoothness of the functions in the associated RKHS. For \(\nu \rightarrow \infty\), the Matérn covariance function converges to the ExpQuad covariance function. 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 covariance 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 (int | Integral | integer | Iterable[int | Integral | integer]) – Shape of the covariance function’s inputs.
nu (int | float | complex | Number | number) – Hyperparameter \(\nu\) controlling differentiability.
lengthscales (_SupportsArray[dtype] | _NestedSequence[_SupportsArray[dtype]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None) – Lengthscales \(l_i\) along the different input dimensions of the covariance function. Describes the input scales on which the process varies. The lengthscales will be broadcast to the input shape of the covariance function.

See also

ExpQuad: Exponentiated Quadratic covariance function.
ProductMatern: Tensor product of 1D Matérn covariance functions.

Examples

>>> import numpy as np
>>> from probnum.randprocs.covfuncs 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_ndim_0`	Syntactic sugar for `len(input_shape_0)`.
`input_ndim_1`	Syntactic sugar for `len(input_shape_1)`.
`input_shape`	Shorthand for the input shape of a covariance function with `input_shape_0` `==` `input_shape_1`.
`input_shape_0`	`input_shape` of the `RandomProcess` \(f_0\).
`input_shape_1`	`input_shape` of the `RandomProcess` \(f_1\).
`input_size`	Syntactic sugar for the product of all entries in `input_shape`.
`input_size_0`	Syntactic sugar for the product of all entries in `input_shape_0`.
`input_size_1`	Syntactic sugar for the product of all entries in `input_shape_1`.
`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_0`	Syntactic sugar for `len(output_shape_0)`.
`output_ndim_1`	Syntactic sugar for `len(output_shape_1)`.
`output_shape_0`	`output_shape` of the `RandomProcess` \(f_0\).
`output_shape_1`	`output_shape` of the `RandomProcess` \(f_1\).
`output_size_0`	Syntactic sugar for the product of all entries in `output_shape_0`.
`output_size_1`	Syntactic sugar for the product of all entries in `output_shape_1`.
`p`	Degree \(p\) of the polynomial part of a Matérn covariance function with half-integer smoothness parameter \(\nu = p + \frac{1}{2}\).

Methods Summary

`__call__`(x0, x1)	Evaluate the (cross-)covariance function.
`half_integer_coefficients`(p)	Computes the rational coefficients \(c_i\) of the polynomial part of a Matérn covariance function with half-integer smoothness parameter \(\nu = \ p + \frac{1}{2}\).
`linop`(x0[, x1])	`LinearOperator` representing the pairwise covariances of evaluations of \(f_0\) and \(f_1\) at the given input points.
`matrix`(x0[, x1])	Matrix containing the pairwise covariances of evaluations of \(f_0\) and \(f_1\) at the given input points.

Attributes Documentation

input_ndim¶: Syntactic sugar for len(input_shape).

input_ndim_0¶: Syntactic sugar for len(input_shape_0).

input_ndim_1¶: Syntactic sugar for len(input_shape_1).

input_shape¶

Shorthand for the input shape of a covariance function with input_shape_0 == input_shape_1.

Raises:: ValueError – If the input shapes of the CovarianceFunction are not equal.

input_shape_0¶: input_shape of the RandomProcess \(f_0\). This defines the shape of a single, i.e. non-batched, first argument \(x_0\) of the CovarianceFunction.

input_shape_1¶: input_shape of the RandomProcess \(f_1\). This defines the shape of a single, i.e. non-batched, second argument \(x_1\) of the CovarianceFunction.

input_size¶: Syntactic sugar for the product of all entries in input_shape.

input_size_0¶: Syntactic sugar for the product of all entries in input_shape_0.

input_size_1¶: Syntactic sugar for the product of all entries in input_shape_1.

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_0¶: Syntactic sugar for len(output_shape_0).

output_ndim_1¶: Syntactic sugar for len(output_shape_1).

output_shape_0¶

output_shape of the RandomProcess \(f_0\).

This defines the first part of the shape of a single, i.e. non-batched, return value of __call__().

output_shape_1¶

output_shape of the RandomProcess \(f_1\).

This defines the second part of the shape of a single, i.e. non-batched, return value of __call__().

output_size_0¶: Syntactic sugar for the product of all entries in output_shape_0.

output_size_1¶: Syntactic sugar for the product of all entries in output_shape_1.

p¶

Degree \(p\) of the polynomial part of a Matérn covariance function 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.

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

Parameters:

x0 (ArrayLike) – shape= batch_shape_0 + input_shape_0 – (Batch of) input(s) for the first argument of the CovarianceFunction.
x1 (ArrayLike | None) – shape= batch_shape_1 + input_shape_1 – (Batch of) input(s) for the second argument of the CovarianceFunction. 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_0 + output_shape_1 – The (cross-)covariance function 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] = k(x0[batch_idx, ...], x1[batch_idx, ...])

where we assume that the batch shapes of x0 and x1 have been broadcast to a common shape bcast_batch_shape, and where batch_idx is an index compatible with bcast_batch_shape.

Return type:

k_x0_x1

Raises:

ValueError – If the shape of \(x_0\) is not of the form batch_shape_0 + input_shape_0.
ValueError – If the shape of \(x_1\) is not of the form batch_shape_1 + input_shape_1.
ValueError – If the inputs can not be broadcast to a common shape.