How gastrodon/eevee works
Project type and purpose
• It provides core APIs for genome representation, mutation, reproduction, speciation, and evaluation through user-defined scenarios.
• It also ships with example applications (e.g., XOR, sentiment analysis, NES-Tetris) and command-line utilities for benchmarking and profiling.
File structure
Top-level artifacts:
• Cargo.toml / Cargo.lock, src/lib.rs – Rust crate manifest and library root
• Dockerfile / .github/workflows – CI and containerization scripts
• benches/, examples/, cmp-bench, cmp-profile, profile – CLI tools for benchmarking & profiling
• src/
– genome/ (connection, recurrent)
– network/ (binary, continuous, simple, non_bias)
– population.rs, reproduce.rs, crossover.rs, random.rs, serialize.rs, scenario.rs, macros.rs
Patterns & architecture:
• Modular Rust library, organized by domain (genome, network, population, etc.)
• Separation of core library vs. example binaries vs. bench/profile tools
• Extensible “Scenario” trait for plugging in evaluation functions
README
• Confirms NEAT-based algorithm; core loop: score genomes via Scenario → mutate/reproduce/cull → repeat
• External dependencies: criterion.rs (benchmarking), flamegraph & perf (profiling), fastrand (RNG), CTRNN code borrowed
• Usage examples in examples/ folder
a. Main components
1. Core Library Modules
• Genome Representation (src/genome)
• Neural Network Layers (src/network)
• Evolution Operations (mutation, crossover, speciation)
• Population Management
• Scenario Trait & Evaluation Engine
• RNG & Serialization
2. CLI Tools
• benches/ + cmp-bench – Benchmark suite using criterion.rs
• profile/ + cmp-profile – Profiling harness with flamegraph/perf
3. Example Clients
• XOR, sentiment, NES-Tetris applications
4. External Dependencies/Services
• criterion.rs, flamegraph, perf, fastrand
b. Relationships & data flows
• Scenario → provides fitness scores for each Genome
• Population Manager consumes genomes + fitness → applies mutation, crossover, speciation → new generation
• RNG module is used throughout (seeding via /dev/urandom)
• Serialization module reads/writes genomes to JSON (used by examples or persisted benchmarks)
• CLI tools invoke core library API in a loop (bench, profile) and collect metrics
• Examples link to the library, instantiate Scenario implementations, and drive training
c. Architectural patterns
• Strategy Pattern: Scenario trait abstracts evaluation function
• Modular layering: separation of concerns between representation (genome/network), evolution, and orchestration
• CLI-wrapper pattern: small binaries that use the library for specialized tasks (bench, profile)
d. Key technologies
• Rust (nightly for unstable features)
• criterion.rs (benchmarking)
• flamegraph/perf (profiling)
• fastrand (WyHash RNG)
• Docker/GitHub Actions (CI)
Summary of steps for the principal software engineer
4. Use clear labels and arrowheads to represent data and control flows in the neuroevolution loop.
8. Iterate with the team to refine clarity and completeness.