MonteCarloMoves

MonteCarloMoves

Module containing functions for performing Monte Carlo moves on atomistic/lattice systems.

MC_cluster_walk!(n_steps::Int, lattice::LatticeWalker{C}, h::ClassicalHamiltonian, emax::Float64, cluster_p::Float64; energy_perturb::Float64=0.0)

Perform a sequence of geometric cluster moves on the lattice system, accepting each if E < emax.

Arguments

• n_steps::Int: The number of cluster move attempts to perform.
• lattice::LatticeWalker{C}: The walker to perform cluster moves on.
• h::ClassicalHamiltonian: The lattice Hamiltonian.
• emax::Float64: The maximum energy allowed for accepting a move (dimensionless).
• cluster_p::Float64: The growth probability for BFS cluster construction.
• energy_perturb::Float64=0.0: Energy perturbation to break degeneracies.

Returns

• accept_this_walker::Bool: Whether at least one move was accepted.
• accept_rate::Float64: The fraction of accepted moves.
• lattice::LatticeWalker: The updated walker.

MC_mixed_moves!(n_steps::Int, at::AtomWalker{C}, pot::AbstractPotential, step_size::Float64, emax::typeof(0.0u"eV"), freq::Vector{Int}) where C

Perform a Monte Carlo mixed move consisting of random walks and atom swaps in the AtomWalker. Arguments

• n_steps::Int: The number of Monte Carlo steps to perform.
• at::AtomWalker{C}: The AtomWalker object.
• pot::AbstractPotential: The potential object for energy calculations.
• step_size::Float64: The step size for the random walk moves.
• emax::typeof(0.0u"eV"): The maximum energy allowed for accepting a move.
• freq::Vector{Int}: A vector containing the frequencies of random walk and swap moves. The first element is the frequency of random walk moves, and the second element is the frequency of swap moves.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• accept_rate::Float64: The acceptance rate of the mixed moves.
• at::AtomWalker{C}: The updated AtomWalker.

MC_new_sample!(lattice::LatticeWalker, h::ClassicalHamiltonian, emax::Float64; energy_perturb::Float64=0.0)

Generate a new sample for the lattice system.

Arguments

• lattice::LatticeWalker: The walker to generate a new sample for.
• h::ClassicalHamiltonian: The Hamiltonian containing the on-site and nearest-neighbor interaction energies.
• emax::Float64: The maximum energy allowed for accepting a move.
• energy_perturb::Float64=0.0: The energy perturbation used to make degenerate configurations distinguishable.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• lattice::LatticeWalker: The updated walker.

MC_random_swap!(n_steps::Int, at::AtomWalker{C}, lj::LennardJonesParameterSets, emax::typeof(0.0u"eV"))

Perform a Monte Carlo random swap of two atoms in the AtomWalker. Only works when there are two or more non-frozen components.

Arguments

• n_steps::Int: The number of Monte Carlo steps to perform.
• at::AtomWalker{C}: The AtomWalker object.
• lj::LennardJonesParameterSets: The Lennard-Jones parameters.
• emax::typeof(0.0u"eV"): The maximum energy allowed for accepting a move.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• accept_rate::Float64: The acceptance rate of the random walk.
• at::AtomWalker{C}: The updated AtomWalker.

MC_random_walk!(n_steps::Int, at::AtomWalker{C}, pot::AbstractPotential, step_size::Float64, emax::typeof(0.0u"eV"), surface::AtomWalker{CS})

Perform a Monte Carlo random walk on the atomic/molecular system with an external surface.

Arguments

• n_steps::Int: The number of Monte Carlo steps to perform.
• at::AtomWalker{C}: The walker to perform the random walk on.
• pot::AbstractPotential: The potential energy function for the system.
• step_size::Float64: The maximum distance an atom can move in any direction.
• emax::typeof(0.0u"eV"): The maximum energy allowed for accepting a move.
• surface::AtomWalker{CS}: The surface walker object to consider in the energy calculation. Typically frozen.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• accept_rate::Float64: The acceptance rate of the random walk.

MC_random_walk!(n_steps::Int, at::AtomWalker, pot::AbstractPotential, step_size::Float64, emax::typeof(0.0u"eV"))

Perform a Monte Carlo random walk on the atomic/molecular system.

Arguments

• n_steps::Int: The number of Monte Carlo steps to perform.
• at::AtomWalker{C}: The walker to perform the random walk on.
• pot::AbstractPotential: The potential energy function for the system.
• step_size::Float64: The maximum distance an atom can move in any direction.
• emax::typeof(0.0u"eV"): The maximum energy allowed for accepting a move.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• accept_rate::Float64: The acceptance rate of the random walk.
• at::AtomWalker: The updated walker.

MC_random_walk!(n_steps::Int, at::AtomWalker, pot::LennardJonesParameterSets, step_size::Float64, emax::typeof(0.0u"eV"))

Perform a Monte Carlo random walk on the atomic/molecular system. Specialized for Lennard-Jones potentials.

