evolve 0.4.0

A generic, composable genetic algorithm framework for Rust
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
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

use crate::{
    core::{context::Context, offspring::Offspring, population::Population, state::State},
    operators::GeneticOperator,
};

/// Determines the target size for a [`Fill`] operator.
pub trait GetSize<G, F> {
    /// Returns the target population size.
    fn get_size(&self, state: &State<G, F>) -> usize;
}

impl<G, F, T> GetSize<G, F> for T
where
    T: Fn(&State<G, F>) -> usize,
{
    fn get_size(&self, state: &State<G, F>) -> usize {
        (self)(state)
    }
}

#[derive(Debug, Clone, Copy)]
pub struct FixedSize(usize);

impl FixedSize {
    /// Creates a new `FixedSize` with the given target.
    pub(crate) fn new(size: usize) -> Self {
        Self(size)
    }
}

impl<G, F> GetSize<G, F> for FixedSize {
    fn get_size(&self, _: &State<G, F>) -> usize {
        self.0
    }
}

#[derive(Debug, Clone, Copy)]
pub struct PopSize(());

impl PopSize {
    /// Creates a new `PopSize`.
    pub(crate) fn new() -> Self {
        Self(())
    }
}

impl<G, F> GetSize<G, F> for PopSize {
    fn get_size(&self, state: &State<G, F>) -> usize {
        state.population().len()
    }
}

/// Repeats an operator until the output reaches a target population size.
///
/// Useful for ensuring the next generation has the right number of individuals,
/// regardless of how many each operator invocation produces. If the last batch
/// would overshoot the target, it is truncated.
///
/// # Examples
///
/// ```
/// use evolve::operators::sequential::combinator::Fill;
/// use evolve::operators::sequential::mutation::RandomReset;
///
/// // Maintain the same population size each generation
/// let op = Fill::from_population_size(RandomReset::<u8>::new());
///
/// // Or fill to a specific size
/// let op = Fill::from_fixed_size(RandomReset::<u8>::new(), 200);
/// ```
#[derive(Debug, Clone)]
pub struct Fill<O, S> {
    operator: O,
    size: S,
}

impl<O, S> Fill<O, S> {
    /// Creates a new `Fill` with a custom size strategy.
    pub fn new(operator: O, size: S) -> Self {
        Self { operator, size }
    }
}

impl<O> Fill<O, PopSize> {
    /// Creates a new `Fill` that maintains the input population size.
    pub fn from_population_size(operator: O) -> Self {
        Self {
            operator,
            size: PopSize::new(),
        }
    }
}

impl<O> Fill<O, FixedSize> {
    /// Creates a new `Fill` that applies the underlying operator until a fixed size is met.
    pub fn from_fixed_size(operator: O, size: usize) -> Self {
        Self {
            operator,
            size: FixedSize::new(size),
        }
    }
}

impl<G, F, Fe, R, C, O, S> GeneticOperator<G, F, Fe, R, C> for Fill<O, S>
where
    O: GeneticOperator<G, F, Fe, R, C>,
    S: GetSize<G, F>, // TODO: see if this can instead impl FnOnce
{
    fn apply(&self, state: &State<G, F>, ctx: &mut Context<Fe, R, C>) -> Offspring<G, F> {
        let target_size = self.size.get_size(state);

        let mut population = Population::with_capacity(target_size);

        while population.len() < target_size {
            let offspring = self.operator.apply(state, ctx);

            match offspring {
                Offspring::Single(ind) => population.add(ind),
                Offspring::Multiple(mut p) => {
                    // this is just to ensure no more than what is needed is added
                    let space_left = target_size - population.len();
                    if p.len() > space_left {
                        p.cull(space_left);
                    }
                    population.extend(p);
                }
            }
        }

        Offspring::Multiple(population)
    }
}