SU2 Singlets

Utilities to construct, group, and inspect SU(2)-singlet spin combinations and their canonical basis vectors.

SU(2) singlet construction utilities and helper data structures.

This module is the user-facing surface for building local SU(2) gauge-invariant (singlet) states. The flow when a caller asks for the singlets of a chain of spin irreps [j_1, j_2, ..., j_N] is:

  1. get_SU2_singlets() converts the spin list to doubled integers and dispatches to the numba enumerator _su2_singlet_enum._enumerate_singlet_paths_doubled(), which returns every chain-of-couplings path that lands on a singlet (J_N = 0), as flat (m_paths, J_paths, cg_products) arrays.

  2. The output is sorted by the intermediate-J chain (J_2, J_3, ..., J_{N-1}); rows sharing the same chain form one multiplet. Each multiplet is wrapped into an SU2_singlet object: sympy-typed J_config / M_configs for downstream compatibility, CG_values kept as floats.

  3. SU2_singlet_canonical_vector() turns one SU2_singlet into a normalized vector in the local Hilbert basis. The per-leg (j, m) → index lookups built from get_spin_Hilbert_spaces() are memoized by _cached_leg_lookup(), so repeated calls with the same leg layout (as in the outer loop of SU2_gauge_invariant_states()) skip the layout reconstruction.

Matter sector

Each matter site carries one fermionic doublet (red + green) per flavor. A single matter leg has four states |n_r, n_g⟩:

|0,0⟩ vacuum (n = 0, J = 0, m = 0) |r,0⟩ (n = 1, J = 1/2, m = +1/2) |0,g⟩ (n = 1, J = 1/2, m = -1/2) |r,g⟩ pair (n = 2, J = 0, m = 0)

The vacuum and the pair share the same SU(2) labels, so we tag each matter slot with its fermion occupation n ∈ {0, 1, 2}. The SU2_singlet records this in its occupations field (one entry per flavor); the per-leg lookup in _cached_leg_lookup() uses (J, m, n) keys on matter legs (and plain (J, m) on gauge and background legs).

For N_f > 1 flavors, each flavor contributes one independent matter leg to the chain. Flavors transform under the same local SU(2), so the singlet-formation step automatically explores chains that combine different flavors into local color singlets — the enumerator is flavor-blind.

The Clebsch-Gordan kernel lives in _clebsch_gordan and the path enumerator in _su2_singlet_enum; both work in pure integer arithmetic on doubled spins / doubled magnetic numbers.

class edlgt.operators.SU2_singlets.SU2_singlet(J_config, M_configs, CG_values, pure_theory=True, occupations=None, background=0)[source]

Bases: object

Representation of one SU(2)-singlet multiplet in coupled-spin form.

Initialize an SU(2)-singlet descriptor.

Parameters:

  • J_config (list) – Total-spin labels for the constituent degrees of freedom. Matter slots carry the physical total spin (S(0) for vacuum / pair, S(1)/2 for half-occupied).

  • M_configs (list) – Allowed sets of magnetic quantum numbers producing the singlet.

  • CG_values (list) – Lists of intermediate Clebsch-Gordan coefficients associated with each M configuration.

  • pure_theory (bool, optional) – If False, matter degrees of freedom are included in the leading entries of the configuration.

  • occupations (tuple of int, optional) – Per-flavor fermion occupation n_f ∈ {0, 1, 2} (vacuum / half / pair). Required when pure_theory=False and the length determines the number of matter flavors.

  • background (int, optional) – Background-charge sector information used for labeling.

Raises:

  • TypeError – If inputs are not in the expected formats.

  • ValueError – If configuration lengths are inconsistent or occupations is missing / out of range for a matter theory.

display_singlet(msg=None)[source]

Log the singlet components and their Clebsch-Gordan coefficients.

edlgt.operators.SU2_singlets.get_SU2_singlets(spin_list, pure_theory=True, occupations=None, background=0)[source]

Enumerate all SU(2) singlets compatible with a list of spin irreps.

Parameters:

  • spin_list (list) – Spin irreps to be coupled. Matter slots (if any) come first and must carry the physical spin associated with each flavor’s occupation (S(0) for vacuum / pair, S(1)/2 for half).

  • pure_theory (bool, optional) – If True, spin_list is treated as gauge-only and occupations must be empty / None.

  • occupations (tuple of int, optional) – Per-flavor fermion occupations n_f ∈ {0, 1, 2}. Required when pure_theory=False.

  • background (int, optional) – Background-charge sector information.

Returns:

List of SU2_singlet objects, or None if no singlet exists.

Return type:

list or None

edlgt.operators.SU2_singlets.SU2_singlet_canonical_vector(spin_list, singlet, background=False)[source]

Construct the canonical basis vector of a specific SU(2) singlet.

Parameters:
Returns:

Normalized canonical state vector for the requested singlet.

Return type:

numpy.ndarray

edlgt.operators.SU2_singlets.get_spin_Hilbert_spaces(max_spin_irrep_list, pure_theory, background=0, n_flavors=None)[source]

Build local spin Hilbert spaces used in singlet construction.

Parameters:

  • max_spin_irrep_list (list) – Maximum spin irrep kept for each gauge degree of freedom.

  • pure_theory (bool) – If False, prepend the matter Hilbert space(s) used by the SU(2) dressed-site construction.

  • background (int, optional) – If nonzero, prepend the background-charge Hilbert space.

  • n_flavors (int, optional) – Number of matter flavors. Each flavor contributes one independent matter leg (4 fermion-occupation states). Defaults to 1 when pure_theory=False and 0 otherwise.

Returns:

(j_list, m_list) with per-degree-of-freedom lists of spin irreps and magnetic quantum numbers. Matter legs carry the physical J ∈ {0, 1/2, 1/2, 0} and m ∈ {0, +1/2, -1/2, 0}; the vacuum and pair states are distinguished by an occupation tag carried separately on SU2_singlet.

Return type:

tuple