Arguments

• n_steps::Int: The number of Monte Carlo steps to perform.
• at::AtomWalker{C}: The walker to perform the random walk on.
• pot::LennardJonesParameterSets: The potential energy function for the system.
• step_size::Float64: The maximum distance an atom can move in any direction.
• emax::typeof(0.0u"eV"): The maximum energy allowed for accepting a move.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• accept_rate::Float64: The acceptance rate of the random walk.
• at::AtomWalker: The updated walker.

MC_random_walk!(n_steps::Int, lattice::LatticeWalker, h::ClassicalHamiltonian, emax::Float64; energy_perturb::Float64=0.0)

Perform a Monte Carlo random walk on the lattice system.

Arguments

• n_steps::Int: The number of Monte Carlo steps to perform.
• lattice::LatticeWalker: The walker to perform the random walk on.
• h::ClassicalHamiltonian: The lattice gas Hamiltonian.
• emax::Float64: The maximum energy allowed for accepting a move.
• energy_perturb::Float64=0.0: The energy perturbation used to make degenerate configurations distinguishable.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• accept_rate::Float64: The acceptance rate of the random walk.
• lattice::LatticeWalker: The updated walker.

MC_random_walk_2D!(n_steps::Int, at::AtomWalker, pot::AbstractPotential, step_size::Float64, emax::typeof(0.0u"eV"); dims::Vector{Int}=[1,2])

Perform a Monte Carlo random walk on the atomic/molecular system in 2D.

Arguments

• n_steps::Int: The number of Monte Carlo steps to perform.
• at::AtomWalker{C}: The walker to perform the random walk on.
• pot::AbstractPotential: The potential energy function for the system.
• step_size::Float64: The maximum distance an atom can move in any direction.
• emax::typeof(0.0u"eV"): The maximum energy allowed for accepting a move.
• dims::Vector{Int}=[1,2]: The dimensions in which the random walk is performed.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• accept_rate::Float64: The acceptance rate of the random walk.
• at::AtomWalker: The updated walker.

MC_rejection_sampling!(lattice::LatticeWalker, h::ClassicalHamiltonian, emax::Float64; energy_perturb::Float64=0.0, max_iter=10_000)

Perform a Monte Carlo rejection sampling on the lattice system.

Arguments

• lattice::LatticeWalker: The walker to perform the rejection sampling on.
• h::ClassicalHamiltonian: The Hamiltonian containing the on-site and nearest-neighbor interaction energies.
• emax::Float64: The maximum energy allowed for accepting a move.
• energy_perturb::Float64=0.0: The energy perturbation used to make degenerate configurations distinguishable.
• max_iter::Int=10_000: The maximum number of iterations to perform.

Returns

• accept_this_walker::Bool: Whether the walker is accepted or not.
• lattice::LatticeWalker: The updated walker.

_build_geometric_cluster(lattice, seed, pivot_gx, pivot_gy, Lx, Ly, Lz, p) -> Vector{Tuple{Int,Int}}

Grow a geometric cluster from seed using BFS with fixed growth probability p. Returns a vector of (site, reflected_site) pairs.

_grid_to_site(gx::Int, gy::Int, gz::Int, Lx::Int, Ly::Int) -> Int

Convert 0-indexed 3D grid coordinates to a 1-indexed site index.

_reflect_site(site::Int, pivot_gx::Int, pivot_gy::Int, Lx::Int, Ly::Int, Lz::Int) -> Int

Compute the point inversion of site through the pivot at grid coordinates (pivot_gx, pivot_gy) with periodic wrapping in x and y. The z-coordinate is preserved (no reflection in the non-periodic z direction).

_site_to_grid(site::Int, Lx::Int, Ly::Int) -> Tuple{Int,Int,Int}

Convert a 1-indexed site index to 0-indexed 3D grid coordinates (gx, gy, gz) for a single-basis square lattice. Site ordering: x varies fastest, then y, then z.

free_component_index(at::AtomWalker{C}) where C

Get the indices of the free particles in each component of the AtomWalker.

Returns

• ind_free_parts::Array{Vector{Int}}: An array of vectors containing the indices of the free particles in each component.

free_par_index(at::AtomWalker{C}) where C

Get the indices of the free particles in the AtomWalker.

generate_random_new_lattice_sample!(lattice::SLattice)

Generate a new random sample for the single-component lattice system.

generate_random_new_lattice_sample!(lattice::MLattice{C}) where C

Generate a new random sample for the multi-component lattice system.

Arguments

• lattice::MLattice{C}: The lattice system to generate a new sample for.

Returns

• lattice::MLattice{C}: The updated lattice system.

geometric_cluster_swap!(lattice::MLattice{C,SquareLattice}, p::Float64) where C

Perform a geometric cluster move on a square lattice by point inversion through a random pivot.

A random pivot site and seed site are chosen on the periodic lattice. A cluster of sites is grown from the seed via BFS, adding first-shell neighbors with fixed probability p (independent of the configuration). Each site in the cluster is paired with its reflection through the pivot, and the occupation states of each pair are swapped across all components.

