parzen/
lib.rs

1// Copyright 2026 Thomas Santerre and Moderately AI Inc.
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5#![cfg_attr(
6    not(test),
7    deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)
8)]
9
10//! High-performance Tree-structured Parzen Estimator optimization.
11//!
12//! ```rust
13//! use parzen::{
14//!     CategoricalDistribution, Direction, Distribution, SearchSpace, Study,
15//!     TpeSampler, TpeSamplerConfig,
16//! };
17//!
18//! # fn main() -> Result<(), parzen::ParzenError> {
19//! let mut space = SearchSpace::new();
20//! space.add("x", Distribution::Categorical(CategoricalDistribution::new(5)?))?;
21//! let sampler = TpeSampler::new(TpeSamplerConfig::performance(42).startup_trials(5))?;
22//! let mut study = Study::new(Direction::Maximize, sampler, space)?;
23//!
24//! for _ in 0..20 {
25//!     let x = study.suggest_categorical("x")?;
26//!     study.complete_trial(if x == 2 { 1.0 } else { 0.1 })?;
27//! }
28//! assert!(study.best_value().is_some_and(|value| value > 0.5));
29//! # Ok(()) }
30//! ```
31//!
32//! Explicit parameter groups use one trial-aligned mixture component for the
33//! entire vector. Their joint likelihood is
34//! `logsumexp(log(weight[k]) + sum_d log(kernel[d][k](x[d])))`, preserving
35//! correlations that independent marginal models discard. Integer and stepped
36//! distributions integrate each Gaussian kernel over the selected grid cell
37//! instead of treating a discrete value as a continuous point.
38//!
39//! [`HistoryPolicy::Bounded`] keeps a fixed-size exact best set, recent bad
40//! observations, and a deterministic reservoir, so estimator state and
41//! incremental update work do not grow with completed-trial count. Raw trial
42//! records remain complete. [`HistoryPolicy::Full`] retains exact full-history
43//! ranking and therefore has linear storage and model-construction costs.
44
45mod distribution;
46mod error;
47mod sampler;
48mod search_space;
49mod storage;
50mod study;
51mod trial;
52
53pub use distribution::{
54    CategoricalDistribution, Distribution, FloatDistribution, FloatScale, IntDistribution, IntScale,
55};
56pub use error::ParzenError;
57pub use sampler::{
58    GammaStrategy, HistoryPolicy, ModelStrategy, TpeSampler, TpeSamplerConfig, WeightStrategy,
59};
60pub use search_space::{Condition, GroupId, ParamId, ParameterRef, SearchSpace};
61pub use study::Study;
62pub use trial::{
63    Direction, ParamValue, Params, TrialId, TrialInput, TrialRecord, TrialRef, Trials,
64};
parzen/lib.rs

parzen/
lib.rs
