algorithmicsuperintelligence/openevolve

OpenEvolve – Evolutionary Code‑Generation Engine

What it is – OpenEvolve is a Python library that uses large language models (LLMs) as a mutation/recombination engine inside a quality‑diversity evolutionary algorithm (MAP‑Elites with island parallelism). It automatically rewrites, optimizes, or invents code in many languages (Python, Rust, R, Metal shaders, etc.) and evaluates the candidates with user‑provided test harnesses. The system is built for research‑grade reproducibility and can be run from the command line, as a Docker container, or imported as a Python module.

Key capabilities

• LLM‑driven evolution – LLMs propose new program variants; the framework handles prompting, fallback ensembles, and artifact feedback.
• MAP‑Elites + islands – Maintains diverse populations across user‑defined feature dimensions (e.g., speed, code size, complexity) and runs several islands in parallel to avoid premature convergence.
• Deterministic runs – Fixed seeds (default 42) make every evolution reproducible across machines.
• Multi‑objective / Pareto optimisation – Automatically discovers trade‑offs between performance, memory, and other metrics.
• Plug‑and‑play LLM back‑ends – Works with OpenAI, Google Gemini, Claude Code CLI, local Ollama/vLLM servers, OptiLLM proxy, Copilot CLI, or Codex app‑server via a unified OPENAI_API_KEY‑style configuration.
• Extensible hooks – Users can supply custom island selectors, population‑strategy callbacks (admit, replace, archive, migration, etc.) to tailor the evolutionary dynamics.

Typical workflow

1. Provide an initial program (file or string) and an evaluator that returns a numeric score or a dict of metrics.
2. Configure the LLM provider and evolutionary parameters in config.yaml (population size, number of islands, feature dimensions, etc.).
3. Run openevolve-run.py (CLI) or call run_evolution / evolve_function from Python.
4. Inspect the resulting result.best_code and the full MAP‑Elites archive for Pareto‑optimal solutions.

Example (Python API)

from openevolve import run_evolution

result = run_evolution(
    initial_program="""
    def bubble_sort(arr):
        for i in range(len(arr)):
            for j in range(len(arr)-1):
                if arr[j] > arr[j+1]:
                    arr[j], arr[j+1] = arr[j+1], arr[j]
        return arr
    """,
    evaluator=lambda path: {"score": benchmark_sort(path)},
    iterations=50,
    llm_config={"primary_model": "gemini-2.5-flash"},
)

print("Evolved algorithm:\n", result.best_code)

The call runs a small evolutionary loop, letting the LLM rewrite the sorting routine. After 50 iterations the printed code is often a hybrid of insertion‑sort and quick‑sort that outperforms the original bubble sort.

Installation

• PyPI (recommended): pip install openevolve
• Development: clone the repo and pip install -e "[dev]"
• Docker: pull ghcr.io/algorithmicsuperintelligence/openevolve:latest and run the container with mounted example files.

Supported platforms – Python 3.10+, works on macOS, Linux, and Windows (note the spawn multiprocessing requirement). GPU‑specific examples (Metal shaders) require Apple Silicon hardware.

Use‑case highlights

Domain	What OpenEvolve does
Performance tuning	Discovers hardware‑aware kernel optimizations (e.g., 2.8× faster Metal attention kernel).
Algorithm discovery	Finds novel sorting, circle‑packing, or symbolic‑regression solutions that match or exceed published benchmarks.
Scientific computing	Automates filter design, equation discovery, and other parameter‑heavy tasks.
Competitive programming	Generates multiple solution strategies for classic contest problems.
Multi‑objective optimisation	Returns Pareto‑optimal sets across speed, memory, and code complexity.

Cost model – The library itself is free; each evolution iteration incurs the LLM provider’s token cost. The README lists typical per‑iteration prices for Gemini, OpenAI o3/o3-mini, and local models, plus tips for reducing spend (fewer iterations, cheaper models, cascade evaluation).

License – The project is released under the repository’s LICENSE file (the README links to it), which is an open‑source license permitting free use and modification.

---

OpenEvolve is positioned as a research‑grade platform for autonomous code discovery, combining evolutionary algorithms with modern LLMs to automate optimization and algorithm invention.