Library documentation

Bollmark{T<:AbstractFloat} <: AbstractHamiltonianTerm

Bollmark term used in a perturbative treatment, parameterizing effective interchain/interladder processes. Ref: Bollmark et al., Phys. Rev. X 13, 011039 (2023)

Fields

• alpha::Vector{T} Self-consistent parameters (e.g. mean-field amplitudes) associated with the first Bollmark term.
• beta::Vector{T} Self-consistent parameters (e.g. mean-field amplitudes) associated with the second Bollmark term.

Notes

• alpha and beta are not fixed couplings: they should be iterated to convergence together with the ground state (or other target state) to satisfy the chosen self-consistency condition.

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/shape 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 = ()).

Validation notes

• CalcConfig throws ArgumentError for invalid user inputs, including duplicate term types, incompatible term dimensions, and invalid filling/cell-width compatibility checks.

HolsteinTerm{T<:AbstractFloat} <: AbstractHamiltonianTerm

Represents Holstein-type electron–phonon coupling terms w b⁺ᵢ bᵢ and gₐ(nᵢₐ-<n>)(b⁺ⱼ + bⱼ) in the Hamiltonian. The coupling may be local (i=j) or exponentially decaying with distance exp(-rᵢⱼ/ξ). Couplings smaller than threshold are neglected.

Fields

• w::Vector{T} Local phonon frequencies (one per mode).
• g::Matrix{T} Electron–phonon coupling strengths, size (bands, nmodes).
• max_b::Int64 Maximum number of phonons allowed per mode (Fock-space truncation).
• mean_ne::T Mean number of electrons per site in the bare Hubbard model, used to normal-order the density operator.
• xi::T Exponential decay length for non-local coupling (0 means strictly local).
• threshold::T Minimum coupling magnitude retained in the Hamiltonian; smaller values are dropped for efficiency.

Constructor

HolsteinTerm(w, g, max_b, mean_ne; xi=zero(T), threshold=zero(T))

All arguments are positional except xi and threshold, which are keyword arguments with default 0. Pass xi > 0 together with a positive threshold to enable exponentially decaying non-local coupling.

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.

SpinMeanField{T<:AbstractFloat} <: AbstractHamiltonianTerm

Mean-field coupling term representing inter-chain spin interactions.

Fields

• J::Matrix{T}: Inter-chain coupling matrix of size NxN, where J[i,j] couples site i in the current chain to site j in neighboring chains.
• spins::Union{Vector{T}, Matrix{T}}: Expected spin expectation values from neighboring chains.
  • Collinear: A Vector{T} of length N containing z-components.
  • Noncollinear: A Matrix{T} of size Nx3 containing (x, y, z) components.

Constructors

• SpinMeanField(J, spins): Creates the term with specified coupling and initial spins.

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, 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.
• filling : Union{Nothing, Rational{Int}}
  • Optional particle filling specified as a rational number P//Q (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 == U1Irrep and filling === nothing, filling defaults to 1//1.

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.

S_min(T::Type{<:Number}, P::Type{<:Sector}, S::Type{<:Sector})

Lowering operator S-. Hermitian conjugate of S+.

S_plus(T::Type{<:Number}, P::Type{<:Sector}, S::Type{<:Sector})

Raising operator S+. Throws ArgumentError if spin symmetry S is U1Irrep or SU2Irrep.

Sx(T::Type{<:Number}, P::Type{<:Sector}, S::Type{<:Sector})

Spin operator Sx = (S+ + S-)/2.

Sy(T::Type{<:Number}, P::Type{<:Sector}, S::Type{<:Sector})

Spin operator Sy = (S+ - S-)/2i.

Sz(T::Type{<:Number}, 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::Type{<:Number}, 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::Type{<:Number}, 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::Type{<:Number}, 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::Type{<:Number}, 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::Type{<:Number}, 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::Type{<:Number}, 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, calc::CalcConfig)

Compute the staggered magnetization in an InfiniteMPS.

compute_bandgap(gs, calc; resolution=5)

Compute the single-particle (charge) band gap from particle–addition and particle–removal excitations over a uniform momentum grid.

Arguments

• gs::Dict{String,Any}: Ground-state data as produced by compute_groundstate, containing the state, Hamiltonian, and environments.
• calc::CalcConfig: Calculation configuration. The particle symmetry must be U1Irrep.

Keyword Arguments

• resolution::Int=5: Number of momentum points in the uniform grid between 0 and π (inclusive).

Returns

• (gap, kmin): The minimum value of E_add(k) + E_remove(k) over the sampled momenta and the corresponding momentum k.

compute_chargegap(gs, calc; resolution=5)

Compute the charge gap from two-particle addition excitations on a uniform momentum grid.

Arguments

• gs::Dict{String,Any}: Ground-state data as produced by compute_groundstate, containing the state, Hamiltonian, and environments.
• calc::CalcConfig: Calculation configuration.

Keyword Arguments

• resolution::Int=5: Number of momentum points in the uniform grid between 0 and π (inclusive).

Returns

