geometric-kernels/GeometricKernels

GeometricKernels – 非欧几里得空间上的核函数

它是什么 – 一个 Python 库，为生活在几何域（如黎曼流形、图和三角网格）上的数据实现经典核函数（热核、Matérn 核等）。通过提供这些核函数，该套件让您可以将高斯过程 (GP) 模型插入到普通欧几里得核不适用的空间中。

为什么重要 – 许多现代机器学习任务涉及结构化域（例如道路图上的传感器网络、网格上的形状分析或球体上的数据）。标准 GP 工具包假设平坦的欧几里得输入，因此无法捕捉内在几何结构。GeometricKernels 提供了数学上正确的协方差函数，实现了在这些域上的不确定性感知学习。

快速入门（安装与小示例）

# optional: create a virtual environment (uv, conda, or virtualenv)
pip install geometric_kernels          # core package
# pick one backend – only the one you need
pip install torch                     # PyTorch backend (or tensorflow, jax, etc.)

import numpy as np
import geometric_kernels as gk
from geometric_kernels.spaces import Hypersphere
from geometric_kernels.kernels import MaternGeometricKernel

# 2‑sphere (dim=2)
S2 = Hypersphere(dim=2)

# three points on the sphere (Cartesian coordinates)
X = np.array([[0., 0., 1.],
              [0., 1., 0.],
              [1., 0., 0.]])

k = MaternGeometricKernel(S2)          # Matérn‑5/2 kernel on the sphere
params = k.init_params()
params["nu"] = np.array([5/2])
params["lengthscale"] = np.array([1.])

print(np.around(k.K(params, X), 2))
# → [[1.   0.36 0.36]
#    [0.36 1.   0.36]
#    [0.36 0.36 1.  ]]

此代码片段展示了如何使用 NumPy 后端为球体上的点建立 3×3 协方差矩阵。

它如何融入机器学习生态系统

层级	GeometricKernels 提供的功能
域	抽象的空间类（例如 `Hypersphere`、`Graph`、`Mesh`）。它们了解底层几何结构上的距离、测地线和体积元素。
核函数	热核、Matérn 核 (ν = 1/2, 3/2, 5/2, …)，尊重空间的几何结构。
后端	轻量级封装 (`lab`)，可在 NumPy、TensorFlow、PyTorch 或 JAX 上运行。选择符合您下游代码的后端。
GP 前端	针对热门 GP 库的小型适配器 – GPflow (TensorFlow)、GPyTorch (PyTorch)、GPJax (JAX)。它们将核函数公开为这些库自身协方差函数的直接替代品。
应用	具备不确定性的图结构回归、流形上的贝叶斯优化、形状建模、地球球体上的地球物理数据等。

文档与学习资源

网站 – https://geometric‑kernels.github.io/GeometricKernels – 完整的 API 参考、教程和可搜索的索引。
示例笔记本 – 托管在仓库的 notebooks/ 文件夹中，并从文档中链接。它们涵盖了每个支持的空间、后端和 GP 前端，以及自定义空间教程。
基准测试 – PeMS Regression 基准测试展示了具备不确定性的图节点回归，并显示基于 GeometricKernels 的 GP 优于 GNN 集成模型。
贝叶斯优化演示 – 一个使用 botorch 的最小笔记本，用于说明流形上的 BO。

开发流程（如果您想贡献）

克隆仓库并运行 make venv（或设置您自己的环境）。
make install 会拉取所有选用的后端和开发依赖项。
运行 make lint 和 make test 来检查风格和单元测试。
遵循贡献指南 – README 中链接了一个 PR 示例。

引用

如果您在研究中使用此库，请引用 JMLR 论文：

@article{JMLR:v26:24-1185,
  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},
  title   = {The GeometricKernels Package: Heat and Matérn Kernels for Geometric Learning on Manifolds, Meshes, and Graphs},
  journal = {Journal of Machine Learning Research},
  year    = {2025},
  volume  = {26},
  number  = {276},
  pages   = {1--14},
  url     = {http://jmlr.org/papers/v26/24-1185.html}
}

其他参考文献列在每个空间的 docstring 和教程笔记本中。

总结

GeometricKernels 是一个维护良好、与后端无关的 Python 套件，它将数学上严谨的核函数带入流形、图和网格，使高斯过程模型（以及下游贝叶斯方法）能够在非欧几里得数据上运作。安装它，选择一个后端，您就可以立即在 GPflow、GPyTorch 或 GPJax 中使用这些核函数。