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

use crate::fitness::FitnessEvaluator;

#[cfg(feature = "parallel")]
use std::sync::OnceLock as FitnessCell;

#[cfg(not(feature = "parallel"))]
use std::cell::OnceCell as FitnessCell;

/// A single candidate solution with lazily evaluated fitness.
///
/// An `Individual` wraps a genome of type `G` and lazily evaluates its fitness
/// using a [`FitnessEvaluator`] on first access.
///
/// # Examples
///
/// ```
/// use evolve::core::individual::Individual;
///
/// let ind = Individual::<[u32; 3], u32>::new([1, 2, 3]);
/// assert_eq!(*ind.genome(), [1, 2, 3]);
/// assert_eq!(*ind.fitness(&|g: &[u32; 3]| g.iter().sum::<u32>()), 6);
/// ```
#[derive(Debug, Clone)]
pub struct Individual<G, F> {
    genome: G,
    fitness: FitnessCell<F>,
}

impl<G, F> Individual<G, F> {
    /// Creates a new `Individual` with the given genome and unevaluated fitness.
    pub fn new(genome: G) -> Self {
        Self {
            genome,
            fitness: FitnessCell::new(),
        }
    }

    /// Creates a new `Individual` with a pre-computed fitness value.
    pub fn from_parts(genome: G, fitness: F) -> Self {
        Self {
            genome,
            fitness: FitnessCell::from(fitness),
        }
    }

    /// Returns the fitness value if it has already been evaluated.
    pub fn try_fitness(&self) -> Option<&F> {
        self.fitness.get()
    }

    /// Returns a reference to the genome.
    pub fn genome(&self) -> &G {
        &self.genome
    }

    /// Returns a reference to the fitness value, evaluating it on first access.
    pub fn fitness<Fe>(&self, fitness_evaluator: &Fe) -> &F
    where
        Fe: FitnessEvaluator<G, F>,
    {
        self.fitness
            .get_or_init(|| fitness_evaluator.evaluate(&self.genome))
    }

    /// Creates a new `Individual` with a clone of this individual's genome
    /// and an unevaluated fitness cell.
    ///
    /// Use this when the cloned individual will have its genome modified
    /// (e.g., by crossover or mutation), making the original fitness irrelevant.
    pub fn clone_genome_only(&self) -> Self
    where
        G: Clone,
    {
        Self {
            genome: self.genome.clone(),
            fitness: FitnessCell::new(),
        }
    }

    /// Consumes this individual, applies a function to its genome, and returns
    /// a new individual with the modified genome and unevaluated fitness.
    pub fn mutate_genome(self, f: impl FnOnce(&mut G)) -> Self {
        let mut genome = self.genome;
        f(&mut genome);
        Self::new(genome)
    }
}