Module fisher_rao 

Fisher–Rao precision-weight normalization for response-geometry REML.

A caller may supply the per-observation Fisher–Rao precision metric coupling the tangent-coordinate residuals as a 1-D vector (a shared isotropic scale per row), a single 2-D (dim, dim) matrix (shared across all rows), or a full 3-D (n_rows, dim, dim) stack. This broadcasts any of those to the canonical per-row block form and validates finiteness, per-row symmetry, and positive semidefiniteness. A precision metric induces the squared residual rᵀ W r, which must be non-negative for every residual r; that holds iff each block is PSD (all eigenvalues ≥ 0). Symmetry plus a non-negative diagonal is not sufficient — e.g. [[1, 2], [2, 1]] is symmetric with a non-negative diagonal yet z = (1, −1) gives zᵀ W z = −2 < 0. The Cholesky-whitening REML consumer needs the stronger positive-definite condition (all eigenvalues > 0), exposed via normalize_fisher_rao_blocks_pd. Single source of truth shared by the response_geometry_normalize_fisher_rao FFI shim and any core consumer.

Enums

FisherRaoDefiniteness

Required definiteness of each per-row Fisher–Rao precision block.

Functions

normalize_fisher_rao_blocks

Broadcast and validate a Fisher–Rao weight array into (n_rows, dim, dim) positive-semidefinite precision blocks (the general metric API). Accepts a 1-D (n_rows,) isotropic scale, a 2-D (dim, dim) shared matrix, or a 3-D (n_rows, dim, dim) stack. Rank-deficient (PSD-singular) blocks are accepted; indefinite blocks are rejected. Use normalize_fisher_rao_blocks_pd for the Cholesky-whitening path.

normalize_fisher_rao_blocks_pd

Broadcast and validate Fisher–Rao weight blocks requiring each block to be positive-definite, as the Cholesky-whitening REML path needs (a singular block has no L Lᵀ = W factor). Same broadcasting rules as normalize_fisher_rao_blocks; the difference is the per-block spectrum must be strictly positive rather than merely non-negative.