Module sampler 

The sampler seam: how a trial’s parameters are chosen.

Deliberate divergences from prior art

Every one of these is a fix for something that hurt in a framework we looked at:

• Fallible everywhere. Sampling returns Result. An infallible sample() forces implementations to panic when a space is exhausted or a numeric decomposition fails, and a panicking sampler takes the whole study down.
• Joint-space aware. Sampler::sample_relative receives the entire relative space at once, so a sampler can model correlations between parameters. A strictly per-parameter API cannot express that, no matter how good the sampler is.
• State is data, not object innards. Sampler::state returns a serializable StateBlob that the framework persists. No pickled objects, no in-instance caches that quietly break multi-process runs.
• Pending trials are always visible. StudyView::running exposes in-flight trials to every sampler, so constant-liar and qEI-style repulsion is possible without each sampler plumbing its own bookkeeping.
• Seeds are handed in, not taken. The framework precomputes TrialMeta::sampler_seed; a stateless sampler that seeds ChaCha8Rng from it is deterministic per trial number by construction.

The built-in samplers

Sampler	Chooses	Keyed on	Determinism
Random	uniformly over each support, independently	(sampler seed, parameter name)	promise 2 (stateless)
Grid	every point of a finite space, once each	the trial number	promise 2 (stateless)
Qmc	a low-discrepancy Sobol point, filling space evenly	the trial number	promise 2 (stateless)
Tpe	the point a learned density ratio prefers	the history it is shown	single-worker + replay
Dehb	a differential-evolution child of a per-fidelity population	the DE state it carries	single-worker + replay
Nsga2	a crossover-and-mutation child of a Pareto-ranked population	the population it carries	single-worker + replay

Random, Grid and Qmc are stateless: their draw is a pure function of the trial number and the space, so they carry the strongest promise the determinism contract offers. Random never draws sequentially from one per-trial RNG — each parameter gets its own stream, derived with seed_for_name, so a value is stable when the search space gains, loses or reorders a parameter, and Sampler::sample_relative and Sampler::sample_independent agree by construction.

Tpe is history-dependent — it learns from completed and pending trials — so it deliberately does not get promise 2 under parallelism. It keeps no hidden mutable state (everything is recomputed from the StudyView each decision), which buys it single-worker determinism plus replayability instead; its own documentation states this precisely.

Dehb is the first genuinely stateful sampler: it carries DE populations, one per multi-fidelity budget, that cannot be recomputed from history — so it is the first real consumer of the M4.0 state seam (state/restore_state), and a study reopened from storage continues with the exact populations it left. Like Tpe it is single-worker deterministic and parallel-replayable.

Nsga2 is the multi-objective sampler: it carries a Pareto-ranked population, ranks it by non-domination and crowding distance (pareto), and answers the question StudyView::best deliberately refuses for a multi-objective study. Like Dehb it is stateful, single-worker deterministic and parallel-replayable.

Status

M1.1 froze the trait; M1.3 added Random and Grid; M2.2 adds the history-dependent Tpe and the quasi-random Qmc; M4.2 adds the stateful Dehb; M4.4 adds the multi-objective Nsga2.

Re-exports

pub use dehb::DEFAULT_CROSSOVER_PROB;

pub use dehb::DEFAULT_MUTATION_FACTOR;

pub use dehb::Dehb;

pub use dehb::MAX_TOTAL_POP_SIZE;

pub use nsga2::DEFAULT_CROSSOVER_ETA;

pub use nsga2::DEFAULT_MUTATION_ETA;

pub use nsga2::DEFAULT_POPULATION_SIZE;

pub use nsga2::DEFAULT_SWAPPING_PROB;

pub use nsga2::MAX_POPULATION_SIZE;

pub use nsga2::MIN_POPULATION_SIZE;

pub use nsga2::Nsga2;

Modules

dehb

DEHB — Differential-Evolution Hyperband, the low-budget black-box tuner for RL.

nsga2

NSGA-II — the elitist non-dominated sorting genetic algorithm, and atune’s multi-objective sampler.

Structs

Grid

Walks every point of a finite space, once each, in a fixed order.

Qmc

A quasi-random Sobol sampler.

Random

Samples every parameter independently and uniformly over its support.

Tpe

A Tree-structured Parzen Estimator sampler.

Constants

SOBOL_DIMENSIONS

The number of Sobol dimensions this implementation covers directly.

SOBOL_POINTS

How many distinct points the sequence has: 2^BITS.

Traits

Sampler

Chooses parameter values for a trial.

Type Aliases

SamplerState

Sampler state as the framework persists it.