Reference

DoubleKagome(t::Float64, n1::Int, n2::Int, PBC::Tuple{Bool,Bool}; antiPBC=(false,false), trunc=Inf)

Construct a double unit cell Kagome lattice with 6 sites per unit cell.

Unlike a single unit cell Kagome lattice (which has 3 sites per unit cell forming one triangle), the DoubleKagome lattice contains 6 sites per unit cell arranged in two triangular sublattices. This structure is useful for studying systems with enlarged unit cells or specific magnetic ordering patterns that require the doubled cell geometry.

Arguments

• t::Float64: Parameter defining the equilateral triangle side length (lattice constant = 2t)
• n1::Int: Number of unit cell repetitions in the a1 direction (must be even)
• n2::Int: Number of unit cell repetitions in the a2 direction
• PBC::Tuple{Bool,Bool}: Periodic boundary conditions in (a1, a2) directions
• antiPBC::Tuple{Bool,Bool}: Antiperiodic boundary conditions (default: (false, false))
• trunc::Float64: Truncation parameter (default: Inf, unused in current implementation)

Returns

• DoubleKagome: Lattice structure with n1 * n2 * 3 total sites

Notes

• The constraint n1 % 2 == 0 ensures proper tiling of the double unit cell
• Total number of sites is n1 * n2 * 3 (though each unit cell has 6 sites, n1 counts double-sized cells)
• Actual number of unit cells is (n1 ÷ 2) * n2, each containing 6 sites
• Lattice vectors: a1 = [4t, 0], a2 = [t, √3*t]
• Each unit cell contains 6 sites arranged in two triangular motifs

Example

# Create a 4×3 DoubleKagome lattice with periodic boundaries
lat = DoubleKagome(1.0, 4, 3, (true, true))
# Total sites: 4 * 3 * 3 = 36 sites (2 unit cells × 3 repetitions × 6 sites per unit cell)

Hamiltonian

Complete specification of the spinon mean-field Hamiltonian for quantum Monte Carlo simulations.

This structure contains all information needed for Variational Monte Carlo calculations of quantum spin liquid properties:

Fields

• N_up::Int: Number of up-spin spinons (determines spin sector)
• N_down::Int: Number of down-spin spinons
• U_up::Matrix{ComplexF64}: Occupied up-spinon orbitals (columns are eigenvectors)
• U_down::Matrix{ComplexF64}: Occupied down-spinon orbitals
• H_mat::Matrix{ComplexF64}: Single-particle spinon Hamiltonian matrix
• nn::AbstractArray: List of nearest-neighbor bonds for efficient iteration

Usage in Monte Carlo

• Uup, Udown define the reference state (filled Fermi sea)
• H_mat provides the hopping amplitudes for Monte Carlo updates
• nn specifies which bonds to consider in interaction terms

Physical Interpretation

• Represents a quantum spin liquid state where spins are fractionalized
• Correlations arise from quantum fluctuations around the mean-field state

Hamiltonian(N_up, N_down, lat; link_in=pi_link_in, link_inter=pi_link_inter, B=0.0)

Construct a complete Hamiltonian structure for quantum Monte Carlo simulations.

This is the main constructor that builds everything needed for SSE Monte Carlo:

1. Constructs the single-particle spinon Hamiltonian matrix
2. Diagonalizes it to find the occupied orbitals
3. Extracts the nearest-neighbor bond structure
4. Packages everything for efficient Monte Carlo usage

Arguments

• N_up::Int, N_down::Int: Number of up/down spinons (determines magnetic sector)
• lat::AbstractLattice: Lattice structure (typically DoubleKagome)
• link_in: Intra-cell hopping dictionary (default: π-flux pattern)
• link_inter: Inter-cell hopping dictionary (default: π-flux pattern)
• B::Float64: Magnetic field strength for Peierls phases (default: 0.0)

Returns

• Hamiltonian: Complete structure ready for Monte Carlo simulations

Physics Notes

• The choice of Nup, Ndown determines the spin sector being studied
• For spin-1/2 systems: Nup + Ndown = number of original spins
• Different (Nup, Ndown) can access different quantum phases

MC <: AbstractMC

