mod cluster_search

module cluster_search

Running a cluster search against an objective.

crate::methods::cluster_hopping::run takes a relaxation and a gradient as closures, which is the right interface for a driver: it does not care where the energy comes from. It is the wrong interface for a caller, because every caller then writes the same three things, and the campaign this crate reports was run against potentials defined inside its own examples.

This is the missing half. Hand it anything implementing DifferentiableObjective<f64> and it builds the relaxation, charges every evaluation to the ledger, counts what converged and runs the search.

What that buys is provenance. rgpot reaches this crate as an eindir_objective_t, wrapped into an Objective<f64>, so a potential from there arrives at the cluster driver by the same route as one written here and neither the driver nor this function can tell them apart.

Variables

const CONVERGED_GRADIENT: f64

Gradient magnitude below which a relaxation counts as converged.

Loose enough that a screening pass is not called converged and tight enough that a genuine minimum is: on a Lennard-Jones cluster a quenched structure comes back at about 1e-6.

Functions

fn catalog_saturated(wells: &[(Array1<f64>, f64)], w0: f64) -> bool

Good-Turing missing mass on shared packings. Saturated: enough observations and few singletons, so the next start should leave.

fn first_encounter(out: &Outcome, target: f64, tolerance: f64, spent: usize) -> Encounter

The first encounter with target in a run’s improvement trace.

target is compared with a tolerance, since a published minimum is quoted to six decimals and a relaxation lands near it rather than on it.

fn median_encounter(runs: &[Encounter]) -> Option<usize>

Median first encounter time under censoring, by Kaplan-Meier.

The median is the point where the survival function first falls to a half. None when more than half the runs are censored, which is the honest answer: the median has not been observed, and quoting the mean of the successes instead reports a number that improves as the method gets worse.

fn search<O>(objective: &O, cfg: &Config, ledger: &mut Ledger, seed: u64) -> (Outcome, RelaxStats)
where
    O: DifferentiableObjective<f64> + ?Sized

Runs a cluster search on objective under ledger.

The relaxation is this crate’s warm-started quasi-Newton one, and its curvature is deliberately not carried between calls: measured on a cluster, retaining it across a structural change costs more than it saves.

fn search_from<O>(objective: &O, cfg: &Config, ledger: &mut Ledger, start: ArrayView1<f64>, seed: u64) -> (Outcome, RelaxStats)
where
    O: DifferentiableObjective<f64> + ?Sized

As search, from a geometry the caller already has.

A slab or a packed molecular start is not a random cluster in a sphere. The hop RNG is seeded independently of that geometry.

fn search_from_bank<O>(objective: &O, cfg: &Config, ledger: &mut Ledger, start: ArrayView1<f64>, seed: u64, sock: &str) -> (Outcome, RelaxStats)
where
    O: DifferentiableObjective<f64> + ?Sized

One HQ chain against the Cap’n Proto bank: own walk, pull a win or a new packing, leave when the shared catalog is saturated.

The start is the caller’s geometry (a packed water cluster, a slab plus adsorbate), not a random LJ sphere.

fn search_from_maybe_bank<O>(objective: &O, cfg: &Config, ledger: &mut Ledger, start: ArrayView1<f64>, seed: u64) -> (Outcome, RelaxStats)
where
    O: DifferentiableObjective<f64> + ?Sized

search_from when BANK_RPC is unset; search_from_bank when it is.

One binary, two arms. The control is the same walk without the shared catalog. First-encounter charged evaluations are what says which is cheaper, not whether both finished.

fn verify<O>(objective: &O, out: &Outcome) -> Option<(f64, f64)>
where
    O: DifferentiableObjective<f64> + ?Sized

Checks that a reported result is what it claims to be.

Returns the energy of the returned structure and its largest gradient component, both computed off the ledger and outside the driver. None when no structure came back at all.

Worth having as a function rather than as a line in each example, because checking only the energy is not enough: an arm of this crate once returned a structure carrying the right energy with a gradient of 0.31, which is not a minimum, and the energy check passed.

Enums

enum Encounter

Work spent before a run first reached target, or how much it spent without reaching it.

The statistic to report. A success rate at a fixed budget is this quantity pushed through an arbitrary threshold: above the budget it saturates and hides the margin, below it censors and hides how near the failures came. Eight seeds in eight at twelve million evaluations and five in eight at three million are the same method described twice, badly.

A first encounter time is a property of the method. It is what lets one paper’s result be compared with another’s, and it is what makes a claim like a seventyfold improvement mean something.

Censoring

A run that never reached the target has not produced a first encounter time; it has produced a lower bound. That is Encounter::Censored, and it must not be dropped or replaced by the budget: dropping the failures reports the mean of the successes, which is smaller than the truth and gets smaller as the method gets worse.

Found

Charged evaluations spent when the target was first reached.

charged: usize

Charged evaluations at the first crossing.

hops: usize

Hops at the first crossing.

Censored

The target was never reached; the run spent this much without it.

charged: usize

Charged evaluations spent in total.

Implementations

impl Encounter

Functions

fn charged(&self) -> usize

The charged count either way, which is the encounter time when found and a lower bound on it when censored.

fn found(&self) -> bool

Whether the target was reached.

Structs and Unions

struct RelaxStats

What a search did, beyond the outcome the driver reports.

converged: usize

Relaxations that reached a point with a small gradient.

screen_charged: usize

Charged evaluations spent in screening passes.

Split from the full relaxations because the two are different levers. Every mechanism in this crate that tried to change where the chain goes was measured and failed; the one that helped, the return screen, buys hops by not paying for relaxations that will be discarded. If throughput is what moves the number then knowing which pass the budget goes to is the first thing to establish, and it has never been measured here.

full_charged: usize

Charged evaluations spent in full relaxations.

check_charged: usize

Charged evaluations spent confirming convergence.

capped: usize

Relaxations that stopped at their iteration cap.

A large share of these is not by itself wrong, because the screening pass is capped deliberately, but a run where nothing converges is not on the quenched landscape and every mechanism above it is acting on noise.

screens: usize

Screening passes run.

probe_stops: usize

Screens where the predictor would have stopped, under probing.

probe_steps: usize

Steps at which it would have stopped, summed.

probe_error: f64

Absolute error of the extrapolation against the full screen, summed.

The number that decides whether a screening pass can be shortened at all. If the extrapolation from five steps predicts the twenty-five step energy to well inside the spacing between neighbouring minima, the extra twenty steps are buying precision nothing uses. If it does not, the screen is not overhead around the quench, it is the quench.

screen_steps_taken: usize

Descent steps those passes took, summed.

Against screens * screen_steps this is what stopping on a decision bought, and it is the only number that says whether it bought anything.

Implementations

impl RelaxStats

Functions

fn charged(&self) -> usize

Charged evaluations across both passes and the convergence check.

fn screen_share(&self) -> f64

Share of the charged budget spent screening.

fn total(&self) -> usize

Relaxation calls made.