spd-learn 0.1.0__tar.gz

spd_learn-0.1.0/CHANGELOG.md

@@ -0,0 +1,146 @@
+# Changelog
+
+All notable changes to SPD Learn will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-05
+
+### 🎉 Initial Release
+
+We are excited to announce the first public release of **SPD Learn** — a pure PyTorch library for geometric deep learning on Symmetric Positive Definite (SPD) matrices.
+
+SPD Learn provides differentiable Riemannian operations, broadcast-compatible layers, and reference implementations of published neural network architectures for SPD data, with a focus on EEG/BCI applications.
+
+---
+
+### ✨ Features
+
+#### Neural Network Models
+
+Seven state-of-the-art deep learning architectures for SPD matrix data:
+
+| Model | Description | Reference |
+|-------|-------------|-----------|
+| **SPDNet** | Foundational architecture for deep learning on SPD manifolds with dimension reduction | Huang & Van Gool, AAAI 2017 |
+| **EEGSPDNet** | Specialized for EEG classification, combining covariance estimation with SPD layers | - |
+| **TSMNet** | Tangent Space Mapping Network with convolutional features and SPD batch normalization | Kobler et al., 2022 |
+| **TensorCSPNet** | Multi-band EEG feature extraction using Tensor Common Spatial Patterns | - |
+| **PhaseSPDNet** | Leverages instantaneous phase information from analytic signals | - |
+| **GREEN** | Gabor Riemann EEGNet combining Gabor wavelets with Riemannian geometry | Chambon et al. |
+| **MAtt** | Manifold Attention mechanism for SPD matrices | - |
+
+#### SPD Neural Network Layers
+
+A comprehensive set of differentiable layers that respect SPD geometry:
+
+- **BiMap** — Bilinear mapping layer for SPD dimension reduction
+- **ReEig** — Eigenvalue rectification to ensure positive definiteness
+- **LogEig** — Logarithmic map to tangent space (Euclidean)
+- **ExpEig** — Exponential map from tangent space back to SPD manifold
+- **SqrtEig** — Matrix square root via eigendecomposition
+- **InvSqrtEig** — Inverse matrix square root
+- **PowerEig** — Matrix power function
+- **VecMat** — Vectorization/matricization operations
+- **CovLayer** — Differentiable covariance matrix estimation
+- **Shrinkage** — Regularized covariance estimation (Ledoit-Wolf, Oracle)
+
+#### Batch Normalization
+
+SPD-specific batch normalization layers respecting Riemannian geometry:
+
+- **SPDBatchNorm** — Standard SPD batch normalization
+- **TSMBatchNorm** — Batch normalization for Tangent Space Mapping
+- **AdaMomSPDBatchNorm** — Adaptive momentum batch normalization
+- **DomainSPDBatchNorm** — Domain-specific batch normalization for transfer learning
+- **TrackingMeanBatchNorm** — Batch normalization with running mean tracking
+
+#### Riemannian Metrics
+
+Four Riemannian metrics for SPD manifolds:
+
+| Metric | Description |
+|--------|-------------|
+| **AffineInvariantRiemannian** | The canonical metric on SPD manifolds (AIRM) |
+| **LogEuclidean** | Computationally efficient metric via matrix logarithm |
+| **LogCholesky** | Metric based on Cholesky decomposition |
+| **BuresWasserstein** | Optimal transport metric between Gaussians |
+
+Each metric provides:
+- Geodesic distance computation
+- Exponential and logarithmic maps
+- Parallel transport along geodesics
+- Fréchet/Karcher mean computation
+
+#### Functional Operations
+
+Low-level differentiable operations in `spd_learn.functional`:
+
+- **Matrix Operations**: `logm`, `expm`, `sqrtm`, `invsqrtm`, `powm`
+- **Geodesics**: `geodesic`, `log_map`, `exp_map`
+- **Statistics**: `frechet_mean`, `log_euclidean_mean`
+- **Parallel Transport**: `parallel_transport`
+- **Covariance**: `covariance`, `scm`, `shrinkage_covariance`
+
+#### Additional Features
+
+- **GPU Acceleration** — Full CUDA support with efficient batched operations
+- **Automatic Differentiation** — Seamless gradient computation on manifolds via PyTorch
+- **scikit-learn Compatible** — Integration with ML pipelines via skorch/Braindecode wrappers
+- **Comprehensive Documentation** — Tutorials, API reference, and theoretical background
+- **Examples Gallery** — Ready-to-run examples for common use cases
+
+---
+
+### 📚 Documentation
+
+- **Installation Guide** — Step-by-step setup instructions
+- **User Guide** — Comprehensive introduction to SPD matrices and Riemannian geometry
+- **Theory Section** — Mathematical background, layer descriptions, and metric details
+- **API Reference** — Complete documentation of all modules and functions
+- **Examples Gallery** — Practical examples including EEG classification
+
+---
+
+### 🔧 Technical Details
+
+- **Python**: 3.11, 3.12, 3.13
+- **PyTorch**: 2.0+
+- **License**: BSD-3-Clause
+
+---
+
+### 🙏 Acknowledgments
+
+SPD Learn is developed and maintained by researchers from:
+
+- Inria (French National Institute for Research in Digital Science and Technology)
+- CNRS (French National Centre for Scientific Research)
+- CEA (French Alternative Energies and Atomic Energy Commission)
+- Université Paris-Saclay
+- ATR (Advanced Telecommunications Research Institute International)
+- Université Savoie Mont Blanc
+
+---
+
+### 📖 Citation
+
+If you use SPD Learn in your research, please cite:
+
+```bibtex
+@article{aristimunha2025spdlearn,
+  title     = {SPDlearn: A Geometric Deep Learning Python Library for Neural
+               Decoding Through Trivialization},
+  author    = {Aristimunha, Bruno and Ju, Ce and Collas, Antoine and
+               Bouchard, Florent and Thirion, Bertrand and
+               Chevallier, Sylvain and Kobler, Reinmar},
+  journal   = {To be submitted},
+  year      = {2026},
+  url       = {https://github.com/spdlearn/spd_learn}
+}
+```
+
+---
+
+**Full Changelog**: https://github.com/spdlearn/spd_learn/commits/v0.1.0

