AbstractHamiltonians

AbstractHamiltonians

Module for defining and implementing Hamiltonians.

struct ClusterInteraction{K,U}

A single multi-body (cluster) interaction figure on a lattice: one coupling plus the explicit list of the figure's embeddings, each an ordered K-tuple of site indices. The coupling is the energy contributed per fully occupied embedding. Each unordered site set appears exactly once, in canonical (strictly increasing) form, so double counting of symmetric motifs is structurally impossible. Embedding lists are typically produced by enumerate_motif_embeddings under the torus (minimum-image) convention, matching how the pair shells count neighbors.

Only orders K ≥ 3 are represented: on-site and pair terms belong in the wrapped GenericLatticeHamiltonian of a ClusterLatticeHamiltonian.

Note: "cluster" here names an interaction figure of a cluster expansion, not the geometric cluster Monte Carlo moves elsewhere in FreeBird.

Constructor

ClusterInteraction(coupling, embeddings::Vector{NTuple{K,Int}})

Throws ArgumentError on K < 3, a non-finite coupling, an embedding that is not strictly increasing or contains a non-positive index, or a duplicate embedding; warns on an empty embedding list (which contributes exactly zero energy).

struct ClusterLatticeHamiltonian{N,U} <: ClassicalHamiltonian

A lattice Hamiltonian with on-site, pair-shell, and multi-body (cluster) terms: a GenericLatticeHamiltonian{N,U} carrying the on-site energy and the N pair-shell couplings, plus a vector of ClusterInteraction figures of arbitrary orders K ≥ 3. The total energy is the pair part plus, for every figure, the coupling times the number of its fully occupied embeddings.

Sign and unit conventions follow GenericLatticeHamiltonian: positive couplings are repulsive. Published binding-energy parameter sets (e.g. the O-Pd(100) lattice-gas Hamiltonian of Zhang, Blum & Reuter, PRB 75, 235406 (2007), whose optimum expansion carries four pair shells, four trios, and one quattro) map onto FreeBird by negating every parameter.

Evaluated by interacting_energy(lattice, h) for single-component (SLattice) configurations, and therefore usable in every sampler that calls it generically.

Constructor

ClusterLatticeHamiltonian(pair_ham::GenericLatticeHamiltonian{N,U}, clusters)

clusters is a vector of ClusterInteractions whose coupling type matches U; heterogeneous orders K are allowed.

struct GenericLatticeHamiltonian{N,U} <: ClassicalHamiltonian

The GenericLatticeHamiltonian struct represents a generic lattice Hamiltonian. It has an on-site interaction energy and a N-elements vector of nth-neighbor interaction energies. Units of energy U is also specified.

Fields

• on_site_interaction::U: The energy of on-site interactions.
• nth_neighbor_interactions::SVector{N, U}: The energy of nth-neighbor interactions.

Constructors

GenericLatticeHamiltonian(on_site_interaction::Float64, nth_neighbor_interactions::Vector{Float64}, energy_units::Unitful.Units)
GenericLatticeHamiltonian(on_site_interaction::U, nth_neighbor_interactions::Vector{U}) where U

All couplings must be finite; Inf is rejected by the constructor because it stalls nested sampling silently (every ceiling comparison becomes Inf >= Inf).

Hard-core (athermal) lattice models

Nearest-neighbor exclusion models — hard squares on the square lattice, hard hexagons on the triangular lattice — are expressed with a finite repulsive coupling on a lattice built with a single cutoff shell, e.g. GenericLatticeHamiltonian(0.0, [1.0], u"eV") with cutoff_radii=[1.1]. The energy is then J × (number of excluded-neighbor pairs), an integer-leveled ladder whose E = 0 manifold is exactly the hard-core configuration space, and the nested-sampling descent through the violating levels measures the hard-core partition function against the full, unrestricted prior (the (1+z0)^M normalization stays valid). Two numerical windows apply:

• Sampling: choose the NS energy_perturbation δ with eps(E_max) ≪ δ ≪ J, where E_max = J·M·c/2 is the maximal violation energy on M sites with excluded-shell coordination c. Concretely, keep δ / eps(E_max) above ~K² so the K walkers draw distinct tie-breaking values on a plateau: δ = 1e-9 at J = 1 eV is safe through E_max ≈ 10³ eV (hard squares near M ≈ 500, hard hexagons near M ≈ 330); scale δ proportionally for larger lattices.
• Post-processing: evaluate at a temperature low enough that β·J ≥ (ladder depth in nats) + ~40, with the depth n_iters · ln((K + n_cull)/K), while keeping β·δ ≪ 1; every violating level's Boltzmann factor is then an exact zero to double precision, the allowed levels' deviate from 1 only by O(β·δ), and all observables are athermal (functions of the activity z = exp(βμ) alone).

Examples

julia> ham = GenericLatticeHamiltonian(-0.04, [-0.01, -0.0025], u"eV")
GenericLatticeHamiltonian{2,Quantity{Float64, 𝐋² 𝐌 𝐓⁻², Unitful.FreeUnits{(eV,), 𝐋² 𝐌 𝐓⁻², nothing}}}:
    on_site_interaction:      -0.04 eV
    nth_neighbor_interactions: [-0.01, -0.0025] eV


julia> ham = GenericLatticeHamiltonian(-0.04u"eV", [-0.01, -0.0025]*u"eV")
GenericLatticeHamiltonian{2,Quantity{Float64, 𝐋² 𝐌 𝐓⁻², Unitful.FreeUnits{(eV,), 𝐋² 𝐌 𝐓⁻², nothing}}}:
    on_site_interaction:      -0.04 eV
    nth_neighbor_interactions: [-0.01, -0.0025] eV

    struct MLatticeHamiltonian{C,N,U} <: ClassicalHamiltonian

