EnergyEval

EnergyEval

Module for evaluating energy-related quantities for a system.

_check_shell_counts(lattice_neighbors, n_coupled::Int)

Throw an ArgumentError when a Hamiltonian couples more neighbor shells than the lattice's neighbor list provides. Called from the energy kernels, so it is a single integer comparison in the common case.

cluster_energy(occupations::Vector{Bool}, c::ClusterInteraction{K,U})

Energy contribution of one cluster figure: the coupling times the number of its embeddings whose K sites are all occupied. The per-figure function barrier keeps the inner loop type-stable across the heterogeneous cluster orders of a ClusterLatticeHamiltonian. Bounds checks stay on: an embedding referencing a site beyond the occupation vector must raise a BoundsError rather than read memory (the liveset constructor validates this once up front).

frozen_energy(at::AbstractSystem, cps::CompositeParameterSets{C,P}, list_num_par::Vector{Int}, frozen::Vector{Bool})

Calculate the energy of the frozen particles in the system using a multi-component potential (CompositeParameterSets). I.e., the components interact with each other using different parameters. The energy is calculated by summing the pairwise interactions between the frozen particles. Since the frozen particles do not move, the energy is typically only calculated once for a given system.

Arguments

• at::AbstractSystem: The system for which the energy is calculated.
• cps::CompositeParameterSets{C,P}: The composite potential parameters.
• list_num_par::Vector{Int}: The number of particles in each component.
• frozen::Vector{Bool}: A vector indicating whether each component is frozen.

Returns

• energy: The energy of the frozen particles in the system.

frozen_energy(at::AbstractSystem, pot::SingleComponentPotential{S}, list_num_par::Vector{Int}, frozen::Vector{Bool}) where {S}

Calculate the energy of the frozen particles in the system using a single-component potential. I.e., the components interact with each other using the same parameters. The energy is calculated by summing the pairwise interactions between the frozen particles. Since the frozen particles do not move, the energy is typically only calculated once for a given system.

Arguments

• at::AbstractSystem: The system for which the energy is calculated.
• pot::SingleComponentPotential{S}: The single-component potential.
• list_num_par::Vector{Int}: The number of particles in each component.
• frozen::Vector{Bool}: A vector indicating whether each component is frozen.

Returns

• energy: The energy of the frozen particles in the system.

inter_component_energy(at1::AbstractSystem, at2::AbstractSystem, pot::SingleComponentPotential{Pairwise})

Compute the energy between two components of a system using a specified pairwise potential.

Arguments

• at1::AbstractSystem: The first component of the system.
• at2::AbstractSystem: The second component of the system.
• pot::SingleComponentPotential{Pairwise}: The potential used to compute the energy.

Returns

• energy: The energy between the two components.

inter_component_energy(lattice1::Vector{Bool}, lattice2::Vector{Bool}, lattice_neighbors::Vector{Vector{Vector{Int64}}}, h::GenericLatticeHamiltonian{N,U})

Compute the interaction energy between two lattice configurations using the Hamiltonian parameters.

Arguments

• lattice1::Vector{Bool}: The first lattice configuration.
• lattice2::Vector{Bool}: The second lattice configuration.
• lattice_neighbors::Vector{Vector{Vector{Int64}}}: The lattice neighbor list.
• h::GenericLatticeHamiltonian{N,U}: The generic lattice Hamiltonian parameters.

Returns

• e_interaction::U: The interaction energy between the two lattice configurations.

Throws an ArgumentError on the same shell-count mismatch as lattice_interaction_energy.

interacting_energy(system::AbstractSystem, calc::ASECalculator)

Evaluate total potential energy (eV) of system using the wrapped ASE calculator.

interacting_energy(at::AbstractSystem, pot::SingleComponentPotential{S}, list_num_par::Vector{Int}, frozen::Vector{Bool})

Calculate the energy from interactions between free-free and free-frozen particles using a single-component potential. I.e., the components interact with each other using the same parameters. The energy is calculated by summing the pairwise interactions between the free particles.

Arguments

• at::AbstractSystem: The system for which the energy is calculated.
• pot::SingleComponentPotential{S}: The single-component potential.
• list_num_par::Vector{Int}: The number of particles in each component.
• frozen::Vector{Bool}: A vector indicating whether each component is frozen.

Returns

• energy: The energy from interactions between particles.

interacting_energy(at::AbstractSystem, 
                        pot::CompositeParameterSets{C,GuptaParameters},
                        list_num_par::Vector{Int}
                        ) where C

Calculate the energy from interactions between particles using the Gupta potential for a multi-component system.

interacting_energy(at::AbstractSystem, cps::CompositeParameterSets{C,P}, list_num_par::Vector{Int}, frozen::Vector{Bool}, surface::AbstractSystem)

Calculate the energy from interactions between free-free and free-frozen particles using a multi-component potential (CompositeParameterSets). The energy is calculated by summing the pairwise interactions between the free particles and the surface.

Arguments

