Evolve NEAT neural-network controllers that balance a double inverted pendulum on a cart, with curriculum learning and an interactive Viz Studio web demo.
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Run tests
pytest tests/ -v
# Quick training smoke (configs/demo.toml)
pendulum-neat train --config configs/demo.toml
# Full training run (configs/full.toml — ~200 pop, curriculum, parallel eval)
pendulum-neat train --config configs/full.toml
# Evaluate a checkpoint
pendulum-neat eval --checkpoint output/runs/<run>/best_genome.pkl
# Interactive Viz Studio (Three.js + FastAPI)
pendulum-neat serve --openPre-baked demo assets in assets/ work offline in replay mode when the server is unavailable.
| Command | Description |
|---|---|
pendulum-neat train |
NEAT training with curriculum |
pendulum-neat train --resume PATH |
Resume from population checkpoint |
pendulum-neat eval --checkpoint PATH |
Print fitness metrics |
pendulum-neat serve |
Launch Viz Studio in browser |
pendulum-neat record -o assets/ |
Export trajectory + network JSON |
pendulum-neat export-network |
Export network topology JSON |
pendulum_neat/— Evaluator, CheckpointStore, TrainingRun, CLIneat/— NEAT algorithm (speciation, crossover, mutation)physics/— RK4 double-pendulum simulationviz/— Trajectory recorder + network graph JSONserver/— FastAPI WebSocket sim backendweb/dist/— Viz Studio frontend (Three.js)
See docs/ARCHITECTURE.md for data flow.
- Start with low gravity + high friction
- Advance when
time_above≥ threshold for N consecutive generations - Ramp toward full physics difficulty
Configure in config.toml under [curriculum].
Each training run writes to output/runs/<timestamp>/:
metrics.jsonl— per-generation statscheckpoint_final.pkl— resumable populationbest_genome.pkl— best evolved controllertraining_progress.png— fitness plotclips/— optional trajectory JSON recordings
Python · NumPy · NEAT · RK4 physics · FastAPI · Three.js · pytest · GitHub Actions
MIT — see LICENSE.