heuropt 0.11.0

A practical Rust toolkit for heuristic single-, multi-, and many-objective optimization.
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

//! Operators for binary (`Vec<bool>`) decisions.

use rand::Rng as _;

use crate::core::rng::Rng;
use crate::traits::Variation;

/// Flip each bit of the first parent independently with probability `p`.
///
/// Always returns exactly one child (spec ยง11.3). Panics if `probability` is
/// outside `[0.0, 1.0]` or if no parents are provided.
///
/// # Example
///
/// ```
/// use heuropt::prelude::*;
///
/// let mut rng = rng_from_seed(42);
/// let mut m = BitFlipMutation { probability: 0.5 };
/// let parent = vec![true, false, true, false];
/// let children = m.vary(std::slice::from_ref(&parent), &mut rng);
/// assert_eq!(children.len(), 1);
/// assert_eq!(children[0].len(), parent.len());
/// ```
#[derive(Debug, Clone)]
pub struct BitFlipMutation {
    /// Per-bit flip probability. Must lie in `[0.0, 1.0]`.
    pub probability: f64,
}

impl Variation<Vec<bool>> for BitFlipMutation {
    fn vary(&mut self, parents: &[Vec<bool>], rng: &mut Rng) -> Vec<Vec<bool>> {
        assert!(
            (0.0..=1.0).contains(&self.probability),
            "BitFlipMutation probability must be in [0.0, 1.0]",
        );
        assert!(
            !parents.is_empty(),
            "BitFlipMutation requires at least one parent",
        );
        let mut child = parents[0].clone();
        for bit in child.iter_mut() {
            if rng.random_bool(self.probability) {
                *bit = !*bit;
            }
        }
        vec![child]
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::core::rng::rng_from_seed;

    #[test]
    fn probability_zero_changes_nothing() {
        let mut m = BitFlipMutation { probability: 0.0 };
        let mut rng = rng_from_seed(0);
        let parent = vec![false, true, false, true, true];
        let children = m.vary(std::slice::from_ref(&parent), &mut rng);
        assert_eq!(children.len(), 1);
        assert_eq!(children[0], parent);
    }

    #[test]
    fn probability_one_flips_everything() {
        let mut m = BitFlipMutation { probability: 1.0 };
        let mut rng = rng_from_seed(0);
        let parent = vec![false, true, false, true, true];
        let children = m.vary(std::slice::from_ref(&parent), &mut rng);
        let expected: Vec<bool> = parent.iter().map(|b| !b).collect();
        assert_eq!(children[0], expected);
    }

    #[test]
    #[should_panic(expected = "must be in [0.0, 1.0]")]
    fn probability_above_one_panics() {
        let mut m = BitFlipMutation { probability: 1.5 };
        let mut rng = rng_from_seed(0);
        m.vary(&[vec![true]], &mut rng);
    }
}