rlevo_evolution/algorithms/metaheuristic/
aco_perm.rs

1//! Ant Colony Optimization over permutation genomes — **stub**.
2//!
3//! This module path is reserved so the public API surface is stable,
4//! but the implementation is deferred to a future release. A useful
5//! ACO-TSP implementation is a substantial design exercise of its own
6//! (pheromone-matrix update, tour construction, candidate lists) and
7//! does not belong inside the continuous-domain strategies that the
8//! other nine swarm algorithms in this module target.
9//!
10//! All trait methods below panic with `todo!()`. The struct exists so
11//! the [`Permutation`](crate::genome::Permutation) genome kind has at
12//! least one declared consumer and downstream crates can
13//! unambiguously reference the future API surface.
14
15use std::marker::PhantomData;
16
17use burn::tensor::{backend::Backend, Int, Tensor};
18use rand::Rng;
19
20use crate::strategy::{Strategy, StrategyMetrics};
21
22/// Static configuration placeholder for the permutation ACO.
23#[derive(Debug, Clone)]
24pub struct AcoPermConfig {
25    /// Number of ants.
26    pub pop_size: usize,
27    /// Number of nodes in the graph (permutation length).
28    pub n_nodes: usize,
29    /// Pheromone evaporation rate, `ρ ∈ (0, 1]`.
30    pub rho: f32,
31    /// Heuristic exponent `α` (pheromone weight).
32    pub alpha: f32,
33    /// Heuristic exponent `β` (desirability weight).
34    pub beta: f32,
35}
36
37impl AcoPermConfig {
38    /// Default configuration for a given population size and graph node count.
39    #[must_use]
40    pub fn default_for(pop_size: usize, n_nodes: usize) -> Self {
41        Self {
42            pop_size,
43            n_nodes,
44            rho: 0.5,
45            alpha: 1.0,
46            beta: 2.0,
47        }
48    }
49}
50
51/// Generation state placeholder.
52#[derive(Debug, Clone)]
53pub struct AcoPermState<B: Backend> {
54    _backend: PhantomData<fn() -> B>,
55}
56
57/// Ant Colony Optimization for permutation problems (TSP, QAP, …).
58///
59/// **Not yet implemented** — planned for a future release.
60///
61/// # Panics
62///
63/// All [`Strategy`] methods except `best` invoke `todo!()`. The struct
64/// is constructible (`new`, `Default`) and useful for declaring
65/// downstream API surface; do not drive it through a harness.
66///
67/// # Example
68///
69/// ```no_run
70/// use burn::backend::NdArray;
71/// use rlevo_evolution::algorithms::metaheuristic::aco_perm::{AntColonyPermutation, AcoPermConfig};
72///
73/// let strategy = AntColonyPermutation::<NdArray>::new();
74/// let params = AcoPermConfig::default_for(32, 20);
75/// let _ = (strategy, params);
76/// ```
77#[derive(Debug, Clone, Copy, Default)]
78pub struct AntColonyPermutation<B: Backend> {
79    _backend: PhantomData<fn() -> B>,
80}
81
82impl<B: Backend> AntColonyPermutation<B> {
83    /// Builds a new (stateless) strategy object (stub; all methods `todo!()`).
84    #[must_use]
85    pub fn new() -> Self {
86        Self {
87            _backend: PhantomData,
88        }
89    }
90}
91
92impl<B: Backend> Strategy<B> for AntColonyPermutation<B> {
93    type Params = AcoPermConfig;
94    type State = AcoPermState<B>;
95    type Genome = Tensor<B, 2, Int>;
96
97    fn init(
98        &self,
99        _params: &AcoPermConfig,
100        _rng: &mut dyn Rng,
101        _device: &B::Device,
102    ) -> AcoPermState<B> {
103        todo!(
104            "permutation ACO is not yet implemented; \
105             use AntColonyReal for continuous problems in the meantime"
106        )
107    }
108
109    fn ask(
110        &self,
111        _params: &AcoPermConfig,
112        _state: &AcoPermState<B>,
113        _rng: &mut dyn Rng,
114        _device: &B::Device,
115    ) -> (Self::Genome, AcoPermState<B>) {
116        todo!("permutation ACO is not yet implemented")
117    }
118
119    fn tell(
120        &self,
121        _params: &AcoPermConfig,
122        _population: Self::Genome,
123        _fitness: Tensor<B, 1>,
124        _state: AcoPermState<B>,
125        _rng: &mut dyn Rng,
126    ) -> (AcoPermState<B>, StrategyMetrics) {
127        todo!("permutation ACO is not yet implemented")
128    }
129
130    fn best(&self, _state: &AcoPermState<B>) -> Option<(Self::Genome, f32)> {
131        None
132    }
133}
134
135#[cfg(test)]
136mod tests {
137    use super::*;
138    use burn::backend::NdArray;
139
140    type TestBackend = NdArray;
141
142    #[test]
143    fn stub_is_constructible() {
144        let _strategy = AntColonyPermutation::<TestBackend>::new();
145        let _params = AcoPermConfig::default_for(32, 20);
146    }
147
148    #[test]
149    #[should_panic(expected = "permutation ACO is not yet implemented")]
150    fn init_panics_with_clear_message() {
151        use rand::SeedableRng;
152        let strategy = AntColonyPermutation::<TestBackend>::new();
153        let params = AcoPermConfig::default_for(4, 5);
154        let mut rng = rand::rngs::StdRng::seed_from_u64(0);
155        let _ = strategy.init(&params, &mut rng, &Default::default());
156    }
157}
rlevo_evolution/algorithms/metaheuristic/aco_perm.rs

rlevo_evolution/algorithms/metaheuristic/
aco_perm.rs
