1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
// Clippy allows for intentional patterns in this library
// Matrix operations are clearer with explicit indices
// Some Default impls have doc comments
// Closure style consistency
// Custom add methods for domain types
// Explicit .get(0) is clearer in some contexts
// into_iter() for clarity
// Pattern clarity
// from_* methods for domain types
// Tree traversal parameters
// Sometimes intentional for clarity
// Explicit clamp logic for clarity
// Matrix operations clarity
//! # fugue-evo
//!
//! A Probabilistic Genetic Algorithm Library for Rust.
//!
//! This library is primarily a broad, standalone **evolutionary computation**
//! toolkit that *optionally* interoperates with the
//! [fugue-ppl](https://github.com/fugue-ppl/fugue) probabilistic-programming
//! library. Being precise about the coupling (EV-17): the default flagship
//! algorithms — [`SimpleGA`](algorithms::simple_ga::SimpleGA), CMA-ES, NSGA-II,
//! Island Model, Evolution Strategy, EDA/UMDA, SteadyState — are ordinary EC.
//! They use fugue's [`Trace`](fugue::Trace) only as an address→value **data
//! container** for the optional `to_trace`/`from_trace` round-trip; they never
//! construct a fugue `Model` or call its inference engines. The genuine
//! "evolution as Bayesian inference over solution spaces" machinery —
//! `EvolutionarySMC` (tempered SMC over a Boltzmann posterior), `EvolutionStep`,
//! and `BayesianAdaptiveGA` — lives entirely in the [`fugue_integration`]
//! module (exercised by `examples/bayesian_evolution.rs`), which is where
//! fugue's `Model`/`factor` inference path is actually used. Treat that module,
//! not the default algorithms, as the "deep integration" story.
//!
//! ## Features
//!
//! - **Multiple Algorithms**: SimpleGA, CMA-ES, NSGA-II, Island Model, EDA, Interactive GA (standalone EC)
//! - **Flexible Genomes**: RealVector, BitString, Permutation, TreeGenome
//! - **Modular Operators**: Pluggable selection, crossover, and mutation operators
//! - **Adaptive Hyperparameters**: opt-in Thompson-sampling tuning of operator parameters (`SimpleGABuilder::adaptive_operators` + `SimpleGA::run_adaptive`)
//! - **Optional Fugue integration**: [`fugue_integration`] adds a genuine tempered-SMC / Boltzmann inference path over evolutionary traces
//! - **Production Ready**: Checkpointing (bit-identical resume), parallel evaluation, WASM support
//!
//! ## Core Concepts
//!
//! - **Fitness as Likelihood**: the exp(f/T) ↔ conditioning correspondence, realized concretely by [`BoltzmannSelection`](operators::selection::BoltzmannSelection) and by the tempered-SMC path in [`fugue_integration`]
//! - **Learnable Operators**: opt-in online tuning of operator parameters via a Thompson-sampling bandit (`SimpleGABuilder::adaptive_operators` + `run_adaptive`); the default `run` path uses fixed parameters
//! - **Trace-Based Evolution**: genomes round-trip through fugue [`Trace`](fugue::Trace)s as a data structure; the deeper Fugue-integrated inference (SMC/Boltzmann) is scoped to the [`fugue_integration`] module, not the default algorithms
//! - **Type Safety**: Compile-time guarantees via Rust's type system
//!
//! ## Quick Start
//!
//! Add to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! fugue-evo = "0.1"
//! rand = "0.8"
//! ```
//!
//! Basic optimization example:
//!
//! ```rust,ignore
//! use fugue_evo::prelude::*;
//! use rand::rngs::StdRng;
//! use rand::SeedableRng;
//!
//! fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let mut rng = StdRng::seed_from_u64(42);
//!
//! // Define search bounds: 10 dimensions in [-5.12, 5.12]
//! let bounds = MultiBounds::symmetric(5.12, 10);
//!
//! // Run optimization. `real_valued()` pins the genome/fitness types (no
//! // turbofish) and pre-installs tournament selection, SBX crossover, and
//! // polynomial mutation as overridable defaults.
//! let result = SimpleGABuilder::real_valued()
//! .population_size(100)
//! .bounds(bounds)
//! .fitness(Sphere::new(10))
//! .max_generations(200)
//! .build()?
//! .run(&mut rng)?;
//!
//! println!("Best fitness: {:.6}", result.best_fitness);
//! Ok(())
//! }
//! ```
//!
//! ## Module Overview
//!
//! - [`algorithms`]: Optimization algorithms (SimpleGA, CMA-ES, NSGA-II, Island Model)
//! - [`genome`]: Genome types and the [`EvolutionaryGenome`](genome::traits::EvolutionaryGenome) trait
//! - [`operators`]: Selection, crossover, and mutation operators
//! - [`fitness`]: Fitness traits and benchmark functions
//! - [`population`]: Population management and individual types
//! - [`termination`]: Stopping criteria (max generations, target fitness, stagnation)
//! - [`hyperparameter`]: Adaptive and Bayesian hyperparameter tuning
//! - [`interactive`]: Human-in-the-loop evolutionary optimization
//! - [`checkpoint`]: State serialization for pause/resume
//! - [`fugue_integration`]: Trace operators and effect handlers
//!
//! ## Examples
//!
//! See the `examples/` directory for complete examples:
//!
//! - `sphere_optimization.rs`: Basic continuous optimization
//! - `rastrigin_benchmark.rs`: Multimodal function optimization
//! - `cma_es_example.rs`: CMA-ES algorithm usage
//! - `island_model.rs`: Parallel island evolution
//! - `hyperparameter_learning.rs`: Bayesian parameter adaptation
//! - `symbolic_regression.rs`: Genetic programming
//! - `checkpointing.rs`: Save/restore evolution state
//! - `interactive_evolution.rs`: Human-in-the-loop optimization
/// Prelude module for convenient imports