Nicole 0.3.0

Nicole 0.3.0 - SU(2) Symmetry Powered by Yuzuha

Release Date: March 26, 2026

Version 0.3.0 introduces full support for the SU(2) non-Abelian symmetry group via Clebsch-Gordan intertwiner algebra, extending Nicole's block-sparse framework from purely Abelian symmetries to include spin-rotational invariance. This release also adds an iterative diagonalization benchmark layer for internal validation of tensor network simulations against analytic and exact-diagonalization reference spectra.

🔵 SU(2) Non-Abelian Symmetry Group

Core Infrastructure

• SU2Group class: Non-Abelian unitary symmetry representation for spin systems
• is_abelian property: Added to all symmetry group classes for runtime dispatch
• irrep_dim method: Symmetry-group-aware physical state counting
• num_states property: Total Hilbert space dimension on Index
• fs_phase function: Frobenius-Schur phase computation for SU(2) charges
• Refactored fuse_channels and fuse_unique: Unified Abelian and unitary branches

Bridge and Clebsch-Gordan Algebra (powered by Yuzuha)

• Bridge class: SU(2) Clebsch-Gordan tensor manipulation with automatic SQLite caching
• compute_xsymbol and compute_rsymbol: X-symbol and R-symbol CG tensor operations
• Bridge.conj(), conj_phase(), invert_edges(), insert_edge(): Full intertwiner manipulation suite
• Device management and cloning: Bridge tensors fully support .to() and .clone()
• BlockSchema extensions: bridge_collinear, block_add, charge_avail, num_components

Non-Abelian Tensor Operations

• Tensor intertwiner fields: Tensor class extended to hold, validate, and manage intertwiner weights for non-Abelian groups
• canonicalize() and regularize(): Canonical form and weight restoration for SU(2) tensors
• copy → clone: Renamed for semantic clarity; deep-clone support for intertwiners
• conj(): Enhanced with Frobenius-Schur-phase-scaled intertwiner weights
• permute() and transpose(): Update intertwiners correctly for non-Abelian tensors
• compress(): Reduces redundant intertwiner components
• Frobenius norm: Implemented for non-Abelian tensors
• Arithmetic: Element-wise addition, subtraction, and scalar multiplication with intertwiners
• subsector(): Extracts intertwiner blocks for non-Abelian groups
• trim_zero_blocks(): Renamed from trim_zero_sectors, with configurable epsilon
• insert_index(): Neutral edge insertion via Bridge.insert_edge()

Tensor Decompositions

• svd(): Extended to support SU(2) via CG-block diagonalization
• qr(): Extended to support SU(2) with appropriate intertwiner handling
• eig(): Extended to support SU(2) with canonical intertwiner restoration via regularize(); new is_hermitian flag for guaranteed real spectra
• decomp(): Refactored to use capcup for bond direction inversions

Tensor Contractions

• contract(): Extended to support non-Abelian groups with R-symbol and X-symbol insertions; row-normalization of intertwiner weights to prevent weight decay; regularization and compression to handle rank-deficient CG structures; charge conservation checks for generic tensors
• trace(): Extended to support SU(2) with pair validation and intertwiner regularization
• Frobenius-Schur phase corrections: Applied in contraction for SU(2) tensors
• Scalar contraction: R-symbol applied for non-trivial charge alignments

Maneuvers and Operators

• capcup(): Inverts tensor contraction pairs with Frobenius-Schur phase correction
• diag(), inv(), oplus(): Extended to support both Abelian and non-Abelian tensor operations
• isometry() and isometry_n(): Extended for multi-channel fusion in non-Abelian groups

🗂️ Physical Presets

• SU(2) symmetry: Spin-J multiplet as a single irreducible sector; operators {S (rank-1 spherical tensor), vac}
• U(1)×SU(2) and Z2×SU(2) variants: Four-state Hilbert space with operators {F (SU(2)-doublet annihilation), Z (Jordan-Wigner), S (rank-1 spin tensor), vac} stored as Wigner-Eckart reduced matrix elements

📐 Iterative Diagonalization Benchmarks

Hamiltonian Builders (bench/system.py)

• build_heisenberg(): MPO for the Heisenberg spin chain under U(1) and SU(2) symmetries
• build_freefermion(): MPO for the free spinless tight-binding chain
• build_conductor(): MPO for the free spinful tight-binding Hamiltonian

Benchmark Routines (bench/)

• iter_diag_spin(): Iterative diagonalization of the Heisenberg spin chain under U(1) and SU(2) symmetry
• iter_diag_ferm(): Iterative diagonalization of the spinless tight-binding fermion chain under U(1) and Z2 symmetry
• iter_diag_band(): Iterative diagonalization of the spinful tight-binding chain with unified F-operator handling for Abelian and non-Abelian cases
• exact_halffilling_energy() and exact_halffilling_energy_band(): Analytic reference energy calculations

🧪 Test Suite (1434 tests)

• SU(2) tests across all modules: construction, arithmetic, permutation, contraction, decomposition, maneuver, diag/inv, oplus, unitarity, consistency
• Bridge unit tests for all new methods
• Integration tests: SU(2) and U(1)×SU(2) Heisenberg spectra; two-site hopping Hamiltonians under U(1), Z2, U(1)×U(1), Z2×U(1), U(1)×SU(2), Z2×SU(2)
• Autograd tests with SU(2) tensors
• eig tests with is_hermitian parameter
• Consistency tests for terminal vs leading insertion with permutation for SU(2) tensors

📊 Statistics

Code Changes

• 260 commits since v0.2.1
• 63 files changed: 22,858 insertions, 4,012 deletions
• New modules: SU2Group, Bridge, delegate.py, maneuver.py (renamed from operators.py)
• New test modules: test_delegate.py, test_group_su2.py, test_capcup.py, test_maneuver.py, test_consistency.py, test_spectrum.py, test_unitarity.py

Test Coverage

• 1428 tests pass, 6 skipped
• Complete SU(2) coverage across all tensor operations and decompositions
• Integration tests validate spectra against analytic reference results

🎓 Target Users

Researchers in quantum many-body physics and quantum information who work with spin systems, Hubbard-type models, or Anderson impurity problems requiring full SU(2) spin-rotational invariance, and developers of tensor network algorithms (DMRG, TEBD, iPEPS) seeking reduced bond dimensions through non-Abelian symmetry exploitation.

✅ Compatibility

Breaking Changes: copy() renamed to clone() for semantic clarity. All other changes are backward compatible with v0.2.x API.

Requirements:

• Python ≥ 3.11
• PyTorch ≥ 2.5
• Yuzuha ≥ 0.1.3

🙏 Notes

Version 0.3.0 represents a major capability expansion of Nicole, bringing genuine non-Abelian SU(2) symmetry support with a mathematically rigorous intertwiner-based implementation. By leveraging the Yuzuha library for high-performance CG coefficient computation with automatic caching, Nicole can now exploit the full power of spin-rotational invariance in tensor network simulations, reducing effective bond dimensions and memory consumption across a broad class of quantum many-body systems.