# Matern¶

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

Matérn covariance function.

Covariance function defined by

$$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),$$

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

$$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}.$$
Parameters:

ExpQuad

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. 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:
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:

matrix

Convenience function computing the full covariance matrix of evaluations at two given sets of input points.

Examples

See documentation of class CovarianceFunction.

static half_integer_coefficients(p)[source]

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}$$.

We leverage the recursion

\begin{align} c_{p - i} & := \frac{p!}{(2p)!} \frac{(p + i)!}{i!(p - i)!} 2^{p - i} \\ & = \frac{2 (i + 1)}{(p + i + 1) (p - i)} c_{p - (i + 1)}, \end{align}

where $$c_0 = c_{p - p} = 1$$.

Parameters:

p (int) – Degree $$p$$ of the polynomial part.

Returns:

A tuple containing the exact rational coefficients of the polynomial part, where the entry at index $$i$$ contains the coefficient corresponding to the monomial with degree $$i$$.

Return type:

coefficients

linop(x0, x1=None)

LinearOperator representing the pairwise covariances of evaluations of $$f_0$$ and $$f_1$$ at the given input points.

Representing the resulting covariance matrix as a matrix-free LinearOperator is often more efficient than a representation as a ndarray, both in terms of memory and computation time, particularly when using iterative methods to solve the associated linear systems.

For instance, covariance matrices induced by separable covariance functions (e.g. tensor products of covariance functions or separable multi-output kernels) can often be represented as KroneckerProducts of smaller covariance matrices and frameworks like pykeops can be used to implement efficient matrix-vector products with covariance matrices without needing to construct the entire matrix in memory.

By default, a KeOps-based matrix-free implementation will be used if available. If there is no KeOps-based implementation, the standard implementation will be used as a fallback.

Parameters:
Returns:

shape= (output_size_0 * N0, output_size_1 * N1) with N0 = prod(batch_shape_0) and N1 = prod(batch_shape_1)LinearOperator representing the covariance matrix corresponding to the given batches of input points. The order of the rows and columns of the covariance matrix corresponds to the order of entries obtained by flattening ndarrays with shapes output_shape_0 + batch_shape_0 and output_shape_1 + batch_shape_1 in “C-order”.

Return type:

k_x0_x1

Raises:
matrix(x0, x1=None)

Matrix containing the pairwise covariances of evaluations of $$f_0$$ and $$f_1$$ at the given input points.

Parameters:
Returns:

shape= (output_size_0 * N0, output_size_1 * N1) with N0 = prod(batch_shape_0) and N1 = prod(batch_shape_1) – The covariance matrix corresponding to the given batches of input points. The order of the rows and columns of the covariance matrix corresponds to the order of entries obtained by flattening ndarrays with shapes output_shape_0 + batch_shape_0 and output_shape_0 + batch_shape_1 in “C-order”.

Return type:

k_x0_x1

Raises: