Load Space

Building physical spaces and operators from scratch requires careful attention to charge assignments, tensor elements, and symmetry conventions. The load_space function provides a high-level interface to quickly construct commonly used quantum many-body systems with correct symmetry implementation.

Supported systems:

• Spin systems ("Spin"): Arbitrary spin-J system with spin operators following spherical Condon–Shortley phase convention; supports U(1) and full SU(2) symmetry
• Spinless fermions ("Ferm"): Fermionic creation/annihilation operators and Jordan-Wigner strings with U(1) or Z(2)
• Spinful fermions ("Band"): Full electronic systems with both charge and spin degrees of freedom; supports Abelian (U(1)×U(1), Z(2)×U(1)) and non-Abelian (U(1)×SU(2), Z(2)×SU(2)) symmetries

Instead of manually defining sectors, charges, and operator tensor elements, load_space generates everything automatically based on the system type and desired symmetry. This is especially valuable for ensuring consistency in operator conventions across different parts of your code.

The function returns:

• Local space index (Spc): Local Hilbert space with appropriate symmetry sectors
• Operator dictionary (Op): Contains physical operators (e.g., spin operators, creation/annihilation operators)
• Vacuum index (vac): A trivial index with neutral charge and dimension 1

Spin Systems

Create spin-½ and spin-1 systems with U(1) symmetry.

Spherical Tensor Convention

The spin operators follow the spherical tensor convention:

\[ S_{+1} = -\frac{1}{\sqrt{2}}(S_x + iS_y), \quad S_{-1} = \frac{1}{\sqrt{2}}(S_x - iS_y) \]

This convention ensures proper commutation relations: \([S_{+1}, S_{-1}] = -S_z\).

# Spin-1/2 system
Spc_half, Op_half = load_space("Spin", "U1", {"J": 0.5})

print(f"Spin-1/2 space dimension: {Spc_half.dim}")
print(f"Available operators: {list(Op_half.keys())}\n")

# Display Sz operator
print(f"Sz operator:\n{Op_half['Sz']}\n")

# Display Sp operator
print(f"Sp operator:\n{Op_half['Sp']}\n")

# Display Sm operator
print(f"Sm operator:\n{Op_half['Sm']}")

Spin-1/2 space dimension: 2
Available operators: ['Sz', 'Sp', 'Sm', 'vac']

Sz operator:

  info:  2x { 2 x 1 }  having 'A',  Operator,  { _init_, _init_* }
  data:  2-D float64 (16 B)    2 x 2 => 2 x 2  @ norm = 0.707107

     1.  1x1     |  1x1     [ -1 ; -1 ]     -0.5     
     2.  1x1     |  1x1     [  1 ;  1 ]      0.5     

Sp operator:

  info:  3x { 1 x 1 }  having 'A',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (8 B)    1 x 1 x 1 => 1 x 1 x 1  @ norm = 0.707107

     1.  1x1x1   |  1x1x1   [ 1 ; -1 ; 2 ]  -0.7071     

Sm operator:

  info:  3x { 1 x 1 }  having 'A',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (8 B)    1 x 1 x 1 => 1 x 1 x 1  @ norm = 0.707107

     1.  1x1x1   |  1x1x1   [ -1 ; 1 ; -2 ]   0.7071     

# Spin-1 system
Spc_one, Op_one = load_space("Spin", "U1", {"J": 1.0})

print(f"Spin-1 space dimension: {Spc_one.dim}")
print(f"Sz operator:\n{Op_one['Sz']}")

Spin-1 space dimension: 3
Sz operator:

  info:  2x { 3 x 1 }  having 'A',  Operator,  { _init_, _init_* }
  data:  2-D float64 (24 B)    3 x 3 => 3 x 3  @ norm = 1.41421

     1.  1x1     |  1x1     [ -2 ; -2 ]      -1.     
     2.  1x1     |  1x1     [  0 ;  0 ]       0.     
     3.  1x1     |  1x1     [  2 ;  2 ]       1.     

Spinless Fermions

Create spinless fermion systems with U(1) or Z2 symmetry.

# U(1) symmetry (particle number conservation)
Spc_ferm_u1, Op_ferm_u1 = load_space("Ferm", "U1")

print(f"Spinless fermion space (U1) dimension: {Spc_ferm_u1.dim}")
print(f"Available operators: {list(Op_ferm_u1.keys())}\n")

# Display F operator (annihilation)
print(f"F operator:\n{Op_ferm_u1['F']}\n")

# Display Z operator (Jordan-Wigner string)
print(f"Z operator:\n{Op_ferm_u1['Z']}")

Spinless fermion space (U1) dimension: 2
Available operators: ['F', 'Z', 'vac']

F operator:

  info:  3x { 1 x 1 }  having 'A',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (8 B)    1 x 1 x 1 => 1 x 1 x 1  @ norm = 1

     1.  1x1x1   |  1x1x1   [ -1 ; 1 ; -2 ]       1.     

