multigeom.analysis.metrics

Cross-encoder similarity measures for the multi-scale Fisher metric G(x) and the classical Fisher J(x).

Two measures, both used in the paper:

  1. **Subspace alignment** — angle-only, eigenvalue-blind.
       𝒜_k(A, B) = (1/k) ‖V_Aᵀ V_B‖_F²
                 = (1/k) Σ_i cos² θ_i        (paper Eq. (eq:subspace-alignment))

  2. **Bures–Wasserstein distance** — sensitive to both orientation and scale.
       d_BW²(A, B) = tr(A) + tr(B) − 2 tr[(A^{1/2} B A^{1/2})^{1/2}]   (Eq. (eq:bures))

       In practice we evaluate the cross term on the truncated eigendecomposition
       A ≈ V_A Λ_A V_Aᵀ, B ≈ V_B Λ_B V_Bᵀ:
           tr[(Λ_A^{1/2} C Λ_B Cᵀ Λ_A^{1/2})^{1/2}] = Σ_i √μ_i
       where C = V_Aᵀ V_B ∈ ℝ^{k × k} and {μ_i} are the eigenvalues of
       M = Λ_A^{1/2} C Λ_B Cᵀ Λ_A^{1/2}. We symmetrise M before
       diagonalisation to guard against numerical asymmetry.

Both functions take two truncated eigendecompositions in the convention
returned by `multigeom.geometry.estimator.conditional_pair_estimate` and
`multigeom.geometry.fisher.fisher_eigendecomposition`: eigenvectors as **rows** of a
[k, P] matrix, eigenvalues as a [k] vector, both descending.

Functions

bures_wasserstein(eigvals_A, eigvecs_A, ...)	Compute the Bures–Wasserstein distance d_BW(A, B) on the cone of PSD matrices, using truncated eigendecompositions.
bures_wasserstein_from_overlap(eigvals_A, ...)	Bures-Wasserstein distance from eigenvalues and the overlap matrix C = V_Aᵀ V_B (eigenvectors as columns; with the rows convention used in this package, C = eigvecs_A @ eigvecs_Bᵀ).
subspace_alignment(eigvecs_A, eigvecs_B[, top_k])	Compute 𝒜_k = (1/k) ‖V_Aᵀ V_B‖_F² where V_A, V_B are the top-k eigenvectors of two PSD matrices.