Models

qsun_hamiltonian(
    L_loc::Integer,
    L_grain::Integer,
    g0::Real,
    α::Real;
    γ::Real=1,
    w::Real=0.5,
    hz::Real=1,
    ζ::Real=0.2,
    S::Real=0.5,
    rng::AbstractRNG=Random.default_rng(),
    use_U1::Bool=false,
    S_z::Real=0.0,
    use_sparse::Bool=true,
)

Construct a Quantum Sun Hamiltonian through the public Polfed.Models namespace.

By default this builds the full Hilbert-space Quantum Sun model. With use_U1=true, it instead builds the U(1)-symmetric version in a fixed total magnetization sector.

Positional Arguments

• L_loc::Integer: Number of outer localized spins ("rays") coupled to the ergodic grain.
• L_grain::Integer: Number of spins inside the ergodic grain.
• g0::Real: Overall prefactor multiplying the grain-to-ray couplings.
• α::Real: Decay parameter controlling the long-range coupling profile α^{u_j}. Smaller α means faster decay away from the grain.

Keyword Arguments

• γ::Real=1: Overall energy scale of the random grain Hamiltonian.
• w::Real=0.5: Half-width of the uniform disorder window for the local S^z fields. The fields are sampled from [hz - w, hz + w].
• hz::Real=1: Center of the disorder window for the local S^z fields.
• ζ::Real=0.2: Randomness in the effective distance exponent u_j = (j - 1) + η_j, where η_j ∈ [-ζ, ζ].
• S::Real=0.5: On-site spin. It must be integer or half-integer.
• rng::AbstractRNG=Random.default_rng(): Random-number generator used for disorder, couplings, and the grain matrix.
• use_U1::Bool=false: If false, build the conventional Quantum Sun Hamiltonian in the full Hilbert space. If true, build the U(1)-symmetric version.
• S_z::Real=0.0: Total magnetization sector used when use_U1=true.
• use_sparse::Bool=true: If true, return a sparse matrix. If false, return a dense matrix.

Returns

• SparseMatrixCSC{Float64,Int} when use_sparse=true.
• Matrix{Float64} when use_sparse=false.

Notes

• This is the public constructor you should use in examples and workflows: using Polfed.Models: qsun_hamiltonian.
• The use_U1=true path reduces the Hilbert-space dimension by keeping only states in the requested total-S_z sector.
• This is a forwarding wrapper around the internal QSun implementation, exposed alongside xxz_hamiltonian and j1j2_hamiltonian.

xxz_hamiltonian(
    L::Integer,
    Lup::Integer,
    J::Real,
    Δ::Real,
    W::Real;
    boundary::Symbol=:periodic,
    field::Real=0.0,
    fields=nothing,
    rng::AbstractRNG=Random.default_rng(),
    use_sparse::Bool=true,
)

Construct a spin-1/2 XXZ-chain Hamiltonian,

\[H = J \sum_{i=1}^{L} \left( S_i^x S_{i+1}^x + S_i^y S_{i+1}^y + \Delta S_i^z S_{i+1}^z \right) + \sum_i h_i S_i^z.\]

where the constructor works in a fixed spin-1/2 magnetization sector.

Positional Arguments

• L::Integer: Chain length.
• Lup::Integer: Number of spin-up sites. This fixes the magnetization sector through $S_z = Lup - L/2$.
• J::Real: Nearest-neighbor exchange scale.
• Δ::Real: XXZ anisotropy parameter.
• W::Real: Disorder width for longitudinal fields.

Keyword Arguments

• boundary::Symbol=:periodic: Boundary condition. Supported values are :periodic and :open.
• field::Real=0.0: Center of the disorder window. When random fields are generated internally, they are sampled from [field - W, field + W].
• fields=nothing: Optional explicit field realization. If given, it should be an AbstractVector{<:Real} of length L, and it is used directly instead of sampling from W.
• rng::AbstractRNG=Random.default_rng(): Random-number generator used when the field realization is sampled internally.
• use_sparse::Bool=true: If true, return a sparse matrix. If false, return a dense matrix.

Returns

• SparseMatrixCSC{Float64,Int} when use_sparse=true.
• Matrix{Float64} when use_sparse=false.

Notes

• This constructor currently targets spin-1/2 chains only.
• With boundary=:periodic, site indices wrap around exactly as written in the defining sum.
• With boundary=:open, boundary-crossing terms are omitted.

j1j2_hamiltonian(
    L::Integer,
    Lup::Integer,
    J1::Real,
    J2::Real,
    Δ1::Real,
    Δ2::Real,
    W::Real;
    boundary::Symbol=:periodic,
    field::Real=0.0,
    fields=nothing,
    rng::AbstractRNG=Random.default_rng(),
    use_sparse::Bool=true,
)

Construct a spin-1/2 J1-J2 XXZ-chain Hamiltonian with nearest-neighbor and next-nearest-neighbor couplings,

\[H = J_1 \sum_{i=1}^{L} \left( S_i^x S_{i+1}^x + S_i^y S_{i+1}^y + \Delta_1 S_i^z S_{i+1}^z \right) + J_2 \sum_{i=1}^{L} \left( S_i^x S_{i+2}^x + S_i^y S_{i+2}^y + \Delta_2 S_i^z S_{i+2}^z \right) + \sum_i h_i S_i^z.\]

where both nearest-neighbor and next-nearest-neighbor terms are included in a fixed spin-1/2 magnetization sector.

Positional Arguments

• L::Integer: Chain length.
• Lup::Integer: Number of spin-up sites. This fixes the magnetization sector through $S_z = Lup - L/2$.
• J1::Real: Nearest-neighbor exchange scale.
• J2::Real: Next-nearest-neighbor exchange scale.
• Δ1::Real: Nearest-neighbor Ising anisotropy.
• Δ2::Real: Next-nearest-neighbor Ising anisotropy.
• W::Real: Disorder width for longitudinal fields.

Keyword Arguments

• boundary::Symbol=:periodic: Boundary condition. Supported values are :periodic and :open.
• field::Real=0.0: Center of the disorder window. When random fields are generated internally, they are sampled from [field - W, field + W].
• fields=nothing: Optional explicit field realization. If given, it should be an AbstractVector{<:Real} of length L, and it is used directly instead of sampling from W.
• rng::AbstractRNG=Random.default_rng(): Random-number generator used when the field realization is sampled internally.
• use_sparse::Bool=true: If true, return a sparse matrix. If false, return a dense matrix.

Returns

• SparseMatrixCSC{Float64,Int} when use_sparse=true.
• Matrix{Float64} when use_sparse=false.

Notes

• This constructor currently targets spin-1/2 chains only.
• With boundary=:periodic, site indices wrap around exactly as in the sums above.
• With boundary=:open, boundary-crossing terms are omitted.
• The disorder conventions match xxz_hamiltonian.