AbstractLiveSets

AbstractLiveSets

Module for defining the livesets, which are collections of walkers that are used in the sampling schemes.

struct GenericAtomWalkers{P<:AbstractPotential} <: AtomWalkers

The GenericAtomWalkers struct represents a collection of atom walkers interacting through any AbstractPotential, for potential types that have no dedicated walker collection (for example the analytic reference potential IdealGasParameters).

Fields

• walkers::Vector{AtomWalker{C}}: A vector of atom walkers, where C is the number of components.
• potential::P: The potential.

Constructor

• GenericAtomWalkers(walkers::Vector{AtomWalker{C}}, pot::P; assign_energy=true): Constructs a new GenericAtomWalkers object with the given walkers and potential. If assign_energy=true, each walker's frozen-part and total energies are assigned through the single-walker assign_frozen_energy! and assign_energy! paths, honoring list_num_par and frozen.

Initial scope: no constant-frozen-part caching (each walker's frozen part is computed individually), and canonical nested sampling flows through the generic AbstractPotential fallback of MC_random_walk! (full-energy evaluation per step), a performance note rather than a defect.

struct GuptaAtomWalkers <: AtomWalkers

The GuptaAtomWalkers struct represents a collection of atom walkers that interact with each other using the Gupta potential.

Fields

• walkers::Vector{AtomWalker{C}}: A vector of atom walkers, where C is the number of components.
• potential::Union{GuptaParameters, CompositeParameterSets{C, GuptaParameters}}: The Gupta potential parameters. See GuptaParameters for more details.

struct LJAtomWalkers <: AtomWalkers

The LJAtomWalkers struct represents a collection of atom walkers that interact with each other using the Lennard-Jones potential.

Fields

• walkers::Vector{AtomWalker{C}}: A vector of atom walkers, where C is the number of components.
• potential::AbstractPotential: The Lennard-Jones potential parameters. See AbstractPotential.

Constructor

• LJAtomWalkers(walkers::Vector{AtomWalker{C}}, pot::AbstractPotential; assign_energy=true): Constructs a new LJAtomWalkers object with the given walkers and Lennard-Jones potential parameters. If assign_energy=true, the energy of each walker is assigned using the Lennard-Jones potential.

struct LJSurfaceWalkers <: AtomWalkers

The LJSurfaceWalkers struct represents a collection of atom walkers interacting through a Lennard-Jones potential, with the presence of an external surface object wrapped in an AtomWalker.

Fields

• walkers::Vector{AtomWalker{C}}: A vector of atom walkers, where C is the number of components.
• pot::CompositeParameterSets{CP, LJParameters}: The Lennard-Jones parameter sets. The surface energy paths evaluate walker components against the surface as an appended LAST component, so the parameter set must carry CP = C + 1 components (walker components first, surface last); the constructors validate this and throw an ArgumentError on a mismatch. A bare LJParameters is not accepted: no surface energy path can evaluate it.
• surface::AtomWalker{CS}: An atom walker representing the surface, where CS is the number of components of the surface.

The frozen-part energy convention

The constructors READ surface.energy_frozen_part and copy it into every walker; they do not compute it unless asked. Callers must either assign the adsorbent self-energy before construction (idiom: surface.energy_frozen_part = interacting_energy(surface.configuration, lj)) or pass compute_frozen_energy=true, which computes it from the surface configuration with the parameter set's surface-surface entry. Under the field's 0.0u"eV" default, walker energies silently omit the entire adsorbent self-energy: within one liveset that is a constant shift, but any quantity comparing totals across systems or conventions inherits it as an error.

Constructor

• LJSurfaceWalkers(walkers::Vector{AtomWalker{C}}, pot::CompositeParameterSets{CP, LJParameters}, surface::AtomWalker{CS}; assign_energy=true, compute_frozen_energy=false)

  Constructs a new LJSurfaceWalkers object with the given walkers, Lennard-Jones parameter sets, and a single surface walker. If assign_energy=true, the energy of each walker is assigned using the Lennard-Jones parameters and the surface.

• `LJSurfaceWalkers(walkers::Vector{AtomWalker{C}}, pot::CompositeParameterSets{CP, LJParameters}, surface::AtomWalker{CS}, assignenergyparallel::Symbol; computefrozenenergy=false, ) where {C, CP, CS}

  Constructs a new LJSurfaceWalkers object with the given walkers, Lennard-Jones parameter sets, and a single surface walker. The assign_energy_parallel argument determines whether to assign energy in parallel using threads (:threads) or distributed processes (:distributed).

LJSurfaceWalkers(walkers::Vector{AtomWalker{C}},
                        pot::CompositeParameterSets{CP, LJParameters},
                        surface::AtomWalker{CS},
                        assign_energy_parallel::Symbol;
                        compute_frozen_energy=false,
                        ) where {C, CP, CS}

Constructs a new LJSurfaceWalkers object with the given walkers, Lennard-Jones parameter sets, and a single surface walker. The assign_energy_parallel argument determines whether to assign energy in parallel using threads (:threads) or distributed processes (:distributed). The parameter set must carry CP = C + 1 components (walker components first, surface last; validated with an ArgumentError), and surface.energy_frozen_part is read, not computed, unless compute_frozen_energy=true; see LJSurfaceWalkers.

Arguments

• walkers::Vector{AtomWalker{C}}: A vector of atom walkers, where C is the number of components.
• pot::CompositeParameterSets{CP, LJParameters}: The Lennard-Jones parameter sets.
• surface::AtomWalker{CS}: An atom walker representing the surface, where CS is the number of components of the surface.
• assign_energy_parallel::Symbol: The method to use for parallel energy assignment. Can be :threads or :distributed.
• compute_frozen_energy::Bool: Whether to compute surface.energy_frozen_part from the surface configuration before assigning walker energies. Default is false (the field is read as-is).

Returns

• LJSurfaceWalkers: A new LJSurfaceWalkers object with the assigned energy.

struct LatticeGasWalkers <: LatticeWalkers

The LatticeGasWalkers struct represents a collection of lattice walkers for a lattice gas system. It is a subtype of LatticeWalkers.

Fields

• walkers::Vector{LatticeWalker{C}}: A vector of lattice walkers.
• hamiltonian::ClassicalHamiltonian: The lattice Hamiltonian associated with the walkers.

Constructors

• LatticeGasWalkers(walkers::Vector{LatticeWalker{C}}, hamiltonian::ClassicalHamiltonian; assign_energy=true, perturb_energy::Float64=0.0): Constructs a new LatticeGasWalkers object with the given walkers and Hamiltonian. If assign_energy is true, the energy of each walker is assigned using the provided Hamiltonian. The optional perturb_energy parameter can be used to add a small perturbation to the assigned energy.

struct MLIPAtomWalkers <: AtomWalkers

The MLIPAtomWalkers struct represents a collection of atom walkers that interact with each other using a machine learning interatomic potential (MLIP).

Fields

• walkers::Vector{AtomWalker{C}}: A vector of atom walkers, where C is the number of components.
• potential::PyMLPotential: The machine learning interatomic potential wrapped in a PyMLPotential.

Constructor

• MLIPAtomWalkers(walkers::Vector{AtomWalker{C}}, pot::PyMLPotential; assign_energy=true): Constructs a new MLIPAtomWalkers object with the given walkers and MLIP potential. If assign_energy=true, the energy of each walker is assigned using the MLIP potential.

_check_cluster_sites(hamiltonian, cfg)

One-time check at run setup (the LatticeGasWalkers constructor and the raw-lattice wang_landau/nvt_monte_carlo entry points): a ClusterLatticeHamiltonian whose embeddings reference site indices beyond the lattice was built for a different lattice; failing here with a descriptive ArgumentError beats a BoundsError from deep inside the energy kernel. A SiteFieldLatticeHamiltonian delegates the check to its wrapped base; a no-op for every other Hamiltonian type. The converse mismatch — a Hamiltonian enumerated on a smaller lattice, whose indices all exist but whose embeddings have wrong geometry — is undetectable from indices alone and remains the caller's responsibility: always enumerate on the lattice being sampled.

_check_field_length(hamiltonian, cfg)

One-time check at run setup (the LatticeGasWalkers constructor and the raw-lattice wang_landau/nvt_monte_carlo entry points): a SiteFieldLatticeHamiltonian whose field length differs from the number of lattice sites was built for a different lattice; failing here with a descriptive ArgumentError beats a DimensionMismatch from inside the energy kernel. A no-op for every other Hamiltonian type. A field of the right length built for a different lattice of the same size is undetectable from the length alone and remains the caller's responsibility: always build the field (e.g. with layer_field) on the lattice being sampled.

_warn_uncoupled_shells(cfg_or_walkers, hamiltonian)

One-time check at run setup: warn when the lattice carries more neighbor shells (cutoff_radii) than the Hamiltonian couples, since the outer shells then contribute exactly zero energy — silently, if unnoticed. The converse mismatch (more coupled shells than the lattice provides) throws an ArgumentError at energy evaluation instead. Complements the empty-shell warning emitted by compute_neighbors at lattice construction. Called from the LatticeGasWalkers constructor and from the lattice entry points of wang_landau and nvt_monte_carlo, which take a raw lattice and never build a liveset.

assign_energy!(walker::AtomWalker, pot::AbstractPotential, surface::AtomWalker)

Assigns the energy to the given walker using the an AbstractPotential pot with an external surface.

Arguments

• walker::AtomWalker: The walker object to assign the energy to.
• pot::AbstractPotential: The potential parameters.
• surface::AtomWalker: The surface walker object to consider in the energy calculation.

Returns

• walker::AtomWalker: The walker object with the assigned energy.

assign_energy!(walker::AtomWalker, pot::AbstractPotential)

Assigns the energy to the given walker using the an AbstractPotential pot.

Arguments

• walker::AtomWalker: The walker object to assign the energy to.
• pot::AbstractPotential: The potential parameters.

Returns

• walker::AtomWalker: The walker object with the assigned energy.

assign_energy!(walker::Vector{AtomWalker{C}}, pot::AbstractPotential) where C

Assigns the energy to each walker in walker using an AbstractPotential pot.

Arguments

• walker::Vector{AtomWalker{C}}: A vector of walker objects to assign the energy to, where C is the number of components.
• pot::AbstractPotential: The abstract potential to use for energy assignment.

Returns

• walker::Vector{AtomWalker{C}}: The vector of walker objects with the assigned energy.

assign_energy!(walkers::Vector{AtomWalker{C}}, pot::Union{LJParameters, CompositeParameterSets{C, LJParameters}}; assign_energy=true, const_frozen_part=true) where C

Assigns the energy to each walker in walkers using the a single-component or multi-component Lennard-Jones potential pot. If const_frozen_part=true, the frozen part of the energy is calculated only once for the first walker and assigned to all walkers. If assign_energy=true, the energy is assigned to each walker.

Arguments

• walkers::Vector{AtomWalker{C}}: A vector of walker objects to assign the energy to, where C is the number of components.
• pot::Union{LJParameters, CompositeParameterSets{C, LJParameters}}: The potential parameters.
• assign_energy::Bool=true: Whether to assign the energy to each walker.
• const_frozen_part::Bool=true: Whether to calculate the frozen part of the energy only once for the first walker and assign it to all walkers.

Returns

• walkers::Vector{AtomWalker{C}}: The vector of walker objects with the assigned energy.

assign_energy!(walker::LatticeWalker{C}, hamiltonian::ClassicalHamiltonian; perturb_energy::Float64=0.0)

Assigns energy to the given walker based on the hamiltonian. If perturb_energy is non-zero, a small random perturbation is added to the energy.

The energy comes from interacting_energy(walker.configuration, hamiltonian), which must return an energy-dimensioned Unitful.Quantity (eV-convertible); a method returning anything else, e.g. a plain Float64 from a custom Hamiltonian, raises a descriptive ArgumentError here rather than a DimensionError from the assignment arithmetic. This is the one return-type obligation of the custom-Hamiltonian extension contract (see the Custom Hamiltonians documentation page).

Arguments

• walker::LatticeWalker{C}: The walker to assign energy to.
• hamiltonian::ClassicalHamiltonian: The Hamiltonian used to calculate the energy.
• perturb_energy::Float64=0.0: The amount of random perturbation to add to the energy.

Returns

• walker::LatticeWalker{C}: The walker with the assigned energy.

assign_frozen_energy!(walker::AtomWalker, pot::AbstractPotential)

Assigns the frozen energy to the given walker using the an AbstractPotential pot.

Arguments

• walker::AtomWalker: The walker object to assign the energy to.
• pot::AbstractPotential: The potential parameters.

Returns

• walker::AtomWalker: The walker object with the assigned energy.