Sampling Schemes

SamplingSchemes

Module for defining the sampling schemes.

mutable struct AtomisticIGRefGCNSParameters <: SamplingParameters

Parameters for atomistic ideal-gas-referenced grand-canonical nested sampling. The sampler is athermal: the temperature never enters a run, and the chemical potential enters only through the ordering scalar when chemical_potential is nonzero (the default keeps the energy-sorted construction); both enter the post-run reduction to Ξ(μ, T), which reweights the recorded (E, N) record to any target.

Fields

• mc_steps::Int64: MCMC steps per replacement walker.
• reference_activity::typeof(1.0u"Å^-3"): The reference activity z0 (dimension inverse volume). The driver folds the dimensionless z0V once from the walkers' shared orthorhombic cell.
• species::Symbol: Chemical identity of inserted particles, passed explicitly because a walker's configuration may be empty.
• initial_step_size::Float64: Initial displacement step size (Angstrom).
• step_size::Float64: Current displacement step size (mutable runtime state).
• step_size_lo::Float64: Lower bound for the step-size adjustment.
• step_size_up::Float64: Upper bound for the step-size adjustment.
• accept_range::Tuple{Float64,Float64}: Acceptance-rate window forwarded to the step-size adjustment.
• fail_count::Int64: Consecutive failed replacements.
• allowed_fail_count::Int64: Maximum consecutive failures before the driver's stall contract fires (see ideal_gas_referenced_nested_sampling). The default (100, matching the canonical atomistic loop) suits interacting descents, where a run of failed replacements is an ordinary sampling hiccup rather than a terminal state.
• plateau_refill_target::Int64: Live-set size to restore after a plateau eviction block (mutable runtime state; reset at driver entry when initialize=true and carried across initialize=false continuations, which own it: a chunked driver restores it from its own checkpoint).
• refill_fail_budget::Int64: Failure budget for one plateau-refill loop. The default 0 keeps the historical behavior of charging refill failures against allowed_fail_count cumulatively; a positive value gives each refill loop its own budget, so recovering from one difficult plateau block cannot permanently shrink the live set within the stall budget.
• move_stats::Dict{Symbol,Int}: Run-total per-move-type attempt/accept counters accumulated from every ordinary-cull decorrelation walk (cleared once at run start; plateau-refill walks are not accumulated).
• n_max::Int64: Upper bound on the particle count, for BOUNDED constructions. The default typemax(Int64) keeps the historical unbounded reference measure draw-for-draw (initialization consumes the identical RNG stream and the kernel guard never fires). A finite n_max defines a different, truncated reference measure — the conditional Poisson on 0:n_max — and is exact for that measure only when all three legs move together: initialization draws the truncated law, the kernel guard-skips insertions above the cap (a null proposal, Metropolis- correct on the truncated measure), and the post-run reduction is normalized by the truncated reference mass. A finite n_max therefore OBLIGATES passing the same n_max to gc_thermodynamic_stats_ideal_ref; mixing a capped run with the unbounded e^{z0V} normalization overstates logXi by exactly -log P(Poisson(z0V) <= n_max) (the surplus reference mass above the cap).
• chemical_potential::typeof(0.0u"eV"): Chemical potential of the ORDERING scalar. The step sorts, detects plateaus, selects parents, and accepts on Ω = E − μN (the grand potential of the lattice grand-canonical construction, GrandCanonicalNestedSamplingParameters), never through the acceptance ratios or the reference measure: insertions and deletions keep the z0-weighted Metropolis factors, and the ceiling indicator is evaluated on the proposal's own Ω, so a particle-number move faces the per-sector energy ceiling Ω* + μ Nafter. The default 0.0u"eV" keeps the energy-sorted construction bit-for-bit: every added term is an exact zero addend, no random draw is added or reordered, and the ledger schema is unchanged. A nonzero μ orders the descent toward the grand ground state of that μ and adds an :omega column recording the culled walker's Ω; :emax still records its energy, so `gcthermodynamicstatsidealrefconsumes the ledger unchanged (its reweighting factor is a function of the recorded (E, N) alone and it never assumes:emaxis monotone) and any target (μ', T') remains reachable by the same post-run reweighting. The reweighting exponent is-β(E - μ'N) - N ln(z0 Λ(T)^3), so for a target temperature T the factor depends on a shell through Ω alone along the lineμ' = μ + kB T ln(z0 Λ(T)^3), and at the run's own μ exactly wherez0 Λ(T)^3 = 1(referenceactivitytemperatureinAnalysisTools), the situation in which pooling the particle-number sectors is exact; at the run's own μ elsewhere the residual(z0 Λ(T)^3)^{-N}is carried per recorded shell at a weight-concentration cost measured by the returnedNeff(of order(1e5)^Nper shell for argon-mass particles at z0V of order unity and room temperature, where that temperature is sub-kelvin). A continued block (initialize=false) must use the same μ as its predecessor. Under a nonzero μ the descent may end at an atom of the ordering scalar's law rather than at the ground-state sector; see the stall contract ofidealgasreferencednested_sampling`.

Two fields carried by sibling parameter structs are deliberately absent. No energy_perturbation: exact energy ties are handled by the plateau-aware eviction machinery, and perturbing recorded energies would break the exactly-zero closed-form checks this construction is validated against. No random_seed: the lattice ideal-gas-referenced sibling documents its field as not consumed by the sampling loop; seed the global RNG before the run instead.

AtomisticIGRefGCNSParameters(;
    mc_steps=100, reference_activity=0.01u"Å^-3", species=:H,
    initial_step_size=0.5, step_size=0.5, step_size_lo=0.01, step_size_up=2.0,
    accept_range=(0.25, 0.75), fail_count=0, allowed_fail_count=100,
    plateau_refill_target=0, refill_fail_budget=0, move_stats=Dict{Symbol,Int}(),
    n_max=typemax(Int64), chemical_potential=0.0u"eV")

Convenience constructor for AtomisticIGRefGCNSParameters. reference_activity (z0) must be positive; choose it so z0V sits near the particle-number range of interest, as post-run reweighting to a target (μ, T) carries a factor (z/z0)^N per sample whose effective sample size degrades away from the reference. A finite n_max selects the bounded construction (see the field docstring); it must be at least 1, and the same n_max must be passed to gc_thermodynamic_stats_ideal_ref. chemical_potential selects the ordering scalar Ω = E − μN (Unitful, eV; see the field docstring); the default keeps the energy ordering bit-for-bit.

mutable struct GrandCanonicalNestedSamplingParameters <: SamplingParameters

Parameters for grand-canonical nested sampling on lattice systems.

The grand potential Ω = E − μN is used as the sorting quantity. Walkers have variable particle count N, and the NS loop records (Ω, E, N) per iteration for thermodynamic reweighting.

Fields

