spd_learn.models.GyroSPD#

class spd_learn.models.GyroSPD(n_chans: int = 22, n_outputs: int = 2, bimap_dims: tuple[int, ...]=(16, 12), drop_prob: float = 0.0, input_type: str = 'raw', cov_method=<function covariance>, threshold: float = 0.0001, upper: bool = True, device: device | None = None, dtype: dtype | None = None)[source]#

Bases: Module

Gyrovector Space Network on the SPD Manifold (GyroSPD).

This class implements the GyroSPD architecture [Nguyen and Yang, 2023], which formulates neural network operations on the Symmetric Positive Definite (SPD) manifold using gyrovector space calculus and left gyro-translations.

The model consists of:

  1. Preprocessing: Covariance estimation via CovLayer, trace normalization via TraceNorm, and learnable shrinkage regularization via Shrinkage.

  2. Gyro-Transformation Stages: Stacked GyroSPDLayer layers across subspace dimensions (n_chans, *bimap_dims), each combining bilinear mapping, rectified eigenvalue non-linearity, and left gyro-translation with a learnable SPD bias.

  3. Riemannian Normalization: Batch centering on the SPD manifold via SPDBatchNormMean.

  4. Riemannian-to-Euclidean Projection: Tangent space projection and upper triangular vectorization via LogEig.

  5. Classification Head: Dropout regularization and a fully connected linear layer.

Parameters:

  • n_chans (int, default=22) – Number of input channels (electrodes in EEG).

  • n_outputs (int, default=2) – Number of output classes for classification.

  • bimap_dims (tuple of int, default=(16, 12)) – Subspace dimensions for successive GyroSPDLayer stages.

  • drop_prob (float, default=0.0) – Dropout probability applied before the linear classification layer.

  • input_type ({"raw", "cov"}, default="raw") – Format of input data (‘raw’ time series or precomputed ‘cov’ matrices).

  • cov_method (callable, default=covariance) – Method to compute covariance when input_type is ‘raw’.

  • threshold (float, default=1e-4) – Eigenvalue rectification threshold for ReEig.

  • upper (bool, default=True) – If True, only upper-triangular elements are used in tangent projection.

  • device (torch.device, optional) – Device on which module parameters are allocated. Default is None.

  • dtype (torch.dtype, optional) – Data type of module parameters. Default is None.

See also

GyroSPDLayer

Building block layer applying left gyro-translation.

SPDResNet

Riemannian ResNet on the SPD manifold.

References

[1]

Xuan Son Nguyen and Shuo Yang. Building neural networks on matrix manifolds: a gyrovector space approach. In Proceedings of the 40th International Conference on Machine Learning, 26059–26073. PMLR, 2023.

Examples

>>> import torch
>>> from spd_learn.models import GyroSPD
>>> model = GyroSPD(n_chans=22, n_outputs=2)
>>> x = torch.randn(2, 22, 1000)
>>> out = model(x)
>>> out.shape
torch.Size([2, 2])
forward(x: Tensor) → Tensor[source]#

Forward pass of the GyroSPD model.

Parameters:

x (torch.Tensor) – Input tensor. If raw signal, shape is (batch_size, n_chans, n_times). If precomputed covariance, shape is (batch_size, n_chans, n_chans).

Returns:

Class logits of shape (batch_size, n_outputs).

Return type:

torch.Tensor