• at::AbstractSystem: The system for which the energy is calculated.
• cps::CompositeParameterSets{C,P}: The composite potential parameters.
• list_num_par::Vector{Int}: The number of particles in each component.
• frozen::Vector{Bool}: A vector indicating whether each component is frozen.
• surface::AbstractSystem: An optional surface system to consider in the energy calculation. See LJSurfaceWalkers.

Returns

• energy: The energy from interactions between particles and the surface.

interacting_energy(at::AbstractSystem, cps::CompositeParameterSets{C,P}, list_num_par::Vector{Int}, frozen::Vector{Bool})

Calculate the energy from interactions between free-free and free-frozen particles using a multi-component potential (CompositeParameterSets). The energy is calculated by summing the pairwise interactions between the free particles.

Arguments

• at::AbstractSystem: The system for which the energy is calculated.
• cps::CompositeParameterSets{C,P}: The composite potential parameters.
• list_num_par::Vector{Int}: The number of particles in each component.
• frozen::Vector{Bool}: A vector indicating whether each component is frozen.

Returns

• energy: The energy from interactions between particles.

interacting_energy(at::AbstractSystem, pot::SingleComponentPotential{S})

Calculate the energy from interactions between particles using the a single-component potential. The energy is calculated by summing the pairwise interactions between the free particles.

Arguments

• at::AbstractSystem: The system for which the energy is calculated.
• pot::SingleComponentPotential{S}: The single-component potential.

Returns

• energy: The energy from interactions between particles.

interacting_energy(lattice::SLattice, h::SiteFieldLatticeHamiltonian{H,U})

Total energy under a site-field wrapper: the wrapped base Hamiltonian's energy, evaluated exactly as if the base were passed directly (including its on_site_interaction × occupied-adsorption-sites term), plus the occupation-masked field sum of site_field_energy. Single-component (SLattice) configurations only.

interacting_energy(lattice::MLattice{C,G}, h::MLatticeHamiltonian{C,N,U})

Compute the interaction energy of a multi-component lattice configuration using the Hamiltonian parameters.

Arguments

• lattice::MLattice{C,G}: The multi-component lattice configuration.
• h::MLatticeHamiltonian{C,N,U}: The multi-component lattice Hamiltonian parameters.

Returns

• e_interaction::Float64: The interaction energy of the lattice configuration.

interacting_energy(lattice::SLattice, h::ClusterLatticeHamiltonian{N,U})

Total energy under a multi-body lattice Hamiltonian: the wrapped pair part (on-site + N pair shells, evaluated exactly as for a bare GenericLatticeHamiltonian) plus every cluster figure's contribution. Single-component (SLattice) configurations only.

interacting_energy(lattice::SLattice, h::GenericLatticeHamiltonian{N})

Compute the interaction energy of a lattice configuration using the Hamiltonian parameters.

Arguments

• lattice::SLattice: The lattice configuration.
• h::GenericLatticeHamiltonian{N,U}: The generic lattice Hamiltonian parameters.

Returns

• e_interaction::Float64: The interaction energy of the lattice configuration.

interacting_gradient(at::AbstractSystem, pot::SingleComponentPotential{Pairwise},
                     list_num_par::Vector{Int}, frozen::Vector{Bool})

The per-particle gradient of the interacting energy, ∇ᵢU, as a vector of SVector{3} in eV/Å, over the same pair split as the matching interacting_energy method: free-free and free-frozen pairs contribute, frozen-frozen pairs are skipped, and frozen particles carry exactly zero entries (they are never displaced; they still exert forces on free particles). O(N²) serial accumulation through pbc_dist-consistent minimum-image displacements; a collective move consumes the full gradient, so there is no single-site variant to prefer. Empty and single-particle systems short-circuit to zero entries.

intra_component_energy(at::AbstractSystem, pot::GuptaParameters)

Calculate the energy from interactions between particles using the Gupta potential for a single component.

intra_component_energy(at::AbstractSystem, pot::SingleComponentPotential{Pairwise})

Compute the energy within a component of a system using a specified pairwise potential.

Arguments

• at::AbstractSystem: The component of the system.
• pot::SingleComponentPotential{Pairwise}: The potential used to compute the energy.

Returns

• energy: The energy within the component.

lattice_interaction_energy(lattice_occupations::Vector{Bool}, lattice_neighbors::Vector{Vector{Vector{Int64}}}, h::GenericLatticeHamiltonian{N,U})

Compute the interaction energy of a lattice configuration using the Hamiltonian parameters.

Arguments

• lattice_occupations::Vector{Bool}: The lattice occupation configuration.
• lattice_neighbors::Vector{Vector{Vector{Int64}}}: The lattice neighbor list.
• h::GenericLatticeHamiltonian{N,U}: The generic lattice Hamiltonian parameters.

Returns

• e_interaction::U: The interaction energy of the lattice configuration.

Throws an ArgumentError when the Hamiltonian couples more neighbor shells than the lattice's neighbor list provides (N > length(cutoff_radii)), which would otherwise surface as a raw BoundsError from the innermost loop. The converse mismatch (fewer coupled shells than the lattice carries) is legal — the outer shells are simply not coupled — and is flagged once, with a warning, at LatticeGasWalkers construction.

