OpenEvolve

🧬 The most advanced open-source evolutionary coding agent

Turn your LLMs into autonomous code optimizers that discover breakthrough algorithms

🚀 Quick Start • Examples • System Messages • Discussions

From random search to state-of-the-art: Watch your code evolve in real-time

---

Why OpenEvolve?

### **Autonomous Discovery** LLMs don't just optimize—they **discover** entirely new algorithms. No human guidance needed.

### **Proven Results** **2-3x speedups** on real hardware. **State-of-the-art** circle packing. **Breakthrough** optimizations.

### **Research Grade** Full reproducibility, extensive evaluation pipelines, and scientific rigor built-in.

OpenEvolve vs Manual Optimization:

Aspect	Manual Optimization	OpenEvolve
Time to Solution	Days to weeks	Hours
Exploration Breadth	Limited by human creativity	Unlimited LLM creativity
Reproducibility	Hard to replicate	Fully deterministic
Multi-objective	Complex tradeoffs	Automatic Pareto optimization
Scaling	Doesn't scale	Parallel evolution across islands

Proven Achievements

Domain	Achievement	Example
GPU Optimization	Hardware-optimized kernel discovery	MLX Metal Kernels
Mathematical	State-of-the-art circle packing (n=26)	Circle Packing
Algorithm Design	Adaptive sorting algorithms	Rust Adaptive Sort
Scientific Computing	Automated filter design	Signal Processing
Multi-Language	Python, Rust, R, Metal shaders	All Examples

🚀 Quick Start

Get from zero to evolving code in 30 seconds:

# Install OpenEvolve
pip install openevolve

# The example uses Google Gemini by default (free tier available)
# Get your API key from: https://aistudio.google.com/apikey
export OPENAI_API_KEY="your-gemini-api-key"  # Yes, use OPENAI_API_KEY env var

# Run your first evolution!
python openevolve-run.py examples/function_minimization/initial_program.py \
  examples/function_minimization/evaluator.py \
  --config examples/function_minimization/config.yaml \
  --iterations 50

Note: The example config uses Gemini by default, but you can use any OpenAI-compatible provider by modifying the config.yaml. See the configs for full configuration options.

Library Usage

OpenEvolve can be used as a library without any external files:

from openevolve import run_evolution, evolve_function

# Evolution with inline code (no files needed!)
result = run_evolution(
    initial_program='''
    def fibonacci(n):
        if n <= 1: return n
        return fibonacci(n-1) + fibonacci(n-2)
    ''',
    evaluator=lambda path: {"score": benchmark_fib(path)},
    iterations=100
)

# Evolve Python functions directly
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

result = evolve_function(
    bubble_sort,
    test_cases=[([3,1,2], [1,2,3]), ([5,2,8], [2,5,8])],
    iterations=50
)
print(f"Evolved sorting algorithm: {result.best_code}")

Prefer Docker? See the Installation & Setup section for Docker options.

See It In Action

Circle Packing: From Random to State-of-the-Art

Watch OpenEvolve discover optimal circle packing in real-time:

Generation 1	Generation 190	Generation 460 (Final)
Random placement	Learning structure	State-of-the-art result

Result: Matches published benchmarks for n=26 circle packing problem.

GPU Kernel Evolution

Before (Baseline):

// Standard attention implementation
kernel void attention_baseline(/* ... */) {
    // Generic matrix multiplication
    float sum = 0.0;
    for (int i = 0; i < seq_len; i++) {
        sum += query[tid] * key[i];
    }
}

After Evolution (2.8x faster):

// OpenEvolve discovered optimization
kernel void attention_evolved(/* ... */) {
    // Hardware-aware tiling + unified memory optimization
    threadgroup float shared_mem[256];
    // ... evolved algorithm exploiting Apple Silicon architecture
}

Performance Impact: 2.8x speedup on Apple M1 Pro, maintaining numerical accuracy.

How OpenEvolve Works

OpenEvolve implements a sophisticated evolutionary coding pipeline that goes far beyond simple optimization:

Core Innovation: MAP-Elites + LLMs

• Quality-Diversity Evolution: Maintains diverse populations across feature dimensions
• Island-Based Architecture: Multiple populations prevent premature convergence
• LLM Ensemble: Multiple models with intelligent fallback strategies
• Artifact Side-Channel: Error feedback improves subsequent generations

Advanced Features

Scientific Reproducibility

• Comprehensive Seeding: Every component (LLM, database, evaluation) is seeded
• Default Seed=42: Immediate reproducible results out of the box
• Deterministic Evolution: Exact reproduction of runs across machines
• Component Isolation: Hash-based isolation prevents cross-contamination

Advanced LLM Integration

• Universal API: Works with OpenAI, Google, local models, and proxies
• Intelligent Ensembles: Weighted combinations with sophisticated fallback
• Test-Time Compute: Enhanced reasoning through proxy systems (see OptiLLM setup)
• Plugin Ecosystem: Support for advanced reasoning plugins

Evolution Algorithm Innovations

• Double Selection: Different programs for performance vs inspiration
• Adaptive Feature Dimensions: Custom quality-diversity metrics
• Migration Patterns: Ring topology with controlled gene flow
• Multi-Strategy Sampling: Elite, diverse, and exploratory selection

Perfect For

