# openevolve **Repository Path**: mirrors_amueller/openevolve ## Basic Information - **Project Name**: openevolve - **Description**: Open-source implementation of AlphaEvolve - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-09-14 - **Last Updated**: 2026-03-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # OpenEvolve
OpenEvolve Logo **๐Ÿงฌ The most advanced open-source evolutionary coding agent** *Turn your LLMs into autonomous code optimizers that discover breakthrough algorithms*

GitHub stars PyPI version PyPI downloads License

[๐Ÿš€ **Quick Start**](#-quick-start) โ€ข [๐Ÿ“– **Examples**](#-examples-gallery) โ€ข [๐Ÿ’ฌ **Discussions**](https://github.com/codelion/openevolve/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** | 2-3x speedup on Apple Silicon | [MLX Metal Kernels](examples/mlx_metal_kernel_opt/) | | **Mathematical** | State-of-the-art circle packing (n=26) | [Circle Packing](examples/circle_packing/) | | **Algorithm Design** | Adaptive sorting algorithms | [Rust Adaptive Sort](examples/rust_adaptive_sort/) | | **Scientific Computing** | Automated filter design | [Signal Processing](examples/signal_processing/) | | **Multi-Language** | Python, Rust, R, Metal shaders | [All Examples](examples/) |
## ๐Ÿš€ Quick Start Get from zero to evolving code in **30 seconds**: ```bash # Install OpenEvolve pip install openevolve # Set your LLM API key (works with any OpenAI-compatible provider) export OPENAI_API_KEY="your-api-key" # Run your first evolution! python -c " from openevolve import run_evolution result = run_evolution( 'examples/function_minimization/initial_program.py', 'examples/function_minimization/evaluator.py' ) print(f'Best score: {result.best_score:.4f}') " ``` ### ๐Ÿ“š **Library Usage** OpenEvolve can be used as a library without any external files: ```python 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}") ``` **Want more control?** Use the full CLI: ```bash python openevolve-run.py examples/function_minimization/initial_program.py \ examples/function_minimization/evaluator.py \ --config examples/function_minimization/config.yaml \ --iterations 1000 ``` **Prefer Docker?** ```bash docker run --rm -v $(pwd):/app ghcr.io/codelion/openevolve:latest \ examples/function_minimization/initial_program.py \ examples/function_minimization/evaluator.py --iterations 100 ``` ## ๐ŸŽฌ 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) | |--------------|----------------|----------------------| | ![Initial](examples/circle_packing/circle_packing_1.png) | ![Progress](examples/circle_packing/circle_packing_190.png) | ![Final](examples/circle_packing/circle_packing_460.png) | | Random placement | Learning structure | **State-of-the-art result** | **Result**: Matches published benchmarks for n=26 circle packing problem.
โšก GPU Kernel Evolution **Before (Baseline)**: ```metal // 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)**: ```metal // 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: ![OpenEvolve Architecture](openevolve-architecture.png) ### ๐ŸŽฏ **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 - **Test-Time Compute**: Integration with [OptiLLM](https://github.com/codelion/optillm) for MoA and enhanced reasoning - **Universal API**: Works with OpenAI, Google, local models - **Plugin Ecosystem**: Support for OptiLLM plugins (readurls, executecode, z3_solver) - **Intelligent Ensembles**: Weighted combinations with sophisticated fallback
๐Ÿงฌ 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) ```bash pip install openevolve ```
๐Ÿ”ง Development Install ```bash git clone https://github.com/codelion/openevolve.git cd openevolve pip install -e ".[dev]" ```
๐Ÿณ Docker ```bash docker pull ghcr.io/codelion/openevolve:latest ```
### LLM Provider Setup OpenEvolve works with **any OpenAI-compatible API**:
๐Ÿ”ฅ OpenAI (Direct) ```bash export OPENAI_API_KEY="sk-..." # Uses OpenAI endpoints by default ```
๐Ÿค– Google Gemini ```yaml # config.yaml llm: api_base: "https://generativelanguage.googleapis.com/v1beta/openai/" model: "gemini-2.5-pro" ``` ```bash export OPENAI_API_KEY="your-gemini-api-key" ```
๐Ÿ  Local Models (Ollama/vLLM) ```yaml # 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: ```bash # Install OptiLLM pip install optillm # Start OptiLLM proxy optillm --port 8000 # Point OpenEvolve to OptiLLM export OPENAI_API_KEY="your-actual-key" ``` ```yaml 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**](examples/function_minimization/) | Optimization | Random โ†’ Simulated Annealing | [View Results](examples/function_minimization/openevolve_output/) | | [โšก **MLX GPU Kernels**](examples/mlx_metal_kernel_opt/) | Hardware | 2-3x Apple Silicon speedup | [Benchmarks](examples/mlx_metal_kernel_opt/README.md) | | [๐Ÿ”„ **Rust Adaptive Sort**](examples/rust_adaptive_sort/) | Algorithms | Data-aware sorting | [Code Evolution](examples/rust_adaptive_sort/) | | [๐Ÿ“ **Symbolic Regression**](examples/symbolic_regression/) | Science | Automated equation discovery | [LLM-SRBench](examples/symbolic_regression/) | | [๐Ÿ•ธ๏ธ **Web Scraper + OptiLLM**](examples/web_scraper_optillm/) | AI Integration | Test-time compute optimization | [Smart Scraping](examples/web_scraper_optillm/) |
### ๐ŸŽฏ **Quick Example**: Function Minimization **Watch OpenEvolve evolve from random search to sophisticated optimization:** ```python # 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 โ†“** ```python # 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: ```yaml # Example: HotpotQA dataset Initial Prompt: "Answer the question based on the context." Evolved Prompt: "As an expert analyst, carefully examine the provided context. Break down complex multi-hop reasoning into clear steps. Cross-reference information from multiple sources to ensure accuracy. Answer: [question]" Result: +23% accuracy improvement on HotpotQA benchmark ``` [Full Example](examples/llm_prompt_optimization/)
๐Ÿ Competitive Programming **Automatic solution generation** for programming contests: ```python # 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](examples/online_judge_programming/)
## โš™๏ธ Configuration OpenEvolve offers extensive configuration for advanced users: ```yaml # Advanced Configuration Example max_iterations: 1000 random_seed: 42 # Full reproducibility llm: # Ensemble with test-time compute models: - name: "gemini-2.5-pro" weight: 0.6 - name: "moa&readurls-o3" # OptiLLM features weight: 0.4 temperature: 0.7 database: # MAP-Elites quality-diversity population_size: 500 num_islands: 5 # Parallel evolution migration_interval: 20 feature_dimensions: ["complexity", "diversity", "performance"] evaluator: enable_artifacts: true # Error feedback to LLM cascade_evaluation: true # Multi-stage testing use_llm_feedback: true # AI code quality assessment prompt: # Sophisticated inspiration system num_top_programs: 3 # Best performers num_diverse_programs: 2 # Creative exploration include_artifacts: true # Execution feedback # Custom templates template_dir: "custom_prompts/" use_template_stochasticity: true # Randomized prompts ```
๐ŸŽฏ Feature Engineering **Control how programs are organized in the quality-diversity grid:** ```yaml database: feature_dimensions: - "complexity" # Built-in: code length - "diversity" # Built-in: structural diversity - "performance" # Custom: from your evaluator - "memory_usage" # Custom: from your evaluator feature_bins: complexity: 10 # 10 complexity levels performance: 20 # 20 performance buckets memory_usage: 15 # 15 memory usage categories ``` **Important**: Return raw values from evaluator, OpenEvolve handles binning automatically.
๐ŸŽจ Custom Prompt Templates **Advanced prompt engineering** with custom templates: ```yaml prompt: template_dir: "custom_templates/" use_template_stochasticity: true template_variations: greeting: - "Let's enhance this code:" - "Time to optimize:" - "Improving the algorithm:" ``` See [prompt examples](examples/llm_prompt_optimization/templates/) for complete template customization.
## ๐Ÿ”ง Artifacts & Debugging **Artifacts side-channel** provides rich feedback to accelerate evolution: ```python # Evaluator can return execution context from openevolve.evaluation_result import EvaluationResult return EvaluationResult( metrics={"performance": 0.85, "correctness": 1.0}, artifacts={ "stderr": "Warning: suboptimal memory access pattern", "profiling_data": {...}, "llm_feedback": "Code is correct but could use better variable names", "build_warnings": ["unused variable x"] } ) ``` **Next generation prompt automatically includes:** ```markdown ## Previous Execution Feedback โš ๏ธ Warning: suboptimal memory access pattern ๐Ÿ’ก LLM Feedback: Code is correct but could use better variable names ๐Ÿ”ง Build Warnings: unused variable x ``` This creates a **feedback loop** where each generation learns from previous mistakes! ## ๐Ÿ“Š Visualization **Real-time evolution tracking** with interactive web interface: ```bash # Install visualization dependencies pip install -r scripts/requirements.txt # Launch interactive visualizer python scripts/visualizer.py # Or visualize specific checkpoint python scripts/visualizer.py --path examples/function_minimization/openevolve_output/checkpoints/checkpoint_100/ ``` **Features:** - ๐ŸŒณ **Evolution tree** with parent-child relationships - ๐Ÿ“ˆ **Performance tracking** across generations - ๐Ÿ” **Code diff viewer** showing mutations - ๐Ÿ“Š **MAP-Elites grid** visualization - ๐ŸŽฏ **Multi-metric analysis** with custom dimensions ![OpenEvolve Visualizer](openevolve-visualizer.png) ## ๐Ÿš€ Roadmap ### **๐Ÿ”ฅ Upcoming Features** - [ ] **Multi-Modal Evolution**: Images, audio, and text simultaneously - [ ] **Federated Learning**: Distributed evolution across multiple machines - [ ] **AutoML Integration**: Hyperparameter and architecture evolution - [ ] **Benchmark Suite**: Standardized evaluation across domains ### **๐ŸŒŸ Research Directions** - [ ] **Self-Modifying Prompts**: Evolution modifies its own prompting strategy - [ ] **Cross-Language Evolution**: Python โ†’ Rust โ†’ C++ optimization chains - [ ] **Neurosymbolic Reasoning**: Combine neural and symbolic approaches - [ ] **Human-AI Collaboration**: Interactive evolution with human feedback Want to contribute? Check out our [roadmap discussions](https://github.com/codelion/openevolve/discussions/categories/roadmap)! ## ๐Ÿค” FAQ
๐Ÿ’ฐ How much does it cost to run? **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
๐Ÿ†š How does this compare to manual optimization? | Aspect | Manual | OpenEvolve | |--------|--------|------------| | **Initial Learning** | Weeks to understand domain | Minutes to start | | **Solution Quality** | Depends on expertise | Consistently explores novel approaches | | **Time Investment** | Days-weeks per optimization | Hours for complete evolution | | **Reproducibility** | Hard to replicate exact process | Perfect reproduction with seeds | | **Scaling** | Doesn't scale beyond human capacity | Parallel evolution across islands | **OpenEvolve shines** when you need to explore large solution spaces or optimize for multiple objectives simultaneously.
๐Ÿ”ง Can I use my own LLM? **Yes!** OpenEvolve supports any OpenAI-compatible API: - **Commercial**: OpenAI, Google, Cohere - **Local**: Ollama, vLLM, LM Studio, text-generation-webui - **Advanced**: OptiLLM for routing and test-time compute Just set the `api_base` in your config to point to your endpoint.
๐Ÿšจ What if evolution gets stuck? **Built-in mechanisms prevent stagnation:** - **Island migration**: Fresh genes from other populations - **Temperature control**: Exploration vs exploitation balance - **Diversity maintenance**: MAP-Elites prevents convergence - **Artifact feedback**: Error messages guide improvements - **Template stochasticity**: Randomized prompts break patterns **Manual interventions:** - Increase `num_diverse_programs` for more exploration - Add custom feature dimensions to diversify search - Use template variations to randomize prompts - Adjust migration intervals for more cross-pollination
๐Ÿ“ˆ How do I measure success? **Multiple success metrics:** 1. **Primary Metric**: Your evaluator's `combined_score` or metric average 2. **Convergence**: Best score improvement over time 3. **Diversity**: MAP-Elites grid coverage 4. **Efficiency**: Iterations to reach target performance 5. **Robustness**: Performance across different test cases **Use the visualizer** to track all metrics in real-time and identify when evolution has converged.
### ๐ŸŒŸ **Contributors** Thanks to all our amazing contributors who make OpenEvolve possible! ### ๐Ÿค **Contributing** We welcome contributions! Here's how to get started: 1. ๐Ÿด **Fork** the repository 2. ๐ŸŒฟ **Create** your feature branch: `git checkout -b feat-amazing-feature` 3. โœจ **Add** your changes and tests 4. โœ… **Test** everything: `python -m unittest discover tests` 5. ๐Ÿ“ **Commit** with a clear message 6. ๐Ÿš€ **Push** and create a Pull Request **New to open source?** Check out our [Contributing Guide](CONTRIBUTING.md) and look for [`good-first-issue`](https://github.com/codelion/openevolve/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) labels! ### ๐Ÿ“š **Academic & Research** **Articles & Blog Posts About OpenEvolve**: - [Towards Open Evolutionary Agents](https://huggingface.co/blog/driaforall/towards-open-evolutionary-agents) - Evolution of coding agents and the open-source movement - [OpenEvolve: GPU Kernel Discovery](https://huggingface.co/blog/codelion/openevolve-gpu-kernel-discovery) - Automated discovery of optimized GPU kernels with 2-3x speedups - [OpenEvolve: Evolutionary Coding with LLMs](https://huggingface.co/blog/codelion/openevolve) - Introduction to evolutionary algorithm discovery using large language models ## ๐Ÿ“Š Citation If you use OpenEvolve in your research, please cite: ```bibtex @software{openevolve, title = {OpenEvolve: an open-source evolutionary coding agent}, author = {Asankhaya Sharma}, year = {2025}, publisher = {GitHub}, url = {https://github.com/codelion/openevolve} } ``` ---
### **๐Ÿš€ Ready to evolve your code?** **Made with โค๏ธ by the OpenEvolve community** *Star โญ this repository if OpenEvolve helps you discover breakthrough algorithms!*