Reorganize repo before update: update readme, move experiments to other repository

Author: Anonymous

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to CodeEvolve
+
+Thank you for your interest in contributing to CodeEvolve! We welcome contributions from the community and appreciate your efforts to improve the framework.
+
+## Getting Started
+
+1. **Check existing issues:** Browse [open issues](https://github.com/inter-co/science-codeevolve/issues) to see if your idea or bug has already been reported
+2. **Create an issue first:** Before starting work, open an issue describing your proposed change, bug fix, or feature
+3. **Wait for feedback:** Discuss your approach with maintainers to ensure alignment with project goals
+
+## Contribution Workflow
+
+### 1. Fork and Clone
+```bash
+git clone https://github.com/YOUR_USERNAME/science-codeevolve.git
+cd science-codeevolve
+```
+
+### 2. Create a Branch
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 3. Make Changes
+- Write clear, documented code
+- Follow existing code style and conventions
+- Add tests for new functionality
+- Update documentation as needed
+
+### 4. Test Your Changes
+```bash
+# Run tests to ensure nothing breaks
+pytest tests/
+```
+
+### 5. Commit and Push
+```bash
+git add .
+git commit -m "Brief description of changes"
+git push origin feature/your-feature-name
+```
+
+### 6. Submit a Pull Request
+- Reference the related issue number
+- Provide a clear description of what your PR does
+- Explain why the change is necessary
+- Include examples or screenshots if applicable
+
+## Pull Request Guidelines
+
+**Keep PRs focused:** Each PR should address a single issue or feature. Avoid combining multiple unrelated changes.
+
+**Write good descriptions:** Clearly explain what your PR does, why it's needed, and how it works.
+
+**Ensure quality:** All code should be tested and documented. PRs with untested changes or massive auto-generated modifications will not be accepted.
+
+**Be responsive:** Address review feedback promptly and be open to suggestions.
+
+## Documentation
+
+Update relevant documentation when making changes:
+- README.md for user-facing changes
+- Docstrings for API changes
+- Comments for complex logic
+
+## Questions?
+
+If you have questions about contributing, feel free to:
+- Open an issue for discussion
+- Reach out to maintainers
+- Check existing documentation
+
+Thank you for helping make CodeEvolve better!

README.md

@@ -1,66 +1,145 @@
 # CodeEvolve
+
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-[![preprint](https://img.shields.io/badge/preprint-arxiv.2510.14150-red)](https://arxiv.org/abs/2510.14150)
+[![arxiv](https://img.shields.io/badge/arxiv-arxiv.2510.14150-red)](https://arxiv.org/abs/2510.14150)
 
-CodeEvolve is an open-source evolutionary coding agent, designed to iteratively improve an initial codebase against a set of user-defined metrics. This project was originally created as an attempt to replicate the results of [AlphaEvolve](https://arxiv.org/abs/2506.13131), a closed-source coding agent announced by Google DeepMind in 2025.
+<img src='assets/codeevolve_diagram.png' align="center" width=900 />
 
-Our primary goal is to implement a transparent, reproducible, and community-driven framework for LLM-driven algorithm discovery. We evaluate CodeEvolve on the same mathematical benchmarks as AlphaEvolve. CodeEvolve has surpassed the reported state-of-the-art performance on 4 of its 13 problems (see the jupyter notebook with our [results](notebooks/results.ipynb)). We are actively working to improve our method on the remaining benchmarks.
+**An open-source framework that combines large language models with evolutionary algorithms to discover and optimize high-performing code solutions.**
 
-## Overview
+CodeEvolve democratizes algorithmic discovery by making LLM-driven evolutionary search transparent, reproducible, and accessible. Whether you're tackling combinatorial optimization, discovering novel algorithms, or optimizing computational kernels, CodeEvolve provides a modular foundation for automated code synthesis guided by quantifiable metrics.
 
-<img src='assets/codeevolve_diagram.png' align="center" width=900 />
+## Why CodeEvolve?
+
+**State-of-the-art performance with transparency.** CodeEvolve matches or exceeds the performance of closed-source systems like Google DeepMind's AlphaEvolve on established algorithm-discovery benchmarks, while remaining fully open and reproducible.
+
+**Cost-effective solutions.** Open-weight models like Qwen often match or outperform expensive closed-source LLMs at a fraction of the compute cost, making cutting-edge algorithmic discovery accessible to researchers and practitioners with limited budgets.
+
+**Designed for real problems.** CodeEvolve addresses meta-optimization tasks where you need to discover programs that solve complex optimization problems.
+
+## Key Features
+
+### Islands-based Genetic Algorithm
+Multiple populations evolve independently and periodically exchange top performers, maintaining diversity while propagating successful solutions across the search space. This parallel architecture enables efficient exploration and scales naturally to concurrent evaluation.
+
+### Modular Operators
+
+**Inspiration-based Crossover:** Contextual recombination that combines successful solution patterns while preserving semantic coherence.
+
+**Meta-prompting Exploration:** Evolves the prompts themselves, enabling the LLM to reflect on and rewrite its own instructions for more diverse search trajectories.
+
+**Depth-based Exploitation:** Targeted refinement mechanism that makes precise edits to promising solutions, balancing global search with local optimization.
+
+## Architecture
+
+CodeEvolve operates through an iterative process at each epoch:
+
+1. **Population Management:** Each island maintains populations of prompts and solutions, evaluated against user-defined fitness metrics
+2. **Evolutionary Operators:** Generate new candidates through crossover, mutation, and meta-prompting
+3. **LLM Ensemble:** Transforms operator instructions into executable code modifications
+4. **Selection & Migration:** Top performers are retained and periodically migrated between islands
+5. **Archive:** MAP-Elites-based archive preserves behavioral diversity across the search
+
+Execution feedback and fitness signals guide the entire loop, translating LLM proposals into testable, executable artifacts.
+
+## Performance Highlights
+
+CodeEvolve demonstrates superior performance on several benchmarks previously used to assess AlphaEvolve:
+
+- **Competitive or better results** across diverse algorithm-discovery tasks
+- **Open-weight models** (e.g., Qwen) matching closed-source performance at significantly lower cost
+- **Extensive ablations** quantifying each component's contribution to search efficiency
 
-CodeEvolve is built upon an island-based genetic algorithm designed to maintain population diversity and increase throughput through parallel search efforts. Within this architecture, the evolutionary cycle is driven by two primary operators designed to balance the search process: 
+For comprehensive evaluation details, see our [technical report](https://arxiv.org/abs/2510.14150).
 
-1. **Depth exploitatiom**: This operator selects high-performing parent solutions ($S$) via rank-based selection and uses the LLM Ensemble to perform targeted, incremental refinements. Crucially, it provides the LLM with the parent's full lineage, including its $k$ closest ancestors, $A_k(S)$, to constrain the search space toward local optima refinement.
- 
-2. **Meta-Prompting Exploration**: This operator fosters diversity by instructing an auxiliary LLM (MetaPromptingLLM) to analyze the current solution $S$ and its original prompt $P(S)$, generating an enriched new prompt $P'$. This new prompt is then used by the LLMEnsemble to generate a potentially novel solution $S'$. This step intentionally excludes the ancestral context, encouraging the model to explore distinct pathways.
+## Reproducing Research Results
 
-Both operators are complemented by an **Inspiration-based Crossover** mechanism, which avoids traditional syntactic splicing by providing the LLMEnsemble with sampled high-performing solutions as additional context. This encourages the LLM to synthesize new solutions by semantically combining successful logic or patterns from multiple parents. 
+For complete experimental configurations, benchmark implementations, and step-by-step examples demonstrating how to run CodeEvolve on various problems, visit our experiments repository:
+
+**[github.com/inter-co/science-codeevolve-experiments](https://github.com/inter-co/science-codeevolve-experiments)**
+
+This companion repository contains all code necessary to reproduce the results from our [technical report](https://arxiv.org/abs/2510.14150).
+
+## Quick Start
+
+### Installation
+
+Clone this repository and create the conda environment:
 
-## Usage
-To setup the proper conda environment, run the following:
 ```bash
+git clone https://github.com/inter-co/science-codeevolve.git
+cd science-codeevolve
 conda env create -f environment.yml
 conda activate codeevolve
 ```
-The command-line version of codeevolve is implemented in ```src/codeevolve/cli.py```, and ```scripts/run.sh``` contains a bash script for running codeevolve on a given benchmark. The most important variables to be defined in this file are the ```API_KEY, API_BASE``` environment variables for connecting with an LLM provider.
 
-More comprehensive tutorials will be released soon.
+### Basic Usage
+
+Configure your LLM provider by setting environment variables:
+
+```bash
+export API_KEY=your_api_key_here
+export API_BASE=your_api_base_url
+```
+
+You can run codeevolve via the terminal as follows:
+```bash
+codeevolve --inpt_dir=INPT_DIR --cfg_path=CFG_PATH --out_dir=RESULTS_DIR --load_ckpt=LOAD_CKPT --terminal_logging
+```
+See `src/codeevolve/cli.py` for further details. Our [experiments repository](https://github.com/inter-co/science-codeevolve-experiments) multiple usage examples.
 
-## Next steps
+### Customizing for Your Problem
 
-We are actively developing CodeEvolve to be a more powerful and robust framework. Our immediate roadmap is focused on incorporating more sophisticated evolutionary mechanisms mentioned in our future work:
+CodeEvolve is designed for algorithmic problems with quantifiable metrics. To apply it to your domain:
 
-1. **Dynamic Exploration/Exploitation**: Currently, the choice between exploration (meta-prompting) and exploitation (depth) is set by a fixed probability (exploration_rate). A major planned feature is to implement a more dynamic scheduling, potentially using Reinforcement Learning methods, to adapt this trade-off based on the state of the evolutionary search.
+1. Define your evaluation function that measures solution quality
+2. Specify the initial codebase or problem structure
+3. Configure evolutionary parameters (population size, mutation rates, etc.)
+4. Choose your LLM ensemble composition
 
-We plan on working on performance improvements, e.g. faster sampling, asynchronous islands algorithm, etc. We also intend on implementing more benchmark problems to test CodeEvolve.
-## Project background and inspirations
+Comprehensive tutorials and example notebooks are coming soon.
 
-This project was initiated as an effort to replicate and build upon the work presented in Google DeepMind's AlphaEvolve whitepaper. The closed-source nature of that project  presented a barrier to community-driven progress. Our goal is to provide a transparent, open-source framework that implements the high-level concepts of LLM-driven evolution, allowing for reproducible research and collective innovation.
+## Use Cases
 
-During the initial stages, we drew inspiration from other open-source efforts like [OpenEvolve](https://github.com/codelion/openevolve), which validated the community's interest in this domain. We are grateful to the contributors of such projects for paving the way and demonstrating the viability of open-source research in this field.
+The framework is suitable for any domain where solutions can be represented as code and evaluated programmatically. Some common examples include:
+
+- **Mathematical constructions:** Finding solutions to open problems in mathematics
+- **Algorithm design:** Optimizing computational kernels and scheduling algorithms
+- **Scientific discovery:** Exploring hypothesis spaces expressed as executable code
 
 ## Contributing
 
-We are not accepting pull requests at this time, as we are still actively developing and changing most of the features from CodeEvolve. We plan on accepting pull requests soon. However, you can contribute by reporting issues or suggesting features through the creation of a [GitHub issue](https://github.com/inter-co/science-codeevolve/issues).
+We welcome contributions from the community! Here's how to get involved:
+
+1. **Start with an issue:** Browse existing issues or create a new one describing your proposed change
+2. **Submit a pull request:** Reference the issue in your PR description
+3. **Keep PRs focused:** Avoid massive changes—smaller, well-tested contributions are easier to review
+4. **Maintain quality:** Ensure code is tested and documented
+
+Please refer to `CONTRIBUTING.md` for detailed guidelines.
 
 ## Citation
 
+If you use CodeEvolve in your research, please cite our paper:
+
 ```bibtex
 @article{assumpção2025codeevolveopensourceevolutionary,
-      title={CodeEvolve: An open source evolutionary coding agent for algorithm discovery and optimization}, 
+      title={CodeEvolve: An open source evolutionary coding agent for algorithm discovery and optimization},
       author={Henrique Assumpção and Diego Ferreira and Leandro Campos and Fabricio Murai},
       year={2025},
       eprint={2510.14150},
       archivePrefix={arXiv},
       primaryClass={cs.AI},
-      url={https://arxiv.org/abs/2510.14150}, 
+      url={https://arxiv.org/abs/2510.14150},
 }
 ```
 
+## Acknowledgements
+
+The authors thank Bruno Grossi for his continuous support during the development of this project. We thank Fernando Augusto and Tiago Machado for useful conversations about possible applications of CodeEvolve. We also thank the [OpenEvolve](https://github.com/codelion/openevolve) community for their inspiration and discussion about evolutionary coding agents.
+
 ## License and Disclaimer
 
 All software is licensed under the Apache License, Version 2.0 (Apache 2.0); you may not use this file except in compliance with the Apache 2.0 license. You may obtain a copy of the Apache 2.0 license at: https://www.apache.org/licenses/LICENSE-2.0.
 
-**This is not an official Inter product.**
+**This is not an official Inter product.**