Monte Carlo simulation state for quantum spin systems on the Kagome lattice.

Fields

• Ham::Hamiltonian: The Hamiltonian describing the physical system
• kappa_up::Vector{Int}: Configuration vector for up-spin electrons
• kappa_down::Vector{Int}: Configuration vector for down-spin electrons
• W_up::AbstractMatrix: One-particle Green's function matrix for up-spin electrons
• W_down::AbstractMatrix: One-particle Green's function matrix for down-spin electrons
• W_up_col_cache::AbstractVector: Cache vector for column operations on W_up
• W_up_row_cache::AbstractVector: Cache vector for row operations on W_up
• W_down_col_cache::AbstractVector: Cache vector for column operations on W_down
• W_down_row_cache::AbstractVector: Cache vector for row operations on W_down

MC(params::AbstractDict)

Create a Monte Carlo object from a dictionary of parameters.

This is the user-facing, high-level constructor that initializes the Monte Carlo simulation state with appropriate dimensions and default configurations.

Arguments

• params::AbstractDict: Dictionary containing simulation parameters

Required Parameters

• :n1::Int: Number of unit cells in x-direction
• :n2::Int: Number of unit cells in y-direction
• :PBC::Tuple{Bool,2}: Periodic boundary conditions
• :N_up::Int: Number of up-spin electrons
• :N_down::Int: Number of down-spin electrons

Optional Parameters

• :antiPBC::Tuple{Bool,2}: Anti-periodic boundary conditions (default: (false, false))
• :lattice::Type: Lattice type (default: DoubleKagome)
• :B::Float64: Magnetic field strength (default: 0.0)
• :link_in::Function: Intra-cell linking function (default: pilinkin)
• :link_inter::Function: Inter-cell linking function (default: pilinkinter)

Returns

• MC: Initialized Monte Carlo state object

MC(Ham, kappa_up, kappa_down, W_up, W_down)

Create a Monte Carlo object from its core components.

This constructor automatically creates the necessary cache arrays for efficient matrix updates. It's primarily used for internal logic and testing purposes.

Arguments

• Ham::Hamiltonian: The Hamiltonian describing the physical system
• kappa_up::Vector{Int}: Initial up-spin configuration vector
• kappa_down::Vector{Int}: Initial down-spin configuration vector
• W_up::AbstractMatrix: Initial one-particle Green's function for up-spin
• W_down::AbstractMatrix: Initial one-particle Green's function for down-spin

Returns

• MC: Monte Carlo state object with initialized cache arrays

Note

The cache arrays enable zero-allocation updates of the Green's function matrices using rank-1 update operations.

Carlo.init!(mc::MC, ctx::MCContext, params::AbstractDict)

Initialize the Monte Carlo object for Carlo.jl framework integration.

This function sets up the Monte Carlo simulation by finding an initial non-singular configuration using QR-based initialization.

Arguments

• mc::MC: Monte Carlo state object
• ctx::MCContext: Carlo.jl context object
• params::AbstractDict: Simulation parameters dictionary

Parameters Used

• :n1::Int: Number of unit cells in x-direction
• :n2::Int: Number of unit cells in y-direction
• :N_up::Int: Number of up-spin electrons

Note

This function integrates with the Carlo.jl framework and is called automatically during simulation initialization to prepare the Monte Carlo state.

@inline function Carlo.measure!(mc::MC, ctx::MCContext)

Measures observables during the simulation and collects data.

This function is called periodically during the simulation to measure physical observables like local energy and collect them for postprocessing.

Arguments

• mc::MC: Monte Carlo state object
• ctx::MCContext: Carlo.jl context object

Measured Quantities

• :OL: Local energy estimator getOL(mc, mc.kappa_up, mc.kappa_down)

Note

Measurements are taken periodically (every n_occupied sweeps) to reduce correlation between samples and improve measurement efficiency.

Carlo.read_checkpoint!(mc::MC, in::HDF5.Group)

Restore Monte Carlo state from saved checkpoint for simulation continuation.

Purpose: Loads previously saved spin configurations to resume a simulation from a specific state or initialize postprocessing analysis.

Arguments

