Why uniform orthogonalization must be SVD-based (the prefix-mask contract)#

A short “why” note. The uniform layer represents per-stack ranks as prefix masks [0, rank) — i.e. it asserts the real orthonormal frame vectors occupy the leading slots of each (padded) frame core, with [rank, pad) being don’t-care garbage. This note records why that assertion is correct only because the orthogonalization is SVD-based, and would break under (non-pivoted or pivoted) QR. Pairs with docs/uniform_masks_vs_ranks.md and docs/uniform_pytree_composition.md.

The contract#

ufv_make_frame_masks builds the frame masks from the structural ranks alone — arange(pad) < rank — and never inspects the core contents. So the masks are correct iff the orthogonalization actually places the rank-many real content in the leading slots [0, rank).

SVD delivers this; QR does not#

Each orthogonalization step factors a core B = U·(S Vᵀ), keeps U as the (orthonormal) frame core, and pushes S Vᵀ into the neighbour.

  • SVD sorts singular values descending, so the nonzero-σ (real) content lands in the leading columns of U — regardless of how the rank deficiency is arranged inside B. Zero-σ columns (padding, or orthonormal rank-completion) go to the trailing slots, which the mask zeroes. The prefix mask therefore identifies the real frame vectors correctly and deterministically (the sort is a function of the rank, not of where the deficiency sits).

  • QR pushes the rank deficiency into the triangular remainder R (which is shipped off to the neighbour), while Q stays full-rank orthonormal in Gram–Schmidt / input-column order — not sorted by importance. Whether the real content ends up in Q’s prefix depends entirely on column order. With internal dependence — which an orthogonalization sweep cannot preclude — the zero pivot lands mid-stream, not trailing, so a prefix mask drops real content.

    Column-pivoted (rank-revealing) QR could prefix-align, but its pivot order is data-dependent, which is fatal twice: a fixed structural prefix mask can’t track a data-dependent permutation, and the structure would change run-to-run.

Empirical confirmation#

A rank-2 matrix with internal dependence, columns [c1, c1, c2, c2]:

singular values        : [5.263 2.484 0. 0.]        (sorted -> rank 2 in the prefix)
SVD  prefix err |M - U[:,:2] (SVᵀ)[:2,:]| = 0.0
QR   R diagonal        : [-3.701 0. -1.507 0.]      (zero pivot at position 1 -- INTERNAL)
QR   prefix err |M - Q[:,:2] R[:2,:]|     = 2.13    (prefix drops real content)

Two properties, both load-bearing#

SVD gives the prefix-mask design exactly the two things it needs:

  1. Correctness — the rank-many real content sits in the masked prefix, for any input arrangement.

  2. Determinism — at fixed rank the prefix structure is identical every time. This is the bridge to the jit-performance story (docs/uniform_pytree_composition.md): in a manifold-optimization loop the frame is re-orthogonalized every step, yet the masks come out identical (same prefix), so they are loop-invariant and neither the backend (close-over) nor the frontend (value-hashed holder) path recompiles. Under pivoted QR the masks would shift each iteration and you would recompile regardless.

Honest caveat (not a bug)#

When the structural rank exceeds the numerical rank, SVD completes the prefix with arbitrary orthonormal vectors at the zero-σ slots. This is intentional — it is how a rank-deficient frame escapes its stratum (the examples’ “completes the rank-deficient frame with orthonormal vectors”). The completion vectors are non-unique, but they are traced data, not the jit cache key, so their wobble is invisible to jit; and the mask still marks them real (they are legitimate orthonormal frame directions).

Code#

SVD throughout: backend/ut3_orthogonalization.py and backend/t3_orthogonalization.py use xnp.linalg.svd; the functions are named down_svd_* / left_svd_* / right_svd_*. There is no QR in any orthogonalization path — by design, per this note.