• (gap, kmin): The minimum charge excitation energy over the sampled momenta and the corresponding momentum k.

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, FiniteMPS}=nothing,
                    maxiter::Int=1000,
                    max_init_dim::Int=50,
                    verbosity::Int=0,
                    finite_mps::Bool=false)

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

Keyword Arguments

• svalue::Float64=2.0: Exponent controlling the Schmidt value truncation cutoff: tensors with Schmidt values below 10^(-svalue) are discarded.
• tol::Float64=1e-8: Requested convergence tolerance for the iterative solver (VUMPS or IDMRG2). Important: tol is automatically floored to schmidtcut / 10 (i.e. 10^(-(svalue+1))), so values tighter than that threshold have no effect. In practice, set svalue first and let tol follow.
• init_state::Union{Nothing, InfiniteMPS, FiniteMPS}=nothing: Optional initial MPS. If finite_mps=false, expects an InfiniteMPS; if true, a FiniteMPS.
• 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.
• finite_mps::Bool=false: If true, performs a finite-size DMRG calculation with periodic boundary conditions; otherwise uses infinite algorithms (VUMPS/IDMRG).

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.

compute_pairing_energy(gs, calc; resolution=5)

Compute the pairing energy from single-particle and two-particle addition excitations on a uniform momentum grid.

Arguments

• gs::Dict{String,Any}: Ground-state data as produced by compute_groundstate, containing the state, Hamiltonian, and environments.
• calc::CalcConfig: Calculation configuration. The particle symmetry calc.symmetries.particle_symmetry must be U1Irrep.

Keyword Arguments

• resolution::Int=5: Number of momentum points in the uniform grid between 0 and π (inclusive).

Returns

• (gap, kmin): The minimum value of 2E_add(k) - E_double(k) over the sampled momenta and the corresponding momentum k.

compute_spingap(gs, calc; resolution=5)

Compute the spin gap from spin-flip excitations above the ground state over a uniform momentum grid.

Arguments

• gs::Dict{String,Any}: Ground-state data as produced by compute_groundstate, containing the state, Hamiltonian, and environments.
• calc::CalcConfig: Calculation configuration. The spin symmetry must not be Trivial.

Keyword Arguments

• resolution::Int=5: Number of momentum points in the uniform grid between 0 and π (inclusive).

Returns

• (gap, kmin): The minimum spin excitation energy over the sampled momenta and the corresponding momentum k.

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

Return the one-body onsite pair creation operator Δ† = c†↑ c†↓. It maps the empty state |0⟩ to the doubly occupied state |↑↓⟩.

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

Return the one-body onsite pair annihilation operator Δ = c↓ c↑. It maps the doubly occupied state |↑↓⟩ to the empty state |0⟩.

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

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

density_correlations(ψ::InfiniteMPS, calc::CalcConfig; R::Int=15, thr::Float64=1e-10)

Compute connected density–density correlations

C(r) = ⟨n₀ n_r⟩ − ⟨n⟩²

for distances r = 1:R in the infinite MPS ψ.

The function prints the correlation values and stops early if the magnitude falls below thr, which helps avoid unnecessary evaluations once correlations have effectively decayed.

The site spacing accounts for interleaved boson modes and electronic bands defined in calc. The resulting correlations can later be used to estimate the charge Luttinger parameter Kρ from the small-q behavior of the density structure factor.

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

Compute the electron density.

• Returns the average density over the full chain.

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

Compute the electron density.

• Returns the density per orbital and per unit-cell position.

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

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

dict_tag(d::Dict)

Returns a canonical string tag from a hopping/interaction dictionary for saving.

dim_state(ψ::Union{InfiniteMPS,FiniteMPS})

Determine the bond dimensions in an 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.

get_alpha(ψ::InfiniteMPS, calc::CalcConfig, ty::T, tz::T, Ep::T) where {T<:AbstractFloat}

Compute α-coefficients from pair correlators.

Here:

• ty is the hopping between neighboring ladders within the same plane,
• tz is the hopping to the ladders below and above the ladder under consideration.

For a 1-band model, returns [a0, a01], where:

• a0 is the onsite contribution from ⟨c↓ c↑⟩,
• a01 is the nearest-neighbor contribution from ⟨c↑₁ c↓₂⟩.

For a 2-band model, returns [a0, a1, a00, a01, a10, a11].

Only onsite and nearest-neighbor terms are included.

get_beta(ψ::InfiniteMPS, calc::CalcConfig, ty::T, tz::T, Ep::T) where {T<:AbstractFloat}

Compute β-coefficients from density and hopping correlators.

Here:

• ty is the hopping between neighboring ladders within the same plane,
• tz is the hopping to the ladders below and above the ladder under consideration.

For a 1-band model, returns [b0, b01], where:

• b0 is the onsite contribution from ⟨n⟩,
• b01 is the nearest-neighbor contribution from ⟨c†₁ c₂⟩.

For a 2-band model, returns [b00, b01, b10, b11].

Only onsite and nearest-neighbor terms are included.

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::Rational{Int}=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 specified as a rational P//Q (particles per sites). The default is 1//1 (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::Type{<:Number}, particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector})

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

number_pair(T::Type{<:Number}, 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.