The MLatticeHamiltonian struct represents a multi-component lattice Hamiltonian. It has a matrix of GenericLatticeHamiltonian{N,U}.

Fields

• Hamiltonians::Matrix{GenericLatticeHamiltonian{N,U}}: The matrix of GenericLatticeHamiltonian{N,U}.

Constructors

MLatticeHamiltonian(Hamiltonians::Vector{GenericLatticeHamiltonian{N,U}})

Examples

julia> hams = [GenericLatticeHamiltonian(-0.04, [-0.01, -0.0025], u"eV") for i in 1:4] # full flattened matrix
julia> mlham = MLatticeHamiltonian(hams)
julia> hams = [GenericLatticeHamiltonian(-0.04, [-0.01, -0.0025], u"eV") for i in 1:3] # upper triangular matrix
julia> mlham = MLatticeHamiltonian(2, hams)

struct SiteFieldLatticeHamiltonian{H,U} <: ClassicalHamiltonian

A wrapper Hamiltonian adding a site-resolved on-site energy (a "field") to a lattice Hamiltonian: the total energy is the wrapped base Hamiltonian's energy plus Σ field[i] over every occupied site i. One number per site breaks the site equivalence the base Hamiltonians assume, which is what layered adsorption physics needs: a substrate potential decaying with height, canonically a contact term plus an inverse-cube tail in the multilayer lattice-gas models of de Oliveira and Griffiths [Surf. Sci. 71, 687 (1978)] and Pandit, Schick and Wortis [Phys. Rev. B 26, 5112 (1982)], is expressed as a per-layer profile broadcast over sites with layer_field.

Fields

• base::H: the wrapped Hamiltonian (GenericLatticeHamiltonian, MLatticeHamiltonian, or ClusterLatticeHamiltonian).
• field::Vector{U}: one on-site energy per site, added once per occupied site; U equals the base's coupling type exactly.

Additive contract

The field adds on top of the base's own on-site term: a base with on_site_interaction = ε still contributes ε × (number of occupied adsorption sites) through lattice.adsorptions. The two on-site channels compose additively, so supplying a full per-site field while the base carries a nonzero on-site energy double-counts every occupied adsorption site. When a full field is supplied, zero the base's on-site energy and put the entire on-site physics in the field.

The wrapper subsumes the adsorption mechanism exactly: for a lattice with adsorption mask A = lattice.adsorptions,

GenericLatticeHamiltonian(ε, J)   # ε once per occupied adsorption site
≡ SiteFieldLatticeHamiltonian(GenericLatticeHamiltonian(zero(ε), J), ε .* A)

since the masked field ε .* A carries ε on each adsorption site and an exact zero elsewhere.

Layer-profile recipe

lat = SLattice{SquareLattice}(supercell_dimensions=(4, 4, 3),
                              periodicity=(true, true, false),
                              cutoff_radii=[1.1])
field = layer_field(lat, [-0.27, -0.03375, -0.01] .* u"eV")  # inverse-cube tail
h = SiteFieldLatticeHamiltonian(GenericLatticeHamiltonian(0.0, [-0.01], u"eV"), field)

Constructors

SiteFieldLatticeHamiltonian(base::ClassicalHamiltonian, field::Vector)
SiteFieldLatticeHamiltonian(base::ClassicalHamiltonian, field::Vector{Float64}, energy_units::Unitful.Units)

The three-argument form attaches energy_units to a plain Float64 vector, like the units convenience constructor of GenericLatticeHamiltonian. The field vector is copied.

Throws an ArgumentError when the base is itself a SiteFieldLatticeHamiltonian (compose site fields by adding the vectors, not by nesting wrappers), when the field is empty, when the base's coupling type cannot be determined, when any entry's type differs from the base's coupling type (exact typeof equality: same units and value type, no promotion), or when any entry is non-finite (an Inf makes every nested-sampling ceiling comparison degenerate and the sampler stalls silently; see the hard-core recipe in the GenericLatticeHamiltonian docstring).

The field length is not checked here (no lattice is in scope at construction) but once per run at setup, in the LatticeGasWalkers constructor and the raw-lattice wang_landau/nvt_monte_carlo entry points, where a length differing from the lattice's site count throws.

_coupling_type(hamiltonian)

Internal trait returning the concrete coupling type U of a lattice Hamiltonian (the exact typeof shared by its on-site, pair, and cluster couplings), or nothing for Hamiltonian types that do not declare one. The SiteFieldLatticeHamiltonian constructor uses it to require that every field entry's type equals the base's coupling type (same units and value type; no promotion), mirroring the per-cluster coupling check of ClusterLatticeHamiltonian. New ClassicalHamiltonian types opt in by adding a method.

supports_site_deltas(hamiltonian::ClassicalHamiltonian) -> Bool

Opt-in trait: whether an exact O(z) single-site occupancy-flip energy delta (site_flip_delta in EnergyEval) is available for the Hamiltonian type.

The false fallback is a contract, not a failure: consumers fall back to full recomputation instead of silently mis-evaluating. ClusterLatticeHamiltonian deliberately stays false (an exact cluster delta needs precomputed site-to-embedding incidence lists that do not exist yet), and the site-field wrapper delegates to its base. New ClassicalHamiltonian types opt in by adding a method alongside their site_flip_delta method.