The Problem
Optimizing numerical kernels, mathematical conjectures, and algorithm implementations is slow and labor-intensive. Manual tuning requires domain expertise and days of iteration. OpenEvolve automates this by using LLMs as an evolutionary engine: it mutates and selects code across generations, discovering solutions that outperform both human baselines and random search.
What This Does
OpenEvolve is an evolutionary coding agent. You provide an initialprogram.py and an evaluator.py (a fitness function), and the system iteratively proposes code variants, evaluates them, and keeps the best performers. The config.yaml files in each example control the LLM provider, population size, mutation rates, and stopping conditions.
The repo is organized around use cases. examples/algotune/ contains seven tasks (FFT convolution, LU factorization, eigenvector computation) each with a bestprogram.py and bestprograminfo.json showing evolved results. examples/alphaevolvemathproblems/ covers circle packing, Heilbronn triangle, and autocorrelation inequalities. examples/arcbenchmark/ includes checkpoints and post-evolution evaluation scripts. The core library is importable via from openevolve import runevolution, evolvefunction.
How To Use It
The README gives a working quick start. Install with pip install openevolve, set an API key, and run:
export OPENAIAPIKEY="your-gemini-api-key" python openevolve-run.py examples/functionminimization/initialprogram.py \ examples/functionminimization/evaluator.py \ --config examples/functionminimization/config.yaml \ --iterations 50
Configuration lives in config.yaml per example. The default uses Google Gemini via an OpenAI-compatible endpoint; you can swap providers by editing that file. A Dockerfile and Makefile exist for containerized builds and task automation, but the README does not document them. The configs/ directory contains defaultconfig.yaml, islandconfigexample.yaml, and earlystoppingexample.yaml for advanced setups. There is no lockfile for Python dependencies; requirements.txt files are per-example and unpinned.
Real-World Use
A practical workflow: take a slow numerical routine, write a fitness function that measures runtime or accuracy, and let OpenEvolve search the program space. For example, the examples/algotune/fftconvolution/ task starts with a naive FFT-based convolution and evolves a faster implementation. The examples/circlepacking/ directory includes bestprogram.py and visualization PNGs, demonstrating a state-of-the-art result for n=26 circles. For teams, the island configuration in configs/islandexamples.yaml enables parallel evolution across independent populations.
Code Health & Issues
Med - No dependency lockfiles - examples/*/requirements.txt declare unpinned versions, so builds are not reproducible across environments. Med - Large examples/ directory (182 files) mixes evolved artifacts (bestprogram.py, JSON checkpoints) with source code, making it hard to distinguish generated output from hand-written code. Low - Only 4 test files, all under examples/attentionoptimization/tests/. The core library has no visible test suite. Low - The examples/arc_benchmark/outputs/ directory contains committed run artifacts (checkpoints, JSON program dumps) that should likely be gitignored. Low - The README claims "fully deterministic" results, but LLM-based mutation is inherently non-deterministic unless temperature is set to 0 and seeds are fixed; no such configuration is documented.
CI is configured via GitHub Actions (python-test.yml, release.yml), and a .pre-commit-config.yaml exists, so basic quality gates are in place.
The Bottom Line
OpenEvolve is a serious, well-structured implementation of LLM-driven evolutionary optimization, with a strong example gallery and a usable library API. It is best suited for researchers or engineers who want to explore automated algorithm discovery and have the patience to configure LLM providers and evaluate results critically. The lack of dependency pinning and committed run artifacts are hygiene issues, not blockers. If you need reproducible, production-grade optimization pipelines today, this is a promising starting point rather than a finished tool.