# Source code for gpytorch.kernels.matern_kernel

#!/usr/bin/env python3

import math

import torch

from ..functions import MaternCovariance
from ..settings import trace_mode
from .kernel import Kernel

[docs]class MaternKernel(Kernel):
r"""
Computes a covariance matrix based on the Matern kernel
between inputs :math:\mathbf{x_1} and :math:\mathbf{x_2}:

.. math::

\begin{equation*}
k_{\text{Matern}}(\mathbf{x_1}, \mathbf{x_2}) = \frac{2^{1 - \nu}}{\Gamma(\nu)}
\left( \sqrt{2 \nu} d \right) K_\nu \left( \sqrt{2 \nu} d \right)
\end{equation*}

where

* :math:d = (\mathbf{x_1} - \mathbf{x_2})^\top \Theta^{-1} (\mathbf{x_1} - \mathbf{x_2})
is the distance between
:math:x_1 and :math:x_2 scaled by the :attr:lengthscale parameter :math:\Theta.
* :math:\nu is a smoothness parameter (takes values 1/2, 3/2, or 5/2). Smaller values are less smooth.
* :math:K_\nu is a modified Bessel function.

There are a few options for the lengthscale parameter :math:\Theta:
See :class:gpytorch.kernels.Kernel for descriptions of the lengthscale options.

.. note::

This kernel does not have an outputscale parameter. To add a scaling parameter,
decorate this kernel with a :class:gpytorch.kernels.ScaleKernel.

Args:
:attr:nu (float):
The smoothness parameter: either 1/2, 3/2, or 5/2.
:attr:ard_num_dims (int, optional):
Set this if you want a separate lengthscale for each
input dimension. It should be d if :attr:x1 is a n x d matrix. Default: None
:attr:batch_shape (torch.Size, optional):
Set this if you want a separate lengthscale for each
batch of input data. It should be b if :attr:x1 is a b x n x d tensor. Default: torch.Size([])
:attr:active_dims (tuple of ints, optional):
Set this if you want to
compute the covariance of only a few input dimensions. The ints
corresponds to the indices of the dimensions. Default: None.
:attr:lengthscale_prior (Prior, optional):
Set this if you want to apply a prior to the lengthscale parameter.  Default: None
:attr:lengthscale_constraint (Constraint, optional):
Set this if you want to apply a constraint to the lengthscale parameter. Default: Positive.
:attr:eps (float):
The minimum value that the lengthscale can take (prevents divide by zero errors). Default: 1e-6.

Attributes:
:attr:lengthscale (Tensor):
The lengthscale parameter. Size/shape of parameter depends on the
:attr:ard_num_dims and :attr:batch_shape arguments.

Example:
>>> x = torch.randn(10, 5)
>>> # Non-batch: Simple option
>>> covar_module = gpytorch.kernels.ScaleKernel(gpytorch.kernels.MaternKernel(nu=0.5))
>>> # Non-batch: ARD (different lengthscale for each input dimension)
>>> covar_module = gpytorch.kernels.ScaleKernel(gpytorch.kernels.MaternKernel(nu=0.5, ard_num_dims=5))
>>> covar = covar_module(x)  # Output: LazyVariable of size (10 x 10)
>>>
>>> batch_x = torch.randn(2, 10, 5)
>>> # Batch: Simple option
>>> covar_module = gpytorch.kernels.ScaleKernel(gpytorch.kernels.MaternKernel(nu=0.5))
>>> # Batch: different lengthscale for each batch
>>> covar_module = gpytorch.kernels.MaternKernel(nu=0.5, batch_shape=torch.Size([2])
>>> covar = covar_module(x)  # Output: LazyVariable of size (2 x 10 x 10)
"""

has_lengthscale = True

def __init__(self, nu=2.5, **kwargs):
if nu not in {0.5, 1.5, 2.5}:
raise RuntimeError("nu expected to be 0.5, 1.5, or 2.5")
super(MaternKernel, self).__init__(**kwargs)
self.nu = nu

def forward(self, x1, x2, diag=False, **params):
if (
x1.requires_grad
or x2.requires_grad
or (self.ard_num_dims is not None and self.ard_num_dims > 1)
or diag
or params.get("last_dim_is_batch", False)
or trace_mode.on()
):
mean = x1.reshape(-1, x1.size(-1)).mean(0)[(None,) * (x1.dim() - 1)]

x1_ = (x1 - mean).div(self.lengthscale)
x2_ = (x2 - mean).div(self.lengthscale)
distance = self.covar_dist(x1_, x2_, diag=diag, **params)
exp_component = torch.exp(-math.sqrt(self.nu * 2) * distance)

if self.nu == 0.5:
constant_component = 1
elif self.nu == 1.5:
constant_component = (math.sqrt(3) * distance).add(1)
elif self.nu == 2.5:
constant_component = (math.sqrt(5) * distance).add(1).add(5.0 / 3.0 * distance ** 2)
return constant_component * exp_component
return MaternCovariance().apply(
x1, x2, self.lengthscale, self.nu, lambda x1, x2: self.covar_dist(x1, x2, **params)
)