• mc::MC: Monte Carlo object to restore (modified in-place)
• in::HDF5.Group: Input HDF5 group containing checkpoint data

Restored Data

• kappa_up: Up-spin configuration vector
• kappa_down: Down-spin configuration vector

Usage Contexts

1. Simulation resumption: Continue interrupted long simulations
2. Postprocessing initialization: Start analysis from specific configurations
3. Reproducibility: Restore exact simulation states

Side Effects

• Modifies mc.kappa_up and mc.kappa_down in-place
• Overwrites current Monte Carlo configuration completely

Notes

• Called automatically by Carlo.jl when resuming from checkpoints
• Essential for maintaining simulation continuity
• Enables reproducible analysis workflows

Carlo.register_evaluables(::Type{MC}, eval::Evaluator, params::AbstractDict)

Register postprocessing evaluators for final analysis after Monte Carlo simulation.

IMPORTANT: This is purely for postprocessing - these evaluators are executed at the end of the simulation or during merge operations to compute final observables from the collected raw measurements. They do NOT affect the Monte Carlo dynamics.

This function defines how to compute physical observables from the raw measured data (:OL values) that was collected during the simulation via Carlo.measure!().

Arguments

• ::Type{MC}: Monte Carlo type dispatch
• eval::Evaluator: Carlo.jl evaluator for postprocessing computations
• params::AbstractDict: Simulation parameters containing lattice dimensions

Registered Evaluables

• :energy: Computes the energy per site from local energy measurements
  • Formula: $energy = ⟨OL⟩ / ns$, where ns = total number of sites
  • Input: Raw :OL measurements collected during simulation
  • Output: Normalized energy per site for final results

Usage in Carlo.jl Workflow

1. During simulation: Carlo.measure!() collects raw :OL data
2. After simulation: This function defines how to postprocess the data
3. Final analysis: Carlo.jl automatically applies these evaluators to compute final results
4. Merge operations: Used when combining data from multiple simulation runs

Physics Notes

• OL represents the local energy estimator $⟨x|H|ψ_G⟩/⟨x|ψ_G⟩$
• Normalization by ns gives energy per site (intensive quantity)
• Essential for comparing results across different system sizes

Performance Notes

• Called only once during setup, not during simulation loops
• Actual evaluation happens in postprocessing phase
• Minimal computational overhead during Monte Carlo sampling

Carlo.sweep!(mc::MC, ctx::MCContext) -> Nothing

Perform one Monte Carlo sweep for Mott state simulation.

This function implements a two-spin swap update where electrons can exchange positions between different spin states at occupied neighboring sites.

Arguments

• mc::MC: Monte Carlo state object
• ctx::MCContext: Carlo.jl context object

Algorithm

1. Calculate number of valid spin exchange moves Zμ
2. Use Metropolis acceptance criterion based on move probability
3. Select random neighbor bond for potential exchange
4. Calculate acceptance ratio using Green's function matrix elements
5. Update configurations if move is accepted
6. Periodically re-evaluate W matrices to maintain numerical stability

Note

The W matrices are re-evaluated periodically (every n_occupied sweeps) to override numerical instability from repeated rank-1 updates. If re-evaluation fails due to singular matrices, a warning is issued and simulation continues.

Carlo.write_checkpoint(mc::MC, out::HDF5.Group)

Save Monte Carlo state for resuming simulations or postprocessing analysis.

Purpose: Serializes the current spin configuration to an HDF5 file for later use in simulation continuation or postprocessing workflows.

Arguments

• mc::MC: Monte Carlo state to save
• out::HDF5.Group: Output HDF5 group for writing checkpoint data

Saved Data

• kappa_up: Current up-spin configuration vector
• kappa_down: Current down-spin configuration vector

Usage Contexts

1. Simulation checkpointing: Save state for restarting long simulations
2. Postprocessing: Preserve final configurations for additional analysis
3. Data archival: Store representative configurations for later study

Notes

• Called automatically by Carlo.jl during simulation checkpointing
• Essential for resuming interrupted simulations
• Enables analysis of specific configurations post-simulation

Hmat(
    lat::DoubleKagome;
    link_in = pi_link_in,
    link_inter = pi_link_inter,
    B = 0.0,
) -> Matrix{ComplexF64}

