spd_learn.models.SSGCNet

class spd_learn.models.SSGCNet(n_chans: int = 22, n_outputs: int = 2, n_nodes: int = 4, temporal_filters: int = 16, stiefel_dim: int = 12, k_neighbors: int = 2, eps: float = 0.0001, drop_prob: float = 0.2)

Bases: Module

Stiefel-SPD Manifold Graph Convolutional Network (SSGCNet).

This class implements the SSGCNet model proposed by Tibermacine, Russo, and Napoli [Tibermacine et al., 2026]. SSGCNet provides an end-to-end geometry-consistent architecture for EEG decoding that connects depthwise temporal-spatial convolutions, Stiefel manifold projections, and tangent-space \(k\)-NN graph attention.

Architecture Stages

1. Temporal & Spatial Convolutions:

   • 2D Temporal Conv: Conv2d(1, temporal_filters, (1, 15), padding=(0, 7))

   • Depthwise Spatial Conv: Conv2d(temporal_filters, temporal_filters, (n_chans, 1), groups=…)

2. Patch Covariance Embedding:

   • PatchEmbeddingLayer: splits temporal features into n_nodes patches.

   • CovLayer: computes sample covariance per patch.

   • TraceNorm: normalizes covariance scale.

   • Shrinkage: regularizes conditioning.

3. Stiefel Projection:

   • BiMap: learnable orthonormal projection on \(\text{St}(\text{temporal\_filters}, \text{stiefel\_dim})\).

   • ReEig: eigenvalue floor enforcement.

4. Tangent-Space :math:`k`-NN Graph-SPD Aggregation:

   • Maps node covariances to Log-Euclidean tangent space.

   • Computes pairwise tangent distances and dynamically selects top-\(k\) nearest neighbors.

   • Aggregates neighbor tangent representations via attention and retracts back to the SPD manifold via matrix_exp().

5. Classification:

   • LogEig: vectorizes upper triangular elements.

   • Flattening, dropout, and a linear classifier.

Parameters:

• n_chans (int, default=22) – Number of EEG electrode channels.

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

• n_nodes (int, default=4) – Number of temporal graph nodes (patches).

• temporal_filters (int, default=16) – Number of temporal convolutional filters.

• stiefel_dim (int, default=12) – Dimension of the reduced SPD matrices after Stiefel projection.

• k_neighbors (int, default=2) – Number of nearest neighbors aggregated in the tangent-space graph.

• eps (float, default=1e-4) – Eigenvalue threshold and regularizer.

• drop_prob (float, default=0.2) – Dropout probability before the final classification layer.

References

[1]

Imad Eddine Tibermacine, Samuele Russo, and Christian Napoli. Stiefel-SPD manifold graph convolution for end-to-end EEG learning. IEEE Transactions on Neural Systems and Rehabilitation Engineering, 2026. doi:10.1109/tnsre.2026.3652858.

Examples

>>> import torch
>>> from spd_learn.models import SSGCNet
>>> model = SSGCNet(n_chans=22, n_outputs=2)
>>> x = torch.randn(4, 22, 1000)
>>> out = model(x)
>>> out.shape
torch.Size([4, 2])

forward(x: Tensor) → Tensor

Forward pass of SSGCNet.

Parameters:

x (torch.Tensor) – Input EEG tensor of shape (batch, n_chans, n_times) or (batch, 1, n_chans, n_times).

Returns:

Output class logits with shape (batch, n_outputs).

Return type:

torch.Tensor