spdlearn/spd_learn

Deep Learning on Symmetric Positive Definite Matrices

SPD Learn is a pure PyTorch library for geometric deep learning on Symmetric Positive Definite (SPD) matrices.
The library provides differentiable Riemannian operations, broadcast-compatible layers, and reference implementations of published neural network architectures for SPD data.

Docs • Install • Examples • API

---

Why SPD Learn?

A PyTorch library providing differentiable Riemannian operations and neural network layers for SPD matrix-valued data.

🐍 Pure PyTorch	🌐 Riemannian Geometry	📦 Model Zoo
Built entirely on PyTorch for seamless integration, automatic differentiation, and GPU acceleration out of the box.	Efficient exponential maps, logarithms, parallel transport, and geodesic distance computations on SPD manifolds.	Implementations of SPDNet, TensorCSPNet, EEGSPDNet, TSMNet, and more state-of-the-art architectures.

---

Model Architectures

State-of-the-art deep learning models for SPD matrix data.

Model	Description	Tags
SPDNet	The foundational architecture for deep learning on SPD manifolds. Performs dimension reduction while preserving the SPD structure.	BiMap ReEig LogEig
EEGSPDNet	Specialized for EEG signal classification. Combines covariance estimation with SPD network layers for BCI applications.	Covariance BiMap ReEig
TSMNet	Tangent Space Mapping Network combining convolutional features with SPD batch normalization.	BatchNorm LogEig Transfer
TensorCSPNet	SPDNet variant with Tensor Common Spatial Patterns for multi-band EEG feature extraction.	Multi-band CSP BiMap
PhaseSPDNet	Phase-based SPDNet that leverages instantaneous phase information from analytic signals.	Phase Hilbert BiMap
GREEN	Gabor Riemann EEGNet combining Gabor wavelets with Riemannian geometry for robust EEG decoding.	Gabor Wavelet Shrinkage

---

Key Features

Core components for constructing and training geometric neural networks on SPD manifolds.

• SPD Layers — Specialized neural network layers for SPD matrices: BiMap for bilinear mappings, ReEig for eigenvalue rectification, and LogEig for tangent space projection.
• Riemannian Operations — Complete toolkit for SPD manifold computations: exponential/logarithmic maps, geodesic distances, Log-Euclidean mean, and geodesic interpolation.
• GPU Accelerated — Full CUDA support with efficient batched operations. Leverage PyTorch's automatic differentiation for seamless gradient computation on manifolds.
• scikit-learn Compatible — Seamlessly integrate with scikit-learn pipelines, cross-validation, and hyperparameter tuning via skorch/Braindecode wrappers.
• Batch Normalization — SPD-specific batch normalization layers that respect the Riemannian geometry, enabling stable training of deep SPD networks.
• Open Source — BSD-3 licensed, actively maintained, and welcoming contributions. Comprehensive documentation and examples to get you started quickly.

---

Getting Started

Three simple steps to start using SPD Learn.

1. Install

pip install spd_learn

Or install from source:

git clone --depth 1 --branch main https://github.com/spdlearn/spd_learn.git
cd spd_learn
pip install -e .

This downloads the latest source snapshot. For development with full history, follow the contributing guide.

Works with Python 3.11+ and PyTorch 2.0+.

2. Import & Create

from spd_learn.models import SPDNet
from spd_learn.modules import BiMap, ReEig

# Create your model
model = SPDNet(n_chans=22, n_outputs=4, subspacedim=16)

3. Train & Evaluate

import torch

# Standard PyTorch training
optimizer = torch.optim.Adam(model.parameters(), lr=1e-4)

for epoch in range(100):
    output = model(X_train)
    loss = criterion(output, y_train)
    loss.backward()
    optimizer.step()

---

Ecosystem Integration

Works seamlessly with your favorite tools.

• PyTorch — Built entirely on PyTorch 2.0+
• scikit-learn — ML pipelines and cross-validation (via skorch/Braindecode wrappers)
• Braindecode — Deep learning for EEG
• MOABB — EEG benchmark datasets
• pyRiemann — Riemannian geometry for BCI

---

Citation

If you use SPD Learn in your research, please cite it as below (GitHub's "Cite this repository" button reads the same entry from CITATION.cff):

@misc{aristimunha2025spdlearn,
  title     = {{SPD Learn}: A Geometric Deep Learning Python Library for
               Neural Decoding Through Trivialization},
  author    = {Aristimunha, Bruno and Ju, Ce and Collas, Antoine and
               Bouchard, Florent and Mian, Ammar and Thirion, Bertrand and
               Chevallier, Sylvain and Kobler, Reinmar},
  year      = {2026},
  note      = {Software, version 0.2.1},
  url       = {https://github.com/spdlearn/spd_learn}
}

---

Open Source & Community Driven

SPD Learn is an open-source project contributed by researchers for researchers. Join our community and help advance deep learning on Riemannian manifolds.

• GitHub Repository
• Report Issues
• Contributing Guide

Supported by

                   

---

License

This project is licensed under the BSD 3-Clause License. See LICENSE.txt for details.