pair_force(r::typeof(1.0u"Å"), pot::SingleComponentPotential{Pairwise})
pair_force(r::typeof(1.0u"Å"), lj::LJParameters)

The scalar radial force -du/dr of a pairwise potential at separation r, in eV/Å. The generic method is a two-sided central finite difference of pair_energy at a machine-scaled step, safe for any smooth pairwise potential; LJParameters carries the analytic override F(r) = 24 ε (2 (σ/r)¹² − (σ/r)⁶) / r for r ≤ r_c σ and exactly zero beyond: plainly truncated, so the force is discontinuous at the cutoff (the stored shift field shifts the energy only and never enters the derivative). In an indicator-acceptance reflective walk the force enters only through the reflection direction, where any deterministic position-dependent direction preserves the stationary measure, so the finite-difference fallback degrades mixing at worst, never sampled averages.

pbc_displacement(pos1, pos2, at::AbstractSystem)

Minimum-image displacement vector from pos2 to pos1 (pos1 - pos2, min-imaged per axis), sharing pbc_dist's per-axis periodicity switch and its orthorhombic scope; its norm matches pbc_dist(pos1, pos2, at) on every axis combination. Positions are assumed wrapped into the cell, the storage convention of the walk kernels.

Arguments

• pos1, pos2: The two positions (Unitful, Å components).
• at::AbstractSystem: The system carrying the cell and boundary conditions.

Returns

• SVector{3}: The minimum-image displacement vector, in Å.

pbc_dist(pos1, pos2, at)

Compute the distance between two positions considering periodic boundary conditions. Currently only works for orthorhombic lattices.

Arguments

• pos1::Union{SVector{T},Vector{T}}: The first position.
• pos2::Union{SVector{T},Vector{T}}: The second position.
• at::AbstractSystem: The abstract system containing boundary conditions and bounding box.

Returns

• d::Float64: The distance between pos1 and pos2 considering periodic boundary conditions.

single_site_energy(index::Int, at::AbstractSystem, pot::SingleComponentPotential{Pairwise})
single_site_energy(index::Int, at::AbstractSystem, cps::CompositeParameterSets{C,P}, list_num_par::Vector{Int})
single_site_energy(index::Int, at::AbstractSystem, cps::CompositeParameterSets{C,P}, list_num_par::Vector{Int}, surface::AbstractSystem)

Calculate the energy of a single site in the system using a pairwise potential. The energy is calculated by summing the pairwise interactions between the site and all other sites in the system.

Arguments

• index::Int: The index of the site for which the energy is calculated.
• at::AbstractSystem: The system for which the energy is calculated.
• pot::SingleComponentPotential{Pairwise}: The single-component pairwise potential.
• cps::CompositeParameterSets{C,P}: The composite potential parameters. The unpacked type P must be Pairwise.
• list_num_par::Vector{Int}: The number of particles in each component.
• surface::AbstractSystem: An optional surface system to consider in the energy calculation. See LJSurfaceWalkers.

Returns

• energy: The energy of the site.

site_field_energy(occupations::Vector{Bool}, field::Vector{U})

Energy contribution of a per-site field: the sum of field[i] over every occupied site i. Iteration runs over eachindex(occupations, field), so a field whose length differs from the occupation vector (a Hamiltonian built for a different lattice) raises a DimensionMismatch rather than silently summing a truncated or padded range; the liveset constructor and the raw-lattice sampler entry points validate the length once up front, with a descriptive error.

site_flip_delta(lattice::SLattice, h::SiteFieldLatticeHamiltonian{H,U}, site::Int) where {H,U}

Delta under the site-field wrapper: the base Hamiltonian's delta plus the signed field entry of the flipped site, mirroring the wrapper's interacting_energy method.

site_flip_delta(lattice::SLattice, h::MLatticeHamiltonian{C,N,U}, site::Int) where {C,N,U}

Single-component delta under a multi-component Hamiltonian: delegates to h.Hamiltonians[1, 1], matching the corresponding interacting_energy method for SLattice.

site_flip_delta(lattice::SLattice, h::GenericLatticeHamiltonian{N,U}, site::Int) where {N,U}

Exact energy change from flipping the occupancy of site: E(after) − E(before), computed as a local O(z) sum over the flipped site's neighbor entries (z the per-site neighbor entry count), the lattice counterpart of the audited single_site_energy path on the continuous side.

The formula respects both conventions of the full sweep (lattice_interaction_energy): each ordered neighbor entry carries half a coupling, so an ordinary neighbor j != site (appearing once in the flipped site's list and once in j's) contributes occ[j] times the full coupling to the delta, while a self-image entry (j == site, present under image_multiplicity = true) appears only in the flipped site's own row and contributes exactly half the coupling per image. The adsorption term mirrors the on-site channel of the full evaluation.

Availability for a Hamiltonian type is declared by the supports_site_deltas trait; consumers fall back to full recomputation when it is false. Throws the same shell-count ArgumentError as the full sweep when the Hamiltonian couples more shells than the lattice provides.