Installation#

SPD Learn requires Python 3.11 or higher and is built on PyTorch 2.0+.

Quick Install#

The simplest way to install SPD Learn is via pip:

pip install spd_learn

This will install the core package with minimal dependencies.

Dependencies#

Core dependencies (installed automatically):

  • PyTorch - Deep learning framework

  • einops - Flexible tensor operations

  • NumPy - Numerical computing

  • pyRiemann (>= 0.12) - SPD/Riemannian geometry. SPD Learn delegates geodesics, parallel transport, and Fréchet derivatives to pyRiemann’s Array API backend (which runs natively on PyTorch tensors) and re-exports pyRiemann’s broader toolkit. It keeps its own numerically-stable, custom-autograd matrix-function primitives (matrix_log/matrix_exp/matrix_sqrt/…), distances, and means, which stay finite/stable on ill-conditioned inputs — important for training.

Note

SPD Learn uses pyRiemann from PyPI, with version 0.12 or newer required for its Array API (PyTorch) backend:

pyriemann>=0.12

Installing from Source#

For the latest development version, you can install directly from GitHub:

git clone https://github.com/spdlearn/spd_learn.git
cd spd_learn
pip install -e .

Optional Dependencies#

SPD Learn provides optional dependency groups for different use cases:

Brain-Computer Interface (BCI) & Neuroimaging#

For EEG and fMRI applications:

pip install "spd_learn[brain]"

This installs:

(pyRiemann is now a core dependency — see above — so it is always installed.)

Documentation#

To build the documentation locally:

pip install "spd_learn[docs]"

Testing#

For running the test suite:

pip install "spd_learn[tests]"

All Dependencies#

To install all optional dependencies:

pip install "spd_learn[all]"

Verifying Installation#

After installation, verify that SPD Learn is working correctly:

import torch
from spd_learn.models import SPDNet

# Create SPDNet for 16-channel data with 2 output classes
model = SPDNet(
    n_chans=16,
    n_outputs=2,
    subspacedim=8,
    input_type="cov",  # Input is pre-computed covariance
)

# Generate random SPD matrix (must be positive definite)
X = torch.randn(4, 16, 16)
X = X @ X.transpose(-1, -2) + 0.1 * torch.eye(16)  # Make SPD

# Forward pass
output = model(X)
print(f"Input shape: {X.shape}")  # (4, 16, 16)
print(f"Output shape: {output.shape}")  # (4, 2)
print("Installation successful!")

Development Installation#

For contributing to SPD Learn:

git clone https://github.com/spdlearn/spd_learn.git
cd spd_learn
pip install -e ".[all]"

This installs the package in editable mode with all dependencies for development, testing, and documentation.

Troubleshooting#

Common Issues#

ImportError: No module named ‘spd_learn’

Make sure you’ve installed the package:

pip install spd_learn

CUDA out of memory

Try reducing batch size or using CPU:

model = model.cpu()
X = X.cpu()

Numerical instability with eigenvalue decomposition

Use the ReEig layer with an appropriate threshold:

from spd_learn.modules import ReEig

# Add small threshold to prevent numerical issues
reeig = ReEig(threshold=1e-4)

Getting Help#