Skip to content

Commit d8bd3a4

Browse files
Fix AGENTS.md: correct file paths, CTRNN API, and citation info
Updated repository structure to reflect that ctrnn, iznn, and export are packages (not single files), added missing statistics.py, corrected CTRNN class name and method signature, and updated citation to match README (version 2.0.1, current Zenodo DOI). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 619e2a7 commit d8bd3a4

File tree

1 file changed

+111
-0
lines changed

1 file changed

+111
-0
lines changed

AGENTS.md

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
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

Comments
 (0)