Because cluster growth does not depend on the occupancy field, the proposal is symmetric: P(cluster | configA) = P(cluster | configB). This means no Metropolis correction is needed; in nested sampling, one simply checks Eproposed < Emax.

The parameter p controls the average cluster size: p ≈ 0 gives single-site moves, p → 1 gives lattice-spanning clusters.

Arguments

• lattice::MLattice{C,SquareLattice}: The lattice to perform the cluster move on.
• p::Float64: Growth probability for BFS cluster construction (0 < p < 1).

Returns

• lattice::MLattice{C,SquareLattice}: The mutated lattice after the cluster swap.

Notes

• Preserves per-component particle counts exactly.
• The move is self-inverse for a fixed cluster: applying the same cluster swap twice restores the original configuration.
• Supports 2D (supercell_dimensions[3] == 1) and 3D lattices. In 3D, the reflection operates in the periodic xy-plane; the z-coordinate is preserved.

References

• Heringa & Blöte, Phys. Rev. E 57, 4976 (1998) — geometric cluster MC framework.
• Adaptation uses fixed growth probability (configuration-independent) for symmetric proposals.

lattice_random_walk!(lattice::SLattice)

Perform a Monte Carlo random walk on the single-component lattice system.

Arguments

• lattice::SLattice: The single-component lattice system to perform the random walk on.

Returns

• lattice::SLattice: The proposed lattice after the random walk.

lattice_random_walk!(lattice::MLattice{C,G}) where {C,G}

Perform a Monte Carlo random walk on the multi-component lattice system.

Arguments

• lattice::MLattice{C,G}: The multi-component lattice system to perform the random walk on.

Returns

• lattice::MLattice{C,G}: The proposed lattice after the random walk.

mean_sq_displacement(at::AtomWalker, at_orig::AtomWalker)

Calculate the mean squared displacement before and after random walk(s). Note that due to the current implementation of the periodic boundary wrap, this function is not appropriate to use for calculating mean displacements in a propagation.

Arguments

• at::AtomWalker{C}: The current AtomWalker after the random walk.
• at_orig::AtomWalker{C}: The original AtomWalker before the random walk.

Returns

• distsq::typeof(0.0u"Å"^2): The mean squared displacement of all free particles.

periodic_boundary_wrap!(pos::SVector{3,T}, system::AbstractSystem) where T

Wrap the position vector pos according to the periodic boundary conditions of the system. If the boundary condition is Periodic(), the position is wrapped using the modulo operator. If the boundary condition is DirichletZero(), the position is wrapped by reflecting the position vector across the boundary.

Arguments

• pos::SVector{3,T}: The position vector to be wrapped.
• system::AbstractSystem: The system containing the periodic boundary conditions.

Returns

The wrapped position vector.

single_atom_random_walk!(at::AtomWalker, pot::AbstractPotential, step_size::Float64)

Perform a single atom random walk on the AtomWalker object at using the potential pot and a specified step_size.

Arguments

• at::AtomWalker{C}: The walker to perform the random walk on.
• pot::AbstractPotential: The potential energy function for the system.
• step_size::Float64: The maximum distance an atom can move in any direction.

Returns

• at::AtomWalker: The updated walker after the random walk.

single_atom_random_walk!(pos::SVector{3,T}, step_size::Float64) where T

Perform a single atom random walk by updating the position pos in each direction by a random amount. The step_size determines the maximum distance the atom can move in any direction.

Arguments

• pos::SVector{3,T}: The current position of the atom as a 3D vector.
• step_size::Float64: The maximum distance the atom can move in any direction.

Returns

• pos: The updated position of the atom.

swap_empty_occupied_sites!(lattice::MLattice{C,G}, hop_from::Int, hop_to::Int) where {C,G}

Swap the occupation state of two sites in the lattice of any component.

Arguments

• lattice::MLattice{C,G}: The lattice to perform the swap on.
• hop_from::Int: The index of the site to hop from.
• hop_to::Int: The index of the site to hop to.

Returns

• lattice::MLattice{C,G}: The updated lattice after the swap.

swap_occupied_sites_across_components!(lattice::MLattice{C,G}, hop_from::Int, hop_to::Int) where {C,G}

Swap the occupation state of two sites across different components in the lattice.

Arguments

• lattice::MLattice{C,G}: The lattice to perform the swap on.
• hop_from::Int: The index of the site to hop from.
• hop_to::Int: The index of the site to hop to.

Returns

• lattice::MLattice{C,G}: The updated lattice after the swap.

two_atoms_swap!(at::AtomWalker{C}, ind1, ind2) where C

Swap the positions of two atoms in the AtomWalker.

Arguments

• at::AtomWalker{C}: The AtomWalker object.
• ind1::Int: The index of the first atom.
• ind2::Int: The index of the second atom.

Returns

• at::AtomWalker{C}: The updated AtomWalker.