neuromodes.eigen.is_orthonormal_basis

neuromodes.eigen.is_orthonormal_basis(emodes: ArrayLike, mass: spmatrix | ArrayLike | None = None, atol: float = 0.001, rtol: float = 1e-05) → bool

Check if a set of vectors is orthonormal in Euclidean space (i.e., emodes.T @ emodes == I) or with respect to a mass matrix (i.e., emodes.T @ mass @ emodes == I), where I is the identity matrix. Mass-orthonormality is expected for the geometric eigenmodes (see notes).

Parameters

emodesarray-like: The vectors array of shape (n_verts, n_modes), where n_modes is the number of vectors.
massarray-like, optional: The mass matrix of shape (n_verts, n_verts). If None, Euclidean orthonormality is checked. Default is None.
atolfloat, optional: Absolute tolerance for the orthonormality check. Default is 1e-3.
rtolfloat, optional: Relative tolerance for the orthonormality check. Default is 1e-5.

Returns

bool: True if the set of vectors is orthonormal (Euclidean or mass-orthonormal), False otherwise.

Raises

ValueError: If emodes does not have shape (n_verts, n_modes), where n_verts ≥ n_modes.
ValueError: If mass is provided but does not have shape (n_verts, n_verts).

Notes

Under discretization, the set of solutions for the generalized eigenvalue problem is expected to be mass-orthogonal (mode_i^T * mass matrix * mode_j = 0 for i ≠ j), rather than orthogonal with respect to the standard Euclidean inner (dot) product (mode_i^T * mode_j = 0 for i ≠ j). Eigenmodes are also expected to be mass-normal (mode_i^T * mass matrix * mode_i = 1). It follows that the first mode is expected to be a specific constant, but precision error during computation can introduce spurious spatial heterogeneity. Since many eigenmode analyses rely on mass-orthonormality (e.g., decomposition, wave simulation), this function serves to ensure the validity of any calculated or provided eigenmodes.