Improve MAP-Elites feature dimension handling

Clarifies default and custom feature dimensions in documentation and config files. Updates ProgramDatabase to raise an error if a specified feature dimension is missing from program metrics, with a helpful message. Adds a test to ensure missing feature dimensions trigger the correct error.

Author: codelion

README.md

@@ -36,6 +36,7 @@ OpenEvolve implements a comprehensive evolutionary coding system with:
 - **Island-Based Evolution**: Multiple populations with periodic migration for diversity maintenance
 - **Inspiration vs Performance**: Sophisticated prompt engineering separating top performers from diverse inspirations
 - **Multi-Strategy Selection**: Elite, diverse, and exploratory program sampling strategies
+- **Adaptive Feature Dimensions**: Default features (complexity & diversity) with customizable multi-dimensional search spaces
 
 #### 📊 **Evaluation & Feedback Systems**
 - **Artifacts Side-Channel**: Capture build errors, profiling data, and execution feedback for LLM improvement
@@ -274,7 +275,7 @@ database:
   population_size: 500
   num_islands: 5  # Island-based evolution
   migration_interval: 20
-  feature_dimensions: ["score", "complexity"]  # Quality-diversity features
+  feature_dimensions: ["complexity", "diversity"]  # Default quality-diversity features
   
 evaluator:
   # Advanced evaluation features
@@ -293,8 +294,41 @@ Sample configuration files are available in the `configs/` directory:
 - `default_config.yaml`: Comprehensive configuration with all available options
 - `island_config_example.yaml`: Advanced island-based evolution setup
 
+### Feature Dimensions in MAP-Elites
+
+Feature dimensions control how programs are organized in the MAP-Elites quality-diversity grid:
+
+**Default Features**: If `feature_dimensions` is NOT specified in your config, OpenEvolve uses `["complexity", "diversity"]` as defaults.
+
+**Built-in Features** (always computed internally by OpenEvolve):
+- **complexity**: Code length (recommended default)
+- **diversity**: Code structure diversity compared to other programs (recommended default)
+
+Only `complexity` and `diversity` are used as defaults because they work well across all program types.
+
+**Custom Features**: You can mix built-in features with metrics from your evaluator:
+```yaml
+database:
+  feature_dimensions: ["complexity", "performance", "correctness"]  # Mix of built-in and custom
+  # Per-dimension bin configuration (optional)
+  feature_bins: 
+    complexity: 10        # 10 bins for complexity
+    performance: 20       # 20 bins for performance (from YOUR evaluator)
+    correctness: 15       # 15 bins for correctness (from YOUR evaluator)
+```
+
+**Important**: OpenEvolve will raise an error if a specified feature is not found in the evaluator's metrics. This ensures your configuration is correct. The error message will show available metrics to help you fix the configuration.
+
 See the [Configuration Guide](configs/default_config.yaml) for a full list of options.
 
+### Default Metric for Program Selection
+
+When comparing and selecting programs, OpenEvolve uses the following priority:
+1. **combined_score**: If your evaluator returns a `combined_score` metric, it will be used as the primary fitness measure
+2. **Average of all metrics**: If no `combined_score` is provided, OpenEvolve calculates the average of all numeric metrics returned by your evaluator
+
+This ensures programs can always be compared even without explicit fitness definitions. For best results, consider having your evaluator return a `combined_score` that represents overall program fitness.
+
 ## Artifacts Channel
 
 OpenEvolve includes an **artifacts side-channel** that allows evaluators to capture build errors, profiling results, etc. to provide better feedback to the LLM in subsequent generations. This feature enhances the evolution process by giving the LLM context about what went wrong and how to fix it.

configs/default_config.yaml

@@ -90,10 +90,32 @@ database:
   # Note: diversity_metric is fixed to "edit_distance" (feature_based not implemented)
 
   # Feature map dimensions for MAP-Elites