Z operator:

  info:  2x { 2 x 1 }  having 'A',  Operator,  { _init_, _init_* }
  data:  2-D float64 (16 B)    2 x 2 => 2 x 2  @ norm = 1.41421

     1.  1x1     |  1x1     [ -1 ; -1 ]       1.     
     2.  1x1     |  1x1     [  1 ;  1 ]      -1.     

# Z2 symmetry (parity conservation)
Spc_ferm_z2, Op_ferm_z2 = load_space("Ferm", "Z2")

print(f"Spinless fermion space (Z2) dimension: {Spc_ferm_z2.dim}")
print(f"F operator:\n{Op_ferm_z2['F']}")

Spinless fermion space (Z2) dimension: 2
F operator:

  info:  3x { 1 x 1 }  having 'Z2',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (8 B)    1 x 1 x 1 => 1 x 1 x 1  @ norm = 1

     1.  1x1x1   |  1x1x1   [ 0 ; 1 ; 1 ]       1.     

Spinful Fermions (Band)

Create spinful fermion systems with product group symmetries.

State Convention

The local basis states are defined as:

\[ |\uparrow\rangle = c^\dagger_\uparrow |0\rangle, \quad |\!\downarrow\rangle = c^\dagger_\downarrow |0\rangle, \quad |\!\uparrow\downarrow\rangle = c^\dagger_\uparrow c^\dagger_\downarrow |0\rangle \]

Spin Operators

The spin operators (Sz, Sp, Sm) follow the same spherical tensor convention as in spin systems.

# U(1) x U(1) symmetry (particle number, spin)
Spc_band_u1u1, Op_band_u1u1 = load_space("Band", "U1,U1")

print(f"Spinful fermion space (U1xU1) dimension: {Spc_band_u1u1.dim}")
print(f"Available operators: {list(Op_band_u1u1.keys())}\n")

# Display F_up operator
print(f"F_up operator:\n{Op_band_u1u1['F_up']}\n")

# Display F_dn operator
print(f"F_dn operator:\n{Op_band_u1u1['F_dn']}\n")

# Display Sz operator
print(f"Sz operator:\n{Op_band_u1u1['Sz']}\n")

# Display Sp operator
print(f"Sp operator:\n{Op_band_u1u1['Sp']}")

Spinful fermion space (U1xU1) dimension: 4
Available operators: ['F_up', 'F_dn', 'Z', 'Sz', 'Sp', 'Sm', 'vac']

F_up operator:

  info:  3x { 2 x 2 }  having 'U1×U1',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (16 B)    2 x 2 x 1 => 2 x 2 x 1  @ norm = 1.41421

     1.  1x1x1   |  1x1x1   [ -1  0 ; 0 1 ; -1 -1 ]       1.     
     2.  1x1x1   |  1x1x1   [  0 -1 ; 1 0 ; -1 -1 ]       1.     

F_dn operator:

  info:  3x { 2 x 2 }  having 'U1×U1',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (16 B)    2 x 2 x 1 => 2 x 2 x 1  @ norm = 1.41421

     1.  1x1x1   |  1x1x1   [ -1  0 ;  0 -1 ; -1  1 ]       1.     
     2.  1x1x1   |  1x1x1   [  0  1 ;  1  0 ; -1  1 ]      -1.     

Sz operator:

  info:  2x { 2 x 2 }  having 'U1×U1',  Operator,  { _init_, _init_* }
  data:  2-D float64 (16 B)    2 x 2 => 2 x 2  @ norm = 0.707107

     1.  1x1     |  1x1     [  0 -1 ;  0 -1 ]     -0.5     
     2.  1x1     |  1x1     [  0  1 ;  0  1 ]      0.5     

Sp operator:

  info:  3x { 1 x 2 }  having 'U1×U1',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (8 B)    1 x 1 x 1 => 1 x 1 x 1  @ norm = 0.707107

     1.  1x1x1   |  1x1x1   [ 0 1 ;  0 -1 ; 0 2 ]  -0.7071     

# Z2 x U(1) symmetry (parity, spin)
Spc_band_z2u1, Op_band_z2u1 = load_space("Band", "Z2,U1")

print(f"Spinful fermion space (Z2xU1) dimension: {Spc_band_z2u1.dim}")
print(f"F_up operator:\n{Op_band_z2u1['F_up']}")

Spinful fermion space (Z2xU1) dimension: 4
F_up operator:

  info:  3x { 2 x 2 }  having 'Z2×U1',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (32 B)    3 x 3 x 1 => 3 x 3 x 1  @ norm = 1.41421

     1.  2x1x1   |  1x1x1   [  0  0 ; 1 1 ;  1 -1 ]    16 B      
     2.  1x2x1   |  1x1x1   [  1 -1 ; 0 0 ;  1 -1 ]    16 B      

Spin SU(2)

With "SU2" symmetry, spin-rotation invariance is fully exploited. Instead of three operators (Sp, Sm, Sz), a single rank-1 spherical tensor S encodes all components via the Wigner–Eckart theorem.

# Spin-1/2 with full SU(2) symmetry
Spc_spin_su2, Op_spin_su2 = load_space("Spin", "SU2", {"J": 0.5})

