mod parallel_tempering

module parallel_tempering

Parallel-tempering driver. Wraps any Sampler<f64> and runs M of them in parallel at a geometric temperature ladder, with adjacent- pair Metropolis swaps every swap_period steps.

Composition: PT is orthogonal to the inner Sampler. Whether the inner kernel is random-walk Metropolis (SaVariant), HMC (HmcSaSampler), or a custom sampler, PT lifts it to a multi-temperature ensemble.

Functions

fn estimate_log_z_ratio(hot_energies: &[f64], t_cold: f64, t_hot: f64) -> (f64, f64)

Estimates log(Z_cold / Z_hot) from energies sampled at the hot rung.

Samples are reweighted with exp(-(beta_cold - beta_hot) * F). This is valid for a fixed-rung Boltzmann distribution; swap acceptances are not importance weights and are intentionally excluded.

fn geometric_ladder(t_cold: f64, t_hot: f64, n_chains: usize) -> Vec<f64>

Geometric temperature ladder spanning [t_cold, t_hot] with n_chains rungs. T_0 = t_cold (production temperature), T_{M-1} = t_hot (broad-exploration temperature).

Structs and Unions

struct ParallelTemperingSampler<S: Sampler<f64>, E: Exchange<f64>>

PT driver. Constraint: the inner sampler’s Cooling is bypassed – each chain operates at a fixed temperature from the ladder, NOT at the cooling schedule’s epoch-indexed value. PT and cooling are orthogonal in this driver.

sampler: S

Shared inner-sampler logic.

exchange: E

The exchange operator. Defaults to MetropolisExchange.

temps: Vec<f64>

Temperature ladder (length = n_chains).

k_inner: usize

Inner-loop step count per epoch per chain.

swap_period: usize

Swap attempt period: try a swap every swap_period inner-loop steps.

Implementations

impl<S: Sampler<f64>> ParallelTemperingSampler<S, MetropolisExchange>

Functions

fn new(sampler: S, temps: Vec<f64>, k_inner: usize, swap_period: usize) -> Self

Constructs with default Metropolis exchange.

impl<S: Sampler<f64>, E: Exchange<f64>> ParallelTemperingSampler<S, E>

Functions

fn run<C>(&self, _cooling: &C, n_epochs: usize, seed: u64) -> PtResult
where
    C: Cooling<f64>

Runs the PT loop for n_epochs epochs.

Each chain’s RNG is seeded from seed.wrapping_add(c as u64). The shared swap RNG is seed.wrapping_add(M+1). Per epoch we run k_inner inner-loop steps per chain, attempting adjacent- pair swaps every swap_period steps. The Cool inside the inner sampler is ignored at the chain temperature; the swap rule targets the Boltzmann distribution at each chain’s fixed temp.

fn with_exchange(sampler: S, exchange: E, temps: Vec<f64>, k_inner: usize, swap_period: usize) -> Self

Constructs with a user-chosen exchange operator.

struct PtChainState

Per-temperature chain state for a PT run.

state: State

Inner-sampler state.

temp: f64

Temperature this chain operates at.

struct PtResult

Result of a PT run: per-temperature chain history + global best.

chain_histories: Vec<History>

One History per chain (M entries).

best_pos: Vec<f64>

Best-seen position across all chains.

best_val: f64

Best-seen objective value across all chains.

swap_attempts: usize

Number of swap attempts.

swap_accepts: usize

Number of accepted swaps.

log_z_ratio_est: f64

Diagnostic log partition-function ratio log(Z_cold / Z_hot). NaN means the exchange operator does not certify detailed balance; interpretation also requires fixed-rung Boltzmann inner samples.

log_z_ratio_se: f64

Delta-method standard error for log_z_ratio_est, with the same validity conditions as log_z_ratio_est.