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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
// 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
//!
//! Evolutionary computation for Rust, in **two layers**:
//!
//! 1. **Classic EC (`classic` feature; standalone, no fugue dependency).**
//! SimpleGA, CMA-ES, NSGA-II, Island Model, Evolution Strategy, EDA/UMDA,
//! SteadyState, the interactive GA, all operators, checkpointing, and the
//! WASM surface. Compiles with
//! `--no-default-features --features std,parallel,checkpoint,classic`
//! with no probabilistic-programming dependency at all. Conversely,
//! `--features std,ppl` builds the inference layer with no classic code.
//! 2. **Evolutionary inference (`ppl` feature, on by default): evolutionary
//! algorithms *as* probabilistic programs.** The prior over genomes is a
//! user-written fugue [`Model`](fugue::Model) (a [`GenomePrior`](inference::prior::GenomePrior)),
//! fitness enters as `factor(β·f(x))`, so the Boltzmann posterior
//! `π_β(x) ∝ p(x)·exp(β·f(x))` **is a fugue program** — and every sampler
//! is fugue's own inference machinery:
//! [`EvolutionChain`](inference::mh::EvolutionChain) (typed single-site MH),
//! [`EvolutionSMC`](inference::smc::EvolutionSMC) (adaptive tempered SMC
//! with a population-coupled crossover kernel and a log-evidence estimate),
//! [`ArithmeticGrammarPrior`](inference::grammar::ArithmeticGrammarPrior)
//! (genetic programming over a probabilistic grammar, where subtree
//! mutation/crossover are generic trace moves),
//! [`GenomeLikelihood`](inference::likelihood::GenomeLikelihood)
//! (likelihoods as observation programs, with latent nuisance parameters
//! jointly inferred), annealed **optimizer mode**
//! ([`EvolutionSMC::anneal`](inference::smc::EvolutionSMC::anneal)), and
//! the **Pareto posterior**
//! ([`ParetoScalarization`](inference::pareto::ParetoScalarization) —
//! multi-objective optimization as inference).
//!
//! The boundary between the layers is the
//! [`TraceGenome`](genome::trace_genome::TraceGenome) extension trait: classic
//! algorithms require only [`EvolutionaryGenome`](genome::traits::EvolutionaryGenome);
//! genomes that also implement `TraceGenome` can be driven by the inference
//! layer.
//!
//! ## 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
//! - **Evolutionary inference** (`ppl`): priors as programs, tempered SMC over the
//! Boltzmann posterior, MH with typed proposals, symbolic regression as exact
//! Bayesian inference
//! - **Production Ready**: Checkpointing (bit-identical resume), parallel evaluation, WASM support
//!
//! ## Quick Start (classic optimization)
//!
//! ```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);
//! let bounds = MultiBounds::symmetric(5.12, 10);
//! 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(())
//! }
//! ```
//!
//! ## Quick Start (evolution as inference, `ppl`)
//!
//! ```rust,ignore
//! use fugue_evo::prelude::*;
//!
//! // Prior as a program; fitness as a likelihood factor; posterior by SMC.
//! let model = EvolutionModel::new(GaussianPrior::new(0.0, 2.0, DIM), fitness);
//! let posterior = EvolutionSMC::run(&mut rng, &model, EvoSmcConfig::default());
//! println!("posterior mean: {}", posterior.weighted_mean(0));
//! println!("log evidence: {}", posterior.log_evidence);
//! ```
//!
//! ## Module Overview
//!
//! - [`algorithms`]: Classic optimization algorithms (SimpleGA, CMA-ES, NSGA-II, Island Model)
//! - [`genome`]: Genome types, [`EvolutionaryGenome`](genome::traits::EvolutionaryGenome), and (behind `ppl`) [`TraceGenome`](genome::trace_genome::TraceGenome)
//! - [`operators`]: Selection, crossover, and mutation operators
//! - [`fitness`]: Fitness traits and benchmark functions
//! - [`population`]: Population management and individual types
//! - [`termination`]: Stopping criteria
//! - [`hyperparameter`]: Adaptive and Bayesian hyperparameter tuning
//! - [`interactive`]: Human-in-the-loop evolutionary optimization
//! - [`checkpoint`]: State serialization for pause/resume
//! - [`inference`]: Evolution as inference — priors as programs, MH, tempered SMC, grammar GP (`ppl`)
//!
//! ## Examples
//!
//! - `sphere_optimization.rs`, `rastrigin_benchmark.rs`, `cma_es_example.rs`,
//! `island_model.rs`, `symbolic_regression.rs` (classic GP),
//! `checkpointing.rs`, `interactive_evolution.rs`: the classic layer
//! - `bayesian_evolution.rs`: the inference layer end-to-end (SMC + MH + adaptive GA)
//! - `symbolic_regression_inference.rs`: **flagship** — symbolic regression as
//! exact Bayesian inference over a probabilistic grammar
/// Deprecated alias for [`inference`] (the module was renamed in 0.2.0).
pub use inference as fugue_integration;
/// Prelude module for convenient imports