Use Case	Why OpenEvolve Excels
Performance Optimization	Discovers hardware-specific optimizations humans miss
Algorithm Discovery	Finds novel approaches to classic problems
Scientific Computing	Automates tedious manual tuning processes
Competitive Programming	Generates multiple solution strategies
Multi-Objective Problems	Pareto-optimal solutions across dimensions

🛠 Installation & Setup

Requirements

• Python: 3.10+
• LLM Access: Any OpenAI-compatible API
• Optional: Docker for containerized runs

Installation Options

📦 PyPI (Recommended)

pip install openevolve

🔧 Development Install

git clone https://github.com/algorithmicsuperintelligence/openevolve.git
cd openevolve
pip install -e ".[dev]"

🐳 Docker

# Pull the image
docker pull ghcr.io/algorithmicsuperintelligence/openevolve:latest

# Run an example
docker run --rm -v $(pwd):/app ghcr.io/algorithmicsuperintelligence/openevolve:latest \
  examples/function_minimization/initial_program.py \
  examples/function_minimization/evaluator.py --iterations 100

Cost Estimation

Cost depends on your LLM provider and iterations:

• o3: ~$0.15-0.60 per iteration (depending on code size)
• o3-mini: ~$0.03-0.12 per iteration (more cost-effective)
• Gemini-2.5-Pro: ~$0.08-0.30 per iteration
• Gemini-2.5-Flash: ~$0.01-0.05 per iteration (fastest and cheapest)
• Local models: Nearly free after setup
• OptiLLM: Use cheaper models with test-time compute for better results

Cost-saving tips: - Start with fewer iterations (100-200) - Use o3-mini, Gemini-2.5-Flash or local models for exploration - Use cascade evaluation to filter bad programs early - Configure smaller population sizes initially

LLM Provider Setup

OpenEvolve works with any OpenAI-compatible API:

🔥 OpenAI (Direct)

export OPENAI_API_KEY="sk-..."
# Uses OpenAI endpoints by default

🤖 Google Gemini

# config.yaml
llm:
  api_base: "https://generativelanguage.googleapis.com/v1beta/openai/"
  model: "gemini-2.5-pro"

export OPENAI_API_KEY="your-gemini-api-key"

🏠 Local Models (Ollama/vLLM)

# config.yaml
llm:
  api_base: "http://localhost:11434/v1"  # Ollama
  model: "codellama:7b"

⚡ OptiLLM (Advanced)

For maximum flexibility with rate limiting, model routing, and test-time compute:

# Install OptiLLM
pip install optillm

# Start OptiLLM proxy
optillm --port 8000

# Point OpenEvolve to OptiLLM
export OPENAI_API_KEY="your-actual-key"

llm:
  api_base: "http://localhost:8000/v1"
  model: "moa&readurls-o3"  # Test-time compute + web access

Examples Gallery

Showcase Projects

Project	Domain	Achievement	Demo
Function Minimization	Optimization	Random → Simulated Annealing	View Results
MLX GPU Kernels	Hardware	Apple Silicon optimization	Benchmarks
Rust Adaptive Sort	Algorithms	Data-aware sorting	Code Evolution
Symbolic Regression	Science	Automated equation discovery	LLM-SRBench
Web Scraper + OptiLLM	AI Integration	Test-time compute optimization	Smart Scraping

Quick Example: Function Minimization

Watch OpenEvolve evolve from random search to sophisticated optimization:

# Initial Program (Random Search)
def minimize_function(func, bounds, max_evals=1000):
    best_x, best_val = None, float('inf')
    for _ in range(max_evals):
        x = random_point_in_bounds(bounds)
        val = func(x)
        if val < best_val:
            best_x, best_val = x, val
    return best_x, best_val

Evolution Process

# Evolved Program (Simulated Annealing + Adaptive Cooling)
def minimize_function(func, bounds, max_evals=1000):
    x = random_point_in_bounds(bounds)
    temp = adaptive_initial_temperature(func, bounds)

    for i in range(max_evals):
        neighbor = generate_neighbor(x, temp, bounds)
        delta = func(neighbor) - func(x)

        if delta < 0 or random.random() < exp(-delta/temp):
            x = neighbor

        temp *= adaptive_cooling_rate(i, max_evals)  # Dynamic cooling

    return x, func(x)

Performance: 100x improvement in convergence speed!

Advanced Examples

Prompt Evolution

Evolve prompts instead of code for better LLM performance. See the LLM Prompt Optimization example for a complete case study with HotpotQA achieving +23% accuracy improvement.

Full Example

🏁 Competitive Programming

Automatic solution generation for programming contests:

# Problem: Find maximum subarray sum
# OpenEvolve discovers multiple approaches:

# Evolution Path 1: Brute Force → Kadane's Algorithm
# Evolution Path 2: Divide & Conquer → Optimized Kadane's
# Evolution Path 3: Dynamic Programming → Space-Optimized DP

Online Judge Integration

Configuration

OpenEvolve offers extensive configuration for advanced users:

```yaml

Advanced Configuration Example

max_iterations: 1000 random_seed: 42 # Full reproducibility

llm: # Ensemble configuration models: - name: "gemini-2.5-pro" weight: 0.6 - name: "gemini-2.5-flash" weight: 0.4 temperature: 0.7