fugue-evo 0.3.0

An implementation of fugue for running evolutionary algorithms as Bayesian inference: priors and likelihoods as probabilistic programs, tempered SMC in trace space, annealed optimization, Pareto posteriors - plus a standalone classical EC toolkit
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
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# BitString Reference

Fixed-length string of bits for binary/discrete optimization.

## Module

```rust,ignore
use fugue_evo::genome::bit_string::BitString;
```

## Construction

```rust,ignore
// From vector
let genome = BitString::new(vec![true, false, true, true]);

// All zeros
let genome = BitString::zeros(10);

// All ones
let genome = BitString::ones(10);

// Random
let genome = BitString::random(10, &mut rng);

// Random with probability
let genome = BitString::random_with_probability(10, 0.3, &mut rng);
```

## Methods

### Access

| Method | Return | Description |
|--------|--------|-------------|
| `bits()` | `&[bool]` | Immutable bit access |
| `bits_mut()` | `&mut [bool]` | Mutable bit access |
| `length()` | `usize` | Number of bits |
| `get(i)` | `Option<bool>` | Get bit at index |

### Bit Operations

| Method | Description |
|--------|-------------|
| `flip(i)` | Flip bit at index |
| `set(i, val)` | Set bit to value |
| `count_ones()` | Number of true bits |
| `count_zeros()` | Number of false bits |

### Binary Operations

| Method | Description |
|--------|-------------|
| `and(&other)` | Bitwise AND |
| `or(&other)` | Bitwise OR |
| `xor(&other)` | Bitwise XOR |
| `not()` | Bitwise NOT |

### Distance

| Method | Description |
|--------|-------------|
| `hamming_distance(&other)` | Number of differing bits |

## Trace Representation

Bits stored as 0.0 or 1.0:

```rust,ignore
addr!("bit", 0) → 0.0 or 1.0
addr!("bit", 1) → 0.0 or 1.0
// ...
```

## Recommended Operators

### Crossover

```rust,ignore
// Uniform: each bit from random parent
UniformCrossover::new()

// One-point crossover
OnePointCrossover::new()

// Two-point crossover
TwoPointCrossover::new()
```

### Mutation

```rust,ignore
// Flip each bit with probability
BitFlipMutation::new(0.01)  // 1% per bit
```

## Example: Knapsack Problem

```rust,ignore
use fugue_evo::prelude::*;

struct KnapsackFitness {
    values: Vec<f64>,
    weights: Vec<f64>,
    capacity: f64,
}

impl Fitness<BitString> for KnapsackFitness {
    type Value = f64;

    fn evaluate(&self, genome: &BitString) -> f64 {
        let mut total_value = 0.0;
        let mut total_weight = 0.0;

        for (i, &selected) in genome.bits().iter().enumerate() {
            if selected {
                total_value += self.values[i];
                total_weight += self.weights[i];
            }
        }

        if total_weight > self.capacity {
            0.0  // Infeasible
        } else {
            total_value
        }
    }
}

// Usage
let fitness = KnapsackFitness {
    values: vec![60.0, 100.0, 120.0],
    weights: vec![10.0, 20.0, 30.0],
    capacity: 50.0,
};

let result = SimpleGABuilder::<BitString, f64, _, _, _, _, _>::new()
    .population_size(50)
    .initial_population((0..50).map(|_| BitString::random(3, &mut rng)).collect())
    .selection(TournamentSelection::new(3))
    .crossover(UniformCrossover::new())
    .mutation(BitFlipMutation::new(0.05))
    .fitness(fitness)
    .max_generations(100)
    .build()?
    .run(&mut rng)?;
```

## See Also

- [Custom Fitness Functions](../../how-to/custom-fitness.md)
- [Custom Operators](../../how-to/custom-operators.md)