geometric-kernels/GeometricKernels

GeometricKernels – 非ユークリッド空間上のカーネル

概要 – リーマン多様体、グラフ、三角メッシュなどの幾何学的領域に存在するデータに対して、古典的なカーネル関数（熱核、Matérnカーネルなど）を実装するPythonライブラリです。これらのカーネルを提供することで、通常のユークリッドカーネルが適用できない空間にガウス過程 (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, …)。
バックエンド	NumPy、TensorFlow、PyTorch、JAX上で動作する薄いラッパー (`lab`)。ダウンストリームのコードに一致するものを選んでください。
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内でカーネルを使用できます。