| Name | geometric_kernels JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | A Python Package offering geometric kernels in NumPy, TensorFlow, PyTorch, and Jax. |
| upload_time | 2024-08-08 18:32:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
geometric-kernels
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# GeometricKernels
[](https://github.com/geometric-kernels/GeometricKernels/actions/workflows/quality-checks.yaml)
[](https://geometric-kernels.github.io/GeometricKernels/index.html)
[](https://geometric-kernels.github.io/)
[](https://geometric-kernels.github.io/)
GeometricKernels 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] create and activate a new virtual environment.
You can use Conda
```bash
conda create -n [env_name] python=3.[version]
conda activate [env_name]
```
or virtualenv
```bash
virtualenv [env_name]
source [env_name]/bin/activate
```
1. Install the library in the active environment by running
```bash
pip install geometric_kernels
```
If you want to install specific GitHub branch called `[branch]`, run
```bash
pip install "git+https://github.com/geometric-kernels/GeometricKernels@[branch]"
```
2. Install a backend of your choice
We use [LAB](https://github.com/wesselb/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 GeometricKernels package. Simply install the backend (and (optionally) a GP package) of your choice. For example,
- [Tensorflow](https://www.tensorflow.org/)
```
pip install tensorflow tensorflow-probability
```
Optionally, you can install the Tensorflow-based Gaussian processes library [GPflow](https://github.com/GPflow/GPflow), for which we provide a frontend.
```
pip install gpflow
```
- [PyTorch](https://pytorch.org/)
```
pip install torch
```
Optionally, you can install the PyTorch-based Gaussian processes library [GPyTorch](https://gpytorch.ai/), for which we provide a frontend.
```
pip install gpytorch
```
- [JAX](https://jax.readthedocs.io/) (the cpu version)—the gpu and tpu versions can be installed [similarly](https://jax.readthedocs.io/en/latest/installation.html).
```
pip install "jax[cpu]"
```
Optionally, you can install the JAX-based Gaussian processes library [GPJax](https://github.com/JaxGaussianProcesses/GPJax), for which we provide a frontend.
```
pip install gpjax
```
**Note**. 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
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](https://geometric-kernels.github.io/GeometricKernels/index.html).
```python
# 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))
```
This should output
```
[[1. 0.36 0.36]
[0.36 1. 0.36]
[0.36 0.36 1. ]]
```
## Documentation
The documentation for GeometricKernels is available on a [separate website](https://geometric-kernels.github.io/GeometricKernels/index.html).
## 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.)
```bash
make install
```
Run style checks
```bash
make lint
```
Run the tests
```bash
make test
```
## If you have a question
Post it in issues using the `"How do I do ..." and other issues` template and the "question" label.
This [link](https://github.com/geometric-kernels/GeometricKernels/issues/new?assignees=&labels=question&projects=&template=other-issue.md) chooses the right template and label for you.
## Citation
If you are using GeometricKernels, please cite the following [paper](https://arxiv.org/pdf/2407.08086):
```
@article{mostowsky2024,
title = {The GeometricKernels Package: Heat and Matérn Kernels for Geometric Learning on Manifolds, Meshes, and Graphs},
author = {Peter Mostowsky and Vincent Dutordoir and Iskander Azangulov and Noémie Jaquier and Michael John Hutchinson and Aditya Ravuri and Leonel Rozo and Alexander Terenin and Viacheslav Borovitskiy},
year = {2024},
journal = {arXiv:2407.08086},
}
```
Furthermore, please consider citing the theoretical papers the package 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "geometric_kernels",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "geometric-kernels",
"author": null,
"author_email": "The GeometricKernels Contributors <geometric-kernels@googlegroups.com>",
"download_url": "https://files.pythonhosted.org/packages/8a/a6/ac96b34cae5d9ec3be10640067f3a0a85a3270517cd3673a15e6d2453985/geometric_kernels-0.2.1.tar.gz",
"platform": null,
"description": "# GeometricKernels\n\n[](https://github.com/geometric-kernels/GeometricKernels/actions/workflows/quality-checks.yaml)\n[](https://geometric-kernels.github.io/GeometricKernels/index.html)\n[](https://geometric-kernels.github.io/)\n\n[](https://geometric-kernels.github.io/)\n\nGeometricKernels is a library that implements kernels including the heat and Mat\u00e9rn class on non-Euclidean spaces as **Riemannian manifolds**, **graphs** and **meshes**.\nThis enables kernel methods — in particular Gaussian process models — to be deployed on such spaces.\n\n## Installation\n\n0. [Optionally] create and activate a new virtual environment.\n\n You can use Conda\n\n ```bash\n conda create -n [env_name] python=3.[version]\n conda activate [env_name]\n ```\n\n or virtualenv\n\n ```bash\n virtualenv [env_name]\n source [env_name]/bin/activate\n ```\n\n1. Install the library in the active environment by running\n\n ```bash\n pip install geometric_kernels\n ```\n\n If you want to install specific GitHub branch called `[branch]`, run\n\n ```bash\n pip install \"git+https://github.com/geometric-kernels/GeometricKernels@[branch]\"\n ```\n\n2. Install a backend of your choice\n\n We use [LAB](https://github.com/wesselb/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 GeometricKernels package. Simply install the backend (and (optionally) a GP package) of your choice. For example,\n\n - [Tensorflow](https://www.tensorflow.org/)\n\n ```\n pip install tensorflow tensorflow-probability\n ```\n\n Optionally, you can install the Tensorflow-based Gaussian processes library [GPflow](https://github.com/GPflow/GPflow), for which we provide a frontend.\n\n ```\n pip install gpflow\n ```\n\n - [PyTorch](https://pytorch.org/)\n\n ```\n pip install torch\n ```\n\n Optionally, you can install the PyTorch-based Gaussian processes library [GPyTorch](https://gpytorch.ai/), for which we provide a frontend.\n\n ```\n pip install gpytorch\n ```\n\n - [JAX](https://jax.readthedocs.io/) (the cpu version)\u2014the gpu and tpu versions can be installed [similarly](https://jax.readthedocs.io/en/latest/installation.html).\n\n ```\n pip install \"jax[cpu]\"\n ```\n\n Optionally, you can install the JAX-based Gaussian processes library [GPJax](https://github.com/JaxGaussianProcesses/GPJax), for which we provide a frontend.\n\n ```\n pip install gpjax\n ```\n\n **Note**. Currently, only some versions of `gpjax` are supported (we tested `gpjax==0.6.9`).\n\n 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.\n\n## A basic example\n\nThis 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](https://geometric-kernels.github.io/GeometricKernels/index.html).\n\n```python\n# Import a backend.\nimport numpy as np\n# Import the geometric_kernels backend.\nimport geometric_kernels\n# Import a space and an appropriate kernel.\nfrom geometric_kernels.spaces import Hypersphere\nfrom geometric_kernels.kernels import MaternGeometricKernel\n\n# Create a manifold (2-dim sphere).\nhypersphere = Hypersphere(dim=2)\n\n# Define 3 points on the sphere.\nxs = np.array([[0., 0., 1.], [0., 1., 0.], [1., 0., 0.]])\n\n# Initialize kernel.\nkernel = MaternGeometricKernel(hypersphere)\nparams = kernel.init_params()\nparams[\"nu\"] = np.array([5/2])\nparams[\"lengthscale\"] = np.array([1.])\n\n# Compute and print out the 3x3 kernel matrix.\nprint(np.around(kernel.K(params, xs), 2))\n```\n\nThis should output\n\n```\n[[1. 0.36 0.36]\n [0.36 1. 0.36]\n [0.36 0.36 1. ]]\n```\n\n## Documentation\n\nThe documentation for GeometricKernels is available on a [separate website](https://geometric-kernels.github.io/GeometricKernels/index.html).\n\n## For development and running the tests\n\nRun these commands from the root directory of the repository.\n\nInstall all backends and the dev requirements (Pytest, black, etc.)\n\n```bash\nmake install\n```\n\nRun style checks\n```bash\nmake lint\n```\n\nRun the tests\n\n```bash\nmake test\n```\n\n## If you have a question\n\nPost it in issues using the `\"How do I do ...\" and other issues` template and the \"question\" label.\n\nThis [link](https://github.com/geometric-kernels/GeometricKernels/issues/new?assignees=&labels=question&projects=&template=other-issue.md) chooses the right template and label for you.\n\n## Citation\n\nIf you are using GeometricKernels, please cite the following [paper](https://arxiv.org/pdf/2407.08086):\n```\n@article{mostowsky2024,\n title = {The GeometricKernels Package: Heat and Mat\u00e9rn Kernels for Geometric Learning on Manifolds, Meshes, and Graphs},\n author = {Peter Mostowsky and Vincent Dutordoir and Iskander Azangulov and No\u00e9mie Jaquier and Michael John Hutchinson and Aditya Ravuri and Leonel Rozo and Alexander Terenin and Viacheslav Borovitskiy},\n year = {2024},\n journal = {arXiv:2407.08086},\n}\n```\n\nFurthermore, please consider citing the theoretical papers the package is based on.\nYou can find the relevant references for any space in\n- the docstring of the respective space class,\n- at the end of the respective tutorial notebook.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python Package offering geometric kernels in NumPy, TensorFlow, PyTorch, and Jax.",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://geometric-kernels.github.io/",
"Source": "https://github.com/geometric-kernels/GeometricKernels"
},
"split_keywords": [
"geometric-kernels"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f7761fc12e8251a86d52b686d76f83758d531b03d42192ced359e897fe9ab86c",
"md5": "6845e8c75e21d0babb09420f6659e784",
"sha256": "7b0bd739e19a466add2f119154ff4b3470cba3381c95ec10701f87366e1aefed"
},
"downloads": -1,
"filename": "geometric_kernels-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6845e8c75e21d0babb09420f6659e784",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 120102,
"upload_time": "2024-08-08T18:32:06",
"upload_time_iso_8601": "2024-08-08T18:32:06.777244Z",
"url": "https://files.pythonhosted.org/packages/f7/76/1fc12e8251a86d52b686d76f83758d531b03d42192ced359e897fe9ab86c/geometric_kernels-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8aa6ac96b34cae5d9ec3be10640067f3a0a85a3270517cd3673a15e6d2453985",
"md5": "2b828609fc6e315ee81202f61588ce1d",
"sha256": "632b07503b10de23d06ef0e0664a3b796220cd306d0f611e15350830081e4b6f"
},
"downloads": -1,
"filename": "geometric_kernels-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "2b828609fc6e315ee81202f61588ce1d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5580170,
"upload_time": "2024-08-08T18:32:09",
"upload_time_iso_8601": "2024-08-08T18:32:09.201962Z",
"url": "https://files.pythonhosted.org/packages/8a/a6/ac96b34cae5d9ec3be10640067f3a0a85a3270517cd3673a15e6d2453985/geometric_kernels-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-08 18:32:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "geometric-kernels",
"github_project": "GeometricKernels",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"test_requirements": [
{
"name": "ipykernel",
"specs": []
},
{
"name": "backends",
"specs": [
[
">=",
"1.5.4"
]
]
},
{
"name": "plotly",
"specs": []
},
{
"name": "kaleido",
"specs": []
},
{
"name": "black",
"specs": [
[
"==",
"24.3.0"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"7.0.0"
]
]
},
{
"name": "isort",
"specs": [
[
"==",
"5.13.2"
]
]
},
{
"name": "autoflake",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "nbmake",
"specs": []
},
{
"name": "mypy",
"specs": []
}
],
"lcname": "geometric_kernels"
}