print(f"Spin-1/2 SU(2) space:")
print(f"  dim (multiplets): {Spc_spin_su2.dim}")
print(f"  num_states (physical): {Spc_spin_su2.num_states}")
print(f"  Available operators: {list(Op_spin_su2.keys())}\n")

# S is the rank-1 spherical tensor (stores reduced tensor element)
print(f"S operator:\n{Op_spin_su2['S']}")

Spin-1/2 SU(2) space:
  dim (multiplets): 1
  num_states (physical): 2
  Available operators: ['S', 'vac']

S operator:

  info:  3x { 1 x 1 }  having 'SU2',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (8 B)    1 x 1 x 1 => 2 x 2 x 3  @ norm = 1.22474

     1.  1x1x1   |  2x2x3   [ 1 ; 1 ; 2 ]    0.866  {+}

# Spin-1 with full SU(2) symmetry
Spc_spin1_su2, Op_spin1_su2 = load_space("Spin", "SU2", {"J": 1.0})

print(f"Spin-1 SU(2) space:")
print(f"  dim (multiplets): {Spc_spin1_su2.dim}")
print(f"  num_states (physical): {Spc_spin1_su2.num_states}")
print(f"S operator:\n{Op_spin1_su2['S']}")

Spin-1 SU(2) space:
  dim (multiplets): 1
  num_states (physical): 3
S operator:

  info:  3x { 1 x 1 }  having 'SU2',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (8 B)    1 x 1 x 1 => 3 x 3 x 3  @ norm = 2.44949

     1.  1x1x1   |  3x3x3   [ 2 ; 2 ; 2 ]    1.414  {+}

Band U(1) × SU(2)

With "U1,SU2" symmetry, particle number (U(1)) and full spin rotation (SU(2)) are conserved simultaneously. The operator set reduces from six explicit operators to three: F (annihilation, rank-½ tensor), Z (Jordan-Wigner string), and S (spin, rank-1 tensor).

State Convention

The U(1)×SU(2) preset uses a different sign convention from the Abelian preset, following the CG tensor convention adopted by Yuzuha:

\[ |\uparrow\rangle = c^\dagger_\uparrow |0\rangle, \quad |\!\downarrow\rangle = -c^\dagger_\downarrow |0\rangle, \quad |\!\uparrow\downarrow\rangle = -c^\dagger_\uparrow c^\dagger_\downarrow |0\rangle \]

The minus signs arise from the phase convention of the standard CG basis in Yuzuha. This difference in convention does not affect physical computations — all expectation values and correlators remain identical.

# U(1) × SU(2) symmetry (particle number + full spin rotation)
Spc_band_u1su2, Op_band_u1su2 = load_space("Band", "U1,SU2")

print(f"Band U1×SU(2) space:")
print(f"  dim (multiplets): {Spc_band_u1su2.dim}")
print(f"  num_states (physical): {Spc_band_u1su2.num_states}")
print(f"  Available operators: {list(Op_band_u1su2.keys())}\n")

# F is the rank-1/2 fermionic annihilation tensor
print(f"F operator:\n{Op_band_u1su2['F']}\n")

# S is the rank-1 spin tensor
print(f"S operator:\n{Op_band_u1su2['S']}")

Band U1×SU(2) space:
  dim (multiplets): 3
  num_states (physical): 4
  Available operators: ['F', 'Z', 'S', 'vac']

F operator:

  info:  3x { 2 x 2 }  having 'U1×SU2',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (16 B)    2 x 2 x 1 => 3 x 3 x 2  @ norm = 2

     1.  1x1x1   |  1x2x2   [ -1  0 ; 0 1 ; -1  1 ]       1.  {+}
     2.  1x1x1   |  2x1x2   [  0  1 ; 1 0 ; -1  1 ]       1.  {+}

S operator:

  info:  3x { 1 x 2 }  having 'U1×SU2',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (8 B)    1 x 1 x 1 => 2 x 2 x 3  @ norm = 1.22474

     1.  1x1x1   |  2x2x3   [ 0 1 ; 0 1 ; 0 2 ]    0.866  {+}

# Z2 × SU(2) symmetry (parity + full spin rotation)
Spc_band_z2su2, Op_band_z2su2 = load_space("Band", "Z2,SU2")

print(f"Band Z2×SU(2) space:")
print(f"  dim (multiplets): {Spc_band_z2su2.dim}")
print(f"  num_states (physical): {Spc_band_z2su2.num_states}")
print(f"F operator:\n{Op_band_z2su2['F']}")

Band Z2×SU(2) space:
  dim (multiplets): 3
  num_states (physical): 4
F operator:

  info:  3x { 2 x 2 }  having 'Z2×SU2',  Operator,  { _init_, _init_*, _aux_* }
  data:  3-D float64 (32 B)    3 x 3 x 1 => 4 x 4 x 2  @ norm = 2

     1.  2x1x1   |  1x2x2   [ 0 0 ; 1 1 ; 1 1 ]    16 B   {+}
     2.  1x2x1   |  2x1x2   [ 1 1 ; 0 0 ; 1 1 ]    16 B   {+}

See Also

• API Reference: load_space
• SU(2) Examples: SU(2) group and tensor basics
• Previous: Build Operators
• Next: Performance Tips