hchen19 / GeometricKernels

Geometric kernels on manifolds, meshes and graphs

Geometric Kernels

Geometric Kernels is a library that implements kernels including the heat and Matérn class on non-Euclidean spaces as Riemannian manifolds, graphs and meshes. This enables kernel methods — in particular Gaussian process models — to be deployed on such spaces.

Installation

0. [Optionally] install and run virtualenv

[sudo] pip install virtualenv
virtualenv [env_name]
source [env_name]/bin/activate

1. [Prerequisite] install LAB following these instructions.

2. Install the library in the active environment by running

pip install git+https://github.com/gpflow/geometrickernels.git

4. Install a backend of your choice

We use LAB to support multiple backends (e.g., TensorFlow, Jax, PyTorch). However, you are not required to install all of them on your system to use the Geometric Kernel package. Simply install the backend (and (optionally) a GP package) of your choice. For example,

• TensorFlow and GPflow

pip install tensorflow tensorflow-probability gpflow

• PyTorch and GPyTorch

pip install torch gpytorch

• JAX (the cpu version) and GPJax

pip install "jax[cpu]" gpjax

Supported backends with associated GP packages

Ready	Backend	GP package
✅	Tensorflow	GPflow
✅	PyTorch	GPyTorch
✅	JAX	GPJax
✅	Numpy	-

A basic example

This example shows how to compute a 3x3 kernel matrix for the Matern52 kernel on the standard two-dimensional sphere. It relies on the numpy-based backend. Look up the information on how to use other backends in the documentation.

# 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.hypersphere import Hypersphere
from geometric_kernels.kernels.geometric_kernels import MaternKarhunenLoeveKernel

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

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

# Initialize kernel, use 10 levels to approximate the infinite series.
kernel = MaternKarhunenLoeveKernel(hypersphere, 10)
params, state = kernel.init_params_and_state()
params["nu"] = np.array([5/2])
params["lengthscale"] = np.array([1.])

# Compute and print out the 3x3 kernel matrix.
print(kernel.K(params, state, xs))

This should output

[[0.00855354 0.00305004 0.00305004]
 [0.00305004 0.00855354 0.00305004]
 [0.00305004 0.00305004 0.00855354]]

Documentation

The documentation for GeometricKernels is available on a separate website.

For development and running the tests

Run these commands from the root directory of the repository.

Install all backends and the dev requirements (Pytest, black, etc.)

pip install -r dev_requirements.txt -r requirements.txt

Run the tests

make test

The structure of the library