load_space¶

Load preset physical space and operators for quantum many-body systems.

load_space ¶

load_space(
    preset: str, preserv: str, option: Optional[Dict[str, Any]] = None
) -> Tuple[Index, Dict[str, Tensor]]

Load physical space and operators for quantum many-body systems.

Parameters:

Name	Type	Description	Default
`preset`	`str`	System preset: "Spin" for bosonic spin systems, "Ferm" for spinless fermions, "Band" for spinful fermions in conduction band	required
`preserv`	`str`	Symmetry to preserve: "U1" for U(1) charge conservation "SU2" for full SU(2) spin rotation (Spin only) "Z2" for Z2 parity "Z2,U1" for Z2 parity + U1 spin (Band only) "U1,U1" for U1 particle number + U1 spin (Band only) "U1,SU2" for U1 particle number + full SU(2) spin (Band only) "Z2,SU2" for Z2 parity + full SU(2) spin (Band only)	required
`option`	`dict`	Additional options specific to the system: For "Spin": {"J": float} where J is the total spin (half-integer) For "Ferm": No options required for spinless fermions For "Band": No options required for spinful fermions	`None`

Returns:

Name	Type	Description
`Spc`	`Index`	Physical space index containing all sectors of the local Hilbert space
`Op`	`dict[str, Tensor \| Index]`	Dictionary of operators and indices.

Description

For spin systems with U(1): {"Sp", "Sm", "Sz", "vac"}

Sz: 2-index tensor (IN, OUT) - charge neutral
Sp: 3-index tensor (IN, OUT, auxiliary) - charge neutral with auxiliary index
Sm: 3-index tensor (IN, OUT, auxiliary) - charge neutral with auxiliary index
vac: Index representing trivial vacuum space with charge 0

For spin systems with SU(2): {"S", "vac"}

S: 3-index tensor (IN, OUT, auxiliary) - rank-1 spherical tensor (spin operator) Stores the reduced matrix element split as: data block = sqrt(J(J+1)), Bridge weight = sqrt(2J+1)
vac: Index representing trivial vacuum space with charge 0

For spinless fermion systems: {"F", "Z", "vac"}

F: 3-index tensor (IN, OUT, auxiliary) - annihilation operator, charge neutral
Z: 2-index tensor (IN, OUT) - Jordan-Wigner string, charge neutral
vac: Index representing trivial vacuum space with charge 0

For spinful fermion (Band) systems with U(1)xU(1) or Z2xU(1): {"F_up", "F_dn", "Z", "Sz", "Sp", "Sm", "vac"}

F_up: 3-index tensor (IN, OUT, auxiliary) - spin-up annihilation operator
F_dn: 3-index tensor (IN, OUT, auxiliary) - spin-down annihilation operator
Z: 2-index tensor (IN, OUT) - Jordan-Wigner string
Sz: 2-index tensor (IN, OUT) - spin z-component
Sp: 3-index tensor (IN, OUT, auxiliary) - spin raising operator
Sm: 3-index tensor (IN, OUT, auxiliary) - spin lowering operator
vac: Index representing trivial vacuum space

For spinful fermion (Band) systems with U(1)xSU(2) or Z2xSU(2): {"F", "Z", "S", "vac"}

F: 3-index tensor (IN, OUT, auxiliary) - rank-½ fermionic annihilation operator Stores the reduced matrix element split as: data block = 1.0, Bridge weight = sqrt(2) Full RME: ⟨j'||F||j⟩ = sqrt(2) for all transitions
Z: 2-index tensor (IN, OUT) - Jordan-Wigner string (scalar, rank-0)
S: 3-index tensor (IN, OUT, auxiliary) - rank-1 spin tensor Stores the reduced matrix element split as: data block = sqrt(¾), Bridge weight = sqrt(2) Full RME: ⟨J=½||T^1||J=½⟩ = sqrt(3/2)
vac: Index representing trivial vacuum space

Raises:

Type	Description
`ValueError`	If `preset` or `preserv` are not supported, or if required options are missing

Examples:

>>> # Create spin-1/2 system with U(1) symmetry
>>> Spc, Op = load_space("Spin", "U1", {"J": 0.5})
>>> Spc.dim  # 2 states: m_z = -1/2, +1/2
2
>>> list(Op.keys())
['Sp', 'Sm', 'Sz', 'vac']

>>> # Create spin-1 system
>>> Spc, Op = load_space("Spin", "U1", {"J": 1.0})
>>> Spc.dim  # 3 states: m_z = -1, 0, +1
3

>>> # Create spin-1/2 system with full SU(2) symmetry
>>> Spc, Op = load_space("Spin", "SU2", {"J": 0.5})
>>> Spc.dim       # 1 multiplet (multiplicity space)
1
>>> Spc.num_states  # 2 physical states: m_z = ±1/2
2
>>> list(Op.keys())
['S', 'vac']

>>> # Create spinless fermion system with U(1) symmetry
>>> Spc, Op = load_space("Ferm", "U1")
>>> Spc.dim  # 2 states: |0⟩, |1⟩
2
>>> list(Op.keys())
['F', 'Z', 'vac']

>>> # Create spinful fermion system with U(1)xU(1) symmetry
>>> Spc, Op = load_space("Band", "U1,U1")
>>> Spc.dim  # 4 states: |0⟩, |↑⟩, |↓⟩, |↑↓⟩
4
>>> list(Op.keys())
['F_up', 'F_dn', 'Z', 'Sz', 'Sp', 'Sm', 'vac']

>>> # Create spinful fermion system with U(1)xSU(2) symmetry
>>> Spc, Op = load_space("Band", "U1,SU2")
>>> Spc.dim       # 3 multiplets: |0⟩, {|↑⟩,|↓⟩}, |↑↓⟩
3
>>> Spc.num_states  # 4 physical states
4
>>> list(Op.keys())
['F', 'Z', 'S', 'vac']

Description¶

Provides pre-configured physical spaces and operator sets for common quantum many-body systems, including spin systems, spinless fermions, and spinful fermions. This simplifies the creation of tensor network models for quantum physics applications.

Returns both the physical space index (defining the local Hilbert space) and a dictionary of operators commonly used in that system.

Supported Systems¶

Spin Systems (`preset="Spin"`)¶

Bosonic spin systems with arbitrary spin quantum number.

from nicole import load_space

# Spin-1/2 system with U(1) symmetry (S_z conservation)
Spc, Op = load_space("Spin", "U1", {"J": 0.5})
print(Spc.dim)  # 2 states: |↓⟩, |↑⟩
print(list(Op.keys()))  # ['Sp', 'Sm', 'Sz', 'vac']

# Spin-1 system
Spc, Op = load_space("Spin", "U1", {"J": 1.0})
print(Spc.dim)  # 3 states: |-1⟩, |0⟩, |+1⟩

# Spin-1/2 with full SU(2) symmetry (spin-rotation invariance)
Spc, Op = load_space("Spin", "SU2", {"J": 0.5})
print(Spc.dim)        # 1 multiplet (one doublet sector)
print(Spc.num_states) # 2 physical states
print(list(Op.keys()))  # ['S', 'vac']

Operators for "U1" symmetry:

Sp: Spin raising operator (S+)
Sm: Spin lowering operator (S-)
Sz: Spin z-component operator
vac: Vacuum index (trivial space)

Operators for "SU2" symmetry:

S: Rank-1 spherical tensor (stores the reduced tensor element via the Wigner–Eckart theorem; encodes all three components Sz, S+, S− in one object)
vac: Vacuum index (trivial space)

Spinless Fermion Systems (`preset="Ferm"`)¶

Fermions without spin degrees of freedom.

# Spinless fermions with U(1) symmetry (particle number conservation)
Spc, Op = load_space("Ferm", "U1")
print(Spc.dim)  # 2 states: |0⟩, |1⟩
print(list(Op.keys()))  # ['F', 'Z', 'vac']

Operators returned:

F: Annihilation operator (f)
Z: Jordan-Wigner string operator
vac: Vacuum index

Spinful Fermion Systems (`preset="Band"`)¶

Fermions with spin-up and spin-down degrees of freedom.

