Library documentation

CalcConfig{T<:AbstractFloat, HamiltonianTerms<:Tuple{Vararg{AbstractHamiltonianTerm}}}

Holds all configuration information for a lattice or many-body calculation, including symmetries, the base Hubbard Hamiltonian, and optional additional Hamiltonian terms.

Fields

• symmetries::SymmetryConfig Contains particle-number and spin symmetries, unit-cell geometry, and optional filling.
• hubbard::HubbardParams{T} Base electronic Hamiltonian parameters (bands, hopping, and two-body interactions).
• terms::HamiltonianTerms Tuple of additional Hamiltonian terms (subtypes of AbstractHamiltonianTerm).

Constructors

• CalcConfig(symmetries, hubbard, terms) — creates a configuration with specified symmetries, Hubbard parameters, and extra terms. Duplicate term types are checked, and band consistency is enforced.
• CalcConfig(symmetries, hubbard, term) — convenience constructor with one extra term (terms = (term,)).
• CalcConfig(symmetries, hubbard) — convenience constructor with no extra terms (terms = ()).

HolsteinTerm{T<:AbstractFloat} <: AbstractHamiltonianTerm

Represents a Holstein-type electron–phonon coupling terms w b⁺ᵢ bᵢ andgₐ(nᵢₐ-<n>)(b⁺ᵢ + bᵢ) in the Hamiltonian.

Fields

• w::T Local phonon frequency.
• g::Vector{T} Electron–phonon coupling strength per Hubbard band.
• max_b::Int64 Maximum number of phonons allowed per site.
• mean_ne::T Mean number of electrons in Hubbard model.

Constructors

• HolsteinTerm(w, g, max_b, mean_ne) — creates the term with specified phonon frequency, coupling, and phonon truncation.

HubbardParams{T<:AbstractFloat}

Represents the standard Hubbard Hamiltonian parameters for a lattice or multi-orbital system.

Fields

• bands::Int64 Number of electronic orbitals or bands per unit cell. Must be positive.
• t::Dict{NTuple{2, Int64}, T} Hopping amplitudes. Convention: t[(i,i)] = μ_i is the on-site potential, t[(i,j)] for i ≠ j is the hopping amplitude from site i to j.
• U::Dict{NTuple{4, Int64}, T} Two-body electronic interaction tensor. Entries U[(i,j,k,l)] correspond to the operator c⁺i c⁺j ck cl. Zero entries can be omitted.

Constructors

• HubbardParams(bands, t::Dict, U::Dict) — standard constructor specifying bands, hopping, and interactions.
• HubbardParams(t::Vector, U::Vector) — single-band convenience constructor from vectors.
• HubbardParams(t::Matrix, U::Matrix) — multi-band constructor from matrices; automatically checks dimensions and Hermiticity.

MagneticField{T<:AbstractFloat} <: AbstractHamiltonianTerm

Represents a magnetic field term in the Hamiltonian B * Sᶻ.

Fields

• B::T Magnetic field strength.

Constructors

• MagneticField(B) — creates the term with specified magnetic field strength.

StaggeredField{T<:AbstractFloat} <: AbstractHamiltonianTerm

Represents a staggered magnetic field term in the Hamiltonian. For multi-band models, the staggering is applied between equivalent orbitals.

Fields

• J::T Inter-chain Hund's coupling.
• Ms::T Initial staggered magnetization.

Constructors

• StaggeredField(J, Ms) — creates the term with specified coupling and initial magnetization.

SymmetryConfig(particle_symmetry, spin_symmetry; cell_width=1, filling=nothing)

Represents the symmetry configuration of a lattice system, including particle and spin symmetries, unit cell width, and optional filling information.

Fields

• particle_symmetry : Union{Type{Trivial}, Type{U1Irrep}, Type{SU2Irrep}}
  • The symmetry type for particle number. Use Trivial for no symmetry, U1Irrep for U(1) symmetry, or SU2Irrep for SU(2) symmetry.
• spin_symmetry : Union{Type{Trivial}, Type{U1Irrep}, Type{SU2Irrep}}
  • The symmetry type for spin degrees of freedom.
• cell_width : Int64
  • Number of sites in the unit cell. Must be a positive integer. Defaults to 1.
• filling : Union{Nothing, Tuple{Int64, Int64}}
  • Optional particle filling specified as a fraction (numerator, denominator). Only allowed if particle_symmetry is U1Irrep.
  Otherwise the filling is determined by the chemical potential.

Constructor Behavior

• If filling is provided, the constructor checks that particle_symmetry == U1Irrep.
• cell_width must be positive.
• If particle_symmetry is U1Irrep and filling is specified, the constructor ensures that cell_width is a multiple of filling[2] * (mod(filling[1], 2) + 1) to accommodate the specified filling.

