ProductMatern

class probnum.randprocs.covfuncs.ProductMatern(input_shape, lengthscales, nus)

Bases: CovarianceFunction

Tensor product of one-dimensional Matérn covariance functions.

Covariance function defined as a product of one-dimensional Matérn covariance functions: \(k(x_0, x_1) = \prod_{i=1}^d k_i(x_{0,i}, x_{1,i})\), where \(x_0 = (x_{0,i}, \ldots, x_{0,d})\) and \(x_0 = (x_{0,i}, \ldots, x_{0,d})\) and \(k_i\) are one-dimensional Matérn covariance functions.

Parameters:

• input_shape (int | Integral | integer | Iterable[int | Integral | integer]) – Shape of the covariance function’s input.

• lengthscales (ndarray | int | float | complex | Number | number) – Lengthscales of the one-dimensional Matérn covariance functions. Describes the input scale on which the process varies. If a scalar, the same lengthscale is used in each dimension.

• nus (ndarray | int | float | complex | Number | number) – Hyperparameters controlling differentiability of the one-dimensional Matérn covariance functions. If a scalar, the same smoothness is used in each dimension.

See also

Matern

Stationary Matérn covariance function.

ExpQuad

Exponentiated Quadratic covariance function.

Examples

>>> import numpy as np
>>> from probnum.randprocs.covfuncs import ProductMatern
>>> lengthscales = np.array([0.1, 1.2])
>>> nus = np.array([0.5, 3.5])
>>> K = ProductMatern(input_shape=(2,), lengthscales=lengthscales, nus=nus)
>>> xs = np.array([[0.0, 0.5], [1.0, 1.0], [0.5, 0.2]])
>>> K.matrix(xs)
array([[1.00000000e+00, 4.03712525e-05, 6.45332482e-03],
       [4.03712525e-05, 1.00000000e+00, 5.05119251e-03],
       [6.45332482e-03, 5.05119251e-03, 1.00000000e+00]])

Raises:

ValueError – If covariance function input is scalar, but lengthscales or nus are not.

Parameters:

• input_shape (int | Integral | integer | Iterable[int | Integral | integer]) –

• lengthscales (ndarray | int | float | complex | Number | number) –

• nus (ndarray | int | float | complex | Number | number) –

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

Methods Summary

__call__(x0, x1)	Evaluate the (cross-)covariance function.
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.

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.

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.

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.

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:

• 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 (potentially using a more efficient implementation for this particular case).

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:

• 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 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 (potentially using a more efficient implementation for this particular case).

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:

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