spd_learn.modules.SPDRMLR#

class spd_learn.modules.SPDRMLR(n_features: int, n_outputs: int, metric: str = 'LEM', theta: float = 1.0, input_tangent: bool = False, device: device | None = None, dtype: dtype | None = None)[source]#

Bases: Module

Riemannian Multinomial Logistic Regression for SPD matrices.

Implements the Riemannian Multinomial Logistic Regression (RMLR) framework [Chen et al., 2024] for Symmetric Positive Definite (SPD) manifolds. RMLR maps SPD matrices \(X \in \mathcal{S}_{++}^n\) to a vectorized tangent space relative to a learnable reference SPD matrix \(P \in \mathcal{S}_{++}^n\), followed by a linear multinomial regression layer:

\[V = \operatorname{Log}_P(X), \quad v = \operatorname{vech}(V), \quad y = W v + b\]

Under the supported Riemannian geometries, the mapping \(\operatorname{Log}_P(X)\) is computed as follows:

  • LEM (Log-Euclidean Metric): \(V = \log(X) - \log(P)\)

  • PEM (Power-Euclidean Metric): \(V = \frac{X^\theta - P^\theta}{\theta}\)

  • AIM (Affine-Invariant Metric): \(V = \log(P^{-1/2} X P^{-1/2})\)

  • LCM (Log-Cholesky Metric): \(V = \log_{\text{chol}}(X) - \log_{\text{chol}}(P)\)

Parameters:

  • n_features (int) – Size of the input SPD matrices (\(n \times n\)).

  • n_outputs (int) – Number of output classes or target features.

  • metric ({"LEM", "LCM", "AIM", "PEM"}, default="LEM") – Riemannian metric used to project matrices onto the tangent space.

  • theta (float, default=1.0) – Power deformation parameter for the “PEM” metric. When \(\theta = 0\), the limit corresponds to the “LEM” metric.

  • input_tangent (bool, default=False) – If True, input is assumed to already reside in the tangent space (as symmetric matrices or pre-vectorized vectors).

  • device (torch.device, optional) – Device on which to allocate parameters.

  • dtype (torch.dtype, optional) – Data type of parameters.

reference#

Learnable reference SPD matrix \(P \in \mathcal{S}_{++}^n\), parameterized via SymmetricPositiveDefinite. Initialized to the identity matrix.

Type:

nn.Parameter

linear#

Linear projection layer from the vectorized tangent space of dimension \(n(n+1)/2\) to n_outputs.

Type:

nn.Linear

References

[1]

Ziheng Chen, Yue Song, Yunmei Liu, and Nicu Sebe. Riemannian multinomial logistic regression for symmetric positive definite matrices. In Advances in Neural Information Processing Systems, volume 37. 2024. URL: https://openreview.net/forum?id=V2m8XQ9j3H.

Examples

>>> import torch
>>> from spd_learn.modules import SPDRMLR
>>> rmlr = SPDRMLR(n_features=4, n_outputs=2, metric="LEM")
>>> X = torch.randn(8, 4, 4)
>>> X = X @ X.mT + 0.1 * torch.eye(4)
>>> y = rmlr(X)
>>> y.shape
torch.Size([8, 2])
extra_repr() → str[source]#

Return the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.

forward(X: Tensor) → Tensor[source]#

Forward pass of SPDRMLR.

Parameters:

X (torch.Tensor) – Input tensor. If input_tangent=False, shape (…, n_features, n_features). If input_tangent=True, shape (…, n_features, n_features) or (…, vec_dim).

Returns:

Classification logits or transformed features of shape (…, n_outputs).

Return type:

torch.Tensor

reset_parameters() → None[source]#

Reset layer parameters to initial state.