Skip to content

Commit 4730c98

Browse files
bruAristimunhabruAristimunha
committed
Add CHANGELOG.md for v0.1.0 release
1 parent d60fa7b commit 4730c98

File tree

1 file changed

+146
-0
lines changed

1 file changed

+146
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Changelog
2+
3+
All notable changes to SPD Learn will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] - 2026-02-05
9+
10+
### 🎉 Initial Release
11+
12+
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.
13+
14+
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.
15+
16+
---
17+
18+
### ✨ Features
19+
20+
#### Neural Network Models
21+
22+
Seven state-of-the-art deep learning architectures for SPD matrix data:
23+
24+
| Model | Description | Reference |
25+
|-------|-------------|-----------|
26+
| **SPDNet** | Foundational architecture for deep learning on SPD manifolds with dimension reduction | Huang & Van Gool, AAAI 2017 |
27+
| **EEGSPDNet** | Specialized for EEG classification, combining covariance estimation with SPD layers | - |
28+
| **TSMNet** | Tangent Space Mapping Network with convolutional features and SPD batch normalization | Kobler et al., 2022 |
29+
| **TensorCSPNet** | Multi-band EEG feature extraction using Tensor Common Spatial Patterns | - |
30+
| **PhaseSPDNet** | Leverages instantaneous phase information from analytic signals | - |
31+
| **GREEN** | Gabor Riemann EEGNet combining Gabor wavelets with Riemannian geometry | Chambon et al. |
32+
| **MAtt** | Manifold Attention mechanism for SPD matrices | - |
33+
34+
#### SPD Neural Network Layers
35+
36+
A comprehensive set of differentiable layers that respect SPD geometry:
37+
38+
- **BiMap** — Bilinear mapping layer for SPD dimension reduction
39+
- **ReEig** — Eigenvalue rectification to ensure positive definiteness
40+
- **LogEig** — Logarithmic map to tangent space (Euclidean)
41+
- **ExpEig** — Exponential map from tangent space back to SPD manifold
42+
- **SqrtEig** — Matrix square root via eigendecomposition
43+
- **InvSqrtEig** — Inverse matrix square root
44+
- **PowerEig** — Matrix power function
45+
- **VecMat** — Vectorization/matricization operations
46+
- **CovLayer** — Differentiable covariance matrix estimation
47+
- **Shrinkage** — Regularized covariance estimation (Ledoit-Wolf, Oracle)
48+
49+
#### Batch Normalization
50+
51+
SPD-specific batch normalization layers respecting Riemannian geometry:
52+
53+
- **SPDBatchNorm** — Standard SPD batch normalization
54+
- **TSMBatchNorm** — Batch normalization for Tangent Space Mapping
55+
- **AdaMomSPDBatchNorm** — Adaptive momentum batch normalization
56+
- **DomainSPDBatchNorm** — Domain-specific batch normalization for transfer learning
57+
- **TrackingMeanBatchNorm** — Batch normalization with running mean tracking
58+
59+
#### Riemannian Metrics
60+
61+
Four Riemannian metrics for SPD manifolds:
62+
63+
| Metric | Description |
64+
|--------|-------------|
65+
| **AffineInvariantRiemannian** | The canonical metric on SPD manifolds (AIRM) |
66+
| **LogEuclidean** | Computationally efficient metric via matrix logarithm |
67+
| **LogCholesky** | Metric based on Cholesky decomposition |
68+
| **BuresWasserstein** | Optimal transport metric between Gaussians |
69+
70+
Each metric provides:
71+
- Geodesic distance computation
72+
- Exponential and logarithmic maps
73+
- Parallel transport along geodesics
74+
- Fréchet/Karcher mean computation
75+
76+
#### Functional Operations
77+
78+
Low-level differentiable operations in `spd_learn.functional`:
79+
80+
- **Matrix Operations**: `logm`, `expm`, `sqrtm`, `invsqrtm`, `powm`
81+
- **Geodesics**: `geodesic`, `log_map`, `exp_map`
82+
- **Statistics**: `frechet_mean`, `log_euclidean_mean`
83+
- **Parallel Transport**: `parallel_transport`
84+
- **Covariance**: `covariance`, `scm`, `shrinkage_covariance`
85+
86+
#### Additional Features
87+
88+
- **GPU Acceleration** — Full CUDA support with efficient batched operations
89+
- **Automatic Differentiation** — Seamless gradient computation on manifolds via PyTorch
90+
- **scikit-learn Compatible** — Integration with ML pipelines via skorch/Braindecode wrappers
91+
- **Comprehensive Documentation** — Tutorials, API reference, and theoretical background
92+
- **Examples Gallery** — Ready-to-run examples for common use cases
93+
94+
---
95+
96+
### 📚 Documentation
97+
98+
- **Installation Guide** — Step-by-step setup instructions
99+
- **User Guide** — Comprehensive introduction to SPD matrices and Riemannian geometry
100+
- **Theory Section** — Mathematical background, layer descriptions, and metric details
101+
- **API Reference** — Complete documentation of all modules and functions
102+
- **Examples Gallery** — Practical examples including EEG classification
103+
104+
---
105+
106+
### 🔧 Technical Details
107+
108+
- **Python**: 3.11, 3.12, 3.13
109+
- **PyTorch**: 2.0+
110+
- **License**: BSD-3-Clause
111+
112+
---
113+
114+
### 🙏 Acknowledgments
115+
116+
SPD Learn is developed and maintained by researchers from:
117+
118+
- Inria (French National Institute for Research in Digital Science and Technology)
119+
- CNRS (French National Centre for Scientific Research)
120+
- CEA (French Alternative Energies and Atomic Energy Commission)
121+
- Université Paris-Saclay
122+
- ATR (Advanced Telecommunications Research Institute International)
123+
- Université Savoie Mont Blanc
124+
125+
---
126+
127+
### 📖 Citation
128+
129+
If you use SPD Learn in your research, please cite:
130+
131+
```bibtex
132+
@article{aristimunha2025spdlearn,
133+
title = {SPDlearn: A Geometric Deep Learning Python Library for Neural
134+
Decoding Through Trivialization},
135+
author = {Aristimunha, Bruno and Ju, Ce and Collas, Antoine and
136+
Bouchard, Florent and Thirion, Bertrand and
137+
Chevallier, Sylvain and Kobler, Reinmar},
138+
journal = {To be submitted},
139+
year = {2026},
140+
url = {https://github.com/spdlearn/spd_learn}
141+
}
142+
```
143+
144+
---
145+
146+
**Full Changelog**: https://github.com/spdlearn/spd_learn/commits/v0.1.0

0 commit comments

Comments
 (0)