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

@@ -7,16 +7,16 @@
   <img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" />
   <a href="https://github.com/SakanaAI/ShinkaEvolve/blob/master/LICENSE.md"><img src="https://img.shields.io/badge/license-Apache2.0-blue.svg" /></a>
   <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" /></a>
-  <a href="http://arxiv.org/abs/2212.04180"><img src="http://img.shields.io/badge/paper-arxiv.2212.04180-B31B1B.svg" /></a>
+  <a href="http://arxiv.org/abs/2509.19349"><img src="http://img.shields.io/badge/paper-arxiv.2509.19349-B31B1B.svg" /></a>
   <a href="https://colab.research.google.com/github/SakanaAI/ShinkaEvolve/blob/main/examples/shinka_tutorial.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" /></a>
 </p>
 
 
-`ShinkaEvolve` is a framework that combines Large Language Models (LLMs) with evolutionary algorithms to drive scientific discovery. By leveraging the creative capabilities of LLMs and the optimization power of evolutionary search, `ShinkaEvolve` enables automated exploration and improvement of scientific code. The system is inspired by the [AI Scientist](https://sakana.ai/ai-scientist/), [AlphaEvolve](https://deepmind.google/discover/blog/alphaevolve-a-gemini-powered-coding-agent-for-designing-advanced-algorithms/) and the [Darwin Goedel Machine](https://sakana.ai/dgm/): It maintains a population of programs that evolve over generations, with an ensemble of LLMs acting as intelligent mutation operators that suggest code improvements.
+[`ShinkaEvolve`](https://arxiv.org/abs/2509.19349) is a framework that combines Large Language Models (LLMs) with evolutionary algorithms to drive scientific discovery. By leveraging the creative capabilities of LLMs and the optimization power of evolutionary search, `ShinkaEvolve` enables automated exploration and improvement of scientific code. The system is inspired by the [AI Scientist](https://sakana.ai/ai-scientist/), [AlphaEvolve](https://deepmind.google/discover/blog/alphaevolve-a-gemini-powered-coding-agent-for-designing-advanced-algorithms/) and the [Darwin Goedel Machine](https://sakana.ai/dgm/): It maintains a population of programs that evolve over generations, with an ensemble of LLMs acting as intelligent mutation operators that suggest code improvements.
 
 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 🚀
 
@@ -52,9 +53,9 @@ For detailed installation instructions and usage examples, see the [Getting Star
 | Example | Description | Environment Setup |
 |---------|-------------|-------------------|
 | ⭕ [Circle Packing](examples/circle_packing) | Optimize circle packing to maximize radii. | `LocalJobConfig` |
-| 🤖 [Agent Design](examples/agent_design) | Design agent scaffolds for math tasks. | `LocalJobConfig` |
+| 🤖 [Agent Design](examples/adas_aime) | Design agent scaffolds for math tasks. | `LocalJobConfig` |
 | 🎯 [ALE-Bench](examples/ale_bench) | Code optimization for ALE-Bench tasks. | `LocalJobConfig` |
-| ✨ [Novelty Generator](examples/novelty_generator_bck) | Generate creative, surprising outputs (e.g., ASCII art). | `LocalJobConfig` |
+| ✨ [Novelty Generator](examples/novelty_generator) | Generate creative, surprising outputs (e.g., ASCII art). | `LocalJobConfig` |
 
 
 ## `shinka` Run with Python API 🐍
@@ -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>
 
@@ -308,9 +315,9 @@ If you use `ShinkaEvolve` in your research, please cite it as follows:
 
 ```
 @article{lange2025shinka,
-  title={ShinkaEvolve: Towards Open-Ended and Sample-Efficient Program Evolution},
+  title={ShinkaEvolve: Towards Open-Ended And Sample-Efficient Program Evolution},
   author={Lange, Robert Tjarko and Imajuku, Yuki and Cetin, Edoardo},
-  journal={arXiv preprint},
+  journal={arXiv preprint arXiv:2509.19349},
   year={2025}
 }
-```
+```

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.