+  # Default if not specified: ["complexity", "diversity"]
+  # 
+  # Built-in features (always available, computed by OpenEvolve):
+  #   - "complexity": Code length
+  #   - "diversity": Code structure diversity
+  #
+  # You can mix built-in features with custom metrics from your evaluator:
   feature_dimensions:                 # Dimensions for MAP-Elites feature map
-    - "score"                         # Performance score
-    - "complexity"                    # Code complexity (length)
+    - "complexity"                    # Code length (built-in)
+    - "diversity"                     # Code diversity (built-in)
+  # Example with custom features:
+  # feature_dimensions:
+  #   - "performance"                 # Must be returned by your evaluator
+  #   - "correctness"                 # Must be returned by your evaluator
+  #   - "memory_efficiency"           # Must be returned by your evaluator
+  
+  # Number of bins per dimension
+  # Can be a single integer (same for all dimensions) or a dict
   feature_bins: 10                    # Number of bins per dimension
+  # Example of per-dimension configuration:
+  # feature_bins:
+  #   complexity: 10                  # 10 bins for complexity
+  #   diversity: 15                   # 15 bins for diversity
+  #   performance: 20                 # 20 bins for custom metric
+  
+  diversity_reference_size: 20        # Size of reference set for diversity calculation
 
 # Evaluator configuration
 evaluator:

configs/island_config_example.yaml

@@ -33,8 +33,14 @@ database:
   # Note: diversity_metric fixed to "edit_distance"
 
   # Feature map dimensions for MAP-Elites
-  feature_dimensions: ["score", "complexity"]
+  # Default if not specified: ["complexity", "diversity"]
+  # Comment out the line below to use the defaults
+  # feature_dimensions: ["complexity", "diversity"]
   feature_bins: 10
+  # Can also use per-dimension bins:
+  # feature_bins:
+  #   performance: 20
+  #   correctness: 10
 
 # Prompt configuration
 prompt:

openevolve/database.py

@@ -721,9 +721,12 @@ def _calculate_feature_coords(self, program: Program) -> List[int]:
                 bin_idx = max(0, min(num_bins - 1, bin_idx))
                 coords.append(bin_idx)
             else:
-                # Default to middle bin if feature not found
-                num_bins = self.feature_bins_per_dim.get(dim, self.feature_bins)
-                coords.append(num_bins // 2)
+                # Feature not found - this is an error
+                raise ValueError(
+                    f"Feature dimension '{dim}' specified in config but not found in program metrics. "
+                    f"Available metrics: {list(program.metrics.keys())}. "
+                    f"Either remove '{dim}' from feature_dimensions or ensure your evaluator returns it."
+                )
         # Only log coordinates at debug level for troubleshooting
         logger.debug(
             "MAP-Elites coords: %s",

tests/test_map_elites_features.py

@@ -244,6 +244,30 @@ def test_feature_coordinates_with_new_defaults(self):
             self.assertGreaterEqual(coord, 0)
             self.assertLess(coord, db.feature_bins)
 
+    def test_missing_feature_dimension_error(self):
+        """Test that missing feature dimensions raise appropriate errors"""
+        config = Config()
+        config.database.in_memory = True
+        config.database.feature_dimensions = ["complexity", "nonexistent_metric"]
+        db = ProgramDatabase(config.database)
+
+        # Add a program without the required metric
+        program = Program(
+            id="test_error",
+            code="def test(): pass",
+            language="python",
+            metrics={"score": 0.5},  # Missing 'nonexistent_metric'
+        )
+
+        # Should raise ValueError when calculating feature coordinates
+        with self.assertRaises(ValueError) as context:
+            db.add(program)
+
+        # Check error message
+        self.assertIn("nonexistent_metric", str(context.exception))
+        self.assertIn("not found in program metrics", str(context.exception))
+        self.assertIn("score", str(context.exception))  # Should show available metrics
+
 
 if __name__ == "__main__":
     unittest.main()