Constructs the Spinon Hamiltonian matrix for a DoubleKagome lattice.

This function calculates the hopping terms within and between unit cells, incorporating a Peierls phase to account for a magnetic field B. The resulting matrix represents the Hamiltonian of the system.

Arguments

• lat::DoubleKagome: The lattice structure for which to construct the Hamiltonian.
• link_in: A dictionary defining in-cell hopping terms. Defaults to pi_link_in.
• link_inter: A dictionary defining inter-cell hopping terms. Defaults to pi_link_inter.
• B::Float64: The magnetic field strength, used to calculate the Peierls phase. Defaults to 0.0.

Returns

• Matrix{ComplexF64}: The Hamiltonian matrix for the given lattice and parameters.

Sz(i::Int, kappa_up::Vector{Int}, kappa_down::Vector{Int}) -> Float64

Calculate the z-component of spin at site i in the spinon representation.

In the spinon formulation, the original spin operators are written as:

• S^zi = 1/2 (f^†{i↑} f{i↑} - f^†{i↓} f_{i↓})
• S^+i = f^†{i↑} f{i↓}, S^-i = f^†{i↓} f{i↑}

where f{iσ} are spinon annihilation operators. The constraint is exactly one spinon per site: n{i↑} + n_{i↓} = 1 (no double occupancy or empty sites).

Arguments

• i::Int: Site index (1-indexed)
• kappa_up::Vector{Int}: Up-spinon configuration (0 = empty, nonzero = occupied)
• kappa_down::Vector{Int}: Down-spinon configuration

Returns

• Float64: +0.5 for up spin, -0.5 for down spin

Exceptions

• ArgumentError: If site is doubly occupied or empty (violates spinon constraint)
• BoundsError: If i is outside valid range [1, length(kappa_up)]
• DimensionMismatch: If kappaup and kappadown have different lengths

Physics Notes

• This enforces the constraint that each site has exactly one spinon
• Configurations violating the constraint (empty or doubly occupied) are unphysical
• Used in Monte Carlo to measure local magnetization and Ising interactions
• The spinon constraint is fundamental to the validity of the spin liquid state

Performance Notes

• Marked @inline for performance in Monte Carlo loops
• Uses @boundscheck for optional bounds checking
• Calls is_occupied() helper function for spinon occupancy detection

SzInteraction!(xprime, kappa_up, kappa_down, i, j)

Compute the Ising (S^z S^z) interaction term for the Heisenberg Hamiltonian.

For the Heisenberg model H = J ∑{<i,j>} (S^+i S^-j + S^-i S^+j + S^zi S^zj), this function handles the S^zi S^z_j term, which is diagonal in the spinon basis.

The Ising term doesn't change the spinon configuration, so it contributes to the identity component of the operator expansion (stored with key (-1,-1,-1,-1)).

Arguments

• xprime::Dict: Dictionary storing operator expansion coefficients
• kappa_up::Vector{Int}: Current up-spinon configuration
• kappa_down::Vector{Int}: Current down-spinon configuration
• i::Int, j::Int: Sites for the interaction

Side Effects

• Modifies xprime[(-1,-1,-1,-1)] by adding Sz(i) * Sz(j)

Physics Notes

• This is the "easy-axis" part of the Heisenberg interaction
• Diagonal in the occupation basis, doesn't create/destroy spinons
• Combined with spinInteraction!() to give the full Heisenberg model

Z(nn::AbstractArray, kappa_up::AbstractVector, kappa_down::AbstractVector) -> Int

Count the number of valid spin exchange moves between neighboring sites.

This function calculates the number of neighboring site pairs where one site is occupied by an up-spin electron and the other by a down-spin electron, indicating potential spin exchange moves.

Arguments

• nn::AbstractArray: Array of neighbor bonds (site pairs)
• kappa_up::AbstractVector: Up-spin configuration vector
• kappa_down::AbstractVector: Down-spin configuration vector

Returns

• Int: Number of valid spin exchange move opportunities

apply_boundary_conditions!(tunneling, lat, s1, s2, link_inter, B)

