geometric_kernels.frontends.gpytorch
====================================

.. py:module:: geometric_kernels.frontends.gpytorch

.. autoapi-nested-parse::

   GPyTorch kernel wrapper.

   A tutorial on how to use this wrapper to run Gaussian process regression on
   a geometric space is available in the
   :doc:`frontends/GPyTorch.ipynb </examples/frontends/GPyTorch>` notebook.





Module Contents
---------------

.. py:class:: GPyTorchGeometricKernel(base_kernel, lengthscale = None, nu = None, trainable_nu = False, **kwargs)

   Bases: :py:obj:`gpytorch.kernels.Kernel`


   GPyTorch wrapper for :class:`~.kernels.BaseGeometricKernel`.

   A tutorial on how to use this wrapper to run Gaussian process regression on
   a geometric space is available in the
   :doc:`frontends/GPyTorch.ipynb </examples/frontends/GPyTorch>` notebook.

   .. note::
       Remember that the `base_kernel` itself does not store any of its
       hyperparameters (like `lengthscale` and `nu`). If you do not set them
       manually—when initializing the object or after, by setting the
       properties—this wrapper will use the values provided by
       `base_kernel.init_params`.

   .. note::
       As customary in GPyTorch, this wrapper does not maintain a
       variance (outputscale) parameter. To add it, use
       :code:`gpytorch.kernels.ScaleKernel(GPyTorchGeometricKernel(...))`.

   :param base_kernel:
       The kernel to wrap.
   :param lengthscale:
       Initial value of the length scale.

       If not given or set to None, uses the default value of the
       `base_kernel`, as provided by its `init_params` method.
   :param nu:
       Initial value of the smoothness parameter nu.

       If not given or set to None, uses the default value of the
       `base_kernel`, as provided by its `init_params` method.
   :param trainable_nu:
       Whether or not the parameter nu is to be optimized over.

       Cannot be True if nu is equal to infinity. You cannot change
       this parameter after constructing the object. Defaults to False.

   :raises ValueError:
       If trying to set nu = infinity together with trainable_nu = True.

   .. todo::
       Handle `ard_num_dims` properly when base_kernel is a product kernel.


   .. py:method:: __call__(x1, x2 = None, diag = False, last_dim_is_batch = False, **params)

      Computes the covariance between :math:`\mathbf x_1` and :math:`\mathbf x_2`.

      .. note::
          Following PyTorch convention, all :class:`~gpytorch.models.GP` objects should use `__call__`
          rather than :py:meth:`~gpytorch.kernels.Kernel.forward`.
          The `__call__` method applies additional pre- and post-processing to the `forward` method,
          and additionally employs a lazy evaluation scheme to reduce memory and computational costs.

      :param x1: First set of data (... x N x D).
      :param x2: Second set of data (... x M x D).
          (If `None`, then `x2` is set to `x1`.)
      :param diag: Should the Kernel compute the whole kernel, or just the diag?
          If True, it must be the case that `x1 == x2`. (Default: False.)
      :param last_dim_is_batch: If True, treat the last dimension
          of `x1` and `x2` as another batch dimension.
          (Useful for additive structure over the dimensions). (Default: False.)

      :return: An object that will lazily evaluate to the kernel matrix or vector.
          The shape depends on the kernel's evaluation mode:

          * `full_covar`: `... x N x M`
          * `full_covar` with `last_dim_is_batch=True`: `... x K x N x M`
          * `diag`: `... x N`
          * `diag` with `last_dim_is_batch=True`: `... x K x N`



   .. py:method:: __init__(base_kernel, lengthscale = None, nu = None, trainable_nu = False, **kwargs)

      Initializes internal Module state, shared by both nn.Module and ScriptModule.



   .. py:method:: forward(x1, x2, diag = False, last_dim_is_batch = False, **kwargs)

      Evaluate the covariance matrix K(x1, x2).

      :param x1:
          First batch of inputs.
      :param x2:
          Second batch of inputs.
      :param diag:
          If set to True, ignores `x2` and returns the diagonal of K(x1, x1).
      :param last_dim_is_batch:
          Ignored.

      :return:
          The covariance matrix K(x1, x2) or, if diag=True, the diagonal
          of the covariance matrix K(x1, x1).

      .. todo::
          Support GPyTorch-style output batching.



   .. py:property:: nu
      :type: torch.Tensor


      The smoothness parameter



   .. py:property:: space
      :type: beartype.typing.Union[geometric_kernels.spaces.Space, beartype.typing.List[geometric_kernels.spaces.Space]]


      Alias to the `base_kernel`\ s space property.