spd_learn.functional.sym_to_upper#

spd_learn.functional.sym_to_upper(X, preserve_norm=True, upper=True)[source]#

Vectorizes symmetric matrices by extracting triangular elements.

This function extracts the upper (or lower) triangular elements of symmetric matrices. When preserve_norm=True (the default), a \(\sqrt{2}\) scaling is applied to off-diagonal elements so that the Euclidean norm of the resulting vector equals the Frobenius norm of the original matrix:

\[\|z\|_2 = \|V\|_F\]

This norm-preserving property is essential for tangent-space machine learning, ensuring that distances computed in the vectorized Euclidean space correspond to intrinsic Riemannian distances on the manifold.

When preserve_norm=False, no scaling is applied and the raw triangular elements are extracted (equivalent to the classical vech operation).

Parameters:

  • X (torch.Tensor) – Symmetric matrices with shape (…, n, n).

  • preserve_norm (bool, default=True) – If True, applies sqrt(2) scaling to off-diagonal elements so that ||vec(X)||_2 = ||X||_F. If False, extracts raw triangular elements.

  • upper (bool, default=True) – If True, extracts upper triangular elements. If False, extracts lower triangular elements.

Returns:

Vectorized triangular part with shape (…, n(n+1)/2).

Return type:

torch.Tensor

See also

vec_to_sym()

Inverse operation, reconstructs symmetric matrix.

LogEig

Uses this vectorization after matrix log.

References

See [Barachant et al., 2013] for tangent space classification.

Examples

>>> import torch
>>> X = torch.tensor([[1., 2.], [2., 3.]])
>>> # With norm preservation (default)
>>> v = sym_to_upper(X)  # [1., 2*sqrt(2), 3.]
>>> # Without norm preservation
>>> v_raw = sym_to_upper(X, preserve_norm=False)  # [1., 2., 3.]