Apply boundary conditions and magnetic field effects to inter-cell hopping terms.

This function modifies the tunneling matrix by adding all possible hopping paths between sites s1 and s2, considering:

1. Periodic/antiperiodic boundary conditions
2. Peierls phase factors from magnetic field B
3. π-flux pattern encoded in link_inter dictionary

Arguments

• tunneling::AbstractMatrix: Hopping matrix to be modified (in-place)
• lat::AbstractLattice: Lattice structure with boundary conditions
• s1::Int, s2::Int: Source and target site indices
• link_inter::Dict: Inter-cell hopping amplitudes with (label1, label2, dx, dy) keys
• B::Float64: Magnetic field strength for Peierls phase calculation

Physics Details

• Peierls phase: exp(iB/2 * (x1+x2)(y2-y1)) accounts for vector potential A = (0, Bx)
• Each boundary crossing can contribute ±1 phase factor from antiperiodic BC

find_initial_configuration!(mc::MC, ns::Int, N_up::Int)

Find a non-singular initial configuration for Monte Carlo simulation.

This function uses a deterministic QR-based method to initialize particle configurations and compute the initial Green's function matrices.

Arguments

• mc::MC: Monte Carlo state object (modified in-place)
• ns::Int: Total number of sites in the lattice
• N_up::Int: Number of up-spin electrons

Algorithm

1. Initialize configurations using QR decomposition with column pivoting
2. Construct tilde_U matrices from the initialized configurations
3. Solve linear systems to compute Green's function matrices
4. Handle singular matrix exceptions with informative error messages

Throws

• ErrorException: If QR-based configuration produces singular matrices, indicating potential rank deficiency in the Hamiltonian

getOL(mc::AbstractMC, kappa_up, kappa_down) -> Float64

Compute the local energy estimator for quantum Monte Carlo.

Calculates the observable OL = ⟨x|H|ψG⟩/⟨x|ψ_G⟩, which provides an unbiased estimator of the ground state energy in the Stochastic Series Expansion method.

In the spinon mean-field framework:

• |ψ_G⟩ is the Slater Determinant spinon state (Gutzwiller projected)
• |x⟩ = |κup⟩ ⊗ |κdown⟩ is a particular spinon configuration
• H is the original Heisenberg Hamiltonian (not the mean-field one!)

The ratio gives the local contribution to the energy from configuration |x⟩.

Arguments

• mc::AbstractMC: Monte Carlo state containing Wup, Wdown matrices
• kappa_up::Vector{Int}: Current up-spinon configuration
• kappa_down::Vector{Int}: Current down-spinon configuration

Returns

• Float64: Local energy contribution from this configuration

Algorithm

1. Compute H|x⟩ using getxprime() to get all reachable configurations
2. For diagonal terms: directly add the Ising contributions
3. For off-diagonal terms: weight by the wavefunction amplitude ratios Wup, Wdown
4. Sum all contributions to get the local energy

Physics Notes

• This is the "local energy" in variational Monte Carlo terminology
• Fluctuations in O_L reflect the quality of the trial wavefunction
• Used to measure energy and other observables in quantum spin liquids
• The Hamiltonian H must be the original physical one, not the mean-field approximation

Performance Notes

• Critical function called in every Monte Carlo step
• Bounds checking disabled with @inbounds for performance
• Uses efficient iteration over pairs() for dictionary access

get_boundary_shifts(lat::AbstractLattice, s1::Int, s2::Int) -> Vector{Tuple{Int,Int,Float64}}

Calculate all possible lattice vector shifts between sites s1 and s2 under periodic/antiperiodic boundary conditions.

For quantum spin systems with twisted boundary conditions:

• Periodic BC: ψ(r + L) = ψ(r)
• Antiperiodic BC: ψ(r + L) = -ψ(r)

Returns all equivalent separations considering lattice periodicity, with associated phase factors.

Arguments

• lat::AbstractLattice: Lattice with boundary condition specifications
• s1::Int, s2::Int: Site indices for the hopping term

Returns

• Vector{Tuple{Int,Int,Float64}}: List of (dx, dy, sign) tuples where:
  • dx, dy: Lattice vector coefficients
  • sign: Phase factor (±1) from antiperiodic boundary crossings