• mc_steps::Int64: MCMC steps per replacement walker.
• chemical_potential::Float64: Chemical potential μ (unitless, in energy units of the Hamiltonian).
• energy_perturbation::Float64: Perturbation to break energy degeneracies.
• random_seed::Int64: Seed for the random number generator.
• fail_count::Int64: Consecutive failed replacements.
• allowed_fail_count::Int64: Maximum consecutive failures before warning.
• init_occupation_p::Float64: Per-site occupation probability for initial walkers.
• n_max::Int64: Upper bound on particle count per walker.
• cluster_p::Float64: Current cluster growth probability (mutable runtime state).
• cluster_accepted::Float64: Accepted cluster moves in current adjustment window.
• cluster_total::Float64: Total cluster moves attempted in current adjustment window.
• cluster_p_history::Vector{Float64}: Trajectory of cluster_p after each adjustment.
• cluster_accept_history::Vector{Float64}: Acceptance rate at each adjustment.
• cluster_adjust_iterations::Vector{Int}: NS iteration index at each adjustment.
• move_stats::Dict{Symbol,Int}: Run-total per-move-type attempt/accept counters accumulated from every decorrelation walk (keys match the walk's move_stats NamedTuple; cleared once at run start, never window-reset).

GrandCanonicalNestedSamplingParameters(;
    mc_steps=100, chemical_potential=0.0, energy_perturbation=1e-12,
    random_seed=1234, fail_count=0, allowed_fail_count=10,
    init_occupation_p=0.5, n_max=typemax(Int64),
    cluster_p=0.3, cluster_accepted=0.0, cluster_total=0.0,
    cluster_p_history=Float64[], cluster_accept_history=Float64[],
    cluster_adjust_iterations=Int[], move_stats=Dict{Symbol,Int}())

Convenience constructor for GrandCanonicalNestedSamplingParameters.

The n_max parameter sets an upper bound on the number of particles per walker. Insertions are rejected when N ≥ n_max. Default is typemax(Int64) (no cap).

The cluster_* fields are mutable runtime state for adaptive cluster move tuning. They are initialized from the static configuration on MCGrandCanonicalMoves at the start of grand_canonical_nested_sampling when clusters_freq > 0.

move_stats holds run-total per-move-type attempt/accept counters accumulated from every decorrelation walk (keys match the walk's move_stats NamedTuple; never window-reset, cleared once at the start of each run).

mutable struct IdealGasReferencedGCNSParameters <: SamplingParameters

Parameters for ideal-gas-referenced grand-canonical nested sampling on lattice systems.

The prior is the non-interacting (ideal) lattice gas at reference fugacity z0: a Bernoulli product measure in which each site is occupied independently with probability p0 = z0/(1 + z0), so a configuration with N particles carries prior weight z0^N and the total prior mass on M sites is (1 + z0)^M. Nested sampling culls on the energy E alone — the chemical potential does not enter the sampler. Both μ and T are recovered in post-processing (see gc_thermodynamic_stats_ideal_ref in AnalysisTools), so a single run yields Ξ(μ, T) over a continuous temperature range and a neighborhood of μ around μ_ref(T) = k_B T ln z0.

Setting reference_fugacity = 1 makes the prior the uniform measure over all 2^M microstates — the same prior as the Ω-sorted construction in GrandCanonicalNestedSamplingParameters, which instead bakes a single μ into the sort quantity Ω = E − μN.

Unlike the Ω-sorted construction there is deliberately no n_max field: the post-processing normalization (1 + z0)^M is the prior mass of the full occupation range N ∈ {0, …, M}, and capping insertions would silently truncate the prior support and bias Ξ.

Fields

• mc_steps::Int64: MCMC steps per replacement walker.
• reference_fugacity::Float64: Reference fugacity z0 of the ideal-lattice-gas prior.
• energy_perturbation::Float64: Perturbation to break energy degeneracies. Required to be nonzero on lattices (degenerate levels stall the strict < ceiling and bias the evidence — enforced by the keyword constructor); must remain ≪ kB·T at the lowest temperature targeted in post-processing, since perturbed energies are recorded. It must also stay above the float resolution of the largest energies on the ladder — keep `energyperturbation / eps(Emax)above ~K²so theKwalkers draw distinct tie-breaking values on a degenerate plateau. The default1e-12satisfies that only forEmaxup toO(1) eV; finite-J hard-core ladders reachEmax = J·M·c/2, so use1e-9there (safe throughEmax ≈ 10³ eV, i.e. a few hundred sites atJ = 1 eV) and scale it proportionally beyond — see the hard-core recipe in theGenericLatticeHamiltonian` docstring.
• random_seed::Int64: Kept for parity with GrandCanonicalNestedSamplingParameters; not currently consumed by the NS loop — call Random.seed! before ideal_gas_referenced_nested_sampling for reproducible runs.
• fail_count::Int64: Consecutive failed replacements.
• allowed_fail_count::Int64: Maximum consecutive failures before warning.
• cluster_p::Float64: Current cluster growth probability (mutable runtime state).
• cluster_accepted::Float64: Accepted cluster moves in current adjustment window.
• cluster_total::Float64: Total cluster moves attempted in current adjustment window.
• cluster_p_history::Vector{Float64}: Trajectory of cluster_p after each adjustment.
• cluster_accept_history::Vector{Float64}: Acceptance rate at each adjustment.
• cluster_adjust_iterations::Vector{Int}: NS iteration index at each adjustment.
• move_stats::Dict{Symbol,Int}: Run-total per-move-type attempt/accept counters accumulated from every decorrelation walk (keys match the walk's move_stats NamedTuple; cleared once at run start, never window-reset).

IdealGasReferencedGCNSParameters(;
    mc_steps=100, reference_fugacity=1.0, energy_perturbation=1e-12,
    random_seed=1234, fail_count=0, allowed_fail_count=10,
    cluster_p=0.3, cluster_accepted=0.0, cluster_total=0.0,
    cluster_p_history=Float64[], cluster_accept_history=Float64[],
    cluster_adjust_iterations=Int[], move_stats=Dict{Symbol,Int}())

Convenience constructor for IdealGasReferencedGCNSParameters.

reference_fugacity (z0) must be positive. Choose z0 near the target fugacity range exp(βμ) of interest: post-run reweighting to a target (μ, T) carries a factor (exp(βμ)/z0)^N per sample, and its effective sample size degrades as |βμ − ln z0| grows (roughly beyond 1/√Var(N)).

The cluster_* fields are mutable runtime state for adaptive cluster move tuning, initialized from the static configuration on MCGrandCanonicalMoves at the start of ideal_gas_referenced_nested_sampling when clusters_freq > 0.

move_stats holds run-total per-move-type attempt/accept counters accumulated from every decorrelation walk (keys match the walk's move_stats NamedTuple; never window-reset, cleared once at the start of each run).

struct MCAtomGrandCanonicalMoves <: MCRoutine

Move routine for atomistic ideal-gas-referenced grand-canonical nested sampling: single-atom displacements mixed with continuous-space insertions and deletions through the atomistic MC_grand_canonical_walk! kernel, optionally cavity-biased through the kernel's deterministic grid-cell channel (p_bias, bias_radius, bias_grid, forwarded verbatim; the defaults keep the uniform channel and its random stream bit-identically). Deliberately lean otherwise: the lattice MCGrandCanonicalMoves carries cluster configuration that has no continuous-space counterpart, and silently ignored fields on a mismatched routine are a known hazard class.

Fields

• p_move::Float64: Probability of a displacement move.
• p_insert::Float64: Probability of an insertion move (deletion takes the remainder).
• step_rate_source::Symbol: Which acceptance rate drives the step-size adjustment. :mixed (the default) keeps the historical behavior, adapting on the kernel's combined rate over all three channels; :move adapts on the displacement-only rate from the walk's per-channel counters, so a collapsing insertion or deletion acceptance in a dense interacting system cannot drag the displacement step size down against a healthy displacement channel (adjustment is skipped when a walk attempted no displacement).
• mc_steps_per_particle::Float64: Extra kernel steps per parent particle: a decorrelation walk for a parent at particle count N runs mc_steps + round(Int, mc_steps_per_particle * N) steps, restoring per-sweep decorrelation as the count grows. The default 0.0 is draw-count identical to the historical fixed-length walk.

struct MCDistributed <: MCRoutineParallel

A type for generating new walkers by performing random walks for decorrelation in parallel using Distributed.jl.

Fields

• n_cull::Int64: The number of lowest-energy walkers to cull (replace) in each iteration. The default is 1.
• n_decorr::Int64: The number of walkers to use for decorrelation (random walks). The default is nworkers() - 1.
• dims::Vector{Int64}: The dimensions along which to perform the random walks.

struct MCGalileanWalk <: MCRoutine

Move routine for canonical atomistic nested sampling through the Galilean reflective walk kernel MC_galilean_walk!: all free particles move collectively along straight lines, reflecting off the constraint boundary through the energy gradient. Clone semantics (a random survivor is cloned and decorrelated); three-dimensional only. ns_params.mc_steps sets the number of trajectories per replacement and ns_params.step_size the 3N-space segment length, adapted through the standard step-size machinery on the segment rate.

Fields

• n_refresh::Int: Straight-line segments per trajectory (velocity redrawn between trajectories).

struct MCGrandCanonicalMoves <: MCRoutine

A type for generating a new walker using grand-canonical MCMC moves that mix fixed-N moves (local swaps and/or geometric cluster moves) with single-site particle insertion and deletion.

Fields

• p_move::Float64: Probability of a fixed-N move per MCMC step (default 0.5).
• p_insert::Float64: Probability of a particle insertion per step (default 0.25). The deletion probability is 1 - p_move - p_insert.
• clusters_freq::Int: Relative weight of cluster moves within the fixed-N branch (default 0 = disabled).
• swaps_freq::Int: Relative weight of local swaps within the fixed-N branch (default 1).
• initial_cluster_p::Float64: Starting growth probability for geometric cluster moves (default 0.3).
• target_cluster_accept::Float64: Target acceptance rate for adaptive cluster p tuning (default 0.3).
• cluster_adjust_interval::Int: Number of NS iterations between cluster p adjustments (default 50).
• cluster_p_floor::Float64: Lower bound for adaptive cluster p (default 0.01).
• cluster_p_ceiling::Float64: Upper bound for adaptive cluster p (default 1.0).
• p_bias::Float64: Probability an insertion draws from the biased site set (default 0.0 = legacy uniform insertions).
• bias_predicate::Symbol: Biased-set predicate, :contact or :cavity (default :contact).
• bias_shells::Int: Neighbor shells scanned by the predicate (default 1).
• incremental::Bool: Opt-in incremental energy evaluation in the walk kernel (default false = the shipped full-recompute arithmetic, draw-count and digit identical). When true, non-cluster proposals under a Hamiltonian with supports_site_deltas advance a per-walk raw-energy anchor by exact O(z) site_flip_delta sums; cluster proposals and unsupported Hamiltonians fall back to the full recompute, which also re-anchors the accumulator. The delta path accumulates energy in a different floating-point order, so same-seed trajectories are not digit-identical to the default; flipping the default is deliberately out of scope (a published-run reproducibility contract).
• swap_mode::Symbol: Local-swap proposal distribution, :uniform_pair (default; the shipped uniform site-pair draw, in which equal-occupancy pairs are accepted no-ops counted by the swap_null_* subset counters) or :occupied_empty (opt-in; hop_from uniform over occupied sites and hop_to uniform over empty sites, symmetric with no acceptance correction, zero nulls by construction, guard-skipped on empty and full lattices). :occupied_empty changes the random stream and stays off by default.

When clusters_freq == 0 (the default), the fixed-N branch uses only local swaps (lattice_random_walk!), preserving backward compatibility with existing scripts. When clusters_freq > 0, the fixed-N branch mixes geometric cluster moves with local swaps according to the clusters_freq:swaps_freq ratio.

With p_bias > 0 insertions mix a sub-channel restricted to lattice_biased_sites(x; predicate=bias_predicate, shells=bias_shells) into the uniform proposal; the walk's composite Metropolis-Hastings correction keeps the sampled prior unchanged. p_bias = 1.0 constructs but warns: the pure biased channel freezes N whenever the biased set is empty, so the uniform sub-channel is what repairs ergodicity.

struct MCMixedMoves <: MCRoutine

A type for generating a new walker by performing a mix of random walks, atom swaps, and/or geometric cluster moves. For atomistic systems, the walks_freq and swaps_freq fields control the ratio of random walks to atom swaps. For lattice systems, walks_freq and clusters_freq control the ratio of local swap moves to geometric cluster moves.

Fields

• walks_freq::Int: The frequency of random walks (atomistic) or local swaps (lattice) to perform.
• swaps_freq::Int: The frequency of atom swaps to perform (atomistic only).
• clusters_freq::Int: The frequency of geometric cluster moves to perform (lattice only, default 0).
• initial_cluster_p::Float64: Starting growth probability for cluster moves (default 0.3).
• target_cluster_accept::Float64: Target acceptance rate for adaptive cluster p tuning (default 0.3).
• cluster_adjust_interval::Int: Number of NS iterations between cluster p adjustments (default 50).
• cluster_p_floor::Float64: Lower bound for adaptive cluster p (default 0.01).
• cluster_p_ceiling::Float64: Upper bound for adaptive cluster p (default 1.0).

struct MCMixedMovesParallel <: MCRoutineParallel

A type for generating a new walker by performing random walks and swapping atoms in parallel. Currently, it is intended to use this routine for multi-component systems. The actual number of random walks and swaps to perform is determined by the weights of the fields walks_freq and swaps_freq. For example, if walks_freq=4 and swaps_freq=1, then the probability of performing a random walk is 4/5, and the probability of performing a swap is 1/5.

Fields

• walks_freq::Int: The frequency of random walks to perform.
• swaps_freq::Int: The frequency of atom swaps to perform.

struct MCNewSample <: MCRoutine

A type for generating a new walker from a random configuration. Currently, it is intended to use this routine for lattice gas systems.

struct MCRandomWalkClone <: MCRoutine

A type for generating a new walker by cloning an existing walker and performing a random walk for decorrelation.

struct MCRandomWalkCloneParallel <: MCRoutineParallel

A type for generating a new walker by cloning an existing walker and performing a random walk for decorrelation in parallel.

struct MCRandomWalkMaxE <: MCRoutine

A type for generating a new walker by performing a random walk for decorrelation on the highest-energy walker.

MCRandomWalkMaxEParallel <: MCRoutineParallel

A type for generating a new walker by performing a random walk for decorrelation on the highest-energy walker(s) in parallel.

struct MCRejectionSampling <: MCRoutine

A type for generating a new walker by performing rejection sampling. Currently, it is intended to use this routine for lattice gas systems.

abstract type MCRoutine

An abstract type representing a Monte Carlo routine.

Currently, the following concrete types are supported:

• MCRandomWalkMaxE: A type for generating a new walker by performing a random walk for decorrelation on the

highest-energy walker.

• MCRandomWalkClone: A type for generating a new walker by cloning an existing walker and performing a random walk

for decorrelation.

• MCNewSample: A type for generating a new walker from a random configuration. Currently, it is intended to use

this routine for lattice gas systems.

• MCMixedMoves: A type for generating a new walker by performing random walks and swapping atoms. Currently, it is

intended to use this routine for multi-component systems. The actual number of random walks and swaps to perform is determined by the weights of the fields walks_freq and swaps_freq. See MCMixedMoves.

• MCRejectionSampling: A type for generating a new walker by performing rejection sampling. Currently, it is intended

to use this routine for lattice gas systems.

• MCDistributed: A type for generating new walkers by performing random walks for decorrelation in parallel using Distributed.jl.

This routine supports multiple culling walkers and multiple decorrelation walkers. See MCDistributed.

abstract type MCRoutineParallel <: MCRoutine

(Internal) An abstract type representing a parallel Monte Carlo routine.

MetropolisMCParameters <: SamplingParameters

Parameters for the Metropolis Monte Carlo algorithm.

Fields

• temperature::Float64: The temperature of the system.
• equilibrium_steps::Int64: The number of steps to equilibrate the system.
• sampling_steps::Int64: The number of steps to sample the system.
• step_size::Float64: The step size for the random walk (for atomistic systems).
• step_size_lo::Float64: The lower bound of the step size.
• step_size_up::Float64: The upper bound of the step size.
• accept_range::Tuple{Float64, Float64}: The range of acceptance rates for adjusting the step size.

e.g. (0.25, 0.75) means that the step size will decrease if the acceptance rate is below 0.25 and increase if it is above 0.75.

• random_seed::Int64: The seed for the random number generator. The monte_carlo_sampling

drivers seed the equilibration phase with random_seed and the production phase with random_seed + 1, so the two phases never share a random stream.

MuVTMCParameters <: SamplingParameters

Parameters for fixed-temperature grand-canonical (μVT) Metropolis sampling of continuous atomistic walkers through MC_muVT_walk!.

Fields

• temperatures::Vector{Float64}: The temperature ladder, in Kelvin.
• activity_volumes::Vector{Float64}: The dimensionless activity-volume zV per temperature (zV = e^(βμ) V / Λ(T)^3, folded by the caller exactly as the kernel documents; the driver never sees μ or Λ). Must match temperatures in length: at fixed μ the activity is temperature-dependent, so each rung carries its own value.
• equilibrium_steps::Int64: Kernel steps of equilibration per temperature, run in ten equal adaptation blocks (documented contract: step-size adjustment acts between blocks on the displacement-only acceptance rate of the block).
• sampling_steps::Int64: Kernel steps of production per temperature, with the step size frozen (adapting during production breaks detailed balance).
• sampling_interval::Int64: Kernel steps between recorded samples.
• step_size::Float64: Displacement step size (Angstrom; mutable runtime state).
• step_size_lo::Float64: Lower bound for the step-size adjustment.
• step_size_up::Float64: Upper bound for the step-size adjustment.
• accept_range::Tuple{Float64,Float64}: Acceptance window for the adjustment.
• random_seed::Int64: Base seed. Temperature rung i seeds equilibration with random_seed + 2(i-1) and production with random_seed + 2(i-1) + 1, so no two phases share a random stream.

mutable struct NestedSamplingParameters <: SamplingParameters

The NestedSamplingParameters struct represents the parameters used in the nested sampling scheme.

Fields

• mc_steps::Int64: The number of total Monte Carlo moves to perform. For a parallel MC routine, this number will be distributed among workers.

If mc_steps is not divisible by the number of workers, the actual number of MC moves per worker will be ceil(mc_steps / nworkers()).

• initial_step_size::Float64: The initial step size, which is the fallback step size if MC routine fails to accept a move.
• step_size::Float64: The on-the-fly step size used in the sampling process.
• step_size_lo::Float64: The lower bound of the step size.
• step_size_up::Float64: The upper bound of the step size.
• accept_range::Tuple{Float64, Float64}: The range of acceptance rates for adjusting the step size.

e.g. (0.25, 0.75) means that the step size will decrease if the acceptance rate is below 0.25 and increase if it is above 0.75.

• fail_count::Int64: The number of failed MC moves in a row.
• allowed_fail_count::Int64: The maximum number of failed MC moves allowed before resetting the step size.
• energy_perturbation::Float64: The perturbation value used to adjust the energy of the walkers.
• random_seed::Int64: The seed for the random number generator.
• cluster_p::Float64: Current cluster growth probability for geometric cluster moves (mutable runtime state).
• cluster_accepted::Float64: Accepted cluster moves in the current adjustment window.
• cluster_total::Float64: Total cluster moves attempted in the current adjustment window.
• cluster_p_history::Vector{Float64}: Trajectory of cluster_p values after each adaptive adjustment.
• cluster_accept_history::Vector{Float64}: Acceptance rate at each adaptive adjustment.
• cluster_adjust_iterations::Vector{Int}: NS iteration index at each adaptive adjustment.
• plateau_refill_target::Int64: Internal bookkeeping for plateau-aware culling in the serial atomistic steps: the live-set size to restore once a block of exact energy ties has been fully evicted without replacement. 0 (the default) means no plateau block is in progress; the field is set and cleared by nested_sampling_step! and should not be set by callers.

struct NestedSamplingParameters

The NestedSamplingParameters struct represents the parameters for various sampling algorithm.

WangLandauParameters

A structure to hold the parameters for the Wang-Landau sampling scheme.

Fields

• num_steps::Int64: The number of Monte Carlo steps.
• flatness_criterion::Float64: The criterion for flatness of the histogram.
• f_initial::Float64: The initial modification factor.
• f_min::Float64: The minimum modification factor.
• energy_bins::Vector{Float64}: The pre-supplied energy bins.
• max_iter::Int64: The maximum number of iterations in each flatness check.
• step_size::Float64: The step size for the random walk (for atomistic systems).
• random_seed::Int64: The seed for the random number generator.

WangLandauParameters(; 
    num_steps::Int64=100,
    flatness_criterion::Float64=0.8,
    f_initial::Float64=Float64(MathConstants.e),
    f_min::Float64=exp(1e-8),
    energy_min::Float64=0.0,
    energy_max::Float64=1.0,
    num_energy_bins::Int64=100,
    max_iter::Int64=1000,
    step_size::Float64=0.01,
    random_seed::Int64=1234
)

Create a WangLandauParameters object with the specified parameters.

Arguments

• num_steps::Int64: The number of Monte Carlo steps.
• flatness_criterion::Float64: The criterion for flatness of the histogram.
• f_initial::Float64: The initial modification factor.
• f_min::Float64: The minimum modification factor.
• energy_min::Float64: The minimum energy.
• energy_max::Float64: The maximum energy.
• num_energy_bins::Int64: The number of energy bins.
• max_iter::Int64: The maximum number of iterations in each flatness check.
• random_seed::Int64: The seed for the random number generator.

Returns

• WangLandauParameters: The parameters for the Wang-Landau sampling scheme.

LatticeNestedSamplingParameters(;
        mc_steps::Int64=100,
        energy_perturbation::Float64=1e-12,
        fail_count::Int64=0,
        allowed_fail_count::Int64=10,
        random_seed::Int64=1234,
        cluster_p::Float64=0.3,
        )

A convenience constructor for NestedSamplingParameters with default values suitable for lattice systems.

_accumulate_cluster_stats!(params::SamplingParameters, mc_routine,
                           cl_accepted::Int, cl_total::Int, ns_iteration::Int)

Accumulate cluster-move acceptance statistics from one decorrelation walk onto params and call adjust_cluster_p when the adjustment window is full. mc_routine supplies the static tuning configuration (cluster_adjust_interval, target_cluster_accept, cluster_p_floor, cluster_p_ceiling). Shared by the grand-canonical nested_sampling_step! methods.

_accumulate_move_stats!(params::SamplingParameters, stats::NamedTuple)

Merge one decorrelation walk's per-move-type attempt/accept counters into params.move_stats as run totals. Unlike the window-reset cluster counters handled by _accumulate_cluster_stats!, these are never reset during a run (the drivers clear them once at run start). Shared by the grand-canonical nested_sampling_step! methods.

_atomistic_igref_z0V(liveset::AtomWalkers, params::AtomisticIGRefGCNSParameters)

Validate the liveset for the atomistic ideal-gas-referenced construction (single unfrozen component per walker, one shared orthorhombic cell) and return the dimensionless product of the reference activity and the cell volume.

_atomistic_igref_z0V(liveset::LJSurfaceWalkers, params::AtomisticIGRefGCNSParameters)

Surface-aware method: the same walker checks as the base (single-component, unfrozen ADSORBATE walkers, one shared orthorhombic cell), accepting the frozen external surface and requiring it to share the walkers' cell. Returns z0V folded from the FULL cell, unconditionally: the reference ideal gas lives in the whole box, and the substrate region is excluded by the energy ceiling, not by the reference measure (consistent with the fixed-N stitch's full-prior-volume convention in AnalysisTools).

_clone_walker_shared_geometry(w::LatticeWalker)

Clone a lattice walker for a replacement walk, copying only its occupancy vectors, energy, and iteration counter while sharing the run-invariant geometry by reference (the Val(:share_geometry) constructor). The geometry fields are never mutated after construction and the lattice drivers are serial loops, so the clone is behaviorally identical to a deepcopy: it draws no randomness and changes no floating-point value.

_grand_potential(walker::AtomWalker{1}, mu::typeof(0.0u"eV")) -> typeof(0.0u"eV")

Compute the ordering scalar Ω = E − μN of an atomistic walker, the continuous counterpart of the lattice method (N = walker.list_num_par[1]). At mu = 0.0u"eV" the product mu * N is an exact +0.0 eV and the subtraction returns walker.energy bit-for-bit, for every finite energy including -0.0.

_grand_potential(walker::LatticeWalker{1}, mu::Float64) -> typeof(0.0u"eV")

Compute Ω = E − μN for a single-component lattice walker.

_init_atomistic_igref_walkers!(liveset::AtomWalkers,
                               params::AtomisticIGRefGCNSParameters,
                               z0V::Float64)

Initialize walkers as exact i.i.d. draws from the continuous ideal-gas prior at the reference activity: each walker's particle count is Poisson(z0V) and its positions are uniform in the cell. Under a finite params.n_max the count is drawn from the exact conditional Poisson on 0:n_max by rejection — chosen over inverse-CDF sampling because it consumes the identical RNG stream whenever no draw exceeds the cap, which is what makes the bounded and unbounded constructions digit-identical away from the cap (the workable-mass guard in _atomistic_igref_z0V bounds the rejection loop).

_init_atomistic_igref_walkers!(liveset::LJSurfaceWalkers,
                               params::AtomisticIGRefGCNSParameters,
                               z0V::Float64)

Surface-aware method: identical reference-law draws (Poisson counts, truncated under a finite n_max; positions uniform in the FULL cell — the substrate is excluded by the energy ceiling, not the reference measure), with energies assigned against the frozen surface. Each walker inherits the surface's energy_frozen_part (the read-not-compute convention of LJSurfaceWalkers) before the surface-aware assign_energy!.

_init_gc_walkers!(liveset::LatticeGasWalkers, gc_params::GrandCanonicalNestedSamplingParameters)

Initialize walkers with random microstates for grand-canonical NS. Each site is occupied independently with probability gc_params.init_occupation_p.

_init_ideal_gas_ref_walkers!(liveset::LatticeGasWalkers,
                             params::IdealGasReferencedGCNSParameters)

Initialize walkers as exact i.i.d. draws from the ideal-lattice-gas prior: each site occupied independently with probability z0/(1 + z0).

_move_rate_columns(mc_routine::MCAtomGrandCanonicalMoves) -> Tuple

The per-iteration rate-column set for the atomistic ideal-gas-referenced ledger, conditional on the routine's active channels: the six base grand-canonical columns always, the cavity pair when p_bias > 0 (the run totals already carry the keys), and the five Galilean counters when galilean_steps > 0. Conditional-on-active-channel keeps the shipped six-column schema byte-identical for routines that use neither channel.

_perturbation_energy_bound(h, lattice) -> Union{Float64,Nothing}

Magnitude bound on the lattice energy in the Hamiltonian's own energy units: the on-site magnitude times the site count, plus each coupled shell's magnitude times its total ordered-entry count over two (image multiplicity included, read from the built neighbor lists), plus the site-field and cluster magnitudes where applicable. Returns nothing for Hamiltonian types without a method, which skips the tie-breaker warning.

_reanchor_igref_energies!(liveset)

Recompute every walker's energy from scratch (the surface-aware method evaluates against the liveset's frozen surface). Used by the driver's initialize=false path so a restored live set enters the loop with energies consistent with the run's potential, whatever precision its serialized positions carried.

_sort_by_grand_potential!(liveset::AtomWalkers, mu::typeof(0.0u"eV"))

Sort the walkers by Ω = E − μN in descending order through the same sort! call, algorithm, and stability as sort_by_energy!, so at mu = 0.0u"eV" the comparator values, the resulting order, and the tie order are identical.

_tie_block_length(walkers, mu::typeof(0.0u"eV"))

Length of the leading block of walkers whose Ω = E − μN equals the first walker's bit-exactly (the sorted-by-Ω analogue of the one-argument method).

_tie_block_length(walkers)

Return the number of leading walkers in an energy-sorted (descending) walker vector whose energies are bit-exactly equal to the worst walker's energy. A return value of 1 means the energy ceiling is unique; a larger value means the ceiling sits on an exact energy plateau (the generic outcome of truncated pair potentials over configuration spaces with vacuum, where the potential is exactly zero beyond every cutoff sphere).

_validate_observables(observables, liveset::AbstractLiveSet)

Validate an observables specification — a vector of name::Symbol => callback pairs — for per-dead-point recording in a nested-sampling loop.

Throws ArgumentError on an empty list, duplicate names, a name colliding with a reserved ledger column, or a callback whose probe evaluation on liveset.walkers[1].configuration does not return a Real; warns when the probe value is non-finite (a non-finite observable contributes NaN/Inf to every weighted average downstream). Callbacks must be pure functions of the configuration: each is evaluated once here as a probe and once per accepted iteration on the culled walker.

_warn_min_image_cutoff(pot, config)

Warn once when a potential's finite interaction range exceeds half the smallest cell edge of config: minimum-image truncation is anisotropic in that regime. An infinite range never warns (an untruncated minimum-image Hamiltonian is a deliberate model choice), and potentials of undeterminable range are skipped.

_warn_perturbation_scale(liveset::LatticeGasWalkers, delta::Float64)

Warn once, at driver entry, when the configured energy_perturbation sits below the documented degenerate-plateau resolution floor K^2 * eps(E_bound): below it the K walkers cannot reliably draw distinct tie-breaking values on a degenerate plateau, and the failure mode is silent (plateaus decompress at machine granularity and read as poor mixing). A warning, never a throw; a zero perturbation is a deliberate no-perturbation choice and is not warned about.

adjust_cluster_p(params::SamplingParameters, rate::Float64, iteration::Int; target::Float64=0.3, floor::Float64=0.01, ceiling::Float64=1.0)

Adjusts the cluster growth probability based on the acceptance rate. Uses a simple multiplicative rule: p *= 0.9 if rate is below target, p *= 1.1 if rate is at or above target, clamped to [floor, ceiling].

Also logs the adjusted cluster_p, acceptance rate, and NS iteration index to params.cluster_p_history, params.cluster_accept_history, and params.cluster_adjust_iterations for post-run diagnostics.

Arguments

• params::SamplingParameters: The parameters containing cluster_p.
• rate::Float64: The cluster move acceptance rate for the current window.
• iteration::Int: The current NS iteration index.
• target::Float64: The target acceptance rate (default 0.3).
• floor::Float64: Lower bound for cluster_p (default 0.01).
• ceiling::Float64: Upper bound for cluster_p (default 1.0).

Returns

• params::SamplingParameters: The updated parameters with adjusted cluster_p.

adjust_step_size(params::SamplingParameters, rate::Float64)

Adjusts the step size of the sampling algorithm based on the acceptance rate. The step size is increased by 10% if the acceptance rate is above the upper limit of the range, and decreased by 10% if the acceptance rate is below the lower limit of the range.

Arguments

• params::SamplingParameters: The parameters of the sampling algorithm.
• rate::Float64: The acceptance rate of the algorithm.
• range::Tuple{Float64, Float64}: The range of acceptance rates for adjusting the step size. Default is (0.25, 0.75).

Returns

• params::SamplingParameters: The updated parameters with adjusted step size.

estimate_temperature(n_walker::Int, n_cull::Int, ediff::Float64)

Estimate the temperature for the nested sampling algorithm from dlog(ω)/dE.

exact_enumeration(lattice::SLattice{G}, cutoff_radii::Tuple{Float64, Float64}, h::ClassicalHamiltonian) where G

Enumerate all possible configurations of a lattice system and compute the energy of each configuration.

Arguments

• lattice::SLattice{G}: The (starting) lattice system to enumerate. All possible configurations will be generated from this lattice system.
• h::ClassicalHamiltonian: The Hamiltonian containing the on-site and nearest-neighbor interaction energies.

Returns

• DataFrame: A DataFrame containing the energy and configuration of each configuration.
• LatticeGasWalkers: A collection of lattice walkers for each configuration.

grand_canonical_nested_sampling(liveset::LatticeGasWalkers,
                                gc_params::GrandCanonicalNestedSamplingParameters,
                                n_steps::Int64,
                                mc_routine::MCGrandCanonicalMoves,
                                save_strategy::DataSavingStrategy)

Run the grand-canonical nested sampling loop.

Initializes walkers with random microstates, then iterates: remove the highest-Ω walker, record (Ω, E, N), replace with a decorrelated clone.

Arguments

• liveset::LatticeGasWalkers: The initial liveset (walkers will be re-initialized).

• gc_params::GrandCanonicalNestedSamplingParameters: GC-NS parameters including μ.

• n_steps::Int64: Number of NS iterations.

• mc_routine::MCGrandCanonicalMoves: The GC move routine.

• save_strategy::DataSavingStrategy: Strategy for periodic output.

• observables: Optional vector of name::Symbol => callback pairs recording per-dead-point observables as extra ledger columns; see nested_sampling.

• dead_point_callback: Optional per-dead-point callback (iter, walker) -> ... invoked with the culled walker immediately after its ledger row is pushed; see nested_sampling for the contract.

• stop_on_stall::Bool=false: When true and fail_count reaches allowed_fail_count, warn once and return the partial ledger and the intact live set (fail_count stays at threshold); the default keeps the shipped warn-and-continue behavior byte-identically.

• record_move_rates::Bool=false: When true the ledger gains the twelve per-iteration lattice acceptance columns (kernel key order, _LATTICE_MOVE_RATE_COLUMNS), snapshot-differenced from the run totals; failed iterations fold into the next recorded row. The default keeps the shipped schema.

Returns

• df::DataFrame: Columns [:iter, :omega, :energy, :num_particles], plus one column per requested observable.
• liveset::LatticeGasWalkers: The final liveset (surviving walkers).
• gc_params::GrandCanonicalNestedSamplingParameters: Updated parameters.

ideal_gas_referenced_nested_sampling(liveset::AtomWalkers,
                                     params::AtomisticIGRefGCNSParameters,
                                     n_steps::Int64,
                                     mc_routine::MCAtomGrandCanonicalMoves,
                                     save_strategy::DataSavingStrategy;
                                     observables=nothing,
                                     dead_point_callback=nothing,
                                     stop_on_stall::Bool=true,
                                     record_move_rates::Bool=false,
                                     initialize::Bool=true)

Run the atomistic ideal-gas-referenced grand-canonical nested sampling loop. Walkers are initialized as exact i.i.d. draws from the continuous ideal-gas prior at the reference activity (particle counts Poisson(z0V), positions uniform in the cell), then the loop iterates: remove the walker of highest ordering scalar Ω = E − μN (the energy at the default chemical_potential = 0.0u"eV"), record (E, N, log-compression) and, under a nonzero μ, Ω, replace with a strictly-below-ceiling clone decorrelated by the grand-canonical kernel under the z0-weighted prior. Exact ceiling ties are handled by the plateau-aware eviction machinery. The temperature never enters the run; the chemical potential enters only the ordering scalar, never the acceptance ratios or the reference measure, so the recorded (E, N) ledger reduces with gc_thermodynamic_stats_ideal_ref to any target (μ', T') exactly as an energy-sorted ledger does (see the chemical_potential field docstring of AtomisticIGRefGCNSParameters).

Stall contract: when params.fail_count reaches params.allowed_fail_count, the driver warns once and, with stop_on_stall=true (the default), returns the partial ledger and the intact live set instead of consuming the remaining iteration budget on proposals that cannot be accepted. A fully degenerate live set (every configuration at exactly one energy, the zero-interaction limit) is a legitimate terminal state whose entire prior mass sits in the live set; the subsequent ledger reduction is then exact. Under a nonzero chemical_potential the descent ends either in the ground-state sector of that μ or at an atom of the ordering scalar's law, most commonly the empty configuration over a frozen substrate (every empty walker carries the identical Ω, its energy_frozen_part): once every walker sits on that atom no proposal can go strictly below it, the stall fires, and the returned record is complete with the atom's reference mass in the live tail. That stall does not certify that the ground-state sector of that μ was reached: when the region below the atom carries far less prior mass than the atom itself, the live set reaches the atom before any walker lands in that region, and its mass is charged to the atom: under a nonzero μ a live set tied in its entirety on one Ω never attempts a replacement walk (the interior below such an atom carries at most a fraction of order 1/K of its mass, which ordinary culls charging K/(K+1) per walker would misstate by up to a factor of order K), so the stall fires after allowed_fail_count counted failures. A plateau whose survivors all sit on such an atom cannot be refilled (isolated particles of a truncated pair potential share one exact energy, so at a nonzero μ every N = 1 walker sits on one Ω, and the refill clones the survivors below it, which are the empties): such a clone stays strictly below the plateau only by accepting no move, which the refill counts as a failure, whatever bound clusters of negligible prior mass also lie below; the refill exhausts its budget, the live set shrinks to the survivors, and a live set reduced to a single walker counts every subsequent replacement as failed rather than drawing a parent from an empty range, so the stall contract fires there too. With stop_on_stall=false the driver keeps the warn-and-continue contract of the sibling loops (the failure counter is reset, the step size is reset to params.initial_step_size following the canonical loop's contract, and the loop continues).

With record_move_rates=true the ledger gains the per-iteration acceptance columns [:move_attempted, :move_accepted, :insert_attempted, :insert_accepted, :delete_attempted, :delete_accepted], recorded as the change in the run-total counters since the previous recorded row: the production diagnostic for how the per-channel acceptances evolve with descent depth. The column set is conditional on the routine's active channels: p_bias > 0 adds the cavity pair [:insert_biased_attempted, :insert_biased_accepted] (subsets of the insertion columns), and galilean_steps > 0 adds the five Galilean counters [:galilean_attempted, :galilean_accepted, :galilean_reflect_attempted, :galilean_reflect_evals, :galilean_reflect_accepted] accumulated from every ordinary-cull burst (unconditionally on the subsequent re-anchor outcome, so every paid burst appears in some row's delta). A trailing :step_size column records the adapted step size at each row push. A recorded row also carries the attempts of any failed replacements since the previous row; plateau-eviction rows run no decorrelation walk of their own, and refill-walk counters (including refill bursts) are deliberately not accumulated. The recorded columns sum exactly to the move_stats run totals accumulated through the last recorded row. The names are reserved ledger columns, rejected as observable names.

Observable callbacks must handle empty configurations: under this construction a walker's particle count may be zero.

An LJSurfaceWalkers liveset dispatches the surface-aware path: initialization inherits the surface's energy_frozen_part and assigns energies against the frozen surface, and every decorrelation and refill walk runs the surface-aware kernel. The cavity-biased insertion channel and the Galilean burst are not surface-aware and are rejected at step entry. The reference measure is unchanged: Poisson counts (truncated under a finite n_max), positions uniform in the FULL cell, z0V folded from the full cell — the substrate excludes volume through the energy ceiling, not the measure.

With initialize=false the driver trusts the supplied live set instead of drawing a fresh one: particle counts, positions, and the walkers' iter counters continue a previous run (the ledger's iter keying stays consistent when every walker carries the same iter, which a continued live set does). Walker energies are re-anchored from scratch on entry (surface livesets also re-inherit the surface's energy_frozen_part), so a live set restored from serialized positions enters the loop consistent with the run's potential. Under a finite n_max the restored counts must respect the cap; a violating walker is rejected with an ArgumentError. The continuation contract the caller owns: the same reference_activity, potential, species, n_max, and chemical_potential as the first block (none of these can be validated against a bare live set, and a mismatch produces a chimera ledger whose blocks sample different constrained reference measures, or, for μ, the same measure under two different ceilings); and a run stopped mid-plateau-eviction resumes the eviction with the refill target the parameters carry (plateau_refill_target is kept on entry when initialize=false; a driver that rebuilds its parameters from a checkpoint must restore it there), so the walkers evicted before the boundary are refilled once the plateau is exhausted; a continuation entered with a zero target re-derives it from the current, reduced live count and never refills them (the compression bookkeeping stays exact either way, since every charge uses the actual live count).

Returns

• df::DataFrame: Columns [:iter, :emax, :num_particles, :log_compression], plus :omega (the culled walker's Ω = E − μN) under a nonzero chemical_potential, plus the acceptance columns when requested, plus one column per requested observable. Zero-accept runs return the schema with no rows.
• liveset::AtomWalkers: The final liveset (surviving walkers).
• params::AtomisticIGRefGCNSParameters: Updated parameters.

ideal_gas_referenced_nested_sampling(liveset::LatticeGasWalkers,
                                     params::IdealGasReferencedGCNSParameters,
                                     n_steps::Int64,
                                     mc_routine::MCGrandCanonicalMoves,
                                     save_strategy::DataSavingStrategy)

Run the ideal-gas-referenced grand-canonical nested sampling loop.

Walkers are initialized as exact i.i.d. draws from the ideal-lattice-gas prior at reference fugacity z0 (each site occupied with probability z0/(1 + z0)), then the loop iterates: remove the highest-energy walker, record (E, N), replace with a clone decorrelated below the energy ceiling under the z0^N-weighted prior. The chemical potential never enters the run; a single run is post-processed to Ξ(μ, T) on an arbitrary (μ, T) grid by gc_thermodynamic_stats_ideal_ref in AnalysisTools, which also needs the surviving live walkers' (E, N) for the live-set tail closure — extract them from the returned liveset.

Arguments

• liveset::LatticeGasWalkers: The initial liveset (walkers will be re-initialized).

• params::IdealGasReferencedGCNSParameters: Parameters including the reference fugacity z0.

• n_steps::Int64: Number of NS iterations.

• mc_routine::MCGrandCanonicalMoves: The GC move routine (reused from the Ω-sorted construction).

• save_strategy::DataSavingStrategy: Strategy for periodic output.

• observables: Optional vector of name::Symbol => callback pairs recording per-dead-point observables (e.g. order_parameter_c2x2) as extra ledger columns; see nested_sampling. The recorded columns feed the observable_cols machinery of gc_thermodynamic_stats_ideal_ref.

• dead_point_callback: Optional per-dead-point callback (iter, walker) -> ... invoked with the culled walker immediately after its ledger row is pushed; see nested_sampling for the contract. Configurations collected here support post-run re-evaluation under a second Hamiltonian, whose energies substitute for the emax column (and the live tail) in gc_thermodynamic_stats_ideal_ref: the prior-volume weights depend only on the iteration index, so the substituted column is a valid estimator of the second Hamiltonian's grand potential over the same ladder, with the returned Kish N_eff as its fidelity diagnostic.

• stop_on_stall::Bool=false: When true and fail_count reaches allowed_fail_count, warn once and return the partial ledger and the intact live set (fail_count stays at threshold); the default keeps the shipped warn-and-continue behavior byte-identically.

• record_move_rates::Bool=false: When true the ledger gains the twelve per-iteration lattice acceptance columns (kernel key order, _LATTICE_MOVE_RATE_COLUMNS), snapshot-differenced from the run totals; failed iterations fold into the next recorded row. The default keeps the shipped schema.

Returns

• df::DataFrame: Columns [:iter, :emax, :num_particles], plus one column per requested observable.
• liveset::LatticeGasWalkers: The final liveset (surviving walkers).
• params::IdealGasReferencedGCNSParameters: Updated parameters.

monte_carlo_sampling(mc_routine::MCAtomGrandCanonicalMoves,
                     at::AtomWalker{1},
                     pot::SingleComponentPotential{Pairwise},
                     mc_params::MuVTMCParameters;
                     kb::Float64=8.617333262e-5)

Fixed-temperature grand-canonical (μVT) Metropolis sampling over a temperature ladder, wrapping MC_muVT_walk!. The routine supplies the channel split (p_move, p_insert); its nested-sampling-only fields (step_rate_source, mc_steps_per_particle) are not consumed here. Per temperature rung: equilibration in ten adaptation blocks (step size adjusted between blocks on the displacement-only rate; a block that attempted no displacement skips the adjustment), then production with the step size frozen, recording the particle count every sampling_interval kernel steps and re-anchoring the walker's incremental energy with a from-scratch interacting_energy recompute every ten recorded samples. Phase seeding follows the documented per-rung law of MuVTMCParameters.random_seed. The final walker of each rung starts the next (sequential annealing over the ladder); the entry check warns once when the potential's finite interaction range exceeds half the smallest cell edge.

Returns

A NamedTuple of per-temperature results:

• mean_N::Vector{Float64}, var_N::Vector{Float64}: Particle-number moments.
• mean_U::Vector{Float64}: Mean total interaction energy, in eV.
• p_N::Vector{Vector{Float64}}, N_support::Vector{UnitRange{Int}}: The recorded particle-number histogram per rung, normalized, over 0:N_max.
• N_series::Vector{Vector{Int}}: The recorded particle-number series per rung (the cross-check artifact; its length is sampling_steps ÷ sampling_interval).
• acceptance::Vector{NamedTuple}: Production per-channel attempt/accept counters per rung (the kernel's move_stats schema).
• walkers::Vector{AtomWalker}: An independent copy of the final walker per rung.

monte_carlo_sampling(
    mc_routine::MCRoutine,
    lattice::AbstractLattice,
    h::ClassicalHamiltonian,
    mc_params::MetropolisMCParameters;
    kb::Float64 = 8.617333262e-5 # eV/K
)

Perform the Metropolis Monte Carlo sampling algorithm for a range of temperatures.

Note: The Boltzmann constant is set to 8.617333262e-5 eV K$^{-1}$. Thus, the units of the temperature should be in Kelvin, and the units of the energy should be in eV (defined in the Hamiltonian).

Arguments

• mc_routine::MCRoutine: The Monte Carlo routine to use. For lattice sampling, use MCNewSample.
• lattice::AbstractLattice: The initial lattice configuration.
• h::ClassicalHamiltonian: The Hamiltonian containing the on-site and nearest-neighbor interaction energies.
• mc_params::MetropolisMCParameters: The parameters for the Metropolis Monte Carlo algorithm.
• kb::Float64: The Boltzmann constant in eV/K (default is 8.617333262e-5 eV/K).

Returns

• energies::Vector{Float64}: The energies of the system at each temperature.
• configs::Vector{typeof(lattice)}: The configurations of the system at each temperature.
• cvs::Vector{Float64}: The heat capacities of the system at each temperature.
• acceptance_rates::Vector{Float64}: The acceptance rates of the system at each temperature.

monte_carlo_sampling(
    mc_routine::MCRoutine,
    at::AtomWalker,
    pot::AbstractPotential,
    mc_params::MetropolisMCParameters;
    kb::Float64 = 8.617333262e-5 # eV/K
)

Perform the Metropolis Monte Carlo sampling algorithm for a range of temperatures.

Note: The Boltzmann constant is set to 8.617333262e-5 eV K$^{-1}$. Thus, the units of the temperature should be in Kelvin, and the units of the energy should be in eV.

Arguments

• mc_routine::MCRoutine: The Monte Carlo routine to use. For atomistic sampling, use MCRandomWalkMaxE or MCMixedMoves.
• at::AtomWalker: The initial atom walker configuration.
• pot::AbstractPotential: The potential energy function.
• mc_params::MetropolisMCParameters: The parameters for the Metropolis Monte Carlo algorithm.

Returns

• energies::Vector{Float64}: The energies of the system at each temperature.
• configs::Vector{typeof(at)}: The configurations of the system at each temperature.
• cvs::Vector{Float64}: The heat capacities of the system at each temperature.
• acceptance_rates::Vector{Float64}: The acceptance rates of the system at each temperature.

nested_sampling(liveset::AbstractLiveSet, ns_params::NestedSamplingParameters, n_steps::Int64, mc_routine::MCRoutine; args...)

Perform a nested sampling loop for a given number of steps.

Arguments

• liveset::AbstractLiveSet: The initial set of walkers.
• ns_params::NestedSamplingParameters: The parameters for nested sampling.
• n_steps::Int64: The number of steps to perform.
• mc_routine::MCRoutine: The Monte Carlo routine to use.
• observables: Optional vector of name::Symbol => callback pairs. Each callback is evaluated on the culled walker's configuration at every accepted iteration and recorded as an extra Float64 ledger column named name, exactly paired with that row's iter-keyed prior-volume weight. Names must not collide with the built-in ledger columns (iter, emax, omega, energy, num_particles, log_compression, move_attempted, move_accepted, insert_attempted, insert_accepted, delete_attempted, delete_accepted, insert_biased_attempted, insert_biased_accepted, galilean_attempted, galilean_accepted, galilean_reflect_attempted, galilean_reflect_evals, galilean_reflect_accepted, step_size, swap_attempted, swap_accepted, swap_null_attempted, swap_null_accepted, cluster_attempted, cluster_accepted, insert_uniform_attempted, insert_uniform_accepted); callbacks must be pure functions of the configuration returning a Real. Parallel and multi-cull MC routines (MCRoutineParallel subtypes) are rejected up front with an ArgumentError; a bit-exact pairing guard additionally raises an error if a step ever culls a different walker than the one the row records. The default nothing leaves the ledger schema unchanged.
• dead_point_callback: Optional function called once per recorded dead point as dead_point_callback(iter, walker), immediately after the ledger row is pushed, with the same culled walker the row describes (protected by the same bit-exact pairing guard as observables, which is engaged whenever either keyword is supplied). Iterations that record no dead point invoke no callback, so the invocation count equals nrow(df). The walker is the loop's live object: treat it as read-only and copy anything kept, e.g. copy(walker.configuration.components[1]) or deepcopy(walker.configuration). Composes freely with observables; the surviving live set needs no callback because the loop returns it. Parallel and multi-cull MC routines are rejected up front. Typical uses: collecting occupation vectors for batch post-processing, and re-evaluating each dead point under a second Hamiltonian, whose energies substitute for the ledger energy column in the grand-canonical stats functions (the prior-volume weights depend only on the iteration index, so the substituted column is a valid estimator over the same ladder). The default nothing changes nothing.
• record_move_rates::Bool=false: Per-iteration acceptance and step-size ledger, supported for the serial atomistic routines (MCRandomWalkMaxE, MCRandomWalkClone, MCGalileanWalk) on an AtomWalkers liveset only; other liveset or routine types throw up front, since their step methods run different kernels. When true the ledger declares log_compression eagerly, then the routine's rate columns (move_attempted/move_accepted for the random-walk routines, the five Galilean counters for the reflective one), then a step_size column recording the adapted value at each row push; observables follow. Deltas are snapshot-differenced run totals: plateau rows record zeros, failed iterations fold into the next recorded row, and refill walks are never accumulated. The default keeps the shipped schema byte-identically.

Returns

• df: A DataFrame containing the iteration number and maximum energy for each step, plus one column per requested observable.
• liveset: The updated set of walkers.
• ns_params: The updated nested sampling parameters.

nested_sampling_step!(liveset::AtomWalkers,
                      params::AtomisticIGRefGCNSParameters,
                      mc_routine::MCAtomGrandCanonicalMoves;
                      ns_iteration::Int=0, z0V::Union{Nothing,Float64}=nothing)

Perform one step of atomistic ideal-gas-referenced grand-canonical nested sampling: sort by the ordering scalar Ω = E − μN (descending; the energy at the default chemical_potential = 0.0u"eV"), handle exact ceiling ties with the plateau-aware eviction machinery of the canonical atomistic steps (refill walks run the grand-canonical kernel, so refilled clones may re-enter at a different particle count; the compression bookkeeping counts walkers, not particle-number sectors), otherwise cull the worst walker and decorrelate a strictly-below-ceiling clone through MC_grand_canonical_walk! under the z0-weighted prior. Accepted clones (cull and refill alike) have their energies re-anchored by a from-scratch interacting_energy recompute and are re-checked against the ceiling before entering the live set: the kernel's incremental bookkeeping leaves rounding dust that would otherwise fragment bit-exact energy plateaus into artificial sub-levels and admit clones whose true energy sits on, not below, the ceiling.

Returns

• iter: Iteration number (or missing if the step failed).
• emax: The energy of the culled walker (with units; missing on failure). Under a nonzero μ the ceiling the step enforced is the walker's Ω = emax − μ num_particles, not this energy.
• num_particles: The particle count of the culled walker (missing on failure).
• liveset: The updated liveset.
• params: The updated parameters.
• log_t: The log prior-volume compression charged for this cull (missing on failure).

nested_sampling_step!(liveset::AtomWalkers, ns_params::NestedSamplingParameters, mc_routine::MCRoutineParallel)

Perform a single step of the nested sampling algorithm using the parallel Monte Carlo random walk routine.

Arguments

• liveset::AtomWalkers: The set of atom walkers.
• ns_params::NestedSamplingParameters: The parameters for nested sampling.
• mc_routine::MCRoutineParallel: The parallel Monte Carlo routine for generating new samples. See MCRoutineParallel.

Returns

• iter: The iteration number after the step.
• emax: The highest energy recorded during the step.
• liveset: The updated set of atom walkers.
• ns_params: The updated nested sampling parameters.

nested_sampling_step!(liveset::AtomWalkers, ns_params::NestedSamplingParameters,
                      mc_routine::MCGalileanWalk; ns_iteration::Int=0)

One canonical nested-sampling step decorrelated by the Galilean reflective walk: the shape of the serial random-walk step (plateau-aware tie eviction included, with refill walks running the reflective kernel below the plateau), with the replacement clone drawn from the survivors and decorrelated through MC_galilean_walk!. Returns the serial steps' five-value shape, so the driver records log_compression as usual.

nested_sampling_step!(liveset::AtomWalkers, ns_params::NestedSamplingParameters, mc_routine::MCMixedMoves)

Perform a single step of the nested sampling algorithm using the Monte Carlo mixed moves routine. By default, this routine performs parallel decorrelation of multiple walkers.

Arguments

• liveset::AtomWalkers: The set of atom walkers.
• ns_params::NestedSamplingParameters: The parameters for nested sampling.
• mc_routine::MCMixedMoves: The Monte Carlo mixed moves routine.

Returns

• iter: The iteration number after the step.
• emax: The highest energy recorded during the step.
• liveset: The updated set of atom walkers.
• ns_params: The updated nested sampling parameters.

Note

• To invoke the parallel version of this routine, use MCMixedMovesParallel as the mc_routine argument.

nested_sampling_step!(liveset::AtomWalkers, ns_params::NestedSamplingParameters, mc_routine::MCRoutine)

Perform a single step of the nested sampling algorithm using the Monte Carlo random walk routine.

Exact energy ties at the ceiling (an energy plateau) are handled with plateau-aware compression following Fowlie, Handley and Su, Mon. Not. R. Astron. Soc. 503, 1199 (2021): when two or more live walkers tie the ceiling bit-exactly, the tied walkers are evicted one by one without replacement, each eviction compressing the prior volume by (n_live - 1)/n_live with the shrinking live count, and the live set is refilled by cloning and decorrelating survivors below the plateau only once the last tied walker has been evicted. A normal (unique-ceiling) cull compresses by n_live/(n_live + 1) as before. The per-cull log-compression is returned as a fifth value and recorded by the nested_sampling driver in a log_compression ledger column, consumed by the log-compression method of ωᵢ; for tie-free ledgers the column is uniformly log(K/(K+1)) and the legacy iteration-based weights are unchanged. One documented corner keeps the previous semantics: if the ENTIRE live set ties (every walker on the plateau), no survivor samples the sub-plateau region, so the step falls back to the ordinary clone-and-walk cull with replacement, charging n_live/(n_live + 1); the plateau under-compression bias of that corner is confined to runs whose live set is entirely on a plateau, which for an i.i.d. initialization occurs with probability f^K for plateau prior fraction f (about 1% at f = 0.91, K = 48, but about 21% at K = 16 — raise K when the vacuum fraction is large). This plateau handling applies to the two SERIAL MCRoutine step methods (AtomWalkers and LJSurfaceWalkers); the parallel, distributed, and mixed-moves step methods keep the previous fixed-compression semantics and their ledgers carry no log_compression column.

Arguments

• liveset::AtomWalkers: The set of atom walkers.
• ns_params::NestedSamplingParameters: The parameters for nested sampling.
• mc_routine::MCRoutine: The Monte Carlo routine for generating new samples. See MCRoutine.

Returns

• iter: The iteration number after the step.
• emax: The highest energy recorded during the step.
• liveset: The updated set of atom walkers.
• ns_params: The updated nested sampling parameters.
• log_t: The log of the prior-volume compression factor charged for this cull (missing when no walker was culled).

nested_sampling_step!(liveset::LJSurfaceWalkers,
                      params::AtomisticIGRefGCNSParameters,
                      mc_routine::MCAtomGrandCanonicalMoves;
                      ns_iteration::Int=0, z0V::Union{Nothing,Float64}=nothing)

Surface-aware method of the atomistic ideal-gas-referenced step: identical to the AtomWalkers method except every decorrelation and refill walk runs the surface-aware grand-canonical kernel against the liveset's frozen surface, and every energy re-anchor recomputes against the surface. The cavity-biased insertion channel and the Galilean burst are not surface-aware, so a routine with p_bias > 0 or galilean_steps > 0 is rejected at step entry (a loud ArgumentError before any walker is touched, mirroring the canonical surface step's routine validation).

nested_sampling_step!(liveset::LJSurfaceWalkers, ns_params::NestedSamplingParameters, mc_routine::MCRoutine)

Serial nested-sampling step for surface livesets. Identical to the AtomWalkers serial method — including the plateau-aware handling of exact energy ties, the fifth log_t return value, and the all-tied fallback documented there — except that every decorrelation and refill walk carries the frozen surface and only dims == [1, 2, 3] is supported.

nested_sampling_step!(liveset::LatticeGasWalkers,
                      gc_params::GrandCanonicalNestedSamplingParameters,
                      mc_routine::MCGrandCanonicalMoves;
                      ns_iteration::Int=0)

Perform one step of grand-canonical nested sampling.

Sorts walkers by Ω = E − μN, removes the worst (highest Ω), clones a parent with Ω < Ω_worst, and decorrelates the clone via grand-canonical MCMC.

Returns

• iter: Iteration number (or missing if the step failed).
• omega_max: The Ω value of the removed walker (with units).
• energy: The E value of the removed walker.
• num_particles: The N value of the removed walker.
• liveset: The updated liveset.
• gc_params: The updated parameters.

nested_sampling_step!(liveset::LatticeGasWalkers,
                      params::IdealGasReferencedGCNSParameters,
                      mc_routine::MCGrandCanonicalMoves;
                      ns_iteration::Int=0)

Perform one step of ideal-gas-referenced grand-canonical nested sampling.

Sorts walkers by energy E (not Ω — the chemical potential plays no role in the sampler), removes the worst (highest E), clones a parent with E < E_worst, and decorrelates the clone via grand-canonical MCMC that preserves the z0^N-weighted prior below the energy ceiling.

Returns

• iter: Iteration number (or missing if the step failed).
• emax: The E value of the removed walker (with units).
• num_particles: The N value of the removed walker.
• liveset: The updated liveset.
• params: The updated parameters.

nested_sampling_step!(liveset::LatticeGasWalkers, ns_params::NestedSamplingParameters, mc_routine::MCMixedMoves)

Perform a single step of the nested sampling algorithm using a mix of geometric cluster moves and local swap moves.

The total mc_steps from ns_params are split between cluster moves and local swaps according to clusters_freq and walks_freq in the mc_routine. Cluster moves use geometric_cluster_swap! with growth probability ns_params.cluster_p, which is adaptively tuned to maintain mc_routine.target_cluster_accept. Local swaps use the standard lattice_random_walk!.

Arguments

• liveset::LatticeGasWalkers: The liveset of lattice gas walkers.
• ns_params::NestedSamplingParameters: The parameters for nested sampling.
• mc_routine::MCMixedMoves: The mixed moves routine with cluster and local swap frequencies.

Returns

• iter: The iteration number of the liveset after the step.
• emax: The maximum energy of the liveset after the step.
• liveset::LatticeGasWalkers: The updated liveset.
• ns_params::NestedSamplingParameters: The updated parameters.

nested_sampling_step!(liveset::LatticeGasWalkers, ns_params::LatticeNestedSamplingParameters, mc_routine::MCNewSample)

Perform a single step of the nested sampling algorithm.

This function takes a liveset of lattice gas walkers, ns_params containing the parameters for nested sampling, and mc_routine representing the Monte Carlo routine for generating new samples. It performs a single step of the nested sampling algorithm by updating the liveset with a new walker.

Arguments

• liveset::LatticeGasWalkers: The liveset of lattice gas walkers.
• ns_params::LatticeNestedSamplingParameters: The parameters for nested sampling.
• mc_routine::MCNewSample: The Monte Carlo routine for generating new samples.

Returns

• iter: The iteration number of the liveset after the step.
• emax: The maximum energy of the liveset after the step.
• liveset::LatticeGasWalkers: The updated liveset after the step.
• ns_params::LatticeNestedSamplingParameters: The updated nested sampling parameters after the step.

nested_sampling_step!(liveset::LatticeGasWalkers, ns_params::LatticeNestedSamplingParameters, mc_routine::MCRoutine)

Perform a single step of the nested sampling algorithm.

This function takes a liveset of lattice gas walkers, ns_params containing the parameters for nested sampling, and mc_routine representing the Monte Carlo routine for generating new samples. It performs a single step of the nested sampling algorithm by updating the liveset with a new walker.

Arguments

• liveset::LatticeGasWalkers: The liveset of lattice gas walkers.
• ns_params::LatticeNestedSamplingParameters: The parameters for nested sampling.
• mc_routine::MCRoutine: The Monte Carlo routine for generating new samples.

Returns

• iter: The iteration number of the liveset after the step.
• emax: The maximum energy of the liveset after the step.

nvt_monte_carlo(
    mc_routine::MCRoutine,
    lattice::AbstractLattice,
    h::ClassicalHamiltonian,
    temperature::Float64,
    num_steps::Int64,
    random_seed::Int64;
    kb::Float64 = 8.617_333_262e-5  # eV K-1
)

Perform the NVT Monte Carlo algorithm to sample the lattice configurations.

Note: The Boltzmann constant is set to 8.617333262e-5 eV K$^{-1}$. Thus, the units of the temperature should be in Kelvin, and the units of the energy should be in eV (defined in the Hamiltonian).

Arguments

• mc_routine::MCNewSample: The Monte Carlo routine to use. For lattice sampling, use MCNewSample.
• lattice::AbstractLattice: The initial lattice configuration.
• h::ClassicalHamiltonian: The Hamiltonian containing the on-site and nearest-neighbor interaction energies.
• temperature::Float64: The temperature of the system.
• num_steps::Int64: The number of Monte Carlo steps.
• random_seed::Int64: The seed for the random number generator.
• kb::Float64: The Boltzmann constant (default is 8.617333262e-5 eV K-1).

Returns

• energies::Vector{Float64}: The energies of the system at each step.
• configurations::Vector{typeof(lattice)}: The configurations of the system at each step.
• accepted_steps::Int64: The number of accepted steps.

nvt_monte_carlo(
    mc_routine::MCRoutine,
    walker::AtomWalker,
    pot::AbstractPotential,
    temperature::Float64,
    num_steps::Int64,
    step_size::Float64,
    random_seed::Int64;
    kb::Float64 = 8.617_333_262e-5  # eV K-1
)

Perform the NVT Monte Carlo algorithm to sample the atom walker configurations. Note: The Boltzmann constant is set to 8.617333262e-5 eV K$^{-1}$. Thus, the units of the temperature should be in Kelvin, and the units of the energy should be in eV (defined in the Hamiltonian).

Arguments

• mc_routine::MCRoutine: The Monte Carlo routine to use. For atomistic sampling, use MCRandomWalkMaxE or MCMixedMoves.
• walker::AtomWalker: The initial atom walker configuration.
• pot::AbstractPotential: The potential energy function for the atoms.
• temperature::Float64: The temperature of the system.
• num_steps::Int64: The number of Monte Carlo steps.
• step_size::Float64: The step size for the random walk.
• random_seed::Int64: The seed for the random number generator.
• kb::Float64: The Boltzmann constant (default is 8.617333262e-5 eV K-1).

Returns

• energies::Vector{typeof(walker.energy)}: The energies of the system at each step.
• configurations::Vector{typeof(walker)}: The configurations of the system at each step.

sort_by_energy!(liveset::LJAtomWalkers)

Sorts the walkers in the liveset by their energy in descending order.

Arguments

• liveset::LJAtomWalkers: The liveset of walkers to be sorted.

Returns

• liveset::LJAtomWalkers: The sorted liveset.

update_iter!(liveset::AtomWalkers)

Update the iteration count for each walker in the liveset.

Arguments

• liveset::AtomWalkers: The set of walkers to update.

wang_landau(
    lattice::AbstractLattice,
    h::ClassicalHamiltonian,
    wl_params::WangLandauParameters
)

wang_landau(
    walker::AtomWalker,
    pot::AbstractPotential,
    wl_params::WangLandauParameters
)

Perform the Wang-Landau sampling scheme for a lattice or an atomistic system.

Arguments

• lattice::AbstractLattice/walker::AtomWalker: The initial lattice/atomistic configuration.
• h::ClassicalHamiltonian/pot::AbstractPotential: The Hamiltonian parameters for the lattice/atomistic system.
• wl_params::WangLandauParameters: The parameters for the Wang-Landau sampling scheme.

Returns

• df::DataFrame/energies::Vector{Float64}: The energies of the system at each step.
• configs::Vector{AbstractLattice}/configs::Vector{AtomWalker}: The configurations of the system at each step.
• wl_params::WangLandauParameters: The parameters for the Wang-Landau sampling scheme.
• S::Vector{Float64}: The entropy of the system.
• H::Vector{Int64}: The histogram of the system.