mod calibrate

module calibrate

Spectral statistics of the curvature, without forming a Hessian. Setting the “same basin” threshold from the search’s own steps.

Every basin-keyed mechanism in this crate compares a distance against a threshold, and until now that threshold was a number. Numbers do not transfer. A radius calibrated at 38 points is wrong at 75, one calibrated in a sorted-distance spectrum is wrong in a shape metric, and a campaign that sweeps it has tuned a constant rather than found a method.

The structure-prediction literature settled this by deriving the threshold from the descriptor’s own statistics rather than choosing it. Oganov and Valle’s fingerprint distance is used with a cutoff read off the distribution of distances the search actually produces, which is what makes fingerprint niching work across systems in USPEX rather than per system.

The definition here is the one the geometry supplies. Two structures are the same basin when one accepted hop can carry the chain between them, so the threshold is a high quantile of the distance a single accepted hop covers. Nothing about that is specific to a size or a potential: the search reports its own step length and the threshold follows.

Measured at 75 points, one accepted hop covers 0.4766 in shape distance and independent minima sit at 0.9212, so the two distributions are separated and a quantile of the first lands between them. That separation is the reason the definition works, and a system where it fails is one where the descriptor cannot tell the two apart, which the caller wants to know.

Structs and Unions

struct StepCalibrator

A threshold tracking a quantile of the steps it is shown.

Robbins-Monro on the quantile: each sample moves the estimate up by step * q` when it lands above and down by step * (1 - q)` when it lands below, so the fixed point is the level with ``q of the mass beneath it. The step decays as 1 / sqrt(n), which converges without needing a schedule.

quantile: f64

Quantile of the step-length distribution the threshold aims at.

warmup: u64

Steps required before the estimate replaces the prior.

Implementations

impl StepCalibrator

Functions

fn mean_step(&self) -> f64

Mean step length seen, which is what the threshold is a quantile of.

fn new(quantile: f64, warmup: u64, prior: f64) -> Self

Tracker aiming at quantile, holding prior until warmup steps.

The prior matters. Until the search has taken enough accepted hops to say anything about its own step length, a threshold read off three samples is worse than the value the caller came with.

fn observe(&mut self, step: f64)

Records the distance one accepted hop covered.

Non-finite and non-positive steps are ignored rather than folded in: a hop that did not move, or a shape match that failed and returned infinity, says nothing about how far a hop reaches.

fn samples(&self) -> u64

Steps recorded.

fn threshold(&self) -> f64

Current threshold: the prior until warmed up, the estimate after.

fn warm(&self) -> bool

Whether enough steps have been seen for the estimate to be used.