get_nn(H_mat::AbstractMatrix) -> Vector{Tuple{Int,Int}}

Extract nearest-neighbor bond list from the Hamiltonian matrix.

Finds all non-zero off-diagonal elements in the upper triangular part of H_mat, which correspond to hopping terms between connected sites. Essential for efficient Monte Carlo sampling since we only need to consider active bonds.

Arguments

• H_mat::AbstractMatrix: Hamiltonian matrix (typically hermitian)

Returns

• Vector{Tuple{Int,Int}}: List of (i,j) pairs where i < j and H_mat[i,j] ≠ 0

Notes

• Only upper triangular elements to avoid double-counting

get_site_coord(lat::AbstractLattice, s::Int) -> Vector{Float64}

Calculate the real-space coordinate of site s in the lattice.

Combines the unit cell position with the intra-cell site offset to give the absolute position in real space. Essential for calculating Peierls phases and analyzing spatial correlations.

Arguments

• lat::AbstractLattice: Lattice structure
• s::Int: Site index (1-indexed)

Returns

• Vector{Float64}: [x, y] coordinate in real space

getxprime(Ham::Hamiltonian, kappa_up, kappa_down) -> Dict{NTuple{4,Int}, Float64}

Compute the action of the Heisenberg Hamiltonian on a spinon configuration.

This is the core function for Stochastic Series Expansion (SSE) Monte Carlo. Given a spinon configuration |κup, κdown⟩, it computes all configurations |κ'up, κ'down⟩ that can be reached by applying H, along with their amplitudes.

The result is H|κ⟩ = Σ_κ' xprime[κ'] |κ'⟩, where xprime encodes the expansion.

Arguments

• Ham::Hamiltonian: Complete Hamiltonian specification
• kappa_up::Vector{Int}: Current up-spinon configuration
• kappa_down::Vector{Int}: Current down-spinon configuration

Returns

• Dict{NTuple{4,Int}, Float64}: Dictionary mapping configurations to amplitudes
  • Key (-1,-1,-1,-1): Diagonal contribution (Ising terms)
  • Key (i,lup,j,ldown): Off-diagonal contribution from spin-flip at sites i,j

Algorithm

1. Iterate over all nearest-neighbor bonds in Ham.nn
2. For each bond, compute Ising (S^z S^z) and transverse (S^+ S^- + S^- S^+) terms
3. Accumulate results in xprime dictionary

Usage in Monte Carlo

• Called during each Monte Carlo update to propose new configurations
• The amplitudes determine acceptance probabilities for updates
• Essential for sampling the quantum mechanical evolution

Physics Notes

• |x⟩ must be a valid Mott state (one spinon per site)
• The Hamiltonian H is the original Heisenberg model, not the mean-field one
• Combines both diagonal (Ising) and off-diagonal (transverse) contributions

init_conf_qr!(mc::MC, ns::Int, N_up::Int)

Initialize particle configurations using QR decomposition with column pivoting.

Reference: Quantum Monte Carlo Approaches for Correlated Systems (Becca and Sorella, 2017) P130

As system size increases, $⟨Φ|x⟩$ becomes exponentially small compared to system size, inversely proportional to the dimension of the Hilbert space.

The smallness of initial $⟨Φ|x⟩$ leads to numerical instability in the first computation of the W matrices, but does not affect Markov chain sampling since we always calculate $⟨Φ|x'⟩/⟨Φ|x⟩$, which should not be numerically unstable.

This method selects sites that maximize linear independence from the U matrices to ensure non-singular tilde_U matrices and avoid random trial-and-error initialization.

Arguments

• mc::MC: Monte Carlo state object (modified in-place)
• ns::Int: Total number of sites in the lattice
• N_up::Int: Number of up-spin electrons

Algorithm

1. Perform QR decomposition on mc.Ham.U_up' to select N_up most linearly independent rows (sites) for up-spin electrons
2. Use remaining unoccupied sites and perform QR decomposition on corresponding subset of mc.Ham.U_down' to select N_down sites for down-spin electrons

Note

