Module scheduler

Expand description

The scheduler seam: how a running trial’s fate is decided.

A scheduler is a superset of a pruner. Conflating the two — as Optuna does — makes pause, resume and fork inexpressible, which rules out the entire PBT/PASHA family (the scheduler). Here a pruner is simply a scheduler that only ever answers Decision::Continue or Decision::Prune.

Two shapes are load-bearing:

Scheduler::on_report takes a slice of values, because pruning is multi-objective-aware from day one (an acknowledged gap in prior art);
step is counted in the study’s declared ResourceUnit, so multi-fidelity arithmetic is explicit rather than “whatever step meant to the caller”.

§The built-in schedulers

Scheduler	Kind	Acts when
`NopScheduler`	none	never — the default
`MedianPruner`	pruner	worse than the percentile of the completed trials at the same step (variance-aware variant available)
`AshaPruner`	pruner	not in the top `1/η` of the trials that reached a rung
`HyperbandPruner`	pruner	as ASHA, within a `crc32(study, trial)`-assigned bracket
`FreezeThaw`	scheduler	pauses underperformers by extrapolated learning-curve asymptotes and resumes promising paused trials when a slot opens
`Patient`	decorator	delays an inner prune until `N` non-improving reports
`WilcoxonPruner`	pruner	significantly worse than the incumbent under a paired signed-rank test
`Pbt`	scheduler	forks an underperformer from a top performer at each interval (exploit + explore)

Pbt is the first scheduler that uses Decision::Fork rights — a population of trials in which an underperformer copies and perturbs a top performer’s checkpoint (the guide’s population-based training walks it end to end).

ASHA and Hyperband share a reusable rung core — the RungLadder of resource levels, the is_promotable promotion rule, and the storage-free bracket_of bracket assignment — which M4’s DEHB reuses unchanged.

§Determinism honesty

Every real scheduler here decides from the ask-time StudyView — median/percentile against the trials completed by then, ASHA/Hyperband against whichever trials had filled a rung. That set is completion-order dependent under parallelism, so a scheduled study is replayable (its recorded history explains every prune) rather than pre-determined (computable from the seed before it runs) — exactly the standing of a history-dependent sampler (determinism, honestly). Under a single worker with a fixed seed the completion order is fixed, so the pruning is fully reproducible. Each scheduler restates this in its own docs.

§Status

M1.1 froze the declarations; M1.3 added NopScheduler; M3.1 adds the real pruners above; M4.1 adds Pbt, the first fork-capable population scheduler.

Structs§

AshaPruner: The asynchronous successive-halving pruner.
FreezeThaw: The freeze-thaw scheduler: pause many, extrapolate, resume the promising few.
HyperbandPruner: Asynchronous Hyperband: a fan of AshaPruner brackets over one ladder.
MedianPruner: Median / percentile stopping.
NopScheduler: Lets every trial run to completion.
Patient: A decorator that delays an inner scheduler’s prune until a trial has stopped improving.
Pbt: Population-based training: exploit-and-explore at a fixed interval — the guide’s population-based training runs one end to end.
Pow3Fit: A fitted Domhan pow-3 power law y(t) = c − a·t^(−α).
RungLadder: A geometric ladder of resource levels a successive-halving scheduler gates trials at.
RungOccupancy: One rung of a RungTable: the resource level and every value that reached it.
RungTable: The typed, serializable snapshot of a whole ladder’s occupancy.
WilcoxonPruner: A statistical pruner: prune a trial that is significantly worse than the incumbent under a paired Wilcoxon signed-rank test.
WilcoxonReport: The result of a paired Wilcoxon signed-rank test over a set of differences.

Enums§

Command: Something a scheduler asks the study loop to do.
Decision: What should happen to a trial that just reported.
Dispersion: How the variance-aware variant estimates the spread of the competitors at a step.
FanReportMode: How a scheduler composes with a multi-seed trial fan.
Perturb: How a scalar hyperparameter is perturbed during the explore step.
ScriptedSchedulerCapability: Scheduler behavior that the scripted CLI can reconstruct exactly in a new process.

Constants§

DEFAULT_ALPHA: The default significance level for WilcoxonPruner.
DEFAULT_BOTTOM_FRACTION: The default exploit quantile: the bottom 20% of the population exploit (Jaderberg et al., 2017).
DEFAULT_FREEZE_FACTOR: The default reduction factor η for the extrapolated-asymptote promotion rule: keep the top half of the field by predicted asymptote, freeze the rest.
DEFAULT_KAPPA: The default acquisition exploration coefficient κ in ĉ + κ·σ̂.
DEFAULT_MIN_PAIRS: The default minimum number of paired reports before WilcoxonPruner will prune.
DEFAULT_MIN_POINTS: The default minimum number of curve points before a trial can be modelled.
DEFAULT_PERTURB_DOWN: The default multiplicative perturbation applied when exploring down.
DEFAULT_PERTURB_UP: The default multiplicative perturbation applied when exploring up.
DEFAULT_REDUCTION_FACTOR: The default reduction factor η: keep the top third at each rung.
DEFAULT_TOP_FRACTION: The default top quantile: an exploit copies a random member of the best 20% (Jaderberg et al., 2017).
FREEZE_THAW_BLOB_KIND: The kind tag of the persisted curve-store StateBlob.
FREEZE_THAW_BLOB_VERSION: The schema version of the FREEZE_THAW_BLOB_KIND payload.
MIN_ALPHA: The smallest decay exponent α a pow-3 fit may report and still be trusted as an asymptote — the shape half of the extrapolation fail-safe.
MIN_REDUCTION_FACTOR: The smallest reduction factor that makes a ladder grow.
REMAINING_FACTOR: The largest extrapolated improvement a pow-3 fit may predict, as a multiple of the improvement already observed — the magnitude half of the fail-safe.

Traits§

Scheduler: Decides the fate of running trials.

Functions§

bracket_of: Which Hyperband bracket a trial belongs to — deterministic, storage-free.
crc32_ieee: The IEEE (reflected, polynomial 0xEDB8_8320) CRC-32 of bytes.
fit_pow3: Fits the Domhan pow-3 law y(t) = c − a·t^(−α) to points (each (t, y) with t ≥ 1) by in-house Levenberg–Marquardt least squares.
is_promotable: The asynchronous successive-halving promotion rule.
wilcoxon_signed_rank: The paired Wilcoxon signed-rank statistic of a set of differences.
wilcoxon_worse: Whether candidate is significantly worse than incumbent under a paired signed-rank test at level alpha, requiring at least min_pairs effective (non-zero) pairs.

Type Aliases§

SchedulerState: Scheduler state as the framework persists it.