fugue_evo/
lib.rs

1// Clippy allows for intentional patterns in this library
2#![allow(clippy::needless_range_loop)] // Matrix operations are clearer with explicit indices
3#![allow(clippy::derivable_impls)] // Some Default impls have doc comments
4#![allow(clippy::redundant_closure)] // Closure style consistency
5#![allow(clippy::should_implement_trait)] // Custom add methods for domain types
6#![allow(clippy::get_first)] // Explicit .get(0) is clearer in some contexts
7#![allow(clippy::useless_conversion)] // into_iter() for clarity
8#![allow(clippy::unnecessary_unwrap)] // Pattern clarity
9#![allow(clippy::wrong_self_convention)] // from_* methods for domain types
10#![allow(clippy::only_used_in_recursion)] // Tree traversal parameters
11#![allow(clippy::if_same_then_else)] // Sometimes intentional for clarity
12#![allow(clippy::manual_clamp)] // Explicit clamp logic for clarity
13#![allow(clippy::manual_memcpy)] // Matrix operations clarity
14
15//! # fugue-evo
16//!
17//! Evolutionary computation for Rust, in **two layers**:
18//!
19//! 1. **Classic EC (`classic` feature; standalone, no fugue dependency).**
20//!    SimpleGA, CMA-ES, NSGA-II, Island Model, Evolution Strategy, EDA/UMDA,
21//!    SteadyState, the interactive GA, all operators, checkpointing, and the
22//!    WASM surface. Compiles with
23//!    `--no-default-features --features std,parallel,checkpoint,classic`
24//!    with no probabilistic-programming dependency at all. Conversely,
25//!    `--features std,ppl` builds the inference layer with no classic code.
26//! 2. **Evolutionary inference (`ppl` feature, on by default): evolutionary
27//!    algorithms *as* probabilistic programs.** The prior over genomes is a
28//!    user-written fugue [`Model`](fugue::Model) (a [`GenomePrior`](inference::prior::GenomePrior)),
29//!    fitness enters as `factor(β·f(x))`, so the Boltzmann posterior
30//!    `π_β(x) ∝ p(x)·exp(β·f(x))` **is a fugue program** — and every sampler
31//!    is fugue's own inference machinery:
32//!    [`EvolutionChain`](inference::mh::EvolutionChain) (typed single-site MH),
33//!    [`EvolutionSMC`](inference::smc::EvolutionSMC) (adaptive tempered SMC
34//!    with a population-coupled crossover kernel and a log-evidence estimate),
35//!    [`ArithmeticGrammarPrior`](inference::grammar::ArithmeticGrammarPrior)
36//!    (genetic programming over a probabilistic grammar, where subtree
37//!    mutation/crossover are generic trace moves),
38//!    [`GenomeLikelihood`](inference::likelihood::GenomeLikelihood)
39//!    (likelihoods as observation programs, with latent nuisance parameters
40//!    jointly inferred), annealed **optimizer mode**
41//!    ([`EvolutionSMC::anneal`](inference::smc::EvolutionSMC::anneal)), and
42//!    the **Pareto posterior**
43//!    ([`ParetoScalarization`](inference::pareto::ParetoScalarization) —
44//!    multi-objective optimization as inference).
45//!
46//! The boundary between the layers is the
47//! [`TraceGenome`](genome::trace_genome::TraceGenome) extension trait: classic
48//! algorithms require only [`EvolutionaryGenome`](genome::traits::EvolutionaryGenome);
49//! genomes that also implement `TraceGenome` can be driven by the inference
50//! layer.
51//!
52//! ## Features
53//!
54//! - **Multiple Algorithms**: SimpleGA, CMA-ES, NSGA-II, Island Model, EDA, Interactive GA (standalone EC)
55//! - **Flexible Genomes**: RealVector, BitString, Permutation, TreeGenome
56//! - **Modular Operators**: Pluggable selection, crossover, and mutation operators
57//! - **Adaptive Hyperparameters**: opt-in Thompson-sampling tuning of operator parameters
58//! - **Evolutionary inference** (`ppl`): priors as programs, tempered SMC over the
59//!   Boltzmann posterior, MH with typed proposals, symbolic regression as exact
60//!   Bayesian inference
61//! - **Production Ready**: Checkpointing (bit-identical resume), parallel evaluation, WASM support
62//!
63//! ## Quick Start (classic optimization)
64//!
65//! ```rust,ignore
66//! use fugue_evo::prelude::*;
67//! use rand::rngs::StdRng;
68//! use rand::SeedableRng;
69//!
70//! fn main() -> Result<(), Box<dyn std::error::Error>> {
71//!     let mut rng = StdRng::seed_from_u64(42);
72//!     let bounds = MultiBounds::symmetric(5.12, 10);
73//!     let result = SimpleGABuilder::real_valued()
74//!         .population_size(100)
75//!         .bounds(bounds)
76//!         .fitness(Sphere::new(10))
77//!         .max_generations(200)
78//!         .build()?
79//!         .run(&mut rng)?;
80//!     println!("Best fitness: {:.6}", result.best_fitness);
81//!     Ok(())
82//! }
83//! ```
84//!
85//! ## Quick Start (evolution as inference, `ppl`)
86//!
87//! ```rust,ignore
88//! use fugue_evo::prelude::*;
89//!
90//! // Prior as a program; fitness as a likelihood factor; posterior by SMC.
91//! let model = EvolutionModel::new(GaussianPrior::new(0.0, 2.0, DIM), fitness);
92//! let posterior = EvolutionSMC::run(&mut rng, &model, EvoSmcConfig::default());
93//! println!("posterior mean: {}", posterior.weighted_mean(0));
94//! println!("log evidence:   {}", posterior.log_evidence);
95//! ```
96//!
97//! ## Module Overview
98//!
99//! - [`algorithms`]: Classic optimization algorithms (SimpleGA, CMA-ES, NSGA-II, Island Model)
100//! - [`genome`]: Genome types, [`EvolutionaryGenome`](genome::traits::EvolutionaryGenome), and (behind `ppl`) [`TraceGenome`](genome::trace_genome::TraceGenome)
101//! - [`operators`]: Selection, crossover, and mutation operators
102//! - [`fitness`]: Fitness traits and benchmark functions
103//! - [`population`]: Population management and individual types
104//! - [`termination`]: Stopping criteria
105//! - [`hyperparameter`]: Adaptive and Bayesian hyperparameter tuning
106//! - [`interactive`]: Human-in-the-loop evolutionary optimization
107//! - [`checkpoint`]: State serialization for pause/resume
108//! - [`inference`]: Evolution as inference — priors as programs, MH, tempered SMC, grammar GP (`ppl`)
109//!
110//! ## Examples
111//!
112//! - `sphere_optimization.rs`, `rastrigin_benchmark.rs`, `cma_es_example.rs`,
113//!   `island_model.rs`, `symbolic_regression.rs` (classic GP),
114//!   `checkpointing.rs`, `interactive_evolution.rs`: the classic layer
115//! - `bayesian_evolution.rs`: the inference layer end-to-end (SMC + MH + adaptive GA)
116//! - `symbolic_regression_inference.rs`: **flagship** — symbolic regression as
117//!   exact Bayesian inference over a probabilistic grammar
118
119#[cfg(feature = "classic")]
120pub mod algorithms;
121#[cfg(feature = "classic")]
122pub mod checkpoint;
123#[cfg(feature = "classic")]
124pub mod diagnostics;
125pub mod error;
126pub mod fitness;
127#[cfg(feature = "ppl")]
128pub mod inference;
129
130/// Deprecated alias for [`inference`] (the module was renamed in 0.2.0).
131#[cfg(feature = "ppl")]
132#[deprecated(since = "0.2.0", note = "renamed to `inference`")]
133pub use inference as fugue_integration;
134pub mod genome;
135#[cfg(feature = "classic")]
136pub mod hyperparameter;
137#[cfg(feature = "classic")]
138pub mod interactive;
139#[cfg(feature = "classic")]
140pub mod operators;
141#[cfg(feature = "classic")]
142pub mod population;
143#[cfg(feature = "classic")]
144pub mod termination;
145
146/// Prelude module for convenient imports
147pub mod prelude {
148    #[cfg(feature = "classic")]
149    pub use crate::algorithms::prelude::*;
150    #[cfg(feature = "classic")]
151    pub use crate::checkpoint::prelude::*;
152    #[cfg(feature = "classic")]
153    pub use crate::diagnostics::prelude::*;
154    pub use crate::error::*;
155    pub use crate::fitness::prelude::*;
156    pub use crate::genome::prelude::*;
157    #[cfg(feature = "classic")]
158    pub use crate::hyperparameter::prelude::*;
159    #[cfg(feature = "ppl")]
160    pub use crate::inference::prelude::*;
161    #[cfg(feature = "classic")]
162    pub use crate::interactive::prelude::*;
163    #[cfg(feature = "classic")]
164    pub use crate::operators::prelude::*;
165    #[cfg(feature = "classic")]
166    pub use crate::population::prelude::*;
167    #[cfg(feature = "classic")]
168    pub use crate::termination::prelude::*;
169}
fugue_evo/lib.rs

fugue_evo/
lib.rs