This deterministic approach produces non-singular tilde_U matrices for stable Green's function initialization.

is_occupied(kappa::Vector{Int}, l::Int) -> Bool

Check if site l is occupied in the configuration vector.

Arguments

• kappa::Vector{Int}: Configuration vector where non-zero values indicate occupation
• l::Int: Site index to check

Returns

• Bool: true if site l is occupied (kappa[l] ≠ 0), false otherwise

Throws

• BoundsError: if l is outside the valid range [1, length(kappa)]

orbitals(H_mat::Matrix{ComplexF64}, N_up::Int, N_down::Int) -> (Matrix{ComplexF64}, Matrix{ComplexF64})

Compute the occupied spinon orbitals for the quantum spin liquid ground state.

In the spinon mean-field theory:

1. Spins are fractionalized into spinons (fermionic particles carrying spin-1/2)
2. The Hamiltonian H_mat describes spinon hopping on the lattice
3. Ground state is a filled Fermi sea of the lowest-energy spinon states
4. Separate up and down spinon sectors (SU(2) symmetry)

Arguments

• H_mat::Matrix{ComplexF64}: Single-particle spinon Hamiltonian matrix
• N_up::Int: Number of up-spin spinons to fill
• N_down::Int: Number of down-spin spinons to fill

Returns

• (U_up, U_down): Matrices whose columns are the occupied spinon orbitals
  • U_up: N_up lowest eigenvectors for up spinons
  • U_down: N_down lowest eigenvectors for down spinons

Physics Notes

• The spinon filling typically corresponds to the original spin-1/2 density
• For a spin-1/2 system: Nup + Ndown = total number of spins
• The specific choice of Nup, Ndown determines the magnetic properties

reevaluateW!(mc::MC)

Recalculate the one-particle Green's function matrices Wup and Wdown.

This function reconstructs the Green's functions from the current spin configuration by solving the linear systems involving the tilde_U matrices.

Arguments

• mc::MC: Monte Carlo state object

Algorithm

1. Construct tilde_U matrices from current kappa configurations
2. Solve linear systems: $tilde_U_up \ I$ and $tilde_U_down \ I$
3. Compute Green's functions: $W = U * (tilde_U \ I)$

Note

$U \ I$ is numerically more stable than computing the inverse directly.

The Green's function matrices W represent the one-particle propagators $⟨x|cᵢ⁺cⱼ|ψ⟩/⟨x|ψ⟩$ for the current configuration.

Periodic re-evaluation is necessary to override numerical instability that accumulates from repeated rank-1 updates to the Green's function matrices.

spinInteraction!(xprime, kappa_up, kappa_down, i, j)

Compute the transverse (spin-flip) part of the Heisenberg interaction.

For the Heisenberg Hamiltonian H = J ∑{<i,j>} (S^+i S^-j + S^-i S^+j + S^zi S^zj), this function handles the transverse terms S^+i S^-j + S^-i S^+_j.

In the spinon representation:

• S^+i S^-j = f^†{i↑} f{i↓} f^†{j↓} f{j↑} (flips spins at both sites)
• S^-i S^+j = f^†{i↓} f{i↑} f^†{j↑} f{j↓} (flips spins at both sites)

These terms change the spinon configuration and are the source of quantum fluctuations.

Arguments

• xprime::Dict: Dictionary storing new configurations and their amplitudes
• kappa_up::Vector{Int}: Current up-spinon configuration
• kappa_down::Vector{Int}: Current down-spinon configuration
• i::Int, j::Int: Sites for the spin-flip interaction

Side Effects

• Adds entries to xprime for each allowed spin-flip process
• Key format: (newupsite, olduporbital, newdownsite, olddownorbital)
• Amplitude: -1/2 for each allowed process (negative from Heisenberg coupling)

Physics Notes

• Only processes that respect the constraint (one spinon per site) are allowed
• Creates quantum entanglement between different spinon configurations
• Essential for accessing quantum spin liquid physics beyond mean-field

tilde_U(U::AbstractMatrix, kappa::Vector{Int})

Construct the tilde_U matrix by selecting and rearranging rows from U.

