Struct MedianPruner 

pub struct MedianPruner { /* private fields */ }

Median / percentile stopping.

Prunes a trial reporting at step k when its value is worse than the p-th percentile of the values that the completed trials reached at step k.

Warm-up guards (Optuna’s n_startup_trials / n_warmup_steps)

Two guards keep the pruner from acting on noise or on an empty baseline:

• with_startup_trials — no pruning until at least this many trials have completed (default 5). Early on there is no trustworthy baseline.
• with_warmup_steps — no pruning at a step below this (default 0). RL curves are often worst right after initialization.
• with_min_trials — the percentile is only formed once at least this many competitors reported at the step itself (default 1).

Direction awareness

“Worse than the percentile” is resolved through Direction::is_better, so a Maximize and a Minimize study prune opposite trials on the same curves. For a Maximize study the (100 − p)-th percentile is used, so p = 50 is the median for both.

Multi-objective

There is no single “worse than the median” across a Pareto front, so on a multi-objective study this pruner never prunes (returns Decision::Continue) rather than guess a total order and risk pruning a Pareto-optimal trial. Single-objective studies gate on their one objective.

Determinism

The decision is a pure function of the StudyView the trial was handed at ask time, so it depends on which other trials had completed by then — which under parallelism is completion-order dependent. A median-scheduled study is therefore replayable, not pre-determined, exactly like a history-dependent sampler (where determinism stops). Under a single worker with a fixed seed the completion order is fixed, so the pruning is fully reproducible.

use atune_core::scheduler::MedianPruner;

// Plain median, no pruning until 10 trials have completed.
let pruner = MedianPruner::new().with_startup_trials(10);

// The variance-aware variant: prune only past 1 standard deviation of noise.
let robust = MedianPruner::variance_aware();

Implementations

impl MedianPruner

pub const fn new() -> Self

The plain median pruner: p = 50, startup_trials = 5, warmup_steps = 0, min_trials = 1, no dispersion gate.

pub fn percentile(percentile: f64) -> Result<Self>

A percentile pruner at percentile (in (0, 100)).

Errors

Error::InvalidSpace if percentile is not strictly inside (0, 100) — 0 or 100 would prune everything or nothing.

pub const fn variance_aware() -> Self

The variance-aware median: prune only when the gap to the median exceeds one Dispersion::Std of the competitors (see the type docs).

pub const fn with_dispersion(self, dispersion: Dispersion) -> Self

Sets the dispersion measure and turns the variance-aware gate on.

pub const fn with_kappa(self, kappa: f64) -> Self

Sets the dispersion multiplier kappa (variance-aware only): the gap must exceed kappa dispersions to prune. Larger is more forgiving.

pub const fn with_startup_trials(self, startup_trials: usize) -> Self

Sets the minimum number of completed trials before any pruning.

pub const fn with_warmup_steps(self, warmup_steps: u64) -> Self

Sets the minimum step before any pruning.

pub const fn with_min_trials(self, min_trials: usize) -> Self

Sets the minimum number of competitors at a step before the percentile is trusted.

pub const fn with_objective(self, obj: usize) -> Self

Selects which objective dimension to gate on (default 0).

Trait Implementations

impl Clone for MedianPruner

fn clone(&self) -> MedianPruner

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for MedianPruner

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for MedianPruner

fn default() -> Self

The plain median with default guards — see MedianPruner::new.

impl Scheduler for MedianPruner

fn on_report( &self, study: &StudyView, _trial: &TrialMeta, step: u64, values: &[f64], ) -> Result<Decision>

Prunes a trial worse than the percentile at its current step; see the type docs.

Errors

Error::InvalidSpace if a configuration knob is invalid or the selected objective is not present in the study.

fn state(&self) -> Result<Option<SchedulerState>>

None: the pruner keeps no persistent state, deriving every decision from the StudyView (the Tpe pattern).

fn fan_report_mode(&self) -> FanReportMode

Declares whether this scheduler accepts aligned aggregate fan reports.

fn scripted_capability(&self) -> ScriptedSchedulerCapability

Declares whether scripted ask/tell can recreate this scheduler.

fn on_trial_end( &self, study: &StudyView, trial: &FrozenTrial, ) -> Result<Vec<Command>>

Called once a trial reaches a terminal state.

fn resume_candidates(&self, study: &StudyView) -> Result<Vec<Command>>

Paused trials worth waking on a freed work slot, in priority order.

fn restore_state(&self, blob: &SchedulerState) -> Result<()>

Restores a scheduler from a previously persisted blob.