add note in readme

Author: codelion

README.md

@@ -91,6 +91,44 @@ OpenEvolve orchestrates a sophisticated evolutionary pipeline:
    - Feature map clustering and archive management
    - Comprehensive metadata and lineage tracking
 
+### Island-Based Evolution with Worker Pinning
+
+OpenEvolve implements a sophisticated island-based evolutionary architecture that maintains multiple isolated populations to prevent premature convergence and preserve genetic diversity.
+
+#### How Islands Work
+
+- **Multiple Isolated Populations**: Each island maintains its own population of programs that evolve independently
+- **Periodic Migration**: Top-performing programs periodically migrate between adjacent islands (ring topology) to share beneficial mutations
+- **True Population Isolation**: Worker processes are deterministically pinned to specific islands to ensure no cross-contamination during parallel evolution
+
+#### Worker-to-Island Pinning
+
+To ensure true island isolation during parallel execution, OpenEvolve implements automatic worker-to-island pinning:
+
+```python
+# Workers are distributed across islands using modulo arithmetic
+worker_id = 0, 1, 2, 3, 4, 5, ...
+island_id = worker_id % num_islands
+
+# Example with 3 islands and 6 workers:
+# Worker 0, 3 → Island 0  
+# Worker 1, 4 → Island 1
+# Worker 2, 5 → Island 2
+```
+
+**Benefits of Worker Pinning**:
+- **Genetic Isolation**: Prevents accidental population mixing between islands during parallel sampling
+- **Consistent Evolution**: Each island maintains its distinct evolutionary trajectory
+- **Balanced Load**: Workers are evenly distributed across islands automatically
+- **Migration Integrity**: Controlled migration happens only at designated intervals, not due to race conditions
+
+**Automatic Distribution**: The system handles all edge cases automatically:
+- **More workers than islands**: Multiple workers per island with balanced distribution
+- **Fewer workers than islands**: Some islands may not have dedicated workers but still participate in migration
+- **Single island**: All workers sample from the same population (degrades to standard evolution)
+
+This architecture ensures that each island develops unique evolutionary pressures and solutions, while periodic migration allows successful innovations to spread across the population without destroying diversity.
+
 ## Getting Started
 
 ### Installation

tests/test_island_isolation.py

@@ -252,22 +252,39 @@ def test_migration_preserves_island_structure(self):
 
         # Record island populations before migration
         island_sizes_before = [len(island) for island in self.database.islands]
+        original_program_count = len(self.database.programs)
 
         # Verify we set up the test correctly
         self.assertEqual(sum(island_sizes_before), 30)
+        self.assertEqual(original_program_count, 30)
 
         # Trigger migration
         self.database.migrate_programs()
 
         # Check islands still have programs
         island_sizes_after = [len(island) for island in self.database.islands]
+        total_programs_after = len(self.database.programs)
 
         # All islands should still have programs
         for size in island_sizes_after:
             self.assertGreater(size, 0)
 
-        # Total population should be unchanged
-        self.assertEqual(sum(island_sizes_before), sum(island_sizes_after))
+        # Migration creates copies, so total population should increase
+        # With migration_rate=0.1 and 10 programs per island, expect ~1 program per island to migrate
+        # Each program migrates to 2 adjacent islands, so we expect ~6 new programs
+        self.assertGreater(total_programs_after, original_program_count)
+        self.assertGreater(sum(island_sizes_after), sum(island_sizes_before))
+        
+        # Verify that migrant programs have correct metadata
+        migrant_count = 0
+        for program in self.database.programs.values():
+            if program.metadata.get("migrant", False):
+                migrant_count += 1
+                # Migrant should have "_migrant_" in their ID
+                self.assertIn("_migrant_", program.id)
+        
+        # Should have some migrant programs
+        self.assertGreater(migrant_count, 0)
 
 
 class TestWorkerPinningEdgeCases(unittest.TestCase):