openevolve: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

OpenEvolve is an open-source implementation of Google DeepMind's AlphaEvolve system - an evolutionary coding agent that uses LLMs to optimize code through iterative evolution. The framework can evolve code in multiple languages (Python, R, Rust, etc.) for tasks like scientific computing, optimization, and algorithm discovery.

Essential Commands

Development Setup

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Or use Makefile
make install

Running Tests

# Run all tests
python -m unittest discover tests

# Or use Makefile
make test

Code Formatting

# Format with Black
python -m black openevolve examples tests scripts

# Or use Makefile
make lint

Running OpenEvolve

# Basic evolution run
python openevolve-run.py path/to/initial_program.py path/to/evaluator.py --config path/to/config.yaml --iterations 1000

# Resume from checkpoint
python openevolve-run.py path/to/initial_program.py path/to/evaluator.py \
  --config path/to/config.yaml \
  --checkpoint path/to/checkpoint_directory \
  --iterations 50

Visualization

# View evolution tree
python scripts/visualizer.py --path examples/function_minimization/openevolve_output/checkpoints/checkpoint_100/

High-Level Architecture

Core Components

1. Controller (openevolve/controller.py): Main orchestrator that manages the evolution process using ProcessPoolExecutor for parallel iteration execution.

2. Database (openevolve/database.py): Implements MAP-Elites algorithm with island-based evolution:

   • Programs mapped to multi-dimensional feature grid
   • Multiple isolated populations (islands) evolve independently
   • Periodic migration between islands prevents convergence
   • Tracks absolute best program separately

3. Evaluator (openevolve/evaluator.py): Cascade evaluation pattern:

   • Stage 1: Quick validation
   • Stage 2: Basic performance testing
   • Stage 3: Comprehensive evaluation
   • Programs must pass thresholds at each stage