Add graph coloring example with DIMACS benchmarks

A complete graph coloring example demonstrating OpenEvolve's ability to
evolve sophisticated algorithms from simple starting points.

Features:
- 3-stage cascade evaluation with DIMACS benchmark graphs
- Simple greedy initial algorithm that evolves into DSatur
- Comprehensive test suite with 22 benchmark graphs
- Benchmark runner for testing algorithms (run_benchmarks.py)

Results from 100 iterations:
- Initial greedy: 389 colors, 10/22 optimal
- Evolved DSatur: 362 colors, 15/22 optimal

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: eilamt

.gitignore

@@ -39,11 +39,15 @@ ENV/
 
 # Output files
 examples/*/output/
+examples/*/archive/
 openevolve_output*/
 *.log
 demo_output*/
 pr_sanity*/
 
+# Claude Code
+.claude/
+
 # Test cache
 .pytest_cache/
 .coverage

examples/graph_coloring/README.md

@@ -21,9 +21,62 @@ To run this example:
 
 ```bash
 cd examples/graph_coloring
-python ../../openevolve-run.py initial_program.py evaluator.py --config config.yaml --iterations 50
+python ../../openevolve-run.py initial_program.py evaluator.py --config config.yaml --iterations 100
 ```
 
+### Running Benchmarks
+
+To test a coloring algorithm on the full DIMACS benchmark suite:
+
+```bash
+# Test the initial greedy algorithm
+python run_benchmarks.py
+
+# Test an evolved program
+python run_benchmarks.py best_program.py
+```
+
+This produces a results table showing colors used vs chromatic number for each graph.
+
+## Evaluation System
+
+The evaluator uses a **3-stage cascade** with DIMACS benchmark graphs:
+
+### Stage 1: Validity Check
+- Tests on 3 simple graphs (Petersen, K5, cycle)
+- Must produce **valid colorings** (no adjacent vertices share colors)
+- Programs that fail validity are rejected immediately
+
+### Stage 2: Quick Evaluation
+- Tests on small DIMACS benchmarks (11-87 vertices)
+- Includes: Mycielski graphs (myciel3-5), Queen graphs (5×5 to 8×8), and book graphs (david, huck, jean)
+- Score threshold: 0.7 to proceed to Stage 3
+
+### Stage 3: Comprehensive Evaluation
+- Full DIMACS benchmark suite (22 graphs, 11-211 vertices)
+- Includes challenging graphs: queen11_11, queen12_12, mulsol.i.1, zeroin.i.1
+- Scoring combines coloring quality (70%) and time efficiency (30%)
+
+### DIMACS Benchmarks
+
+The evaluator uses standard [DIMACS graph coloring benchmarks](https://mat.tepper.cmu.edu/COLOR/instances.html) with known chromatic numbers:
+
+| Graph | Vertices | χ (chromatic number) |
+|-------|----------|---------------------|
+| myciel3 | 11 | 4 |
+| myciel4 | 23 | 5 |
+| myciel5 | 47 | 6 |
+| queen5_5 | 25 | 5 |
+| queen6_6 | 36 | 7 |
+| queen8_8 | 64 | 9 |
+| david | 87 | 11 |
+| huck | 74 | 11 |
+| jean | 80 | 10 |
+| anna | 138 | 11 |
+| games120 | 120 | 9 |
+| mulsol.i.1 | 197 | 49 |
+| zeroin.i.1 | 211 | 49 |
+
 ## Algorithm Evolution
 
 ### Initial Algorithm (Simple Greedy)
@@ -47,47 +100,71 @@ def graph_coloring(graph):
     return coloring
 ```
 
-### Evolved Algorithm
+### Evolved Algorithm (DSatur)
 
-*To be updated after running OpenEvolve*
+After 100 iterations, OpenEvolve independently discovered an optimized **DSatur algorithm**:
 
-## Key Improvements
+```python
+def graph_coloring(graph):
+    coloring = {}
+    uncolored = set(range(graph.num_vertices))
 
-Through evolution, OpenEvolve may discover improvements such as:
+    # Cache saturation degrees for efficiency
+    sat_degrees = [0] * graph.num_vertices
+    neighbor_color_sets = [set() for _ in range(graph.num_vertices)]
 
-1. **Vertex Ordering**: Processing high-degree vertices first (Welsh-Powell)
-2. **Saturation Degree**: DSatur algorithm - prioritize vertices with most neighbor colors
-3. **Independent Set Building**: RLF-style algorithms
-4. **Local Search**: Color swapping to reduce total colors
+    while uncolored:
+        # Select vertex with highest saturation degree, then highest degree
+        vertex = max(uncolored,
+                    key=lambda v: (sat_degrees[v], graph.get_degree(v), -v))
+
+        # Assign smallest available color
+        color = 0
+        while color in neighbor_color_sets[vertex]:
+            color += 1
 
-## Test Graphs
+        coloring[vertex] = color
+        uncolored.remove(vertex)
+
+        # Update saturation degrees of uncolored neighbors
+        for neighbor in graph.get_neighbors(vertex):
+            if neighbor in uncolored:
+                if color not in neighbor_color_sets[neighbor]:
+                    neighbor_color_sets[neighbor].add(color)
+                    sat_degrees[neighbor] += 1
+
+    return coloring
+```
 
-The evaluator tests on multiple graph types:
-- **Petersen Graph**: Classic graph, χ = 3
-- **Complete Graph K5**: χ = 5
-- **Bipartite Graphs**: χ = 2
-- **Cycle Graphs**: χ = 2 (even) or 3 (odd)
-- **Random Graphs**: Varying density
+Key improvements discovered:
+1. **Saturation-based vertex ordering**: Prioritizes vertices with the most distinct neighbor colors
+2. **Cached neighbor color sets**: O(1) lookup for available colors
+3. **Tie-breaking by degree**: When saturation is equal, prefer high-degree vertices
 
 ## Results
 
-*To be updated after running OpenEvolve*
+| Metric | Initial (Greedy) | Evolved (DSatur) |
+|--------|------------------|------------------|
+| Combined Score | 0.893 | **0.938** |
+| Optimal Colorings | 10/22 | **15/22** |
+| Total Colors | 389 | **362** |
 
-| Metric | Initial | Evolved |
-|--------|---------|---------|
-| Combined Score | TBD | TBD |
-| Optimal Colorings | TBD | TBD |
+The evolved algorithm:
+- Uses **27 fewer colors** across the test suite
+- Achieves **optimal coloring on 5 additional graphs**
+- Was discovered by **iteration 14** (generation 2)
 
 ## References
 
 - Welsh, D.J.A. and Powell, M.B. (1967). "An upper bound for the chromatic number of a graph and its application to timetabling problems."
 - Brélaz, D. (1979). "New Methods to Color the Vertices of a Graph" (DSatur algorithm)
 - Leighton, F.T. (1979). "A graph coloring algorithm for large scheduling problems" (RLF algorithm)
-- Hertz, A. and de Werra, D. (1987). "Using Tabu Search Techniques for Graph Coloring"
+- DIMACS Graph Coloring Challenge: https://mat.tepper.cmu.edu/COLOR/instances.html
 
 ## Next Steps
 
 Try modifying the config.yaml to:
 - Increase iterations for more evolution
-- Change LLM models
-- Adjust the system message to guide evolution differently
+- Change LLM models or weights
+- Adjust the system message to guide evolution toward specific algorithms
+- Add larger DIMACS benchmarks to the test suite