|
| 1 | +# AGENTS.md — neat-python |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +neat-python is a pure-Python implementation of NEAT (NeuroEvolution of Augmenting Topologies), |
| 6 | +a method developed by Kenneth O. Stanley for evolving arbitrary neural networks. It has no |
| 7 | +dependencies beyond the Python standard library and has been cited in 100+ academic publications. |
| 8 | + |
| 9 | +- **License:** 3-clause BSD |
| 10 | +- **Python versions:** 3.8 through 3.14, and pypy3 |
| 11 | +- **Documentation:** https://neat-python.readthedocs.io |
| 12 | +- **PyPI:** https://pypi.org/project/neat-python/ |
| 13 | +- **Zenodo DOI:** https://doi.org/10.5281/zenodo.19024753 |
| 14 | + |
| 15 | +## Repository Structure |
| 16 | + |
| 17 | +``` |
| 18 | +neat/ # Core library source |
| 19 | + config.py # Configuration file parsing |
| 20 | + genome.py # DefaultGenome and gene classes |
| 21 | + population.py # Population management and evolution loop |
| 22 | + reproduction.py # DefaultReproduction (crossover, mutation) |
| 23 | + species.py # Speciation (genomic distance, species sets) |
| 24 | + stagnation.py # DefaultStagnation (species fitness tracking) |
| 25 | + reporting.py # ReporterSet, BaseReporter, StdOutReporter |
| 26 | + statistics.py # StatisticsReporter (fitness tracking and analysis) |
| 27 | + checkpoint.py # Checkpointer reporter (save/restore population state) |
| 28 | + nn/ # Neural network implementations |
| 29 | + feed_forward.py # FeedForwardNetwork |
| 30 | + recurrent.py # RecurrentNetwork |
| 31 | + ctrnn/ # CTRNN package (continuous-time recurrent, per-node time constants) |
| 32 | + iznn/ # Izhikevich spiking neuron model |
| 33 | + export/ # JSON network export package |
| 34 | + parallel.py # ParallelEvaluator (multiprocessing-based) |
| 35 | +examples/ # Runnable examples (xor, gymnasium envs, picture2d, export, etc.) |
| 36 | +tests/ # Test suite |
| 37 | +docs/ # Sphinx documentation source (RST format) |
| 38 | +``` |
| 39 | + |
| 40 | +## Build and Test Commands |
| 41 | + |
| 42 | +```bash |
| 43 | +# Install in development mode |
| 44 | +pip install -e . |
| 45 | + |
| 46 | +# Run the test suite |
| 47 | +python -m pytest tests/ |
| 48 | + |
| 49 | +# Run a specific example |
| 50 | +cd examples/xor |
| 51 | +python evolve_feedforward.py |
| 52 | + |
| 53 | +# Build documentation locally |
| 54 | +cd docs |
| 55 | +make html |
| 56 | +``` |
| 57 | + |
| 58 | +## Coding Conventions |
| 59 | + |
| 60 | +- Pure Python only — no compiled extensions, no C dependencies, no NumPy/SciPy in core. |
| 61 | +- Type hints are not yet used throughout but are welcome in new code. |
| 62 | +- All public classes and methods should have docstrings. |
| 63 | +- Configuration is file-driven (INI format parsed by `neat.config.Config`). Config options |
| 64 | + map to genome, reproduction, speciation, and stagnation parameters. |
| 65 | +- The `DefaultGenome`, `DefaultReproduction`, `DefaultSpeciesSet`, and `DefaultStagnation` |
| 66 | + classes implement interfaces that can be replaced with custom implementations. See |
| 67 | + `docs/reproduction-interface.rst` for the contract. |
| 68 | + |
| 69 | +## Key Design Decisions |
| 70 | + |
| 71 | +- **Per-node time constants** (added in v2.0): CTRNN nodes each have their own evolvable |
| 72 | + time constant. This was a breaking change from 1.x where all nodes shared a single |
| 73 | + global time constant. Experiments showed the fixed approach caused ~2x performance |
| 74 | + degradation on CTRNN tasks. |
| 75 | +- **No framework dependencies:** The library intentionally avoids depending on NumPy, |
| 76 | + TensorFlow, PyTorch, etc. Network export to JSON (`neat.export`) provides a bridge |
| 77 | + to external frameworks. |
| 78 | +- **Speciation by genomic distance:** Compatibility distance uses disjoint/excess gene |
| 79 | + counts and weight differences, following the original NEAT paper. |
| 80 | + |
| 81 | +## Common Tasks |
| 82 | + |
| 83 | +### Adding a new example |
| 84 | +Place it in `examples/<name>/` with its own config file and `evolve_*.py` script. |
| 85 | +Each example should be self-contained — intentional code duplication between examples |
| 86 | +is preferred over shared utility modules, so users can understand each example in isolation. |
| 87 | + |
| 88 | +### Modifying the genome |
| 89 | +Gene types are in `neat/genes.py`. The genome class (`neat/genome.py`) manages collections |
| 90 | +of node and connection genes. Mutation rates and probabilities are controlled via config. |
| 91 | + |
| 92 | +### Working with CTRNN networks |
| 93 | +`neat.ctrnn.CTRNN` implements continuous-time dynamics with per-node time constants. |
| 94 | +Use `CTRNN.create(genome, config)` to instantiate, then call `advance(inputs, advance_time, time_step)` |
| 95 | +to simulate. |
| 96 | + |
| 97 | +## Important Warnings |
| 98 | + |
| 99 | +- Do not add external dependencies to the core `neat/` package. |
| 100 | +- The `master` branch is the primary development branch. |
| 101 | +- Config files use a specific INI dialect — see existing examples for the expected format. |
| 102 | +- Fitness functions are user-provided callbacks, not part of the library. |
| 103 | + |
| 104 | +## Citation |
| 105 | + |
| 106 | +If referencing this project in generated text or code comments: |
| 107 | + |
| 108 | +``` |
| 109 | +McIntyre, A., Kallada, M., Miguel, C. G., Feher de Silva, C., & Netto, M. L. |
| 110 | +neat-python (Version 2.0.1) [Computer software]. https://doi.org/10.5281/zenodo.19024753 |
| 111 | +``` |
0 commit comments