# ShinkaEvolve for Verifiable Scientific Code Optimization > ShinkaEvolve is a Python framework for improving scientific programs through LLM-generated mutations, evolutionary selection, and local or Slurm-based parallel evaluation. It is designed for research tasks with executable verifiers and measurable objectives. **SakanaAI/ShinkaEvolve** — ShinkaEvolve: Towards Open-Ended and Sample-Efficient Program Evolution 🧬 - Repository: https://github.com/SakanaAI/ShinkaEvolve - Website: https://sakanaai.github.io/ShinkaEvolve/ - Stars: 1,481 · Forks: 292 - Language: Python - License: Apache-2.0 - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/sakanaai-shinkaevolve ## Where ShinkaEvolve Fits in Scientific Computing ShinkaEvolve addresses programs whose quality can be tested rather than judged only from a textual description. The repository positions it for scientific discovery, algorithm discovery, and optimization tasks where a verifier can execute candidate code, reject invalid programs, and return metrics such as correctness, performance, or fitness. That combination matters because an LLM can propose a change without any guarantee that the change improves the actual scientific result. The intended users are research teams working in Python or supported example languages, engineers optimizing algorithms, and scientists who can formalize a useful evaluation function. The bundled examples include circle packing, heat diffusion, 2048, Collatz steps, prime counting, novelty generation, RTLLM, sine approximation, and Wolfram-style GCD work. This range indicates that ShinkaEvolve is intended as a framework around a task, rather than as one domain-specific optimizer. It is a poor fit when the objective cannot be executed reliably. A verifier that rewards superficial text changes, leaks expected answers to the model, or penalizes useful exploratory behavior can direct evolution toward the wrong program. ShinkaEvolve also does not replace domain validation. Its documentation says the system is particularly suitable when correctness and readability should be maintained, but the repository does not claim that generated scientific conclusions are automatically trustworthy. ## Population Search, LLM Mutation, and Verification The core mechanism is evolutionary search over a population of programs. Instead of asking an LLM for one replacement program, ShinkaEvolve retains multiple candidates and uses LLMs as mutation operators. A selected program can therefore produce related variants that are evaluated under the same scientific objective while preserving useful structure from earlier candidates. The process also maintains an archive of successful solutions. According to the README, knowledge can transfer between different evolutionary islands, meaning separately managed populations can exchange successful material rather than progress only within one isolated group. This matters for long searches because a strong mutation found in one lineage may inform work elsewhere without replacing every candidate at once. Candidate evaluation can run locally in parallel or on a Slurm cluster. Evaluation is the decisive feedback path: generated code must execute, a verifier must score it, and selection logic must reward better candidates while rejecting invalid ones. LLM output is only a proposal until that verification stage accepts it. The repository layout also includes a WebUI for tracking and result analysis, while an async evolution guide documents concurrent proposal and evaluation settings. That architecture separates code generation from the costly or potentially risky work of executing candidates. ## Installing shinka-evolve and Launching Circle Packing The distribution name is `shinka-evolve`, while Python code imports the package as `shinka`. The package requires Python 3.10 or later. For the quickest documented path, install the PyPI release and launch the built-in circle packing preset. The following command installs the package and starts the first documented evolution experiment. The README names `shinka_launch variant=circle_packing_example` as the command; it does not document a fixed output format for that run. ```bash pip install shinka-evolve shinka_launch variant=circle_packing_example ``` Users who prefer `uv` can install the same distribution with the documented command. This does not change the Python import name. ```bash uv pip install shinka-evolve shinka_launch variant=circle_packing_example ``` For source development, the repository uses a Python 3.11 virtual environment. The `git clone`, environment creation, activation, and editable installation commands are shown below. ```bash git clone https://github.com/SakanaAI/ShinkaEvolve cd ShinkaEvolve uv venv --python 3.11 source .venv/bin/activate uv pip install -e . ``` The package exposes four command-line entry points in `pyproject.toml`: `shinka_launch`, `shinka_models`, `shinka_run`, and `shinka_visualize`. These names indicate distinct setup, launch, model, execution, and visualization responsibilities, although the README does not provide a first-use example for each one. ## Custom Variants Through Hydra Configuration ShinkaEvolve uses Hydra-style composition. Built-in presets are packaged below `shinka/configs/`, and the CLI accepts group overrides such as `task` and `database`. This makes a preset the starting point for an experiment rather than a hard-coded application. The README documents the following shorthand overrides. These select or alter configuration groups; they do not by themselves explain how a custom task is implemented. ```bash shinka_launch variant=circle_packing_example shinka_launch task=novelty_generator database=island_small ``` Custom variants can live outside a source checkout. Create a `variant` directory, save a YAML preset in it, and pass its parent directory through `--config-dir`. The documented sequence deliberately keeps the editor choice as an environment-specific placeholder rather than defining a nonexistent editor command. ```bash mkdir -p ~/my-shinka-configs/variant $EDITOR ~/my-shinka-configs/variant/my_variant.yaml shinka_launch --config-dir ~/my-shinka-configs variant=my_variant ``` The precise YAML schema is delegated to the configuration guide. From the repository documentation, an adopter must connect at least four pieces in the configuration: code candidates, mutation models, executable evaluation, and database or island behavior. Missing a verifier or giving evaluation and mutation the same fault can make an otherwise valid evolutionary loop ineffective. Config errors also matter because the WebUI can reveal run history, but it cannot determine whether the scoring function encodes the scientific goal correctly. ## Local, Slurm, Async, and Headless Execution Paths ShinkaEvolve supports several execution arrangements, but they address different costs. Local parallel evaluation is convenient for bounded experiments and modest hardware. Slurm execution is for candidates that need cluster scheduling. The async evolution documentation focuses on high-throughput operation through concurrent proposal and evaluation tuning and advertises a 5x to 10x speedup in its guide description. That range is the project's documented claim, not an independently established result. LLM access is also not limited to a single hosted integration path. The dependencies include `openai`, `anthropic`, and `google-genai`, while the local-model documentation describes integration of open-source models and embeddings. The May 2026 update added Headless CLI-backed mutation models for subscription-backed agent use, including model strings such as `headless/codex@gpt-5.5?effort=high` and `headless/claude`. Such a setup still depends on the selected external agent service and its authentication path. The repository also includes agent skills for Claude Code and Codex workflows. Installation is documented as a single `npx skills` command that adds all listed skills for both agents. ```bash npx skills add SakanaAI/ShinkaEvolve --skill '*' -a claude-code -a codex -y ``` The named skills cover setup, repository conversion, evolution, and result inspection. This is useful for teams that want to keep experiment definition inside coding-agent workflows, but it adds another interface to configure and inspect. The README does not claim that agent skills are required for normal Python use. ## Constraints, Alternatives, and Apache-2.0 Licensing The clearest constraint is verifier dependence. ShinkaEvolve can optimize only what its evaluation environment measures. Candidate code may consume substantial compute during parallel or Slurm execution, and LLM-backed mutation introduces provider configuration, request cost, model availability, and non-determinism. The package also has an alpha status in `pyproject.toml`, so adopters should expect interface and packaging changes while reviewing releases and changelogs. A traditional optimizer is the main alternative when the representation and objective are fixed and the mutable representation is not source code. ShinkaEvolve instead edits programs, which makes it more appropriate when the useful change involves algorithm structure, control flow, or code readability. Conversely, direct optimization is easier to constrain when the solution must remain within a known mathematical parameter space and every accepted result must satisfy explicit constraints. Apache-2.0 permits use, modification, and distribution under its conditions, including preservation of applicable notices and the license text. That is a repository licensing fact, not legal advice. Derived internal tools should review their own distribution, notice, and model-service obligations. Maintenance status can be assessed from repository activity. The repository is not archived, its last push was on 2026-10-05, and the listed releases include `v0.0.7`, `v0.0.6`, and `v0.0.5`. Those facts show recent repository activity, but the package remains classified as alpha. ## Conclusion Researchers with executable verifiers, measurable objectives, and code-generation costs should evaluate ShinkaEvolve. Users seeking a fixed optimizer, immediate deterministic results, or a system without model-provider dependencies should choose a narrower tool. Verify first that candidate execution is isolated, scoring rewards the intended behavior, and generated patches remain acceptable under the Apache-2.0-licensed codebase. ## FAQ ### How do I install ShinkaEvolve and run its circle packing example? Install the `shinka-evolve` distribution with `pip install shinka-evolve`, then run `shinka_launch variant=circle_packing_example`. The import name remains `shinka`. ### Does ShinkaEvolve require Python 3.10 or newer? Yes. `pyproject.toml` declares `requires-python = ">=3.10"` and lists Python 3.10, 3.11, and 3.12 classifiers. ### Can ShinkaEvolve evaluate candidates on a Slurm cluster? Yes. The README states that candidate evaluation can run locally in parallel or on a Slurm cluster. The README does not provide a complete Slurm submission example. ### What license applies to ShinkaEvolve? The repository and package metadata identify `Apache-2.0`. The `LICENSE` file is included at the repository root. ### Is ShinkaEvolve suitable without an executable verifier? The README describes ShinkaEvolve as best suited to tasks with a verifier and measurable objectives. It does not claim that verifier-free creative generation is a supported primary use case. ## Sources - [License: Apache-2.0](https://github.com/SakanaAI/ShinkaEvolve/blob/main/LICENSE) - [Project website](https://sakanaai.github.io/ShinkaEvolve/) - [README](https://github.com/SakanaAI/ShinkaEvolve/blob/main/README.md) - [Releases](https://github.com/SakanaAI/ShinkaEvolve/releases) - [SakanaAI/ShinkaEvolve on GitHub](https://github.com/SakanaAI/ShinkaEvolve) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sakanaai-shinkaevolve