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: GWO and BA per Camacho
28//! Villalón et al. (2020), WOA per Camacho Villalón et al. (2023) — the
29//! 2020 paper covers only GWO/FA/BA, not WOA — and SSA per Sörensen
30//! (2015)'s general metaphor critique plus Castelli et al. (2022), since
31//! neither Camacho Villalón paper analyzes SSA. The library ships them
32//! because they are widely cited; users asking "which one should I pick?"
33//! should start with [`pso`] and move to CMA-ES or LSHADE once those land.
34//!
35//! See `README.md` in this module's source directory for the full
36//! calibration table and prose guidance.
37//!
38//! # Custom kernels
39//!
40//! The [`kernels`] submodule ships fused `CubeCL` kernels for two
41//! operator paths where the pure-tensor decomposition is measurably
42//! wasteful: the pairwise-attract inner loop used by
43//! [`firefly`] and the Lévy-flight sampling used by
44//! [`cuckoo`] (and optionally [`bat`]). The kernels are gated behind
45//! the crate-level `custom-kernels` feature; pure-tensor fallbacks
46//! always compile.
47
48pub mod abc;
49pub mod aco_perm;
50pub mod aco_r;
51pub mod bat;
52pub mod cuckoo;
53pub mod firefly;
54pub mod gwo;
55pub mod kernels;
56pub mod pso;
57pub mod salp;
58pub mod woa;
59
60use rlevo_core::config::{ConfigError, ConstraintKind};
61
62/// Rejects a host-side per-individual vector whose length is neither `pop`
63/// nor `0`.
64///
65/// Swarm `*State` structs cache one host-side scalar per individual (fitness,
66/// trial counters, loudness, …). Every such vector must have length `pop`,
67/// except at bootstrap where `init` leaves the caches empty until the first
68/// `tell`. This is the shared length invariant checked by each state's
69/// `try_new`, so a mismatched non-empty length is rejected at construction
70/// rather than surfacing as an out-of-bounds panic generations later.
71pub(crate) fn len_matches_pop(
72    config: &'static str,
73    field: &'static str,
74    pop: usize,
75    len: usize,
76) -> Result<(), ConfigError> {
77    if len == 0 || len == pop {
78        Ok(())
79    } else {
80        Err(ConfigError {
81            config,
82            field,
83            kind: ConstraintKind::Custom("per-individual vector length must equal pop_size"),
84        })
85    }
86}
rlevo_evolution/algorithms/metaheuristic/mod.rs

rlevo_evolution/algorithms/metaheuristic/
mod.rs