ThreeBodyTerm{T<:AbstractFloat} <: AbstractHamiltonianTerm

Represents three-body interactions in the Hamiltonian.

Fields

• bands::Int64 Number of bands (orbitals) in the system.
• V::Dict{NTuple{6,Int}, T} Three-body interaction amplitudes c⁺_i c⁺_j c⁺_k c_l c_m c_n. Zero entries can be omitted.

Constructors

• ThreeBodyTerm(V::Vector{T}) — single-band constructor from a vector.
• ThreeBodyTerm(V::Matrix{T}) — multi-band constructor from a matrix.

Sz(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the one-body spin operator Sᶻ = 1/2 (n↑ - n↓).

b_min(elt::Type{<:Number}, ps::Type{<:Sector}, ss::Type{<:Sector}, cutoff::Int64)

The truncated bosonic annihilation operator, with a maximum of cutoff bosons per site.

b_plus(elt::Type{<:Number}, ps::Type{<:Sector}, ss::Type{<:Sector}, cutoff::Int64)

The truncated bosonic creation operator, with a maximum of cutoff bosons per site.

boson_space(ps::Type{<:Sector}, ss::Type{<:Sector}, cutoff::Int64; kwargs...)

The bosonic physical space compatible with a Hubbard space with particle symmetry ps and spin symmetry ss, truncated at a maximum of cutoff bosons per site.

c_minplus(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the two-body operator that annihilates a particle at the first site and creates a particle at the second. This is the sum of c_minplus_up and c_minplus_down.

c_minplus_down(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the Hermitian conjugate of c_plusmin_down, i.e. $(c†_{1,↓}, c_{2,↓})† = -c_{1,↓}, c†_{2,↓}$ (note the extra minus sign). It annihilates a spin-down electron at the first site and creates a spin-down electron at the second.

c_minplus_up(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the Hermitian conjugate of c_plusmin_up, i.e. $(c†_{1,↑}, c_{2,↑})† = -c_{1,↑}, c†_{2,↑}$ (note the extra minus sign). It annihilates a spin-up electron at the first site and creates a spin-up electron at the second.

c_plusmin(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the two-body operator that creates a particle at the first site and annihilates a particle at the second. This is the sum of c_plusmin_up and c_plusmin_down.

c_plusmin_down(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the two-body operator $c†_{1,↓}, c_{2,↓}$ that creates a spin-down electron at the first site and annihilates a spin-down electron at the second.

c_plusmin_up(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the two-body operator $c†_{1,↑}, c_{2,↑}$ that creates a spin-up electron at the first site and annihilates a spin-up electron at the second.

calc_ms(ψ::InfiniteMPS, symm::SymmetryConfig)

Compute the staggered magnetization in an InfiniteMPS.

compute_domainwall(groundstate_dict, momenta, charges; nums=1, shift=1, solver=Arnoldi(...))

Compute domain-wall excitations between a ground state and a spatially shifted version of itself.

Arguments

• groundstate_dict::Dict{String,Any}: A dictionary produced by compute_groundstate, containing "groundstate", "ham", and "environments".
• momenta::Union{Float64,Vector{Float64}}: A collection of momentum values (in units of lattice sites) at which domain-wall excitations are evaluated.
• charges::Vector{Float64}: Target quantum numbers defining the excitation sector (one value per symmetry).
• nums::Int64=1: Number of excitations to compute per momentum.
• shift::Int64=1: The number of lattice sites by which to shift the reference ground state to form the domain wall.
• solver: The eigensolver used for diagonalization (default is Arnoldi(; krylovdim=30, tol=1e-6, eager=true)).

Returns

A dictionary with the following keys:

• "Es": Eigenenergies of the domain-wall excitations.
• "qps": Domain-wall quasiparticle ansatz states.
• "momenta": The input momentum values.

Notes

This function constructs the second “shifted” ground state and its environments automatically using circshift and environments. It then computes excitations between the two MPS states within the specified symmetry sector.

compute_excitations(groundstate_dict, momenta, charges; nums=1, solver=Arnoldi(...))

Compute the low-lying quasiparticle excitations above a given ground state.

Arguments

• groundstate_dict::Dict{String,Any}: A dictionary produced by compute_groundstate, containing the keys "groundstate", "ham", and "environments".
• momenta::Union{Float64,Vector{Float64}}: A collection of momentum values (in units of lattice sites) at which excitations are evaluated.
• charges::Vector{Float64}: Target quantum numbers defining the excitation sector (one value per symmetry).
• nums::Int64=1: Number of excitations to compute per momentum.
• solver: The eigensolver used for diagonalization (default is Arnoldi(; krylovdim=30, tol=1e-6, eager=true)).

Returns

A dictionary with the following keys:

• "Es": Eigenenergies of the excitations.
• "qps": Quasiparticle ansatz states.
• "momenta": The input momentum values.

compute_groundstate(calc::CalcConfig;
                    svalue::Float64=2.0,
                    tol::Float64=1e-8,
                    init_state::Union{Nothing, InfiniteMPS}=nothing,
                    maxiter::Int=1000,
                    max_init_dim::Int=50,
                    verbosity::Int=0)

Compute the ground state of the Hamiltonian defined by the CalcConfig calc.

Keyword Arguments

• svalue::Float64=2.0: Exponent used to define the truncation cutoff as 10^(-svalue) for Schmidt value truncation.
• tol::Float64=1e-8: Convergence tolerance for iterative solvers (used by VUMPS or IDMRG2).
• init_state::Union{Nothing, InfiniteMPS}=nothing: Optional initial infinite MPS. If not provided, a random symmetry-consistent MPS.
• maxiter::Int=1000: Maximum number of iterations for ground state optimization.
• max_init_dim::Int=50: Maximum bond dimension for the initial MPS construction.
• verbosity::Int=0: Controls the level of printed output from the solver.

Returns

A Dict with the following entries:

• "groundstate" → optimized infinite MPS representing the ground state.
• "environments" → left and right environment tensors.
• "ham" → Hamiltonian MPO used in the optimization.
• "error" → final convergence error.

density_b(ψ::InfiniteMPS, calc::CalcConfig)

Compute the number of bosons per site in the unit cell.

density_e(ψ::InfiniteMPS, calc::CalcConfig)

Compute the number of electrons per site in the unit cell.

density_spin(ψ::InfiniteMPS, symm::CalcConfig)

Compute the electron spin density per site in the unit cell.

dim_state(ψ::InfiniteMPS)

Determine the bond dimensions in an infinite MPS.

find_chemical_potential(calc::CalcConfig, 
                        filling::Float64;
                        mu_lower_init::Float64=0.0,
                        mu_upper_init::Float64=1.0,
                        svalue::Float64=2.0,
                        tol_filling::Float64=1e-8, 
                        maxiter::Int64=25,
                        verbosity::Int64=0)

Find the chemical potential μ that yields the desired filling in the ground state.

hamiltonian(calc::CalcConfig)

Constructs the many-body Hamiltonian for a system defined by configuration calc.

Notes

• Lattice sites are represented using an InfiniteChain of length cell_width * bands.
• The resulting MPO can be used directly for DMRG, VUMPS, or other tensor network calculations.

hubbard_space(particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector}; filling::Tuple{Int64, Int64}=(1,1))

Return the local hilbert space for a Hubbard-type model with the given particle and spin symmetries. The possible symmetries are Trivial, U1Irrep, and SU2Irrep, for both particle number and spin. When using U1Irrep particle symmetry, the filling can be adjusted to P particles per Q sites by passing the keyword filling=(P,Q). The default is (1,1), i.e., half-filling.

load_computation(path_to_file::String)

Load the output dictionary of e.g. compute_groundstate stored as a .jld2 file.

load_state(path::String) -> InfiniteMPS

Load an InfiniteMPS object from a directory of saved .jld2 tensor files.

Arguments

• path::String: Path to the directory containing the saved MPS tensor files (e.g., state1.jld2, state2.jld2, ...).

Description

This function reconstructs an InfiniteMPS object previously saved with save_state. It reads all .jld2 files in the specified directory, converts each stored Dict back into a TensorMap, and combines them into a periodic array before wrapping the result in an InfiniteMPS object.

Returns

• InfiniteMPS: The reconstructed infinite matrix product state.

number_b(elt::Type{<:Number}, ps::Type{<:Sector}, ss::Type{<:Sector}, cutoff::Int64)

The truncated bosonic number operator, with a maximum of cutoff bosons per site.

number_down(particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the one-body operator that counts the number of spin-down electrons.

number_e(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the one-body operator that counts the number of particles.

number_pair(T, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the one-body operator that counts the number of doubly occupied sites.

number_up(particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

Return the one-body operator that counts the number of spin-up electrons.

save_computation(d::Dict{String, Any}, path::String, file_name::String)

Save the output dictionary of e.g. compute_groundstate as a .jld2 file at the specified path.

save_state(ψ::InfiniteMPS, path::String, name::String)

Save the tensors of an InfiniteMPS object to disk as individual .jld2 files.

Arguments

• ψ::InfiniteMPS: The infinite matrix product state (MPS) whose tensors will be saved.
• path::String: The base directory where the state folder will be created.
• name::String: The name of the subdirectory under path where the tensors will be stored.

Description

This function creates a subdirectory joinpath(path, name) and saves each tensor ψ.AL[i] as a .jld2 file named state<i>.jld2 inside it. Each tensor is converted to a Dict before saving for serialization compatibility. The function prints a message after each tensor is successfully saved. This approach may be useful for storing large MPS objects.