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 theExpQuad
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
Syntactic sugar for
len(
input_shape
)
.Syntactic sugar for
len(
input_shape_0
)
.Syntactic sugar for
len(
input_shape_1
)
.Shorthand for the input shape of a covariance function with
input_shape_0
==
input_shape_1
.input_shape
of theRandomProcess
\(f_0\).input_shape
of theRandomProcess
\(f_1\).Syntactic sugar for the product of all entries in
input_shape
.Syntactic sugar for the product of all entries in
input_shape_0
.Syntactic sugar for the product of all entries in
input_shape_1
.Indicates whether \(\nu\) is a half-integer.
Deprecated.
Input lengthscales along the different input dimensions.
Smoothness parameter \(\nu\).
Syntactic sugar for
len(
output_shape_0
)
.Syntactic sugar for
len(
output_shape_1
)
.output_shape
of theRandomProcess
\(f_0\).output_shape
of theRandomProcess
\(f_1\).Syntactic sugar for the product of all entries in
output_shape_0
.Syntactic sugar for the product of all entries in
output_shape_1
.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 theRandomProcess
\(f_0\). This defines the shape of a single, i.e. non-batched, first argument \(x_0\) of theCovarianceFunction
.
- input_shape_1¶
input_shape
of theRandomProcess
\(f_1\). This defines the shape of a single, i.e. non-batched, second argument \(x_1\) of theCovarianceFunction
.
- 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 theRandomProcess
\(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 theRandomProcess
\(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 theCovarianceFunction
.x1 (ArrayLike | None) – shape=
batch_shape_1 +
input_shape_1
– (Batch of) input(s) for the second argument of theCovarianceFunction
. Can also be set toNone
, in which case the function will behave as ifx1 = 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
andx1
have been broadcast to a common shapebcast_batch_shape
, and wherebatch_idx
is an index compatible withbcast_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.
See also
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 andarray
, 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
KroneckerProduct
s of smaller covariance matrices and frameworks likepykeops
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:
x0 (ArrayLike) – shape=
batch_shape_0 +
input_shape_0
– (Batch of) input(s) for the first argument of theCovarianceFunction
.x1 (ArrayLike | None) – shape=
batch_shape_1 +
input_shape_1
– (Batch of) input(s) for the second argument of theCovarianceFunction
. Can also be set toNone
, in which case the function will behave as ifx1 == x0
(potentially using a more efficient implementation for this particular case).
- Returns:
shape=
(
output_size_0
* N0,
output_size_1
* N1)
withN0 = prod(batch_shape_0)
andN1 = 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 flatteningndarray
s with shapesoutput_shape_0
+ batch_shape_0
andoutput_shape_1
+ batch_shape_1
in “C-order”.- 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
.
- matrix(x0, x1=None)¶
Matrix containing the pairwise covariances of evaluations of \(f_0\) and \(f_1\) at the given input points.
- Parameters:
x0 (ArrayLike) – shape=
batch_shape_0 +
input_shape_0
– (Batch of) input(s) for the first argument of theCovarianceFunction
.x1 (ArrayLike | None) – shape=
batch_shape_1 +
input_shape_1
– (Batch of) input(s) for the second argument of theCovarianceFunction
. Can also be set toNone
, in which case the function will behave as ifx1 == x0
(potentially using a more efficient implementation for this particular case).
- Returns:
shape=
(
output_size_0
* N0,
output_size_1
* N1)
withN0 = prod(batch_shape_0)
andN1 = 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 flatteningndarray
s with shapesoutput_shape_0
+ batch_shape_0
andoutput_shape_0
+ batch_shape_1
in “C-order”.- 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
.