spd_learn.models.GyroSPDLayer

class spd_learn.models.GyroSPDLayer(in_features: int, out_features: int, threshold: float = 0.0001, device: device | None = None, dtype: dtype | None = None)

Bases: Module

Gyrovector Space Layer on the SPD Manifold.

This module applies a bilinear projection BiMap followed by eigenvalue rectification ReEig, and then applies left gyro-translation on the SPD manifold [Nguyen and Yang, 2023]:

\[X \oplus B = B^{1/2} X B^{1/2}\]

where \(B \in \mathcal{S}_{++}^{\text{out\_features}}\) is a learnable SPD bias matrix parameterized via SymmetricPositiveDefinite.

Parameters:

• in_features (int) – Input SPD matrix dimension.

• out_features (int) – Output SPD matrix dimension.

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

• 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

GyroSPD

Full architecture combining stacked gyro layers.

BiMap

Bilinear projection layer.

SymmetricPositiveDefinite

SPD parametrization.

Examples

>>> import torch
>>> from spd_learn.models import GyroSPDLayer
>>> layer = GyroSPDLayer(in_features=8, out_features=4)
>>> X = torch.randn(2, 8, 8)
>>> X = X @ X.mT + 0.1 * torch.eye(8)
>>> out = layer(X)
>>> out.shape
torch.Size([2, 4, 4])

forward(X: Tensor) → Tensor

Forward pass applying BiMap, ReEig, and left gyro-translation.

Parameters:

X (torch.Tensor) – Input SPD tensor of shape (…, in_features, in_features).

Returns:

Transformed SPD tensor of shape (…, out_features, out_features).

Return type:

torch.Tensor

reset_parameters() → None

Reset layer parameters to their initial states.