Adaptive migration: stabilize evolution by adapting mutation/selection based on progress

.gitignore

@@ -173,3 +173,5 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
+
+/results/

README.md

@@ -16,7 +16,7 @@
 
 The framework supports **parallel evaluation of candidates** locally or on a Slurm cluster. It maintains an archive of successful solutions, enabling knowledge transfer between different evolutionary islands. `ShinkaEvolve` is particularly well-suited for scientific tasks where there is a verifier available and the goal is to optimize performance metrics while maintaining code correctness and readability.
 
-![](docs/conceptual.png)
+![evolution](https://github.com/user-attachments/assets/22cf3468-17fe-4995-9e13-d602b490a54e)
 
 ## Documentation 📝
 
@@ -26,6 +26,7 @@ The framework supports **parallel evaluation of candidates** locally or on a Slu
 | 📓 **[Tutorial Notebook](examples/shinka_tutorial.ipynb)** | Interactive walkthrough of Shinka features | Hands-on examples, configuration, best practices |
 | ⚙️ **[Configuration](docs/configuration.md)** | Comprehensive configuration reference | All config options, optimization settings, advanced features |
 | 🎨 **[WebUI](docs/webui.md)** | Interactive visualization and monitoring | Real-time tracking, result analysis, debugging tools | 
+|🕹️ **[Local LLM Support](https://github.com/SakanaAI/ShinkaEvolve/blob/main/docs/support_local_llm.md)**| Instructions for Local LLMs | How to setup local LLMs on your machine|
 
 ## Installation & Quick Start 🚀
 
@@ -127,6 +128,7 @@ runner.run()
 | `migration_interval` | `10` | `int` | Generations between island migrations |
 | `migration_rate` | `0.1` | `float` | Proportion of island population to migrate |
 | `island_elitism` | `True` | `bool` | Keep best programs on their original islands |
+| `migration_adaptation` | `None` | `Optional[dict]` | Optional adaptive migration configuration per island |
 | `enforce_island_separation` | `True` | `bool` | Enforce full separation between islands |
 | `parent_selection_strategy` | `"power_law"` | `str` | Parent selection: "weighted", "power_law", "beam_search" |
 | `exploitation_alpha` | `1.0` | `float` | Power-law exponent (0=uniform, 1=power-law) |
@@ -136,6 +138,11 @@ runner.run()
 
 </details>
 
+Adaptive migration (success/diversity/bandit feedback that updates
+`migration_rate`, `migration_interval`, and `island_elitism` per island) is
+described in `docs/migration_adaptation.md`. A ready-to-run Hydra example lives
+at `configs/database/island_adaptive.yaml`.
+
 <details>
 <summary><strong>JobConfig Parameters</strong> (click to expand)</summary>
 

configs/config.yaml

@@ -2,9 +2,9 @@ defaults:
   - _self_
   - database@_global_: island_small
   - evolution@_global_: small_budget
-  - task@_global_: mad_tf
+  - task@_global_: circle_packing
   - cluster@_global_: local
-  - variant@_global_: mad_tf_example
+  - variant@_global_: default
 
 verbose: false
 results_dir: results

configs/database/island_adaptive.yaml

@@ -0,0 +1,45 @@
+# Adaptive migration sample configuration
+db_config:
+  _target_: shinka.database.DatabaseConfig
+  db_path: "evolution_db.sqlite"
+  num_islands: 4
+  archive_size: 100
+  elite_selection_ratio: 0.3
+  num_archive_inspirations: 5
+  num_top_k_inspirations: 2
+  migration_interval: 10
+  migration_rate: 0.1
+  island_elitism: 0.1
+  migration_adaptation:
+    enabled: true
+    methods: ["success", "diversity", "bandit"]
+    success:
+      window: 8
+      target_improvement: 0.01
+      step_up: 1.2
+      step_down: 0.83
+      ema_beta: 0.75
+    diversity:
+      metric: "score_std"
+      low_thresh: 0.25
+      high_thresh: 0.6
+      adjust_strength: 0.15
+    bandit:
+      policy_arms:
+        donor: ["random", "ring", "topk"]
+        payload: ["random", "elite", "novel"]
+        size: ["small", "medium", "large"]
+      algo: "ucb1"
+      ucb_c: 1.0
+      epsilon: 0.1
+    bounds:
+      rate_min: 0.02
+      rate_max: 0.5
+      interval_min: 2
+      interval_max: 40
+      elitism_min: 0.05
+      elitism_max: 0.4
+    weights:
+      success: 1.0
+      diversity: 0.5
+      bandit: 0.5

configs/database/island_large_adaptive.yaml

@@ -0,0 +1,49 @@
+# Adaptive variant of island_large
+db_config:
+  _target_: shinka.database.DatabaseConfig
+  db_path: "evolution_db.sqlite"
+  num_islands: 5
+  archive_size: 40
+  elite_selection_ratio: 0.3
+  num_archive_inspirations: 4
+  num_top_k_inspirations: 2
+  migration_interval: 10
+  migration_rate: 0.1
+  island_elitism: true
+  parent_selection_strategy: "weighted"
+  exploitation_alpha: 1.0
+  exploitation_ratio: 0.2
+  parent_selection_lambda: 10.0
+  migration_adaptation:
+    enabled: true
+    methods: ["success", "diversity", "bandit"]
+    success:
+      window: 8
+      target_improvement: 0.01
+      step_up: 1.2
+      step_down: 0.83
+      ema_beta: 0.75
+    diversity:
+      metric: "score_std"
+      low_thresh: 0.25
+      high_thresh: 0.6
+      adjust_strength: 0.15
+    bandit:
+      policy_arms:
+        donor: ["random", "ring", "topk"]
+        payload: ["random", "elite", "novel"]
+        size: ["small", "medium", "large"]
+      algo: "ucb1"
+      ucb_c: 1.0
+      epsilon: 0.1
+    bounds:
+      rate_min: 0.02
+      rate_max: 0.5
+      interval_min: 2
+      interval_max: 40
+      elitism_min: 0.05
+      elitism_max: 0.4
+    weights:
+      success: 1.0
+      diversity: 0.5
+      bandit: 0.5

configs/database/island_medium_adaptive.yaml

@@ -0,0 +1,48 @@
+# Adaptive variant of island_medium
+db_config:
+  _target_: shinka.database.DatabaseConfig
+  db_path: "evolution_db.sqlite"
+  num_islands: 2
+  archive_size: 40
+  exploitation_ratio: 0.2
+  elite_selection_ratio: 0.3
+  num_archive_inspirations: 4
+  num_top_k_inspirations: 2
+  migration_interval: 10
+  migration_rate: 0.0
+  island_elitism: true
+  parent_selection_strategy: "weighted"
+  parent_selection_lambda: 10.0
+  migration_adaptation:
+    enabled: true
+    methods: ["success", "diversity", "bandit"]
+    success:
+      window: 8
+      target_improvement: 0.01
+      step_up: 1.2
+      step_down: 0.83
+      ema_beta: 0.75
+    diversity:
+      metric: "score_std"
+      low_thresh: 0.25
+      high_thresh: 0.6
+      adjust_strength: 0.15
+    bandit:
+      policy_arms:
+        donor: ["random", "ring", "topk"]
+        payload: ["random", "elite", "novel"]
+        size: ["small", "medium", "large"]
+      algo: "ucb1"
+      ucb_c: 1.0
+      epsilon: 0.1
+    bounds:
+      rate_min: 0.02
+      rate_max: 0.5
+      interval_min: 2
+      interval_max: 40
+      elitism_min: 0.05
+      elitism_max: 0.4
+    weights:
+      success: 1.0
+      diversity: 0.5
+      bandit: 0.5

configs/database/island_small_adaptive.yaml

@@ -0,0 +1,46 @@
+# Adaptive variant of island_small
+db_config:
+  _target_: shinka.database.DatabaseConfig
+  db_path: "evolution_db.sqlite"
+  num_islands: 2
+  archive_size: 20
+  exploitation_ratio: 0.2
+  elite_selection_ratio: 0.3
+  num_archive_inspirations: 4
+  num_top_k_inspirations: 2
+  migration_interval: 10
+  migration_rate: 0.1
+  island_elitism: true
+  migration_adaptation:
+    enabled: true
+    methods: ["success", "diversity", "bandit"]
+    success:
+      window: 8
+      target_improvement: 0.01
+      step_up: 1.2
+      step_down: 0.83
+      ema_beta: 0.75
+    diversity:
+      metric: "score_std"
+      low_thresh: 0.25
+      high_thresh: 0.6
+      adjust_strength: 0.15
+    bandit:
+      policy_arms:
+        donor: ["random", "ring", "topk"]
+        payload: ["random", "elite", "novel"]
+        size: ["small", "medium", "large"]
+      algo: "ucb1"
+      ucb_c: 1.0
+      epsilon: 0.1
+    bounds:
+      rate_min: 0.02
+      rate_max: 0.5
+      interval_min: 2
+      interval_max: 40
+      elitism_min: 0.05
+      elitism_max: 0.4
+    weights:
+      success: 1.0
+      diversity: 0.5
+      bandit: 0.5

docs/configuration.md

@@ -157,6 +157,7 @@ exp_name: "shinka_my_task"
 | `migration_interval` | int | 10 | Generations between island migrations |
 | `migration_rate` | float | 0.1 | Fraction of population migrated |
 | `island_elitism` | bool | true | Preserve elites per island |
+| `migration_adaptation` | dict | null | Optional per-island adaptive migration settings |
 
 ### Resource Parameters
 
@@ -169,6 +170,14 @@ exp_name: "shinka_my_task"
 | `conda_env` | str | `"shinka"` | Conda environment name |
 | `modules` | list | `[]` | Environment modules to load |
 
+#### Adaptive Migration Settings
+
+The optional `migration_adaptation` block enables automatic adjustment of
+`migration_rate`, `migration_interval`, and `island_elitism` per island. Each
+method (`success`, `diversity`, `bandit`) can be toggled independently and has a
+dedicated configuration block. Refer to `docs/migration_adaptation.md` and the
+sample `configs/database/island_adaptive.yaml` file for a complete walkthrough.
+
 ## Pre-configured Variants
 
 Shinka uses [Hydra](https://hydra.cc/) for flexible, hierarchical configuration management. The system is designed around composable configuration files that can be mixed and matched to create different experimental setups.