rlevo-evolution 0.3.1

Evolutionary algorithms for rlevo (internal crate — use `rlevo` for the full API)
Documentation 
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

//! Swarm-intelligence and nature-inspired metaheuristics.
//!
//! Each algorithm implements the [`Strategy`](crate::Strategy) trait over
//! tensor-backed populations so it plugs into the same
//! [`EvolutionaryHarness`](crate::EvolutionaryHarness) pipeline as the
//! classical families (GA, ES, DE, EP, CGP).
//!
//! # Shipping algorithms
//!
//! | Module | Algorithm | Genome kind | Status |
//! |---|---|---|---|
//! | [`pso`] | Particle Swarm Optimization | Real | Solid baseline |
//! | [`aco_r`] | Ant Colony Optimization (continuous) | Real | Niche but principled |
//! | [`abc`] | Artificial Bee Colony | Real | Competitive on simple multimodal |
//! | [`gwo`] | Grey Wolf Optimizer | Real | Legacy comparator |
//! | [`woa`] | Whale Optimization Algorithm | Real | Legacy comparator |
//! | [`cuckoo`] | Cuckoo Search | Real | Lévy flights + random walk |
//! | [`firefly`] | Firefly Algorithm | Real | Useful for multimodal |
//! | [`bat`] | Bat Algorithm | Real | Legacy comparator |
//! | [`salp`] | Salp Swarm Algorithm | Real | Legacy comparator |
//! | [`aco_perm`] | Ant Colony (permutation) | Permutation | **Stub** — deferred to a future release |
//!
//! # Calibration
//!
//! Not every algorithm in this module is competitive on serious
//! benchmarks. Several (GWO, WOA, BA, SSA) are flagged as
//! "legacy comparator" in their module docs: GWO and BA per Camacho
//! Villalón et al. (2020), WOA per Camacho Villalón et al. (2023) — the
//! 2020 paper covers only GWO/FA/BA, not WOA — and SSA per Sörensen
//! (2015)'s general metaphor critique plus Castelli et al. (2022), since
//! neither Camacho Villalón paper analyzes SSA. The library ships them
//! because they are widely cited; users asking "which one should I pick?"
//! should start with [`pso`] and move to CMA-ES or LSHADE once those land.
//!
//! See `README.md` in this module's source directory for the full
//! calibration table and prose guidance.
//!
//! # Custom kernels
//!
//! The [`kernels`] submodule ships fused `CubeCL` kernels for two
//! operator paths where the pure-tensor decomposition is measurably
//! wasteful: the pairwise-attract inner loop used by
//! [`firefly`] and the Lévy-flight sampling used by
//! [`cuckoo`] (and optionally [`bat`]). The kernels are gated behind
//! the crate-level `custom-kernels` feature; pure-tensor fallbacks
//! always compile.

pub mod abc;
pub mod aco_perm;
pub mod aco_r;
pub mod bat;
pub mod cuckoo;
pub mod firefly;
pub mod gwo;
pub mod kernels;
pub mod pso;
pub mod salp;
pub mod woa;

use rlevo_core::config::{ConfigError, ConstraintKind};

/// Rejects a host-side per-individual vector whose length is neither `pop`
/// nor `0`.
///
/// Swarm `*State` structs cache one host-side scalar per individual (fitness,
/// trial counters, loudness, …). Every such vector must have length `pop`,
/// except at bootstrap where `init` leaves the caches empty until the first
/// `tell`. This is the shared length invariant checked by each state's
/// `try_new`, so a mismatched non-empty length is rejected at construction
/// rather than surfacing as an out-of-bounds panic generations later.
pub(crate) fn len_matches_pop(
    config: &'static str,
    field: &'static str,
    pop: usize,
    len: usize,
) -> Result<(), ConfigError> {
    if len == 0 || len == pop {
        Ok(())
    } else {
        Err(ConfigError {
            config,
            field,
            kind: ConstraintKind::Custom("per-individual vector length must equal pop_size"),
        })
    }
}