# Spinful fermions with U(1)×U(1) symmetry (N_up and N_down conservation)
Spc, Op = load_space("Band", "U1,U1")
print(Spc.dim)  # 4 states: |0⟩, |↑⟩, |↓⟩, |↑↓⟩
print(list(Op.keys()))  # ['F_up', 'F_dn', 'Z', 'Sz', 'Sp', 'Sm', 'vac']

# With Z2×U(1) symmetry (parity and total spin conservation)
Spc, Op = load_space("Band", "Z2,U1")

# With U(1)×SU(2) symmetry (particle number + full spin rotation)
Spc, Op = load_space("Band", "U1,SU2")
print(list(Op.keys()))  # ['F', 'Z', 'S', 'vac']

# With Z2×SU(2) symmetry (parity + full spin rotation)
Spc, Op = load_space("Band", "Z2,SU2")

Operators for "U1,U1" and "Z2,U1" symmetry:

F_up: Spin-up annihilation operator
F_dn: Spin-down annihilation operator
Z: Jordan-Wigner string operator
Sz: Spin z-component
Sp: Spin raising operator
Sm: Spin lowering operator
vac: Vacuum index

Operators for "U1,SU2" and "Z2,SU2" symmetry:

F: Rank-½ fermionic annihilation operator (spherical tensor; reduced tensor element ⟨j'‖F‖j⟩ = √2 for all allowed transitions)
Z: Jordan-Wigner string operator (scalar, rank-0)
S: Rank-1 spin tensor (reduced tensor element; encodes full spin-rotation algebra)
vac: Vacuum index

State Convention

The Abelian ("U1,U1" / "Z2,U1") and SU(2) ("U1,SU2" / "Z2,SU2") presets use different sign conventions:

State	Abelian	SU(2)
\(\vert\!\uparrow\rangle\)	\(c^\dagger_\uparrow \vert 0\rangle\)	\(c^\dagger_\uparrow \vert 0\rangle\)
\(\vert\!\downarrow\rangle\)	\(c^\dagger_\downarrow \vert 0\rangle\)	\(-c^\dagger_\downarrow \vert 0\rangle\)
\(\vert\!\uparrow\downarrow\rangle\)	\(c^\dagger_\uparrow c^\dagger_\downarrow \vert 0\rangle\)	\(-c^\dagger_\uparrow c^\dagger_\downarrow \vert 0\rangle\)

The minus signs in the SU(2) case follow the phase convention of the standard CG basis used by Yuzuha. This difference does not affect physical computations — all expectation values and correlators remain identical.

Symmetry Options¶

`preserv`	Applicable presets	Description
`"U1"`	Spin, Ferm	U(1) charge/magnetization conservation
`"Z2"`	Ferm	Z2 parity conservation
`"SU2"`	Spin	Full SU(2) spin-rotation symmetry
`"U1,U1"`	Band	U(1) particle number + U(1) spin
`"Z2,U1"`	Band	Z2 parity + U(1) spin
`"U1,SU2"`	Band	U(1) particle number + full SU(2) spin
`"Z2,SU2"`	Band	Z2 parity + full SU(2) spin

Notes¶

For spin systems, the "J" option (total spin) is required for all symmetry choices
For U(1) spin systems, charges are 2×m_z (doubled to keep integers)
For SU(2) systems, charges are 2j integers; Spc.num_states gives the total physical Hilbert space dimension
SU(2) operators store reduced tensor elements (Wigner–Eckart theorem); some are 3^rd order tensors with an auxiliary index carrying the spin-channel label
The vac entry is an Index representing the trivial vacuum space (neutral charge, dim=1)
All operators are returned as Tensor objects except vac, which is an Index

load_space¶

load_space ¶

Description¶

Supported Systems¶

Spin Systems (preset="Spin")¶

Spinless Fermion Systems (preset="Ferm")¶

Spinful Fermion Systems (preset="Band")¶

Symmetry Options¶

See Also¶

Notes¶

Spin Systems (`preset="Spin"`)¶

Spinless Fermion Systems (`preset="Ferm"`)¶

Spinful Fermion Systems (`preset="Band"`)¶