Skip to content

CLAUDE.md

Latest commit

 

History

History
103 lines (76 loc) · 3.45 KB

CLAUDE.md

File metadata and controls

103 lines (76 loc) · 3.45 KB

CLAUDE.md

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

Common Development Commands

# 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 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)
  • 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