spd_learn.models.AdaptiveLogEuclidean#

class spd_learn.models.AdaptiveLogEuclidean(num_features: int, return_spd: bool = False, eps: float = 1e-06, device: device | None = None, dtype: dtype | None = None)[source]#

Bases: Module

Adaptive Log-Euclidean Metric (ALEM) Layer.

This module implements the learnable eigenvalue deformation of the Adaptive Log-Euclidean Metric framework [Chen et al., 2024]. Given an SPD matrix \(X = U \Lambda U^\top\), it deforms the eigenvalues via a learnable positive power \(p\) and an affine scale/shift in the deformed log-eigenvalue space:

\[p = \text{softplus}(p_{\text{raw}}) + 0.1\]
\[\tilde{\lambda}_i = w_i \frac{\lambda_i^p - \lambda_i^{-p}}{2p} + b_i\]

When return_spd=False, the module returns the symmetric tangent matrix:

\[S = U \text{Diag}(\tilde{\lambda}) U^\top \in \mathcal{S}_d\]

When return_spd=True, it projects back to the SPD manifold:

\[Y = U \text{Diag}(\exp(\tilde{\lambda})) U^\top \in \mathcal{S}_{++}^d\]
Parameters:

  • num_features (int) – Dimension \(d\) of the SPD matrices.

  • return_spd (bool, default=False) – If True, exponentiates the deformed eigenvalues and returns an SPD matrix. If False, returns a symmetric tangent matrix.

  • eps (float, default=1e-6) – Lower clamp threshold for eigenvalues.

  • 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

SPDResNet

Network architecture utilizing ALEM.

LogEig

Standard static matrix logarithm.

Examples

>>> import torch
>>> from spd_learn.models import AdaptiveLogEuclidean
>>> alem = AdaptiveLogEuclidean(num_features=4, return_spd=False)
>>> X = torch.randn(2, 4, 4)
>>> X = X @ X.mT + 0.1 * torch.eye(4)
>>> out = alem(X)
>>> out.shape
torch.Size([2, 4, 4])
forward(X: Tensor) → Tensor[source]#

Forward pass applying adaptive eigenvalue deformation.

Parameters:

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

Returns:

Deformed tensor of shape (…, d, d). Symmetric tangent matrix if return_spd=False, SPD matrix if return_spd=True.

Return type:

torch.Tensor

reset_parameters() → None[source]#

Reset learnable parameters to initial identity-like values.