genetic_algorithm 0.27.1

A genetic algorithm implementation
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

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Common Development Commands

```bash
# Build the project
cargo build
cargo build --release

# Run all tests
cargo test

# Run a specific test
cargo test test_name

# Run tests with verbose output
cargo test -- --nocapture

# Run examples (in release mode for performance)
cargo run --example evolve_nqueens --release
cargo run --example hill_climb_nqueens --release
cargo run --example permutate_knapsack --release

# Run benchmarks
cargo bench
cargo bench bench_name

# Generate documentation
cargo doc --open

# Check code without building
cargo check

# Format code
cargo fmt

# Lint code
cargo clippy
```

## High-Level Architecture

This is a Rust genetic algorithm library with three core abstractions:

**AI agent guide**: See [AGENTS.md](AGENTS.md) for decision matrices, constructor
parameter reference, copy-paste templates, and troubleshooting.

### 1. **Genotype** (Search Space)
Located in `src/genotype/`, defines the representation of solutions:
- `BinaryGenotype`: Boolean alleles (Vec<bool>)
- `ListGenotype<T>`: List of values from a fixed set of alleles
- `UniqueGenotype<T>`: Positional permutation (swap-only mutation, default T = usize)
- `RangeGenotype<T>`: Numeric values within a range (default f32)
- `MultiListGenotype<T>`: Per-gene allele lists
- `MultiUniqueGenotype<T>`: Multiple unique sets
- `MultiRangeGenotype<T>`: Per-gene ranges with heterogeneous MutationType support

### 2. **Fitness** (Search Goal)
Located in `src/fitness/`, evaluates chromosome quality:
- Trait `Fitness` with method `calculate_for_chromosome()`
- Returns `FitnessValue` (isize, not f64! — isize enables equality checks for staleness detection) to be maximized or minimized
- Can be parallelized with `with_par_fitness()`
- Cache wrapper available for expensive fitness calculations

### 3. **Strategy** (Search Method)
Located in `src/strategy/`, implements the search algorithm:

#### **Evolve** (`src/strategy/evolve/`)
Classical genetic algorithm with:
- **Select**: Tournament or Elite selection to choose parents
- **Crossover**: Uniform, SinglePoint, MultiPoint, etc. to combine parents
- **Mutate**: SingleGene, MultiGene with configurable rates
- **Extensions**: MassExtinction, MassGenesis, MassDegeneration for diversity management

#### **HillClimb** (`src/strategy/hill_climb/`)
Local search when crossover is inefficient:
- Variants: Stochastic, SteepestAscent
- Works with neighbor generation instead of crossover

#### **Permutate** (`src/strategy/permutate/`)
Exhaustive search for small spaces with 100% guarantee

## Key Design Patterns

1. **Builder Pattern**: All major components use builders for configuration
2. **Trait-based Architecture**: Core behaviors defined as traits (Genotype, Fitness, Select, Crossover, Mutate)
3. **Parallelization**: Built on rayon for automatic parallelization
4. **Reporter Pattern**: Strategies accept reporters for monitoring progress

## Testing Approach

- Integration tests in `tests/` directory organized by module
- Use `.with_rng_seed_from_u64(0)` for deterministic test results
- Benchmarks in `benches/` using criterion
- Examples serve as both documentation and integration tests

## Performance Considerations

- Use `with_par_fitness()` for expensive fitness calculations
- Monitor with reporters to identify bottlenecks (fitness vs framework overhead)
- Framework overhead is mostly Crossover; practical overhead is mostly Fitness