AbstractWalkers

AbstractWalkers

Module containing abstract definitions for walkers.

mutable struct AtomWalker

The AtomWalker struct represents a walker composed of atoms/molecules.

Fields

• configuration::FastSystem: The configuration of the walker.
• energy::typeof(0.0u"eV"): The energy of the walker.
• iter::Int64: The current iteration number of the walker.
• list_num_par::Vector{Int64}: The list of the number of particles for each component.
• frozen::Vector{Bool}: A boolean vector indicating whether each component is frozen or not.
• energy_frozen_part::typeof(0.0u"eV"): The energy of the frozen particles in the walker, serves as a constant energy offset to the interacting part of the system.

Constructor

• AtomWalker(configuration::FastSystem; energy=0.0u"eV", iter=0, list_num_par=zeros(Int,C), frozen=zeros(Bool,C), energy_frozen_part=0.0u"eV"): Constructs a new AtomWalker object with the given configuration and optional parameters.

AtomWalker(configuration::AbstractSystem; freeze_species::Vector{Symbol}=Symbol[], merge_same_species=true)

Constructs an AtomWalker object with the given configuration.

Arguments

• configuration::AbstractSystem: The configuration of the walker.
• freeze_species::Vector{Symbol}: A vector of species to freeze.
• merge_same_species::Bool: A boolean indicating whether to merge the same species into one component.

Returns

• AtomWalker{C}: The constructed AtomWalker object.

An empty configuration is rejected with an ArgumentError: the number of components cannot be inferred from zero atoms. Construct AtomWalker{1}(configuration) directly for a zero-particle single-component walker.

Example

julia> at = FreeBirdIO.generate_multi_type_random_starting_config(10.0,[2,1,3,4,5,6];particle_types=[:H,:O,:H,:Fe,:Au,:Cl])
FastSystem(Au₅Cl₆Fe₄H₅O, periodic = FFF):
    bounding_box      : [ 5.94392        0        0;
                                0  5.94392        0;
                                0        0  5.94392]u"Å"

        .--------------.  
       /|Fel           |  
      / H   H   Cl     |  
     /  Hu   O         |  
    *   |       Au   Fe|  
    |   |FeCl        Fe|  
    |   |        Au    |  
    |   .---------Au---.  
    |  /           H  /   
    | Au Cl          /    
    |/              /     
    *--------------*      

