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 中使用這些核函數。