mod dmc_population

module dmc_population

Classical population-controlled diffusion search (dmc_pop).

Budgeted multi-walker global search for box-constrained continuous objectives. Walkers propose via adaptive DE (SHADE F/CR memory; current-to-pbest / best / rand), Tsallis/GSA long jumps, and isotropic diffusion; residual resampling controls population size with D8 entropy-calibrated inverse temperature (calibrate_beta / population_control_ecit); dual-style visit→L-BFGS polish (or derivative-free local search) refines elites.

Engineering pattern draws on diffusion Monte Carlo multi-walker bookkeeping (Reynolds–Ceperley–Alder–Lester; Foulkes et al.) with classical f(x) only — no trial wavefunction or electronic Hamiltonian.

Public API: dmc_population_optimize, run_dmc_population_seeded (Python anneal.dmc_population_optimize, portfolio DmcPop arm).

Variables

const DEFAULT_BETA0: f64

Initial inverse-temperature scale relative to energy gap heuristics.

const DEFAULT_STEPS_PER_CONTROL: usize

Diffusion steps between population-control events.

const DEFAULT_TARGET_WALKERS: usize

Default target walker population when the caller does not set one.

Functions

fn beta_search_max(energies: &[f64]) -> f64

Safe bisection upper bound (beta_{max}=20log N / R) (D8.6).

fn calibrate_beta(energies: &[f64], h_star: f64) -> f64

Unique (beta^star=H^{-1}(H_star)) by bisection (Corollary D8.4).

fn default_sigma(bounds: &Bounds<f64>) -> f64

Mean box half-width for setting a default diffusion scale.

fn diffusion_displace(x: ArrayView1<f64>, bounds: &Bounds<f64>, sigma: f64, grad: Option<ArrayView1<f64>>, rng: &mut impl Rng) -> Array1<f64>

Isotropic diffusion proposal, reflected into the box.

sigma is per-coordinate Gaussian scale. Optional Langevin drift uses a crude Euler–Maruyama step when grad is provided: x <- x - 0.5 * dt * g + sigma * z` with ``dt = sigma^2`.

fn dmc_population_optimize<O, G>(obj: &O, grad: Option<&G>, budget: usize, seed: u64) -> DmcPopulationResult
where
    O: Objective<f64>,
    G: Gradient<f64>

Convenience wrapper with a fresh RNG from seed.

fn ecit_residual_probs(energies: &[f64], progress: f64, elite_floor: f64) -> (Vec<f64>, f64, f64)

D8 ECIT residual masses: pure softmax (p_i^star(beta^star)) (D8.2) at the entropy-calibrated (beta^star=H^{-1}(H_star(rho))).

Returns (normalized_probs, beta_star, h_star). These are the exact residual weight law used by population_control_ecit (not the soft-ref legacy path in population_control).

fn mass_entropy(weights: &[f64]) -> f64

Shannon entropy of an arbitrary positive mass vector (normalized in-place for the sum). Used to audit residual weight laws against (H_star).

fn population_control<R: Rng>(walkers: &[Walker], target_n: usize, beta: f64, rng: &mut R) -> Vec<Walker>

Residual population control with legacy soft-reference weights (w_i=exp(-beta(E_i-E_{mathrm{ref}})_+)) where (E_{mathrm{ref}}) is the min/median blend from branch_reference. Prefer population_control_ecit for the D8 pure-softmax residual law.

fn population_control_ecit<R: Rng>(walkers: &[Walker], target_n: usize, progress: f64, elite_floor: f64, rng: &mut R) -> (Vec<Walker>, f64)

D8 ECIT residual control: calibrate (beta^star) to (H_star(rho)), form pure D8.2 softmax masses, residual-resample. Returns (offspring, beta_star).

fn population_control_weighted<R: Rng>(walkers: &[Walker], target_n: usize, weights: &[f64], rng: &mut R) -> Vec<Walker>

Residual + multinomial branch/kill given explicit positive weights.

Residual resampling (Liu): place (lfloor m_irfloor) copies, then multinomial-fill fractional remainders. Weight law is caller-supplied so D8 pure-softmax and legacy soft-ref weights share one residual core.

