frontier.utils.so_decomposition

so_decomposition(U: ndarray, atol: float = 1e-10) → Tuple[List[GivensRotation], ndarray][source]

Decompose a real special-orthogonal matrix into Givens rotations.

This implements a Clements-style scheme specialized to real matrices:

\[U = D \prod_k G_k,\]

where each \(G_k\) is a real Givens rotation and \(D\) is a real diagonal matrix with entries \(\pm 1\).

Parameters:

  • U – (N, N) real-valued matrix that should lie in \(SO(N)\).

  • atol – Absolute tolerance used to validate orthogonality.

Returns:

Tuple (G, D) where

  • G is a list of GivensRotation objects ordered so that:

    reconstruct(G, D) ~= U

  • D is an (N, N) real diagonal NumPy array with entries \(\pm 1\).

Raises:

ValueError – If U is not square, not (approximately) orthogonal, or its determinant is not (approximately) +1.