spd_learn-0.1.0/LICENSE.txt

@@ -0,0 +1,33 @@
+BSD 3-Clause License, unless the header of the code section
+explicitly states otherwise.
+
+Copyright (c) 2024-now SPD Learn Developers.
+
+All rights reserved
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A P
+ARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
+WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

spd_learn-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include LICENSE.txt
+include README.md
+include CHANGELOG.md
+include pyproject.toml
+
+recursive-include spd_learn *.py

spd_learn-0.1.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: spd_learn
+Version: 0.1.0
+Summary: Deep Riemannian Learning for Symmetric Positive Definite matrices
+Author-email: Bruno Aristimunha <b.aristimunha@gmail.com>
+Maintainer-email: Bruno Aristimunha <b.aristimunha@gmail.com>
+Keywords: python,deep-learning,pytorch,spdnet,torch
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development
+Classifier: Topic :: Scientific/Engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: torch
+Requires-Dist: einops
+Requires-Dist: numpy
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: pytest-codeblocks; extra == "tests"
+Requires-Dist: sybil; extra == "tests"
+Requires-Dist: codecov; extra == "tests"
+Requires-Dist: pytest_cases; extra == "tests"
+Requires-Dist: mypy; extra == "tests"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
+Requires-Dist: sphinx_gallery; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-sitemap; extra == "docs"
+Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: memory_profiler; extra == "docs"
+Requires-Dist: ipython; extra == "docs"
+Requires-Dist: sphinx_design; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: hydra-core; extra == "docs"
+Requires-Dist: omegaconf; extra == "docs"
+Requires-Dist: nbformat; extra == "docs"
+Provides-Extra: brain
+Requires-Dist: moabb; extra == "brain"
+Requires-Dist: braindecode; extra == "brain"
+Requires-Dist: moabb; extra == "brain"
+Requires-Dist: nilearn; extra == "brain"
+Requires-Dist: pyriemann; extra == "brain"
+Requires-Dist: skada; extra == "brain"
+Provides-Extra: dev
+Requires-Dist: spd_learn[tests]; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: rich; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Provides-Extra: all
+Requires-Dist: spd_learn[tests]; extra == "all"
+Requires-Dist: spd_learn[docs]; extra == "all"
+Requires-Dist: spd_learn[brain]; extra == "all"
+Requires-Dist: spd_learn[dev]; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/source/_static/spd_learn.png" alt="SPD Learn Logo" width="400">
+</p>
+
+<h3 align="center">Deep Learning on Symmetric Positive Definite Matrices</h3>
+
+<p align="center">
+  <strong>SPD Learn</strong> is a pure PyTorch library for geometric deep learning on Symmetric Positive Definite (SPD) matrices.<br>
+  The library provides differentiable Riemannian operations, broadcast-compatible layers, and reference implementations of published neural network architectures for SPD data.
+</p>
+
+<p align="center">
+  <a href="https://spdlearn.org/">Docs</a> •
+  <a href="https://spdlearn.org/installation.html">Install</a> •
+  <a href="https://spdlearn.org/generated/auto_examples/index.html">Examples</a> •
+  <a href="https://spdlearn.org/api.html">API</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/spdlearn/spd_learn"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue?style=flat-square" alt="Python"></a>
+  <a href="https://github.com/spdlearn/spd_learn/blob/main/LICENSE.txt"><img src="https://img.shields.io/badge/license-BSD--3--Clause-green?style=flat-square" alt="License"></a>
+  <a href="https://github.com/spdlearn/spd_learn"><img src="https://img.shields.io/badge/PyTorch-2.0%2B-red?style=flat-square&logo=pytorch" alt="PyTorch"></a>
+  <a href="https://github.com/spdlearn/spd_learn"><img src="https://img.shields.io/github/stars/spdlearn/spd_learn?style=social" alt="GitHub Stars"></a>
+</p>
+
+---
+
+## 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](https://spdlearn.org/generated/spd_learn.models.SPDNet.html)** | The foundational architecture for deep learning on SPD manifolds. Performs dimension reduction while preserving the SPD structure. | `BiMap` `ReEig` `LogEig` |
+| **[EEGSPDNet](https://spdlearn.org/generated/spd_learn.models.EEGSPDNet.html)** | Specialized for EEG signal classification. Combines covariance estimation with SPD network layers for BCI applications. | `Covariance` `BiMap` `ReEig` |
+| **[TSMNet](https://spdlearn.org/generated/spd_learn.models.TSMNet.html)** | Tangent Space Mapping Network combining convolutional features with SPD batch normalization. | `BatchNorm` `LogEig` `Transfer` |
+| **[TensorCSPNet](https://spdlearn.org/generated/spd_learn.models.TensorCSPNet.html)** | SPDNet variant with Tensor Common Spatial Patterns for multi-band EEG feature extraction. | `Multi-band` `CSP` `BiMap` |
+| **[PhaseSPDNet](https://spdlearn.org/generated/spd_learn.models.PhaseSPDNet.html)** | Phase-based SPDNet that leverages instantaneous phase information from analytic signals. | `Phase` `Hilbert` `BiMap` |
+| **[GREEN](https://spdlearn.org/generated/spd_learn.models.Green.html)** | 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
+
+```bash
+pip install spd_learn
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/spdlearn/spd_learn
+cd spd_learn && pip install -e .
+```
+
+Works with Python 3.11+ and PyTorch 2.0+.
+
+### 2. Import & Create
+
+```python
+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
+
+```python
+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](https://pytorch.org/)** — Built entirely on PyTorch 2.0+
+- **[scikit-learn](https://scikit-learn.org/)** — ML pipelines and cross-validation (via skorch/Braindecode wrappers)
+- **[Braindecode](https://braindecode.org/)** — Deep learning for EEG
+- **[MOABB](https://moabb.neurotechx.com/)** — EEG benchmark datasets
+- **[pyRiemann](https://pyriemann.readthedocs.io/)** — Riemannian geometry for BCI
+
+---
+
+## Citation
+
+If you use SPD Learn in your research, please cite:
+
+```bibtex
+@article{aristimunha2025spdlearn,
+  title     = {SPDlearn: A Geometric Deep Learning Python Library for Neural
+               Decoding Through Trivialization},
+  author    = {Aristimunha, Bruno and Ju, Ce and Collas, Antoine and
+               Bouchard, Florent and Thirion, Bertrand and
+               Chevallier, Sylvain and Kobler, Reinmar},
+  journal   = {To be submitted},
+  year      = {2026},
+  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](https://github.com/spdlearn/spd_learn)
+- [Report Issues](https://github.com/spdlearn/spd_learn/issues)
+- [Contributing Guide](CONTRIBUTING.md)
+
+### Supported by
+
+<p align="center">
+  <a href="https://www.inria.fr/"><img src="docs/source/_static/support/inria_red.png" alt="Inria" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.cnrs.fr/"><img src="docs/source/_static/support/cnrs_dark.png" alt="CNRS" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.cea.fr/"><img src="docs/source/_static/support/cea_dark.png" alt="CEA" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.universite-paris-saclay.fr/"><img src="docs/source/_static/support/paris_saclay_dark.jpg" alt="Université Paris-Saclay" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.atr.jp/"><img src="docs/source/_static/support/atr_logo_white.png" alt="ATR" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.univ-smb.fr"><img src="docs/source/_static/support/usmb_dark.png" alt="USMB" height="60"></a>
+</p>
+
+---
+
+## License
+
+This project is licensed under the BSD 3-Clause License, unless the header of the code section explicitly states otherwise. See [LICENSE.txt](LICENSE.txt) for details.

spd_learn-0.1.0/README.md

@@ -0,0 +1,172 @@
+<p align="center">
+  <img src="docs/source/_static/spd_learn.png" alt="SPD Learn Logo" width="400">
+</p>
+
+<h3 align="center">Deep Learning on Symmetric Positive Definite Matrices</h3>
+
+<p align="center">
+  <strong>SPD Learn</strong> is a pure PyTorch library for geometric deep learning on Symmetric Positive Definite (SPD) matrices.<br>
+  The library provides differentiable Riemannian operations, broadcast-compatible layers, and reference implementations of published neural network architectures for SPD data.
+</p>
+
+<p align="center">
+  <a href="https://spdlearn.org/">Docs</a> •
+  <a href="https://spdlearn.org/installation.html">Install</a> •
+  <a href="https://spdlearn.org/generated/auto_examples/index.html">Examples</a> •
+  <a href="https://spdlearn.org/api.html">API</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/spdlearn/spd_learn"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue?style=flat-square" alt="Python"></a>
+  <a href="https://github.com/spdlearn/spd_learn/blob/main/LICENSE.txt"><img src="https://img.shields.io/badge/license-BSD--3--Clause-green?style=flat-square" alt="License"></a>
+  <a href="https://github.com/spdlearn/spd_learn"><img src="https://img.shields.io/badge/PyTorch-2.0%2B-red?style=flat-square&logo=pytorch" alt="PyTorch"></a>
+  <a href="https://github.com/spdlearn/spd_learn"><img src="https://img.shields.io/github/stars/spdlearn/spd_learn?style=social" alt="GitHub Stars"></a>
+</p>
+
+---
+
+## 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](https://spdlearn.org/generated/spd_learn.models.SPDNet.html)** | The foundational architecture for deep learning on SPD manifolds. Performs dimension reduction while preserving the SPD structure. | `BiMap` `ReEig` `LogEig` |
+| **[EEGSPDNet](https://spdlearn.org/generated/spd_learn.models.EEGSPDNet.html)** | Specialized for EEG signal classification. Combines covariance estimation with SPD network layers for BCI applications. | `Covariance` `BiMap` `ReEig` |
+| **[TSMNet](https://spdlearn.org/generated/spd_learn.models.TSMNet.html)** | Tangent Space Mapping Network combining convolutional features with SPD batch normalization. | `BatchNorm` `LogEig` `Transfer` |
+| **[TensorCSPNet](https://spdlearn.org/generated/spd_learn.models.TensorCSPNet.html)** | SPDNet variant with Tensor Common Spatial Patterns for multi-band EEG feature extraction. | `Multi-band` `CSP` `BiMap` |
+| **[PhaseSPDNet](https://spdlearn.org/generated/spd_learn.models.PhaseSPDNet.html)** | Phase-based SPDNet that leverages instantaneous phase information from analytic signals. | `Phase` `Hilbert` `BiMap` |
+| **[GREEN](https://spdlearn.org/generated/spd_learn.models.Green.html)** | 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
+
+```bash
+pip install spd_learn
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/spdlearn/spd_learn
+cd spd_learn && pip install -e .
+```
+
+Works with Python 3.11+ and PyTorch 2.0+.
+
+### 2. Import & Create
+
+```python
+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
+
+```python
+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](https://pytorch.org/)** — Built entirely on PyTorch 2.0+
+- **[scikit-learn](https://scikit-learn.org/)** — ML pipelines and cross-validation (via skorch/Braindecode wrappers)
+- **[Braindecode](https://braindecode.org/)** — Deep learning for EEG
+- **[MOABB](https://moabb.neurotechx.com/)** — EEG benchmark datasets
+- **[pyRiemann](https://pyriemann.readthedocs.io/)** — Riemannian geometry for BCI
+
+---
+
+## Citation
+
+If you use SPD Learn in your research, please cite:
+
+```bibtex
+@article{aristimunha2025spdlearn,
+  title     = {SPDlearn: A Geometric Deep Learning Python Library for Neural
+               Decoding Through Trivialization},
+  author    = {Aristimunha, Bruno and Ju, Ce and Collas, Antoine and
+               Bouchard, Florent and Thirion, Bertrand and
+               Chevallier, Sylvain and Kobler, Reinmar},
+  journal   = {To be submitted},
+  year      = {2026},
+  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](https://github.com/spdlearn/spd_learn)
+- [Report Issues](https://github.com/spdlearn/spd_learn/issues)
+- [Contributing Guide](CONTRIBUTING.md)
+
+### Supported by
+
+<p align="center">
+  <a href="https://www.inria.fr/"><img src="docs/source/_static/support/inria_red.png" alt="Inria" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.cnrs.fr/"><img src="docs/source/_static/support/cnrs_dark.png" alt="CNRS" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.cea.fr/"><img src="docs/source/_static/support/cea_dark.png" alt="CEA" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.universite-paris-saclay.fr/"><img src="docs/source/_static/support/paris_saclay_dark.jpg" alt="Université Paris-Saclay" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.atr.jp/"><img src="docs/source/_static/support/atr_logo_white.png" alt="ATR" height="60"></a>
+  &nbsp;&nbsp;&nbsp;
+  <a href="https://www.univ-smb.fr"><img src="docs/source/_static/support/usmb_dark.png" alt="USMB" height="60"></a>
+</p>
+
+---
+
+## License
+
+This project is licensed under the BSD 3-Clause License, unless the header of the code section explicitly states otherwise. See [LICENSE.txt](LICENSE.txt) for details.