fn recommend_target_n(budget: usize, dim: usize) -> usize

Recommend a walker count from the remaining evaluation budget.

fn residual_expected_counts(weights: &[f64], target_n: usize) -> Vec<f64>

Expected residual offspring counts (m_i = N_{mathrm{tgt}},w_i/sum w) from a positive weight vector (length must match the walker count).

fn run_dmc_population<O, G, R>(obj: &O, grad: Option<&G>, budget: usize, seed: u64, target_n: usize, steps_per_control: usize, beta0: f64, rng: &mut R) -> DmcPopulationResult
where
    O: Objective<f64>,
    G: Gradient<f64>,
    R: Rng

Run population-controlled diffusion under a hard evaluation budget.

Each objective evaluation increments n_evals. Optional gradients for Langevin drift increment n_grads. Population control (branch/kill to target_n) runs every steps_per_control diffusion rounds.

When seed_x is Some, the first walker is placed at that point (clipped into the box) so portfolio slices can continue from the incumbent.

fn run_dmc_population_seeded<O, G, R>(obj: &O, grad: Option<&G>, budget: usize, seed: u64, target_n: usize, steps_per_control: usize, beta0: f64, seed_x: Option<ArrayView1<f64>>, rng: &mut R) -> DmcPopulationResult
where
    O: Objective<f64>,
    G: Gradient<f64>,
    R: Rng

Same as run_dmc_population with an optional seed position for walker 0.

fn softmax_entropy(energies: &[f64], beta: f64) -> f64

Shannon entropy (H(beta)=-sum p_ilog p_i) of the exponential family (p_ipropto e^{-beta E_i}) (D8.3). Energies are shifted by their min for numerical stability; the shift does not change (H).

fn softmax_probs(energies: &[f64], beta: f64) -> Vec<f64>

Pure D8.2 softmax probabilities (p_ipropto e^{-beta E_i}) (normalized).

Non-finite energies get mass 0; if every energy is non-finite, returns a uniform distribution over the length of energies. Shift by (min E) is for numerical stability only.

fn target_entropy(n: usize, progress: f64, elite_floor: f64) -> f64

Progress-linked target entropy (D8.5): (H_star(rho)=(1-rho)log N+rholog(max{1,f_{mathrm{elite}}})).

elite_floor is the elite count in entropy units (default 2).

fn walker_weight(energy: f64, e_ref: f64, beta: f64) -> f64

Unnormalized DMC-style weight from energy relative to a reference energy.

weight = exp(-beta * (E - E_ref)), floored away from zero for resampling. Callers typically set E_ref to the population minimum or a soft quantile.

Structs and Unions

struct DmcPopulationResult

Result of a budgeted population-controlled diffusion run.

best_pos: Array1<f64>

Best feasible point found under the budget.

best_val: f64

Objective value at best_pos.

n_evals: usize

Objective evaluations charged.

n_grads: usize

Gradient evaluations charged (Langevin drift).

final_population: usize

Walker count at exit.

controls: usize

Number of population-control (branch/kill) events.

struct Population

Population of walkers with a target size for control.

walkers: Vec<Walker>

Live walkers (length may transiently differ from target_n).

target_n: usize

Population size restored after each control step.

Implementations

impl Population

Functions

fn best_energy(&self) -> f64

Best finite energy in the population.

fn best_pos(&self, bounds: &Bounds<f64>) -> Array1<f64>

Position of the best finite walker (or box center if none).

fn is_empty(&self) -> bool

Whether the population has no walkers.

fn len(&self) -> usize

Current number of walkers.

fn new_random<R: Rng>(n: usize, bounds: &Bounds<f64>, energy_fn: impl Fn(ArrayView1<f64>) -> f64, rng: &mut R) -> Self

Build n walkers by reflecting random (or provided) starts into the box.

struct Walker

One walker: position and last evaluated energy.

pos: Array1<f64>

Box-feasible coordinates.

energy: f64

Last evaluated objective value at pos.