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//! A Probabilistic Genetic Algorithm Library for Rust.
18//!
19//! This library implements genetic algorithms through the lens of probabilistic programming,
20//! treating evolution as Bayesian inference over solution spaces. It integrates with
21//! [fugue-ppl](https://github.com/fugue-ppl/fugue) for trace-based evolutionary operators.
22//!
23//! ## Features
24//!
25//! - **Multiple Algorithms**: SimpleGA, CMA-ES, NSGA-II, Island Model, EDA, Interactive GA
26//! - **Flexible Genomes**: RealVector, BitString, Permutation, TreeGenome
27//! - **Modular Operators**: Pluggable selection, crossover, and mutation operators
28//! - **Adaptive Hyperparameters**: Bayesian learning of mutation rates and other parameters
29//! - **Production Ready**: Checkpointing, parallel evaluation, WASM support
30//!
31//! ## Core Concepts
32//!
33//! - **Fitness as Likelihood**: Selection pressure maps directly to Bayesian conditioning
34//! - **Learnable Operators**: Automatic inference of optimal hyperparameters using conjugate priors
35//! - **Trace-Based Evolution**: Deep Fugue integration enables novel probabilistic operators
36//! - **Type Safety**: Compile-time guarantees via Rust's type system
37//!
38//! ## Quick Start
39//!
40//! Add to your `Cargo.toml`:
41//!
42//! ```toml
43//! [dependencies]
44//! fugue-evo = "0.1"
45//! rand = "0.8"
46//! ```
47//!
48//! Basic optimization example:
49//!
50//! ```rust,ignore
51//! use fugue_evo::prelude::*;
52//! use rand::rngs::StdRng;
53//! use rand::SeedableRng;
54//!
55//! fn main() -> Result<(), Box<dyn std::error::Error>> {
56//!     let mut rng = StdRng::seed_from_u64(42);
57//!
58//!     // Define search bounds: 10 dimensions in [-5.12, 5.12]
59//!     let bounds = MultiBounds::symmetric(5.12, 10);
60//!
61//!     // Run optimization
62//!     let result = SimpleGABuilder::<RealVector, f64, _, _, _, _, _>::new()
63//!         .population_size(100)
64//!         .bounds(bounds)
65//!         .selection(TournamentSelection::new(3))
66//!         .crossover(SbxCrossover::new(20.0))
67//!         .mutation(PolynomialMutation::new(20.0))
68//!         .fitness(Sphere::new(10))
69//!         .max_generations(200)
70//!         .build()?
71//!         .run(&mut rng)?;
72//!
73//!     println!("Best fitness: {:.6}", result.best_fitness);
74//!     Ok(())
75//! }
76//! ```
77//!
78//! ## Module Overview
79//!
80//! - [`algorithms`]: Optimization algorithms (SimpleGA, CMA-ES, NSGA-II, Island Model)
81//! - [`genome`]: Genome types and the [`EvolutionaryGenome`](genome::traits::EvolutionaryGenome) trait
82//! - [`operators`]: Selection, crossover, and mutation operators
83//! - [`fitness`]: Fitness traits and benchmark functions
84//! - [`population`]: Population management and individual types
85//! - [`termination`]: Stopping criteria (max generations, target fitness, stagnation)
86//! - [`hyperparameter`]: Adaptive and Bayesian hyperparameter tuning
87//! - [`interactive`]: Human-in-the-loop evolutionary optimization
88//! - [`checkpoint`]: State serialization for pause/resume
89//! - [`fugue_integration`]: Trace operators and effect handlers
90//!
91//! ## Examples
92//!
93//! See the `examples/` directory for complete examples:
94//!
95//! - `sphere_optimization.rs`: Basic continuous optimization
96//! - `rastrigin_benchmark.rs`: Multimodal function optimization
97//! - `cma_es_example.rs`: CMA-ES algorithm usage
98//! - `island_model.rs`: Parallel island evolution
99//! - `hyperparameter_learning.rs`: Bayesian parameter adaptation
100//! - `symbolic_regression.rs`: Genetic programming
101//! - `checkpointing.rs`: Save/restore evolution state
102//! - `interactive_evolution.rs`: Human-in-the-loop optimization
103
104pub mod algorithms;
105pub mod checkpoint;
106pub mod diagnostics;
107pub mod error;
108pub mod fitness;
109pub mod fugue_integration;
110pub mod genome;
111pub mod hyperparameter;
112pub mod interactive;
113pub mod operators;
114pub mod population;
115pub mod termination;
116
117/// Prelude module for convenient imports
118pub mod prelude {
119    pub use crate::algorithms::prelude::*;
120    pub use crate::checkpoint::prelude::*;
121    pub use crate::diagnostics::prelude::*;
122    pub use crate::error::*;
123    pub use crate::fitness::prelude::*;
124    pub use crate::fugue_integration::prelude::*;
125    pub use crate::genome::prelude::*;
126    pub use crate::hyperparameter::prelude::*;
127    pub use crate::interactive::prelude::*;
128    pub use crate::operators::prelude::*;
129    pub use crate::population::prelude::*;
130    pub use crate::termination::prelude::*;
131}
fugue_evo/lib.rs

fugue_evo/
lib.rs