The tilde_U matrix is formed by selecting the rows of U corresponding to occupied sites (where kappa[l] ≠ 0) and placing them in the order specified by kappa.

Arguments

• U::AbstractMatrix: Source matrix of size (n × m) where n is number of sites
• kappa::Vector{Int}: Configuration vector where non-zero values indicate occupied sites

Returns

• A matrix of size (m × m) with same element type as U

Throws

• DimensionMismatch: If length(kappa) ≠ number of rows in U
• ArgumentError: If kappa does not contain exactly m non-zero entries
• BoundsError: If any non-zero kappa value is out of bounds

Note

This matrix is used in the construction of the one-particle Green's function W.

unitcell_coord(lat::AbstractLattice, s::Int) -> Vector{Float64}

Compute the real-space coordinate of the unit cell containing site s.

For DoubleKagome lattice:

• Sites 1-6 belong to unit cell 1, sites 7-12 to unit cell 2, etc.
• Each unit cell has 6 sites arranged in two triangular motifs
• Returns the coordinate of the unit cell origin in real space

Arguments

• lat::AbstractLattice: The lattice structure
• s::Int: Site index (1-indexed)

Returns

• Vector{Float64}: Real-space coordinate of the unit cell origin

unitcell_diff(lat, unitcell_coord1, unitcell_coord2) -> (Int, Int)

Calculate the lattice vector difference between two unit cells in terms of basis vectors (a1, a2).

This function solves the linear system: unitcellcoord1 - unitcellcoord2 = dxa1 + dya2 to find integer coefficients (dx, dy) representing the separation in lattice units.

Arguments

• lat::AbstractLattice: The lattice structure containing basis vectors a1, a2
• unitcell_coord1::Vector{Float64}: Real-space coordinate of first unit cell
• unitcell_coord2::Vector{Float64}: Real-space coordinate of second unit cell

Returns

• (dx::Int, dy::Int): Lattice vector coefficients such that coord1 - coord2 = dxa1 + dya2

update_W!(W::AbstractMatrix, l::Int, K::Int, col_cache::AbstractVector, row_cache::AbstractVector)

Perform a rank-1 update on the Green's function matrix using Sherman-Morrison formula.

Arguments

• W::AbstractMatrix: Green's function matrix to update
• l::Int: Column index for the update
• K::Int: Row index for the update
• col_cache::AbstractVector: Pre-allocated cache for column operations
• row_cache::AbstractVector: Pre-allocated cache for row operations

Algorithm

Implements the Sherman-Morrison update: $W'_{I,j} = W_{I,j} - W_{I,l} / W_{K,l} * (W_{K,j} - δ_{l,j})$

This represents a rank-1 update to the matrix inverse that maintains the Green's function relationship after a single-particle move.

update_W_matrices!(mc::MC; K_up::Int, K_down::Int, l_up::Int, l_down::Int)

Update the one-particle Green's function matrices using rank-1 updates.

This function performs simultaneous updates of both Wup and Wdown matrices using the Sherman-Morrison formula for efficient matrix inversion updates.

Arguments

• mc::MC: Monte Carlo state object
• K_up::Int: Row index for up-spin matrix update
• K_down::Int: Row index for down-spin matrix update
• l_up::Int: Column index for up-spin matrix update
• l_down::Int: Column index for down-spin matrix update

Algorithm

Performs rank-1 updates: W' = W - (W[:,l] * (W[K,:] - δ_{l,:})') / W[K,l] for both spin components using pre-allocated cache arrays.

update_configurations!(mc, flag::Int, i::Int, site::Int, l_up::Int, l_down::Int)

Update both Green's function matrices and configuration vectors for a spin exchange move.

This function performs the complete update for a spin exchange between sites i and site, including both the Green's function matrices (Wup, Wdown) and the configuration vectors (kappaup, kappadown).

Arguments

• mc: Monte Carlo state object
• flag::Int: Move type indicator (1 or 2)
• i::Int: First site index
• site::Int: Second site index
• l_up::Int: Up-spin label to move
• l_down::Int: Down-spin label to move

Move Types

• flag = 1: Move up-spin from site i to site, down-spin from site to i
• flag = 2: Move up-spin from site to i, down-spin from site i to site