bencher.results.optimize_result

OptimizeResult — first-class container for optimization results.

Classes

`Aggregation`	How a study reduced several evaluations of one design to the value it ranked.
`OptimizeResult`	Wraps an `optuna.Study` with bencher-friendly accessors.

Module Contents

class bencher.results.optimize_result.Aggregation

How a study reduced several evaluations of one design to the value it ranked.

A study aggregates whenever it evaluated a design more than once: over the dimensions Bench.optimize(aggregate=...) looped inside each trial, over the repeats, or both. So dims is empty for a study that only had repeats > 1, and the presence of an Aggregation is the separate — and, for a reader of the front, the load-bearing — fact that a trial’s value is a different number from any one sample of it.

This describes how the study searched, which is not a guarantee about every trial in it: warm start seeds one trial per recorded sample, so a seeded trial’s value is one evaluation whatever this says. Such a trial is marked bencher.bencher.WARM_STARTED.

fn: What combined them.

dims: The input variables looped inside each trial rather than suggested by optuna, in the study’s order. Empty when only the repeats were reduced.

fn: bencher.utils.AggFn

dims: tuple[str, ...] = ()

class bencher.results.optimize_result.OptimizeResult

Wraps an optuna.Study with bencher-friendly accessors.

study: The underlying optuna study.

n_warm_start_trials: Number of trials seeded from cache / prior results.

n_new_trials: Number of new trials evaluated during optimization.

target_names: Names of the optimization target variables.

bench_cfg: Optional BenchCfg for rich report generation.

aggregation: How several evaluations of one design became the value the study ranked, or None when a trial’s value is one sample — see Aggregation.

study: bencher.optional_deps.optuna.Study

n_warm_start_trials: int = 0

n_new_trials: int = 0

target_names: list[str] = []

bench_cfg: bencher.bench_cfg.BenchCfg | None = None

aggregation: Aggregation | None = None

_ensure_single_objective() → None: Raise if study is multi-objective.

property best_params: dict[str, Any]: Best parameters found (single-objective only).

property best_value: float: Best objective value (single-objective only).

property best_trials: list[bencher.optional_deps.optuna.trial.FrozenTrial]: Pareto-optimal trials (multi-objective).

pareto_trials(objective: str | None = None) → list[bencher.optional_deps.optuna.trial.FrozenTrial]

The Pareto front ordered along one objective, best first.

best_trials is a set in trial order, which is the order optuna happened to find them in. Sorting the front along objective — the first target by default — turns it into a walk: the trial that is best on that objective first, then each trade-off in turn, ending at the one that gave the most of it away. That is the order a slider through the front should take. A single-objective study has a front of one, its best trial.

Raises:: ValueError – if objective is not one of target_names.

property target_directions: list[bencher.variables.results.OptDir]: Each target’s direction, in target_names order, as bencher spells it.

_target_index(objective: str) → int

property searched: list[str]

Names of the input variables optuna suggested, in the study’s order.

The complement of aggregation.dims within the study’s inputs, so it is empty without a bench_cfg.

summary() → str: Return a human-readable summary of the optimization.