rlevo_evolution/algorithms/metaheuristic/
mod.rs

1//! Swarm-intelligence and nature-inspired metaheuristics.
2//!
3//! Each algorithm implements the [`Strategy`](crate::Strategy) trait over
4//! tensor-backed populations so it plugs into the same
5//! [`EvolutionaryHarness`](crate::EvolutionaryHarness) pipeline as the
6//! classical families (GA, ES, DE, EP, CGP).
7//!
8//! # Shipping algorithms
9//!
10//! | Module | Algorithm | Genome kind | Status |
11//! |---|---|---|---|
12//! | [`pso`] | Particle Swarm Optimization | Real | Solid baseline |
13//! | [`aco_r`] | Ant Colony Optimization (continuous) | Real | Niche but principled |
14//! | [`abc`] | Artificial Bee Colony | Real | Competitive on simple multimodal |
15//! | [`gwo`] | Grey Wolf Optimizer | Real | Legacy comparator |
16//! | [`woa`] | Whale Optimization Algorithm | Real | Legacy comparator |
17//! | [`cuckoo`] | Cuckoo Search | Real | Lévy flights + random walk |
18//! | [`firefly`] | Firefly Algorithm | Real | Useful for multimodal |
19//! | [`bat`] | Bat Algorithm | Real | Legacy comparator |
20//! | [`salp`] | Salp Swarm Algorithm | Real | Legacy comparator |
21//! | [`aco_perm`] | Ant Colony (permutation) | Permutation | **Stub** — deferred to a future release |
22//!
23//! # Calibration
24//!
25//! Not every algorithm in this module is competitive on serious
26//! benchmarks. Several (GWO, WOA, BA, SSA) are flagged as
27//! "legacy comparator" in their module docs, per Camacho Villalón et al.
28//! (2020) and Sörensen (2015). The library ships them because they are
29//! widely cited; users asking "which one should I pick?" should start
30//! with [`pso`] and move to CMA-ES or LSHADE once those land.
31//!
32//! See `README.md` in this module's source directory for the full
33//! calibration table and prose guidance.
34//!
35//! # Custom kernels
36//!
37//! The [`kernels`] submodule ships fused `CubeCL` kernels for two
38//! operator paths where the pure-tensor decomposition is measurably
39//! wasteful: the pairwise-attract inner loop used by
40//! [`firefly`] and the Lévy-flight sampling used by
41//! [`cuckoo`] (and optionally [`bat`]). The kernels are gated behind
42//! the crate-level `custom-kernels` feature; pure-tensor fallbacks
43//! always compile.
44
45pub mod abc;
46pub mod aco_perm;
47pub mod aco_r;
48pub mod bat;
49pub mod cuckoo;
50pub mod firefly;
51pub mod gwo;
52pub mod kernels;
53pub mod pso;
54pub mod salp;
55pub mod woa;
56
57use rlevo_core::config::{ConfigError, ConstraintKind};
58
59/// Rejects a host-side per-individual vector whose length is neither `pop`
60/// nor `0`.
61///
62/// Swarm `*State` structs cache one host-side scalar per individual (fitness,
63/// trial counters, loudness, …). Every such vector must have length `pop`,
64/// except at bootstrap where `init` leaves the caches empty until the first
65/// `tell`. This is the shared length invariant checked by each state's
66/// `try_new`, so a mismatched non-empty length is rejected at construction
67/// rather than surfacing as an out-of-bounds panic generations later.
68pub(crate) fn len_matches_pop(
69    config: &'static str,
70    field: &'static str,
71    pop: usize,
72    len: usize,
73) -> Result<(), ConfigError> {
74    if len == 0 || len == pop {
75        Ok(())
76    } else {
77        Err(ConfigError {
78            config,
79            field,
80            kind: ConstraintKind::Custom("per-individual vector length must equal pop_size"),
81        })
82    }
83}
rlevo_evolution/algorithms/metaheuristic/mod.rs

rlevo_evolution/algorithms/metaheuristic/
mod.rs
