docs(0.9): release notes, cookbook recipe, README polish

Companion to the feat(explorer) commit. Bumps the version and
brings every cross-referencing doc up to v0.9 currency.

- Cargo.toml: version 0.8.0 -> 0.9.0.
- CHANGELOG: 0.9.0 entry covering the explorer export, the
  Problem-side metadata additions, the AlgorithmInfo trait, the
  pick_a_car example, and the new cookbook recipe.
- README: closing paragraph of the PickACar example points users
  at the explorer with a one-call snippet
  (`ExplorerExport::from_result(...).with_algorithm_info(...)
  .to_file(...)?`). Version snippets bumped 0.8 -> 0.9.
- New cookbook recipe at docs/book/src/cookbook/explorer.md
  covering: enabling the serde feature, enriching Problem with
  labels/units/decision-schema, the export call, the JSON schema,
  and custom decision-type handling.
- SUMMARY.md and cookbook.md link the new recipe.
- migration.md: new "To 0.9" section documenting the additive
  changes (purely backwards-compatible upgrade from 0.8.x).
- introduction.md, comparison.md, choosing-an-algorithm.md,
  stability.md: version refs bumped 0.8 -> 0.9.
- cookbook/parallel.md, cookbook/async.md: version refs bumped
  0.8 -> 0.9.
- getting-started.md: version refs bumped, serde feature
  description expanded to mention the explorer module.
