Overview

GeometricKernels is a library that implements natural kernels (heat [1], Matérn) on such non-Euclidean spaces as Riemannian manifolds, graphs and meshes.

The main projected application is Gaussian processes.

Installation and Requirements

This is a Python 3 library.

Before doing anything, you might want to create and activate a new virtual environment:

conda create -n [env_name] python=[version]
conda activate [env_name]

where [env_name] is the name of the environment and [version] is the version of Python you want to use, we currently support 3.8, 3.9, 3.10, 3.11.

virtualenv [env_name]
source [env_name]/bin/activate

To install GeometricKernels, run

pip install geometric_kernels

Note

If you want to install specific GitHub branch called [branch], run

pip install "git+https://github.com/geometric-kernels/GeometricKernels@[branch]"

The kernels are compatible with several backends, namely

Any backend, except for NumPy, should be manually installed.

You need both tensorflow and tensorflow-probability. You can get them by running

pip install tensorflow tensorflow-probability

[Optional] We support the TensorFlow-based Gaussian process library gpflow which you can install by running

pip install gpflow

You can get PyTorch by running

pip install torch

[Optional] We support the PyTorch-based Gaussian process library gpytorch which you can install by running

pip install gpytorch

To install JAX, follow these instructions.

[Optional] We support the JAX-based Gaussian process library GPJax which you can install by running

pip install gpjax

Warning

Currently, only some versions of gpjax are supported (we tested gpjax==0.6.9).

Furthermore, installation might be far from trivial and result in a broken environment. This is due to our conflicting dependencies, see https://github.com/JaxGaussianProcesses/GPJax/issues/441.


A Basic Example

In the following example we show how to initialize the Matern52 kernel on the two-dimensional sphere and how to compute a kernel matrix for a few points on the sphere.

>>> # Import a backend.
>>> import numpy as np
>>> # Import the geometric_kernels backend.
>>> import geometric_kernels
>>> # Import a space and an appropriate kernel.
>>> from geometric_kernels.spaces import Hypersphere
>>> from geometric_kernels.kernels import MaternGeometricKernel

>>> # Create a manifold (2-dim sphere).
>>> hypersphere = Hypersphere(dim=2)

>>> # Define 3 points on the sphere.
>>> xs = np.array([[0., 0., 1.], [0., 1., 0.], [1., 0., 0.]])

>>> # Initialize kernel.
>>> kernel = MaternGeometricKernel(hypersphere)
>>> params = kernel.init_params()
>>> params["nu"] = np.array([5/2])
>>> params["lengthscale"] = np.array([1.])

>>> # Compute and print out the 3x3 kernel matrix.
>>> print(np.around(kernel.K(params, xs), 2))
[[1.   0.36 0.36]
 [0.36 1.   0.36]
 [0.36 0.36 1.  ]]


>>> import numpy as np
>>> # Import a backend.
>>> import tensorflow as tf
>>> # Import the geometric_kernels backend.
>>> import geometric_kernels.tensorflow
>>> # Import a space and an appropriate kernel.
>>> from geometric_kernels.spaces import Hypersphere
>>> from geometric_kernels.kernels import MaternGeometricKernel

>>> # Create a manifold (2-dim sphere).
>>> hypersphere = Hypersphere(dim=2)

>>> # Define 3 points on the sphere.
>>> xs = tf.convert_to_tensor([[0., 0., 1.], [0., 1., 0.], [1., 0., 0.]])

>>> # Initialize kernel.
>>> kernel = MaternGeometricKernel(hypersphere)
>>> params = kernel.init_params()
>>> params["nu"] = tf.convert_to_tensor([5/2])
>>> params["lengthscale"] = tf.convert_to_tensor([1.])

>>> # Compute and print out the 3x3 kernel matrix.
>>> print(np.around(kernel.K(params, xs).numpy(), 2))
[[1.   0.36 0.36]
 [0.36 1.   0.36]
 [0.36 0.36 1.  ]]


>>> import numpy as np
>>> # Import a backend.
>>> import torch
>>> # Import the geometric_kernels backend.
>>> import geometric_kernels.torch
>>> # Import a space and an appropriate kernel.
>>> from geometric_kernels.spaces import Hypersphere
>>> from geometric_kernels.kernels import MaternGeometricKernel

>>> # Create a manifold (2-dim sphere).
>>> hypersphere = Hypersphere(dim=2)

>>> # Define 3 points on the sphere.
>>> xs = torch.tensor([[0., 0., 1.], [0., 1., 0.], [1., 0., 0.]])

>>> # Initialize kernel.
>>> kernel = MaternGeometricKernel(hypersphere)
>>> params = kernel.init_params()
>>> params["nu"] = torch.tensor([5/2])
>>> params["lengthscale"] = torch.tensor([1.])

>>> # Compute and print out the 3x3 kernel matrix.
>>> print(np.around(kernel.K(params, xs).detach().cpu().numpy(), 2))
[[1.   0.36 0.36]
 [0.36 1.   0.36]
 [0.36 0.36 1.  ]]


>>> import numpy as np
>>> # Import a backend.
>>> import jax.numpy as jnp
>>> # Import the geometric_kernels backend.
>>> import geometric_kernels.jax
>>> # Import a space and an appropriate kernel.
>>> from geometric_kernels.spaces import Hypersphere
>>> from geometric_kernels.kernels import MaternGeometricKernel

>>> # Create a manifold (2-dim sphere).
>>> hypersphere = Hypersphere(dim=2)

>>> # Define 3 points on the sphere.
>>> xs = jnp.array([[0., 0., 1.], [0., 1., 0.], [1., 0., 0.]])

>>> # Initialize kernel.
>>> kernel = MaternGeometricKernel(hypersphere)
>>> params = kernel.init_params()
>>> params["nu"] = jnp.array([5/2])
>>> params["lengthscale"] = jnp.array([1.0])

>>> # Compute and print out the 3x3 kernel matrix.
>>> print(np.around(np.asarray(kernel.K(params, xs)), 2))
[[1.   0.36 0.36]
 [0.36 1.   0.36]
 [0.36 0.36 1.  ]]

You can find more examples here.

Citation

If you are using GeometricKernels, please consider citing the theoretical papers it is based on.

You can find the relevant references for any space in

  • the docstring of the respective space class,

  • at the end of the respective tutorial notebook.

Footnotes