Crate hyperopt_rs 

hyperopt

hyperopt-rs — an Optuna-shaped hyperparameter optimization framework for Rust. This is the ergonomic facade crate: it re-exports the core types and every sampler, pruner, and storage backend, and adds a StudyBuilder so a study can be assembled in one fluent expression.

use hyperopt_rs::prelude::*;

let study = StudyBuilder::new("quadratic")
    .direction(Direction::Minimize)
    .sampler(TpeSampler::seeded(42))
    .build()?;

study.optimize(|trial| {
    let x = trial.suggest_float("x", -10.0, 10.0);
    let y = trial.suggest_float("y", -10.0, 10.0);
    Ok((x - 2.0).powi(2) + (y + 3.0).powi(2))
}, 200)?;

println!("best = {:?}", study.best_trial()?);

Modules

prelude

Common imports for using the framework: the builder, the study/trial types, direction, error/objective types, and all samplers and pruners.

Structs

CmaEsSampler

A Sampler driven by CMA-ES over the study’s numeric parameters.

GridSampler

Exhaustive search over a caller-provided discrete grid.

InMemoryStorage

In-memory storage: trials kept in a BTreeMap per study (ordered by trial number) behind a Mutex. Fast and dependency-free, but everything is lost when the process exits. This is the Phase 1–2 default.

MedianPruner

Prunes a trial when its latest intermediate value is worse than the median of other trials’ values at the same step.

NopPruner

A no-op pruner: should_prune always returns false. Use it when early-stopping isn’t wanted but the objective still calls should_prune() so the same code runs with and without pruning.

ParamRecord

One recorded (name, distribution, value) triple, in suggestion order.

RandomSampler

The simplest possible Sampler: every parameter is drawn independently and uniformly (or log-uniformly / categorically) from its distribution, with no learning from prior trials. It is the right baseline to validate the whole Trial/TrialContext/Study plumbing against, and the reference every adaptive sampler is compared to.

SqliteStorage

SQLite-backed storage: trials are persisted to a file so studies survive process restarts and can be resumed. Mirrors Optuna’s RDB storage pattern.

Study

A single optimization run: a direction, a sampler, a pruner, and a storage backend, tied to a named study whose trials live in that storage.

StudyBuilder

Fluent builder for a Study, with sensible defaults: a RandomSampler, a NopPruner, an InMemoryStorage, and Direction::Minimize. Override any of them before calling StudyBuilder::build.

StudyMetadata

Persisted study-level metadata (everything about a study except its trials).

StudyState

A read-only snapshot of a study’s history, handed to samplers and pruners.

SuccessiveHalvingPruner

ASHA-style (Asynchronous Successive Halving) pruner — the “advanced” option.

TpeSampler

Tree-structured Parzen Estimator sampler.

Trial

A single optimization trial: its suggested parameters, intermediate reports, and final objective value.

TrialContext

The handle passed into the user’s objective closure.

Enums

BoundHandling

How CMA-ES repairs a drawn coordinate that lands outside a parameter’s [0, 1] normalized box.

Direction

Optimization direction: whether the objective should be minimized or maximized. Samplers and pruners read this from StudyState::direction and adjust accordingly (e.g. TPE always minimizes internally, negating values under Maximize).

Distribution

The search-space shape recorded for a single suggested parameter.

HyperoptError

Errors raised by crate::Study operations (currently all storage-backed).

ObjectiveError

Signalled by a user objective to describe how a trial ended.

StorageError

Errors a Storage backend can raise.

TrialState

Lifecycle state of a single trial.

Value

A concrete hyperparameter value suggested for a trial.

Traits

Pruner

A pluggable early-stopping policy.

Sampler

A pluggable search algorithm.

Storage

Where a study’s trial history lives.

Type Aliases

ObjectiveResult

The value an objective closure returns for one trial.