Nicole 0.3.4

Nicole 0.3.4 — SVD Isometry for SU(2) Tensors

Release Date: April 24, 2026

Version 0.3.4 fixes a bug where Vh (and V in LV mode) returned by decomp and the
low-level svd function was not a physical isometry for SU(2) tensors. For Abelian groups
the standard block-wise matrix SVD guarantees Vh @ Vh† = I directly. For SU(2) groups,
where each block carries a weight matrix W encoding Clebsch-Gordan structure, that
guarantee requires W W^T = irrep_dim(q) · I — a condition that was not enforced: prior
operations may leave W in any state (row-normalized but not row-orthogonal, or with
non-canonical scaling), silently breaking the isometry.

🛠️ Bug Fix

SVD — Vh Isometry for SU(2)

Root cause. Each SU(2) tensor block is parameterized as a product R @ W of a
reduced data matrix R and an intertwiner weight matrix W. Prior operations —
contractions, explicit Tensor.regularize() calls, or any sequence that leaves W in an
arbitrary state — can produce a weight matrix that is row-normalized but not row-orthogonal,
or one whose rows have non-canonical scaling. In all such cases W W^T ≠ irrep_dim(q) · I,
and the resulting Vh fails the isometry test Vh @ Vh† = I.

Fix. A new internal function _regularize_for_svd is applied to the input tensor
before the SVD. For each block it performs a thin SVD of the weight matrix
W = U S Vhᵀ and re-parameterizes:

W_new  = √irrep_dim(q) · Vh[:k, :]      # orthonormal rows at the canonical scale
R_new  = R @ (U[:, :k] · S[:k]) / √irrep_dim(q)

so that R_new @ W_new = R @ W (the physical tensor is unchanged) and
W_new @ W_new^T = irrep_dim(q) · I (the isometry condition is satisfied).

Autograd compatibility. The coefficient matrix M = (U[:,:k] · S[:k]) / √irrep_dim
is derived entirely from bridge.weights, which carries no requires_grad. The
transformation R_new = R @ M is therefore a differentiable linear map from the original
data blocks; gradients flow from the SVD output back through the regularization to any
upstream parameters unchanged.

Scope. The fix applies inside svd() before any axis merging or truncation, so it
covers all four output modes of the high-level decomp function: SVD, UR, LV, and QR.
For Abelian tensors and tensors without an intertwiner the function returns the original
tensor unchanged (zero overhead).

🧪 Test Suite (1540 tests)

• 1530 tests pass, 10 skipped (accelerator-only tests on CPU-only CI)
• Five new tests added to tests/operations/test_factorize.py:
  • test_svd_su2_vh_isometric_via_contract_2nd_order — 2nd-order tensor, all axes
  • test_svd_su2_vh_isometric_via_contract_3rd_order — 3rd-order tensor, all axes
  • test_svd_su2_vh_isometric_via_contract_4th_order — 4th-order tensor, all axes
  • test_svd_su2_vh_isometric_via_contract_5th_order — 5th-order tensor, all axes
  • test_svd_su2_vh_isometric_via_contract_6th_order — 6th-order tensor, all axes

Each test contracts Vh @ Vh† using contract(Vh, Vh.conj()) and compares the result
with identity(Vh.indices[0]).

📊 Statistics

Code Changes

• 8 commits since v0.3.3
• 8 files changed: 135 insertions, 25 deletions
• Source modules touched: src/nicole/decomp.py, src/nicole/blocks.py, src/nicole/tensor.py
• Test module touched: tests/operations/test_factorize.py

✅ Compatibility

Breaking Changes: None. The physical tensors produced by decomp and svd are
identical to those of v0.3.3 (up to a change of orthonormal basis in the bond dimension,
which does not affect any observable quantity). The isometry guarantee is now enforced
rather than assumed.

Requirements:

• Python ≥ 3.11
• PyTorch ≥ 2.5
• Yuzuha ≥ 0.1.5

📝 Notes

The bug was latent since SU(2) support was introduced. Tests that checked reconstruction
(T ≈ U @ S @ Vh) passed because the physical content is preserved regardless of the
weight basis. No existing test verified Vh @ Vh† = I via explicit contraction using
contract(Vh, Vh.conj()); those tests were added in this release.