julia> AtomWalker(at;freeze_species=[:H],merge_same_species=false)
AtomWalker{6}(FastSystem(Au₅Cl₆Fe₄H₅O, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å"), 0.0 eV, 0, [2, 3, 1, 6, 4, 5], Bool[1, 1, 0, 0, 0, 0], 0.0 eV)

julia> AtomWalker(at;freeze_species=[:H],merge_same_species=true)
AtomWalker{5}(FastSystem(Au₅Cl₆Fe₄H₅O, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å"), 0.0 eV, 0, [5, 1, 6, 4, 5], Bool[1, 0, 0, 0, 0], 0.0 eV)

abstract type LatticeGeometry

The LatticeGeometry abstract type represents the geometry of a lattice. It has the following subtypes:

• SquareLattice: A square lattice.
• TriangularLattice: A triangular lattice.
• GenericLattice: A generic lattice. Currently used for non-square and non-triangular lattices.

mutable struct LatticeWalker

The LatticeWalker struct represents a walker on a 3D lattice.

Fields

• configuration::AbstractLattice: The configuration of the walker.
• energy::Float64: The energy of the walker.
• iter::Int64: The current iteration number of the walker.

Constructor

LatticeWalker(configuration::AbstractLattice; energy=0.0, iter=0)

Create a new LatticeWalker with the given configuration and optional energy and iteration number.

mutable struct MLattice{C,G}

A mutable struct representing a lattice with the following fields:

• lattice_vectors::Matrix{Float64}: The lattice vectors defining the unit cell.
• positions::Matrix{Float64}: The positions of the lattice points.
• basis::Vector{Tuple{Float64, Float64, Float64}}: The basis vectors within the unit cell.
• supercell_dimensions::Tuple{Int64, Int64, Int64}: The dimensions of the supercell.
• periodicity::Tuple{Bool, Bool, Bool}: The periodicity in each dimension.
• components::Vector{Vector{Bool}}: The components of the lattice.
• neighbors::Vector{Vector{Vector{Int}}}: The neighbors of each lattice point.
• adsorptions::Vector{Bool}: The adsorption sites on the lattice.

Inner Constructor

MLattice{C,G}(
    lattice_vectors::Matrix{Float64},
    basis::Vector{Tuple{Float64, Float64, Float64}},
    supercell_dimensions::Tuple{Int64, Int64, Int64},
    periodicity::Tuple{Bool, Bool, Bool},
    cutoff_radii::Vector{Float64},
    components::Vector{Vector{Bool}},
    adsorptions::Vector{Bool};
    image_multiplicity::Bool=false,
) where {C,G}

Creates an MLattice instance with the specified parameters. The constructor performs the following steps:

1. Validates that the number of components matches the expected value C.
2. Computes the positions of the lattice points using lattice_positions.
3. Computes the supercell lattice vectors.
4. Computes the neighbors of each lattice point using compute_neighbors, passing the image_multiplicity keyword through.

Throws an ArgumentError if the number of components does not match C.

Outer Constructors

MLattice{C,SquareLattice}(; lattice_constant::Float64=1.0,
                           interlayer_spacing::Union{Nothing,Float64}=nothing,
                           basis::Vector{Tuple{Float64,Float64,Float64}}=[(0.0, 0.0, 0.0)],
                           supercell_dimensions::Tuple{Int64,Int64,Int64}=(4, 4, 1),
                           periodicity::Tuple{Bool,Bool,Bool}=(true, true, false),
                           cutoff_radii::Vector{Float64}=[1.1, 1.5],
                           components::Union{Vector{Vector{Int64}},Vector{Vector{Bool}},Symbol}=:equal,
                           adsorptions::Union{Vector{Int},Symbol}=:full,
                           image_multiplicity::Bool=false)

MLattice{C,TriangularLattice}(; lattice_constant::Float64=1.0,
                              interlayer_spacing::Union{Nothing,Float64}=nothing,
                              basis::Vector{Tuple{Float64,Float64,Float64}}=[(0.0, 0.0, 0.0),(1/2, sqrt(3)/2, 0.0)],
                              supercell_dimensions::Tuple{Int64,Int64,Int64}=(4, 2, 1),
                              periodicity::Tuple{Bool,Bool,Bool}=(true, true, false),
                              cutoff_radii::Vector{Float64}=[1.1, 1.8],
                              components::Union{Vector{Vector{Int64}},Vector{Vector{Bool}},Symbol}=:equal,
                              adsorptions::Union{Vector{Int},Symbol}=:full,
                              image_multiplicity::Bool=false)

Constructs a square/triangular lattice with the specified parameters. The components and adsorptions arguments can be a vector of integers specifying the indices of the occupied sites, or a symbol. If components is :equal, the lattice is divided into C equal components when possible, or nearest to equal components otherwise. If adsorptions is :full, all sites are classified as adsorption sites.

The image_multiplicity keyword selects the neighbor-counting convention of compute_neighbors: under the default minimum-image convention each site pair is counted once and a warning reports any shells that wrap the periodic cell; with image_multiplicity=true every in-cutoff periodic image is counted, self-image entries included (the cluster-expansion small-cell convention, under which the cell's energy equals the bulk energy per cell of the tiled configuration). The duplicated entries compose correctly downstream: the energy kernels add coupling/2 per ordered-pair entry, so a doubled bond reaches the full bond energy and a self-image entry passes the occupation test exactly when the site is occupied; geometric-cluster growth reads only the first shell, and growth across a duplicated bond remains a configuration-independent symmetric proposal.

The interlayer_spacing keyword sets the out-of-plane (third-axis) lattice spacing. The default nothing means isotropic spacing: the third lattice vector is [0, 0, lattice_constant]. Note this is a behavior change on one previously broken path: 3D cells built with lattice_constant ≠ 1 used to mix scales (the out-of-plane spacing was fixed at 1.0, so a "nearest-neighbor" cutoff could select only interlayer bonds without warning); such cells now default to isotropic spacing. Pass interlayer_spacing = 1.0 to reproduce the old geometry. An explicit value c gives a tetragonal cell whose square-lattice distance ladder is a, c, √2·a, √(a² + c²), 2a, …, so a suitable cutoff ladder separates in-plane from interlayer nearest neighbors into distinct shells: with a = 1.0, c = 1.25 and cutoff_radii = [1.1, 1.35], shell 1 is in-plane only and shell 2 interlayer only (the next distance √2 ≈ 1.414 is excluded), so a GenericLatticeHamiltonian with couplings [J∥, J⊥] expresses direction-resolved nearest-neighbor interactions with no other library changes. Avoid degenerate spacings that alias the two bond classes into one shell (c = √2·a puts interlayer bonds at the in-plane second-neighbor distance, c = 2a at the third); the strictly-increasing cutoff-ladder validation and the empty-shell warning of compute_neighbors are the runtime backstops. The keyword composes with image_multiplicity; the third axis is non-periodic by default, so slabs gain no z-wrap images. Must be finite and strictly positive when given; violations throw an ArgumentError.

Returns

• MLattice{C,G}: A square/triangular lattice object with C components.

_check_planar_basis(caller::Symbol, lattice::MLattice)

Shared guard for the layer helpers: throw an ArgumentError, naming the public entry point caller, unless all basis z-components are equal. Layers along dimension 3 are geometrically well defined only for a planar basis.

_minimum_image_distance(supercell_lattice_vectors, reciprocal_lattice_vectors,
                        periodicity, pos_i, pos_j)

Minimum-image distance between two Cartesian positions under the given supercell and periodicity — the single distance kernel shared by compute_neighbors and enumerate_motif_embeddings, so pair shells and cluster embeddings follow the identical torus convention.

_out_of_plane_spacing(lattice_constant, interlayer_spacing)

Resolve the third-axis lattice spacing for the keyword constructors: nothing means isotropic spacing (the in-plane lattice_constant); an explicit value must be finite and strictly positive, the cutoff-ladder idiom of compute_neighbors, and violations throw an ArgumentError.

bragg_amplitude(lattice::MLattice{1,SquareLattice}, m::Int, n::Int) -> Float64

Normalized Bragg-peak amplitude of the occupation pattern on a single-component square lattice:

|ρ(k)| = |Σ_{occupied sites} e^{ik·r}| / M,   k = 2π·(m/d₁, n/d₂),

in units of the inverse lattice constant, where (d₁, d₂) are the in-plane supercell dimensions and M = d₁·d₂ is the number of sites. This is the LEED-intensity convention of Zhang, Blum & Reuter [PRB 75, 235406 (2007)]; order_parameter_c2x2 is the k = (π, π) member of the family, and bragg_amplitude(lat, d1 ÷ 2, d2 ÷ 2) == order_parameter_c2x2(lat) on even-dimension cells. Integer indices on the supercell reciprocal grid make every representable k commensurate by construction; indices wrap modulo the dimensions, so negative and out-of-range values are valid: bragg_amplitude(lat, m, n) == bragg_amplitude(lat, m + d1, n). The empty and the full lattice give 0 for any (m, n) not both ≡ 0 modulo the dimensions; a single particle gives 1/M.

Like the named order parameters, |ρ(k)| is not a function of (E, N) and must be evaluated on configurations (e.g. per culled walker, via the observables keyword of the nested-sampling loops); see order_parameter_stripe for the composed-observable recipes.

Requires a single-site basis and a strictly two-dimensional supercell (supercell_dimensions[3] == 1); violations throw an ArgumentError.

bragg_amplitude(lattice::MLattice{1,TriangularLattice}, m::Int, n::Int) -> Float64

Normalized Bragg-peak amplitude of the occupation pattern on a single-component triangular lattice:

|ρ(k)| = |Σ_{occupied sites} e^{ik·r}| / M,   k = 2π·(m/d₁, n/(√3·d₂)),

in units of the inverse lattice constant, where (d₁, d₂) are the in-plane supercell dimensions of the conventional (centered-rectangular) cell and M = 2·d₁·d₂ is the number of sites; the sum runs over both basis sites, so the two-site basis phases are included. Integer indices on the conventional-cell reciprocal grid make every representable k commensurate by construction, in the same LEED-intensity convention as the square-lattice method [Zhang, Blum & Reuter, PRB 75, 235406 (2007)].

Because the basis sites live on the half-integer grid of the conventional cell, amplitudes are periodic under the primitive reciprocal lattice rather than index-wise: bragg_amplitude(lat, m, n) == bragg_amplitude(lat, m + d1, n - d2) == bragg_amplitude(lat, m, n + 2*d2) (the two index shifts add the primitive reciprocal vectors b₁ = 2π·(1, −1/√3) and b₂ = 2π·(0, 2/√3)), and both identities hold exactly. The three M points of the triangular Brillouin zone sit at (m, n) = (0, d2) (representable on any cell) and (d1 ÷ 2, ∓(d2 ÷ 2)) (integer indices for even in-plane dimensions); M-point phases are exactly ±1.0 (u and v share the parity of the basis index, so the quarter-turn table entries always combine to half turns), so the documented values of order_parameter_p2x2 hold to full precision. The empty lattice gives exactly 0 at every k; the full lattice gives 0 for any k that is not a reciprocal-lattice vector of the triangular lattice, exactly at the three M points and to floating-point roundoff at generic indices (where the phasor components are irrational). A single particle gives 1/M.

Like the named order parameters, |ρ(k)| is not a function of (E, N) and must be evaluated on configurations (e.g. per culled walker, via the observables keyword of the nested-sampling loops); see order_parameter_p2x2 for the composed-observable recipes.

Requires the standard two-site centered-rectangular triangular basis [(0, 0, 0), (a/2, √3·a/2, 0)] consistent with the lattice vectors and a strictly two-dimensional supercell (supercell_dimensions[3] == 1); violations throw an ArgumentError.

check_num_components(C::Int, list_num_par::Vector{Int}, frozen::Vector{Bool})

Check that the number of components matches the length of the list of number of particles and frozen particles.

Arguments

• C::Int: The number of components.
• list_num_par::Vector{Int}: The number of particles in each component.
• frozen::Vector{Bool}: A vector indicating whether each component is frozen.

compute_neighbors(supercell_lattice_vectors::Matrix{Float64},
                  positions::Matrix{Float64},
                  periodicity::Tuple{Bool, Bool, Bool},
                  cutoff_radii::Vector{Float64};
                  image_multiplicity::Bool=false)

Compute the neighbor shells of every site in a supercell. Each in-cutoff distance is assigned to the first shell whose cutoff admits it (a nested <= cutoff ladder), so cutoff_radii must be non-empty, finite, strictly positive, and strictly increasing; anything else throws an ArgumentError.

Arguments

• supercell_lattice_vectors::Matrix{Float64}: The lattice vectors of the supercell, one cell vector per column.
• positions::Matrix{Float64}: The Cartesian positions of the sites, one site per row.
• periodicity::Tuple{Bool, Bool, Bool}: A Boolean tuple of length three indicating periodicity in each dimension (true for periodic, false for non-periodic).
• cutoff_radii::Vector{Float64}: The cutoff radii for the index-th nearest neighbors, strictly increasing.
• image_multiplicity::Bool=false: The neighbor-counting convention, see below.

Returns

• neighbors::Vector{Vector{Vector{Int}}}: For each site, one vector of neighbor indices per shell.

Conventions

With image_multiplicity=false (the default), each site pair is counted once, in the shell of its minimum-image distance. On a cell whose periodic circumference does not exceed twice a shell cutoff, pairs connected through more than one periodic image are still counted once — the affected shells sit below their bulk-tiled coordination — and one warning listing every such shell and its collapsed-image count is emitted per call. Detection is exact (the periodic images are enumerated), so faithful cells never warn.

With image_multiplicity=true, a neighbor index is pushed once per in-cutoff periodic image, including a site's own images (self-entries, j == i, which arise when a periodic circumference is within the cutoff): the cluster-expansion small-cell convention, under which the periodic cell's energy equals the bulk energy per cell of the tiled configuration.

custom_sort(arr::Vector{Int}, period::Int)

Sorts [1,2,3,4,5,6,7,8] into [1,3,5,7,2,4,6,8] for period = 2. Useful for printing triangular lattices.

enumerate_motif_embeddings(lattice::MLattice, distances::AbstractVector{<:Real};
                           tol::Float64=1e-6,
                           expected_count::Union{Int,Nothing}=nothing)
    -> Vector{NTuple{K,Int}}

Enumerate every embedding of a cluster motif on a periodic lattice. The motif is declared by the sorted multiset of its pairwise minimum-image distances (K is inferred from the multiset length: 1 → pair, 3 → trio, 6 → quattro, 10 → quinto); motif_distances builds the multiset from a coordinate template. Distances are compared with absolute tolerance tol, using the same minimum-image kernel as compute_neighbors, so embeddings follow the identical torus convention as the pair shells: one entry per unordered site set whose distances match, in canonical strictly increasing order — the form ClusterInteraction requires.

Diagnostics:

• The total embedding count and the count per site are logged (@info).
• A warning is emitted when the per-site embedding membership is not uniform: on a site-transitive lattice, nonuniformity indicates distance aliasing or an unsuitable tol.
• A warning is emitted when any periodic circumference does not exceed K · maximum(distances): such a cell is not a faithful quotient, and winding (wrap-around) embeddings are counted under the torus convention (e.g. the 18-site triangular cell carries 42 nearest-neighbor-triangle embeddings: 36 faces plus 6 winding three-cycles).
• When expected_count is given (e.g. a hand-derived per-cell multiplicity), a mismatch throws an ArgumentError — the recommended guard against silent transcription errors.

Note: for a pair signature (K = 2) this reproduces the sites of a neighbor shell as unordered pairs — useful as a counting diagnostic; pair couplings themselves belong in GenericLatticeHamiltonian.

Homometry caveat: for K ≥ 4, non-congruent figures can share a distance multiset (homometric figures), and this method then enumerates the embeddings of every such figure together — it warns about this. Pass the coordinate template instead (the coords method) to enumerate only embeddings whose full distance matrix matches the template under some site permutation, which excludes homometric aliases while preserving the torus counting convention. For K ≤ 3 the multiset determines the figure and the two methods agree.

enumerate_motif_embeddings(lattice::MLattice, coords::AbstractVector{<:Tuple};
                           tol=1e-6, expected_count=nothing)

Template method: declare the motif by its site coordinates (as accepted by motif_distances) and enumerate only the embeddings whose full minimum-image distance matrix matches the template's under some site permutation. This is the recommended method for K ≥ 4, where a distance multiset alone does not determine the figure (homometric figures).

insert_particle!(walker::AtomWalker{1}, pos, species)

Append one particle of species (a Symbol or ChemicalSpecies) at position pos to the walker's configuration, updating list_num_par in the same call. The two mutations are kept in lockstep here so the configuration arrays and the particle count cannot drift apart. The operation is purely structural: the walker's energy is not touched and the component's frozen flag is not consulted; callers own the energy bookkeeping (see MC_grand_canonical_walk!).

Arguments

• walker::AtomWalker{1}: The single-component walker to extend.
• pos: The new particle's position (any 3-vector of lengths accepted by the configuration).
• species: The chemical identity of the new particle.

Returns

• walker::AtomWalker{1}: The updated walker.

latticepositions(latticevectors::Matrix{Float64}, basis::Vector{Tuple{Float64, Float64, Float64}}, supercell_dimensions::Tuple{Int64, Int64, Int64})

Compute the positions of atoms in a 3D lattice.

Arguments

• lattice_vectors::Matrix{Float64}: The lattice vectors of the system.
• basis::Vector{Tuple{Float64, Float64, Float64}}: The basis of the system.
• supercell_dimensions::Tuple{Int64, Int64, Int64}: The dimensions of the supercell.

Returns

• positions::Matrix{Float64}: The positions of the atoms in the supercell.

layer_coverage(lattice::MLattice{1,G}, layer::Int) -> Float64

Occupied fraction of one layer of a single-component lattice: the number of occupied sites in layer layer's contiguous block of B = length(basis) · d₁ · d₂ sites (see site_layers), divided by B. This is the layer-resolved complement of the in-plane order parameters for three-dimensional supercells; the per-layer coverages θk are the order parameters of lattice-gas layering transitions. It returns a scalar Real, so `cfg -> layercoverage(cfg, k)is directly usable as anobservablescallback in the nested-sampling loops: like the shipped order parameters, θ is not a function of(E, N)and must be evaluated per configuration rather than reconstructed from an energy ledger. Atd₃ == 1it degenerates to the total coverageN/M`, which is legal and intentional, so no two-dimensionality guard applies.

Requires a planar basis (all basis z-components equal) and 1 ≤ layer ≤ d₃; violations throw an ArgumentError.

layer_field(lattice::MLattice, per_layer::AbstractVector) -> Vector

Broadcast a per-layer value over every site of its layer: the result has num_sites(lattice) entries, with per_layer[k] at every site of layer k (see site_layers). The element type of per_layer is preserved, so a Unitful profile feeds a SiteFieldLatticeHamiltonian directly:

field = layer_field(lat, [-0.27, -0.03375, -0.01] .* u"eV")
h = SiteFieldLatticeHamiltonian(GenericLatticeHamiltonian(0.0, [-0.01], u"eV"), field)

A height profile is physically meaningful only when dimension 3 is non-periodic (periodicity[3] == false); this is not checked.

Requires a planar basis (all basis z-components equal) and length(per_layer) == d₃ (= supercell_dimensions[3]); violations throw an ArgumentError.

merge_components(lattice::MLattice{C}) where C

Merges the boolvec of components into a single vector of integers, where each integer represents the component number.

mlattice_setup(C::Int, 
                 basis::Vector{Tuple{Float64, Float64, Float64}},
                 supercell_dimensions::Tuple{Int64, Int64, Int64},
                 components::Union{Vector{Vector{Int64}},Vector{Vector{Bool}},Symbol},
                 adsorptions::Union{Vector{Int}, Vector{Bool}, Symbol})

Setup the components and adsorptions for a lattice.

Arguments

• C::Int: The number of components.
• basis::Vector{Tuple{Float64, Float64, Float64}}: The basis of the lattice.
• supercell_dimensions::Tuple{Int64, Int64, Int64}: The dimensions of the supercell.
• components::Union{Vector{Vector{Int64}},Vector{Vector{Bool}},Symbol}: The components of the lattice.
• adsorptions::Union{Vector{Int}, Vector{Bool}, Symbol}: The adsorption sites on the lattice.

Returns

• lattice_comp::Vector{Vector{Bool}}: The components of the lattice.
• lattice_adsorptions::Vector{Bool}: The adsorption sites on the lattice.

motif_distances(coords::AbstractVector{<:Tuple}) -> Vector{Float64}

Sorted multiset of the pairwise Euclidean distances of a coordinate template, for transcribing a cluster-interaction figure straight from a paper's geometry (e.g. the trio [(0, 0), (1, 0), (0, 1)] gives [1, 1, √2]). Two-component tuples are treated as in-plane coordinates with z = 0. The result is the distances argument of enumerate_motif_embeddings.

num_sites(lattice::AbstractLattice)

Returns the total number of sites in a lattice given a AbstractLattice object. Returns the total number of sites.

occupancy_profile(lattice::MLattice{1,G}) -> Vector{Float64}

Vector of layer coverages, [layer_coverage(lattice, k) for k in 1:d₃], computed in one pass. Every layer holds B = length(basis) · d₁ · d₂ sites, so mean(occupancy_profile(lat)) == N/M exactly (N occupied sites, M total sites).

The return value is a Vector, not a scalar, so occupancy_profile is not directly usable as an observables callback (callbacks must return a Real); record per-layer coverages by composing scalar callbacks caller-side, with no library change:

observables = [Symbol(:theta, k) => (cfg -> layer_coverage(cfg, k)) for k in 1:d₃]

after which ⟨θ₁⟩ … ⟨θd₃⟩ come from `observablecols=[:theta1, :theta2, …]` in the grand-canonical stats functions.

Requires a planar basis (all basis z-components equal); violations throw an ArgumentError.

occupied_site_count(MLattice::MLattice{C})

Returns the number of occupied sites in each component of a lattice in an array.

order_parameter_c2x2(lattice::MLattice{1,SquareLattice}) -> Float64

Sublattice order parameter for c(2×2) checkerboard ordering on a single-component square lattice:

Ψ = |Σ_{occupied sites} (−1)^(i+j)| / M,

where (i, j) are the integer lattice coordinates of each site and M is the number of sites. Equivalent to the four-sublattice Ψ_c(2×2) = |N_a + N_d − N_b − N_c| / M of Zhang, Blum & Reuter [PRB 75, 235406 (2007), Eq. (8)]: sublattices (a, d) share one checkerboard parity and (b, c) the other. A perfect c(2×2) arrangement at half filling gives 1/2; the empty and the full lattice give 0.

Ψ is not a function of (E, N) — degenerate energy levels contain ordered and disordered configurations alike — so it must be evaluated on configurations (e.g. per culled walker, via the observables keyword of the nested-sampling loops) rather than reconstructed from an energy ledger.

Requires a single-site basis, a strictly two-dimensional supercell (supercell_dimensions[3] == 1), and even in-plane dimensions (the two checkerboard sublattices must tile the periodic cell evenly); violations throw an ArgumentError.

order_parameter_p2x2(lattice::MLattice{1,TriangularLattice}) -> Float64

Orientation-degenerate M-point order parameter for p(2×2) and p(2×1)/row ordering on a single-component triangular lattice: the quadrature sum of the three normalized M-point Bragg amplitudes,

Ψ = √(|ρ(M₁)|² + |ρ(M₂)|² + |ρ(M₃)|²),

i.e. sqrt(bragg_amplitude(lat, d1 ÷ 2, -(d2 ÷ 2))^2 + bragg_amplitude(lat, 0, d2)^2 + bragg_amplitude(lat, d1 ÷ 2, d2 ÷ 2)^2) with the amplitudes of bragg_amplitude. A perfect p(2×2) arrangement at coverage 1/4 contributes exactly 1/4 at every M point, giving √3/4 ≈ 0.4330; a perfect single-orientation p(2×1) row phase at coverage 1/2 puts exactly 1/2 on one M point and 0 on the other two, giving 1/2; the perfect (√3×√3)R30° state (K-point order) and the empty and the full lattice give exactly 0; disordered configurations give O(1/√M). Translation and orientation degeneracies are divided out, so all degenerate ordered states of each phase give the same value.

The M-point pattern separates the two phases where the scalar cannot: the max-to-quadrature ratio of the three amplitudes is 1/√3 for p(2×2) (three equal M points) and 1 for a single p(2×1) orientation; compose it caller-side from bragg_amplitude when needed. order_parameter_sqrt3 is exactly 0 on both M-point phases and this function is exactly 0 on the √3×√3 phase, so the two observables are orthogonal discriminators.

Ψ is not a function of (E, N) and must be evaluated on configurations (e.g. per culled walker, via the observables keyword of the nested-sampling loops). Higher moments for Binder-cumulant analysis are composed caller-side, with no library change:

observables = [:psi  => order_parameter_p2x2,
               :psi2 => cfg -> order_parameter_p2x2(cfg)^2,
               :psi4 => cfg -> order_parameter_p2x2(cfg)^4]

Requires the structural guards of bragg_amplitude plus even in-plane supercell dimensions: the M points sit at half-integer reciprocal indices, and even circumferences are exactly the wrap-invariance condition of the p(2×2) sublattice. A cell hosting this order parameter and order_parameter_sqrt3 simultaneously needs supercell_dimensions[1] divisible by 6 with an even second dimension; the shipped default (4, 2, 1) satisfies this function's guards but not the √3×√3 one's.

order_parameter_sqrt3(lattice::MLattice{1,TriangularLattice}) -> Float64

Three-sublattice order parameter for (√3×√3)R30° ordering on a single-component triangular lattice:

Ψ = |Σ_{occupied sites} ω^{c(s)}| / M,   ω = e^{2πi/3},

where c(s) ∈ {0,1,2} is the site's sublattice label under the standard tripartition of the triangular lattice and M is the number of sites. This is the modulus of the complex three-state Potts order parameter: the Z₃ phase distinguishing the three degenerate ordered states is divided out, so all three give the same value. A perfect √3×√3 arrangement at coverage 1/3 gives 1/3; the empty and the full lattice give 0 (1 + ω + ω² = 0).

Ψ is not a function of (E, N): degenerate energy levels contain ordered and disordered configurations alike, so it must be evaluated on configurations (e.g. per culled walker, via the observables keyword of the nested-sampling loops). Higher moments for Binder-cumulant analysis are composed caller-side, with no library change:

observables = [:psi  => order_parameter_sqrt3,
               :psi2 => cfg -> order_parameter_sqrt3(cfg)^2,
               :psi4 => cfg -> order_parameter_sqrt3(cfg)^4]

after which ⟨Ψ⟩, ⟨Ψ²⟩, ⟨Ψ⁴⟩ come from observable_cols=[:psi, :psi2, :psi4] in the grand-canonical stats functions.

Requires the standard two-site centered-rectangular triangular basis [(0, 0, 0), (a/2, √3·a/2, 0)] consistent with the lattice vectors, a strictly two-dimensional supercell (supercell_dimensions[3] == 1), and supercell_dimensions[1] divisible by 3 (the tripartition closes on the periodic cell iff the a₁ circumference is a multiple of 3; the a₂ dimension is unconstrained); violations throw an ArgumentError. Note the shipped default supercell_dimensions = (4, 2, 1) is not commensurate.

order_parameter_stripe(lattice::MLattice{1,SquareLattice}; period::Int = 2) -> Float64

Orientation-degenerate axial stripe order parameter on a single-component square lattice: the quadrature sum of the two axial Bragg amplitudes at wavevector 2π/P, with P = period in lattice constants,

Ψ = √(|ρ(2π/P, 0)|² + |ρ(0, 2π/P)|²),

i.e. sqrt(bragg_amplitude(lat, d1 ÷ period, 0)^2 + bragg_amplitude(lat, 0, d2 ÷ period)^2) with the normalized amplitudes of bragg_amplitude. A perfect single-orientation period-P stripe with the half-period filled attains 1/(P·sin(π/P)): each of the d₂ rows contributes d₁/P copies of the geometric phasor sum Σ_{x=0}^{P/2−1} e^{2πix/P}, of modulus 1/sin(π/P), and dividing by M = d₁·d₂ leaves 1/(P·sin(π/P)). That gives 1/2 at P = 2 (matching the c(2×2) = 1/2 convention at half filling) and √2/4 at P = 4; the perpendicular component vanishes on a perfect stripe, so the quadrature maximum equals the single-orientation value. period = 2 detects the (2×1) row and column stripes — the superantiferromagnetic phase of the square lattice with nearest- and next-nearest-neighbor couplings [Binder & Landau, PRB 21, 1941 (1980)] — period = 4 the axial period-4 phases that appear with third-neighbor couplings [Landau & Binder, PRB 31, 5946 (1985)], and period = 2h the width-h stripes of dipolar-frustrated ferromagnets [MacIsaac, Whitehead, Robinson & De'Bell, PRB 51, 16033 (1995)]. The perfect checkerboard and the empty and the full lattice give 0.

Ψ is not a function of (E, N) — degenerate energy levels contain ordered and disordered configurations alike — so it must be evaluated on configurations (e.g. per culled walker, via the observables keyword of the nested-sampling loops). Higher moments for Binder-cumulant analysis are composed caller-side, with no library change:

observables = [:stripe  => order_parameter_stripe,
               :stripe2 => cfg -> order_parameter_stripe(cfg)^2,
               :stripe4 => cfg -> order_parameter_stripe(cfg)^4]

Diagonal period-4 order is composed the same way, from the k = (π/2, ±π/2) quadrature

cfg -> sqrt(bragg_amplitude(cfg, d1 ÷ 4, d2 ÷ 4)^2 +
            bragg_amplitude(cfg, d1 ÷ 4, -(d2 ÷ 4))^2)

which equals √2/4 on every member of the k = (π/2, ±π/2) ground manifold of the nearest-neighbor-attraction plus isotropic third-neighbor-repulsion model — p(2×2) blocks and diagonal period-4 stripes alike — while order_parameter_stripe(period=4) is exactly 0 there; the two observables separate the axial and diagonal period-4 phases.

Requires a single-site basis, a strictly two-dimensional supercell (supercell_dimensions[3] == 1), period >= 2, and period dividing both in-plane dimensions (both orientations are evaluated, and an incommensurate orientation leaks a spurious amplitude); violations throw an ArgumentError.

remove_particle!(walker::AtomWalker{1}, i::Int)

Remove particle i from the walker's configuration, order-preserving, updating list_num_par in the same call. Purely structural, like insert_particle!: the walker's energy is not touched.

Arguments

• walker::AtomWalker{1}: The single-component walker to shrink.
• i::Int: The index of the particle to remove.

Returns

• walker::AtomWalker{1}: The updated walker.

replicate_walkers(template::MLattice{C,G}, K::Int) -> Vector{LatticeWalker}

Build K walkers whose configurations share the template's run-invariant geometry (lattice vectors, positions, basis, supercell dimensions, periodicity, cutoff radii, neighbor lists, and adsorption mask) by reference, each with its own independent occupancy vectors copied from the template. The geometry fields are written only during construction and the Monte Carlo kernels mutate occupancies exclusively, so sharing is safe on the serial lattice drivers; relative to the deepcopy(template) idiom the saving is one whole neighbor nest per walker. Walkers start at energy = 0.0u"eV", iter = 0, matching the deepcopy idiom's usual construction.

site_layers(lattice::MLattice) -> Vector{Int}

Layer index of every site along the third supercell dimension: site s belongs to layer (s − 1) ÷ B + 1 with B = length(basis) · d₁ · d₂, exact because lattice_positions orders sites with dimension 3 outermost (basis innermost, dimension 1 fastest), making each layer one contiguous block of B sites. The result has num_sites(lattice) entries with values in 1:d₃.

Requires a planar basis (all basis z-components equal), so that "layer" is geometrically unambiguous; violations throw an ArgumentError.

sort_components_by_atomic_number(at::AbstractSystem; merge_same_species=true)

Sorts the components of an AbstractSystem object at by their atomic number.

Arguments

• at::AbstractSystem: The input AbstractSystem object.

Keyword Arguments

• merge_same_species::Bool=true: Whether to merge components with the same species.

Returns

• list_num_par::Vector{Int64}: A vector containing the number of each component species.
• new_list::FastSystem: A new FastSystem object with the sorted components.

The function first extracts the atomic numbers of the components in at. If merge_same_species is true, it sorts the unique species and counts the number of each species. If merge_same_species is false, it creates a list of species and their counts. It then sorts the species and counts by atomic number. Finally, it constructs a new FastSystem object with the sorted components and returns the list of species counts and the new FastSystem object. An empty system returns an empty list_num_par and a zero-atom system, under either flag.

Examples

julia> at = FreeBirdIO.generate_multi_type_random_starting_config(10.0,[2,1,3,4,5,6];particle_types=[:H,:O,:H,:Fe,:Au,:Cl])
FastSystem(Au₅Cl₆Fe₄H₅O, periodic = FFF):
    bounding_box      : [ 5.94392        0        0;
                                0  5.94392        0;
                                0        0  5.94392]u"Å"

        .--------------.  
       /|     Cl    H  |  
      / |      Fe      |  
     /  |  Au     FeH  |  
    *   |   FeH  ACl   |  
    |   |    Cl     Au |  
    |   |            O |  
    |   .--Fe----------.  
    |  /H  Cl         /   
    | /          Au  /    
    |/Cl          Cl/     
    *--------------*      


julia> AbstractWalkers.sort_components_by_atomic_number(at; merge_same_species=false)
([2, 3, 1, 6, 4, 5], FastSystem(Au₅Cl₆Fe₄H₅O, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å"))

julia> AbstractWalkers.sort_components_by_atomic_number(at)
([5, 1, 6, 4, 5], FastSystem(Au₅Cl₆Fe₄H₅O, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å"))

split_components(at::AbstractSystem, list_num_par::Vector{Int})

Split the system into components based on the number of particles in each component.

Arguments

• at::AbstractSystem: The system to split.
• list_num_par::Vector{Int}: The number of particles in each component.

Returns

• components: An array of FastSystem objects representing the components of the system.

An empty system, or a zero-count component, yields a zero-atom FastSystem carrying the parent system's cell and periodicity.

split_components_by_chemical_species(at::AbstractSystem)

Split an AbstractSystem into multiple components based on the chemical species.

Arguments

• at::AbstractSystem: The input AbstractSystem to be split.

Returns

An array of FastSystem objects, each representing a component of the input system. An empty system returns an empty array.

Example

julia> at = FreeBirdIO.generate_multi_type_random_starting_config(10.0,[2,1,3,4,5,6];particle_types=[:H,:O,:H,:Fe,:Au,:Cl])
FastSystem(Au₅Cl₆Fe₄H₅O, periodic = FFF):
    bounding_box      : [ 5.94392        0        0;
                                0  5.94392        0;
                                0        0  5.94392]u"Å"

        .--------------.  
       /Au      Cl     |  
      / |HAu Fe        |  
     /  |     Cl Cl Cl |  
    *   |Cle           |  
    |   | Cl      H    |  
    |   |      OAuH    |  
    |FeFe-----------H--.  
    |  /          Au  /   
    | /      Au      /    
    |/              /     
    *--------------*      


julia> AbstractWalkers.split_components_by_chemical_species(at)
5-element Vector{FastSystem}:
 FastSystem(H₅, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å")
 FastSystem(O, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å")
 FastSystem(Cl₆, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å")
 FastSystem(Fe₄, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å")
 FastSystem(Au₅, periodic = FFF, bounding_box = [[5.943921952763129, 0.0, 0.0], [0.0, 5.943921952763129, 0.0], [0.0, 0.0, 5.943921952763129]]u"Å")

split_into_subarrays(arr::AbstractVector, N::Int)

Split an array into N subarrays of approximately equal size.

Arguments

• arr::AbstractVector: The array to split.
• N::Int: The number of subarrays to create.

Returns

• subarrays::Vector{Vector{eltype(arr)}}: A vector of subarrays.

update_walker!(walker::AtomWalker, key::Symbol, value)

Update the properties of an AtomWalker object.

A convenient function that updates the value of a specific property of an AtomWalker object.

Arguments

• walker::AtomWalker: The AtomWalker object to be updated.
• key::Symbol: The key of the property to be updated.
• value: The new value of the property.

Returns

• walker::AtomWalker: The updated AtomWalker object.

Example

update_walker!(walker, :energy, 10.0u"eV")
update_walker!(walker, :iter, 1)

view_structure(at::AbstractSystem)
view_structure(walker::AtomWalker)

Print an ASCII representation of the system.