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 내에서 커널을 사용할 수 있습니다.