- SECURITY.md: supported-versions table moves to 0.9.x.
This commit is contained in:
2026-05-06 22:45:59 -06:00
parent 729842c260
commit 6371d82f40
55 changed files with 721 additions and 354 deletions
+4 -1
View File
@@ -426,7 +426,10 @@ fn estimate_p(front_indices: &[usize], translated: &[Vec<f64>], m: usize) -> f64
impl<I, V> crate::traits::AlgorithmInfo for AgeMoea<I, V> {
fn name(&self) -> &'static str {
"AgeMoea"
"AGE-MOEA"
}
fn full_name(&self) -> &'static str {
"Adaptive Geometry Estimation Multi-Objective Evolutionary Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -431,7 +431,10 @@ fn better_than_so(
impl crate::traits::AlgorithmInfo for AntColonyTsp {
fn name(&self) -> &'static str {
"AntColonyTsp"
"Ant Colony"
}
fn full_name(&self) -> &'static str {
"Ant Colony System for TSP"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -542,7 +542,10 @@ impl BayesianOpt {
impl crate::traits::AlgorithmInfo for BayesianOpt {
fn name(&self) -> &'static str {
"BayesianOpt"
"Bayesian Optimization"
}
fn full_name(&self) -> &'static str {
"Gaussian Process Bayesian Optimization with Expected Improvement"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -630,7 +630,10 @@ fn better_than_so(
impl crate::traits::AlgorithmInfo for CmaEs {
fn name(&self) -> &'static str {
"CmaEs"
"CMA-ES"
}
fn full_name(&self) -> &'static str {
"Covariance Matrix Adaptation Evolution Strategy"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -305,7 +305,10 @@ fn pick_three_distinct(
impl crate::traits::AlgorithmInfo for DifferentialEvolution {
fn name(&self) -> &'static str {
"DifferentialEvolution"
"DE"
}
fn full_name(&self) -> &'static str {
"Differential Evolution"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -398,7 +398,10 @@ fn box_dominates(a: &[i64], b: &[i64]) -> bool {
impl<I, V> crate::traits::AlgorithmInfo for EpsilonMoea<I, V> {
fn name(&self) -> &'static str {
"EpsilonMoea"
"ε-MOEA"
}
fn full_name(&self) -> &'static str {
"ε-dominance Multi-Objective Evolutionary Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -319,7 +319,10 @@ fn compare_for_fitness<D>(
impl<I, V> crate::traits::AlgorithmInfo for GeneticAlgorithm<I, V> {
fn name(&self) -> &'static str {
"GeneticAlgorithm"
"GA"
}
fn full_name(&self) -> &'static str {
"Genetic Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -336,7 +336,10 @@ fn environmental_selection<D: Clone>(
impl<I, V> crate::traits::AlgorithmInfo for Grea<I, V> {
fn name(&self) -> &'static str {
"Grea"
"GrEA"
}
fn full_name(&self) -> &'static str {
"Grid-based Evolutionary Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -226,7 +226,10 @@ impl<I, V> HillClimber<I, V> {
impl<I, V> crate::traits::AlgorithmInfo for HillClimber<I, V> {
fn name(&self) -> &'static str {
"HillClimber"
"Hill Climber"
}
fn full_name(&self) -> &'static str {
"Hill Climbing"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -461,7 +461,10 @@ fn binary_tournament(fitness: &[f64], rng: &mut Rng) -> usize {
impl<I, V> crate::traits::AlgorithmInfo for Hype<I, V> {
fn name(&self) -> &'static str {
"Hype"
"HypE"
}
fn full_name(&self) -> &'static str {
"Hypervolume Estimation Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+3
View File
@@ -337,6 +337,9 @@ where
fn name(&self) -> &'static str {
"Hyperband"
}
fn full_name(&self) -> &'static str {
"Hyperband multi-fidelity bandit search"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
}
+4 -1
View File
@@ -387,7 +387,10 @@ fn binary_tournament(fitness: &[f64], rng: &mut Rng) -> usize {
impl<I, V> crate::traits::AlgorithmInfo for Ibea<I, V> {
fn name(&self) -> &'static str {
"Ibea"
"IBEA"
}
fn full_name(&self) -> &'static str {
"Indicator-Based Evolutionary Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -289,7 +289,10 @@ fn better(a: &Evaluation, b: &Evaluation, direction: Direction) -> bool {
impl crate::traits::AlgorithmInfo for IpopCmaEs {
fn name(&self) -> &'static str {
"IpopCmaEs"
"IPOP-CMA-ES"
}
fn full_name(&self) -> &'static str {
"Increasing-Population CMA-ES with Restarts"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -330,7 +330,10 @@ fn perpendicular_distance(point: &[f64], extremes: &[usize], oriented: &[Vec<f64
impl<I, V> crate::traits::AlgorithmInfo for Knea<I, V> {
fn name(&self) -> &'static str {
"Knea"
"KnEA"
}
fn full_name(&self) -> &'static str {
"Knee point-driven Evolutionary Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -365,7 +365,10 @@ fn weight_distance(a: &[f64], b: &[f64]) -> f64 {
impl<I, V> crate::traits::AlgorithmInfo for Moead<I, V> {
fn name(&self) -> &'static str {
"Moead"
"MOEA/D"
}
fn full_name(&self) -> &'static str {
"Multi-Objective Evolutionary Algorithm based on Decomposition"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -332,7 +332,10 @@ impl Mopso {
impl crate::traits::AlgorithmInfo for Mopso {
fn name(&self) -> &'static str {
"Mopso"
"MOPSO"
}
fn full_name(&self) -> &'static str {
"Multi-Objective Particle Swarm Optimization"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -452,7 +452,10 @@ impl NelderMead {
impl crate::traits::AlgorithmInfo for NelderMead {
fn name(&self) -> &'static str {
"NelderMead"
"Nelder-Mead"
}
fn full_name(&self) -> &'static str {
"Nelder-Mead simplex direct search"
}
}
+4 -1
View File
@@ -366,7 +366,10 @@ fn binary_tournament<D>(entries: &[Nsga2Entry<D>], rng: &mut Rng) -> usize {
impl<I, V> crate::traits::AlgorithmInfo for Nsga2<I, V> {
fn name(&self) -> &'static str {
"Nsga2"
"NSGA-II"
}
fn full_name(&self) -> &'static str {
"Non-dominated Sorting Genetic Algorithm II"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -544,7 +544,10 @@ fn associate(
impl<I, V> crate::traits::AlgorithmInfo for Nsga3<I, V> {
fn name(&self) -> &'static str {
"Nsga3"
"NSGA-III"
}
fn full_name(&self) -> &'static str {
"Non-dominated Sorting Genetic Algorithm III"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -287,7 +287,10 @@ impl OnePlusOneEs {
impl crate::traits::AlgorithmInfo for OnePlusOneEs {
fn name(&self) -> &'static str {
"OnePlusOneEs"
"(1+1)-ES"
}
fn full_name(&self) -> &'static str {
"(1+1) Evolution Strategy with one-fifth success rule"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -244,7 +244,10 @@ impl<I, V> Paes<I, V> {
impl<I, V> crate::traits::AlgorithmInfo for Paes<I, V> {
fn name(&self) -> &'static str {
"Paes"
"PAES"
}
fn full_name(&self) -> &'static str {
"Pareto Archived Evolution Strategy"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -359,7 +359,10 @@ fn best_index(values: &[f64], direction: Direction) -> usize {
impl crate::traits::AlgorithmInfo for ParticleSwarm {
fn name(&self) -> &'static str {
"ParticleSwarm"
"PSO"
}
fn full_name(&self) -> &'static str {
"Particle Swarm Optimization"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -411,7 +411,10 @@ fn truncate_by_grid<D: Clone>(archive: &mut ParetoArchive<D>, max_size: usize, d
impl<I, V> crate::traits::AlgorithmInfo for PesaII<I, V> {
fn name(&self) -> &'static str {
"PesaII"
"PESA-II"
}
fn full_name(&self) -> &'static str {
"Pareto Envelope-based Selection Algorithm II"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+1 -1
View File
@@ -160,7 +160,7 @@ impl<I> RandomSearch<I> {
impl<I> crate::traits::AlgorithmInfo for RandomSearch<I> {
fn name(&self) -> &'static str {
"RandomSearch"
"Random Search"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -468,7 +468,10 @@ fn smallest_neighbor_angle(references: &[Vec<f64>]) -> f64 {
impl<I, V> crate::traits::AlgorithmInfo for Rvea<I, V> {
fn name(&self) -> &'static str {
"Rvea"
"RVEA"
}
fn full_name(&self) -> &'static str {
"Reference Vector-guided Evolutionary Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+1 -1
View File
@@ -335,7 +335,7 @@ impl<I, V> SimulatedAnnealing<I, V> {
impl<I, V> crate::traits::AlgorithmInfo for SimulatedAnnealing<I, V> {
fn name(&self) -> &'static str {
"SimulatedAnnealing"
"Simulated Annealing"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -291,7 +291,10 @@ fn pick_drop_index<D>(
impl<I, V> crate::traits::AlgorithmInfo for SmsEmoa<I, V> {
fn name(&self) -> &'static str {
"SmsEmoa"
"SMS-EMOA"
}
fn full_name(&self) -> &'static str {
"S-Metric Selection Evolutionary Multi-Objective Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -391,7 +391,10 @@ fn better(a: &Evaluation, b: &Evaluation, direction: Direction) -> bool {
impl crate::traits::AlgorithmInfo for SeparableNes {
fn name(&self) -> &'static str {
"SeparableNes"
"sNES"
}
fn full_name(&self) -> &'static str {
"Separable Natural Evolution Strategy"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -505,7 +505,10 @@ fn binary_tournament(fitness: &[f64], rng: &mut Rng) -> usize {
impl<I, V> crate::traits::AlgorithmInfo for Spea2<I, V> {
fn name(&self) -> &'static str {
"Spea2"
"SPEA2"
}
fn full_name(&self) -> &'static str {
"Strength Pareto Evolutionary Algorithm 2"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+1 -1
View File
@@ -338,7 +338,7 @@ where
N: FnMut(&D, &mut Rng) -> Vec<D>,
{
fn name(&self) -> &'static str {
"TabuSearch"
"Tabu Search"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -327,7 +327,10 @@ fn better(a: &Evaluation, b: &Evaluation, direction: Direction) -> bool {
impl crate::traits::AlgorithmInfo for Tlbo {
fn name(&self) -> &'static str {
"Tlbo"
"TLBO"
}
fn full_name(&self) -> &'static str {
"Teaching-Learning-Based Optimization"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -481,7 +481,10 @@ impl Tpe {
impl crate::traits::AlgorithmInfo for Tpe {
fn name(&self) -> &'static str {
"Tpe"
"TPE"
}
fn full_name(&self) -> &'static str {
"Tree-structured Parzen Estimator"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+4 -1
View File
@@ -354,7 +354,10 @@ fn better_than_so(
impl crate::traits::AlgorithmInfo for Umda {
fn name(&self) -> &'static str {
"Umda"
"UMDA"
}
fn full_name(&self) -> &'static str {
"Univariate Marginal Distribution Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(self.config.seed)
+19 -4
View File
@@ -101,10 +101,16 @@ pub struct RunMeta {
/// Optional human-readable problem name (e.g. `"Pick a car"`).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub problem_name: Option<String>,
/// Canonical algorithm name (e.g. `"Nsga3"`). Pulled from
/// [`AlgorithmInfo::name`] when an algorithm is provided.
/// Canonical short algorithm name (e.g. `"NSGA-III"`). Pulled
/// from [`AlgorithmInfo::name`] when an algorithm is provided.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub algorithm: Option<String>,
/// Academic long form (e.g. `"Non-dominated Sorting Genetic
/// Algorithm III"`). Pulled from [`AlgorithmInfo::full_name`]
/// when an algorithm is provided. Display tools render this
/// as a tooltip / aria-label on the short name.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub algorithm_full_name: Option<String>,
/// Seed driving this run, if applicable. Pulled from
/// [`AlgorithmInfo::seed`].
#[serde(default, skip_serializing_if = "Option::is_none")]
@@ -216,10 +222,12 @@ impl ExplorerExport {
}
}
/// Populate `algorithm` and `seed` from anything implementing
/// [`AlgorithmInfo`] — every built-in algorithm does.
/// Populate `algorithm`, `algorithm_full_name`, and `seed`
/// from anything implementing [`AlgorithmInfo`] — every
/// built-in algorithm does.
pub fn with_algorithm_info<A: AlgorithmInfo>(mut self, algorithm: &A) -> Self {
self.run.algorithm = Some(algorithm.name().to_owned());
self.run.algorithm_full_name = Some(algorithm.full_name().to_owned());
self.run.seed = algorithm.seed();
self
}
@@ -412,6 +420,9 @@ mod tests {
fn name(&self) -> &'static str {
"DummyAlgo"
}
fn full_name(&self) -> &'static str {
"Dummy Test Algorithm"
}
fn seed(&self) -> Option<u64> {
Some(123)
}
@@ -513,6 +524,10 @@ mod tests {
let result = make_result(vec![vec![0.0, 1.0]], |d| d.to_vec());
let export = ExplorerExport::from_result(&problem, &result).with_algorithm_info(&DummyAlgo);
assert_eq!(export.run.algorithm.as_deref(), Some("DummyAlgo"));
assert_eq!(
export.run.algorithm_full_name.as_deref(),
Some("Dummy Test Algorithm"),
);
assert_eq!(export.run.seed, Some(123));
}
+35 -15
View File
@@ -1,25 +1,45 @@
//! Lightweight metadata about an algorithm — its short canonical name
//! and the seed driving the current run.
//! Lightweight metadata about an algorithm — its canonical short
//! name, an academic long name, and the seed driving the current
//! run.
//!
//! `AlgorithmInfo` is separate from [`Optimizer<P>`](super::Optimizer)
//! so multi-fidelity algorithms (which use `PartialProblem` instead of
//! `Problem`) can implement it uniformly. Every built-in algorithm in
//! `heuropt` implements `AlgorithmInfo`; the explorer JSON export reads
//! these methods to populate `algorithm` and `seed` fields in the
//! exported run metadata.
//! so multi-fidelity algorithms (which use `PartialProblem` instead
//! of `Problem`) can implement it uniformly. Every built-in
//! algorithm in `heuropt` implements `AlgorithmInfo`; the explorer
//! JSON export reads these methods to populate the `algorithm` and
//! `algorithm_full_name` fields in the exported run metadata.
/// Algorithm metadata used by tooling such as the explorer JSON export.
/// Algorithm metadata used by tooling such as the explorer JSON
/// export.
///
/// Implementors return a short canonical name like `"Nsga3"` or
/// `"DifferentialEvolution"`, and the seed driving their current run
/// when applicable.
/// Implementors return:
/// - **`name`** — the canonical short display name as it appears
/// in the literature: `"NSGA-II"`, `"MOEA/D"`, `"ε-MOEA"`,
/// `"CMA-ES"`. *Not* the Rust type name.
/// - **`full_name`** — the academic long form, e.g.
/// `"Non-dominated Sorting Genetic Algorithm II"`. Defaults to
/// `name()` when not overridden, which is the right answer for
/// algorithms whose short name *is* their full name (Random
/// Search, Hill Climber, Tabu Search, …).
/// - **`seed`** — the deterministic seed driving this run, when
/// the algorithm uses one. Defaults to `None`.
pub trait AlgorithmInfo {
/// Short, canonical algorithm name — e.g. `"Nsga3"`,
/// `"DifferentialEvolution"`, `"BayesianOpt"`.
/// Canonical short algorithm name — e.g. `"NSGA-II"`,
/// `"DE"`, `"CMA-ES"`. This is the form that should appear
/// in tables, plot legends, and exported JSON metadata.
fn name(&self) -> &'static str;
/// The deterministic seed driving this run, if the algorithm uses
/// one. Default: `None`. Built-in algorithms return
/// Academic long name, expanded — e.g.
/// `"Non-dominated Sorting Genetic Algorithm II"`. Defaults
/// to `name()` for algorithms whose short and long forms
/// coincide (Random Search, Hill Climber, Tabu Search,
/// Hyperband, …).
fn full_name(&self) -> &'static str {
self.name()
}
/// The deterministic seed driving this run, if the algorithm
/// uses one. Default: `None`. Built-in algorithms return
/// `Some(self.config.seed)`.
fn seed(&self) -> Option<u64> {
None