optalph 1.0.0__tar.gz

optalph-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: astral-sh/setup-uv@v4
+      with:
+        python-version: "3.13"
+        enable-cache: true
+    - run: uv run --frozen --extra dev ruff check .
+    - run: uv run --frozen --extra dev mypy src/optalph/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+    - uses: actions/checkout@v4
+    - uses: astral-sh/setup-uv@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+    - run: uv run --frozen --extra dev pytest -q
+
+  publish:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [lint, test]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+    - uses: astral-sh/setup-uv@v4
+    - run: uv build
+    - uses: pypa/gh-action-pypi-publish@release/v1

optalph-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+data/
+scripts/

optalph-1.0.0/.python-version

@@ -0,0 +1 @@
+3.14

optalph-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 optalph contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

optalph-1.0.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: optalph
+Version: 1.0.0
+Summary: Optimize alphabet permutation to maximize dictionary word coverage
+Project-URL: Repository, https://github.com/4bstr4ct/optalph
+Project-URL: Bug-Tracker, https://github.com/4bstr4ct/optalph/issues
+Author: optalph contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alphabet,english,iterated-local-search,optimization,russian,simulated-annealing
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: dawg
+Requires-Dist: dawg-python>=0.7.2; extra == 'dawg'
+Requires-Dist: pymorphy2-dicts-ru>=2.4.417127.4579844; extra == 'dawg'
+Requires-Dist: pymorphy2>=0.9.1; extra == 'dawg'
+Provides-Extra: dev
+Requires-Dist: hypothesis<6.155,>=6.131.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: tqdm
+Requires-Dist: tqdm>=4.60; extra == 'tqdm'
+Description-Content-Type: text/markdown
+
+# optalph
+
+**Optimize alphabet permutation to maximize dictionary word coverage.**
+
+[![CI](https://github.com/4bstr4ct/optalph/actions/workflows/ci.yml/badge.svg)](https://github.com/4bstr4ct/optalph/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/optalph)](https://pypi.org/project/optalph/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Supports Russian and English alphabets (auto-detected from dictionary), incremental evaluation, 2D grid extraction (Boggle-like), weighted scoring, and parallel multistart.
+
+Requires Python >= 3.10.
+
+## Install
+
+```bash
+pip install optalph
+```
+
+Or with [pipx](https://pypa.github.io/pipx/) (recommended for CLI tools):
+
+```bash
+pipx install optalph
+```
+
+### Optional dependencies
+
+```bash
+# Progress bar
+pip install optalph[tqdm]
+
+# Russian DAWG dictionary (fast, 1.5M word forms)
+pip install optalph[dawg]
+```
+
+## Quick Start
+
+```bash
+# Easiest: download English dictionary automatically
+optalph --download english -w 3 4 5 --iter 500000
+
+# Russian with DAWG dictionary
+optalph -w 3 4 5
+
+# Custom dictionary file
+optalph -w 3 4 5 --dict-file words.txt --no-dawg
+
+# Weighted scoring (frequency file: "word count" per line)
+optalph -w 3 4 5 --freq-file freqs.txt --dict-file words.txt --no-dawg
+
+# 2D Boggle-like grid
+optalph --grid-rows 4 --grid-cols 8 --dict-file words.txt --no-dawg
+```
+
+Alphabet is auto-detected from the dictionary. Use `--alphabet` to override.
+
+### Dictionary Sources
+
+- **`--download english`**: Downloads and caches ~370k English words in `~/.optalph/`
+- **`--download russian`**: Downloads and caches Russian words in `~/.optalph/`
+- **DAWG**: `pymorphy2-dicts-ru` (install via `[dawg]` extra, provides 1.5M Russian word forms)
+- **Custom**: any UTF-8 text file, one word per line
+
+## Optimization Methods
+
+| Method | Flag | Description |
+|--------|------|-------------|
+| SA | `--method sa` (default) | Simulated annealing with tabu list option |
+| ILS | `--method ils` | Iterated local search — SA with perturbation restarts |
+| Multistart | `-r N` | N independent SA runs, best result wins |
+| Parallel | `-r N --parallel` | Multistart with ProcessPoolExecutor |
+
+### Key Parameters
+
+```bash
+--iter N          # Total iterations (default: 500000)
+--t-start T       # Starting temperature (default: 100)
+--cooling R       # Cooling rate (default: 0.9999)
+--tabu            # Enable tabu list (prevents cycling)
+--tabu-tenure N   # Tabu tenure (default: 20)
+--seed N          # Reproducible results
+--incremental     # Use incremental evaluator (faster for large alphabets)
+--ils-steps N     # ILS perturbation steps (default: 10)
+--ils-perturb N   # ILS perturbation strength (default: 3)
+```
+
+## Extraction Rules
+
+- **Adjacent(k)**: Contiguous k-character substrings (e.g. `-w 3` → all 3-letter substrings)
+- **SkipAdjacent(k, step)**: Every `step`-th character in a k-length window (`--skip k step`)
+- **GridRule(rows, cols)**: 2D grid, 8-directional word extraction (`--grid-rows --grid-cols`)
+- Multiple windows are composed: `-w 3 4 5` → Adjacent(3)+Adjacent(4)+Adjacent(5)
+
+## Example Results
+
+### English (26 letters, ~370k words)
+
+```
+$ optalph --download english -w 3 4 5 --iter 500000 --seed 42 --tabu
+
+Best score: 29/25237  (initial: 7, +22)
+Best permutation: jclownqkhumpfgridestabvxyz
+  jclownqkhumpfgridestabvxyz
+  ^^^ jcl
+   ^^^ clo
+   ^^^^ clow
+   ^^^^^ clown
+    ^^^ low
+    ^^^^ lown
+     ^^^ own
+  Words: jcl, clo, clow, clown, low, lown, own, khu, hum, hump, ump, ...
+```
+
+### Russian with weighted scoring (33 letters, ~1.5M forms)
+
+```
+$ optalph -w 3 4 5 --iter 500000 --seed 42 --freq-file ru_50k.txt --tabu
+
+Best score: 129.5  (initial: 12.3, +117.3)
+Best permutation: фбризъцшщёкгспалевыйдячьюхнэтомуж
+  Words: бри, бриз, риз, изъ, щёк, спа, спал, пал, лев, левы, левый, ...
+```
+
+## Library Usage
+
+```python
+from optalph import (
+    evaluate, evaluate_detailed, IncrementalEvaluator,
+    simulated_annealing, iterated_local_search, multistart_sa,
+    greedy_init, build_rules, RUSSIAN_ALPHABET, ENGLISH_ALPHABET,
+    load_dictionary, download_dictionary, load_frequencies,
+    OptimizerConfig, GridRule, IncrementalGridEvaluator,
+)
+
+# Download and load dictionary
+download_dictionary("english")
+dictionary = load_dictionary(download="english", use_dawg=False, min_len=3, max_len=5)
+
+# Build rules
+rules = build_rules(adjacent_windows=[3, 4, 5])
+
+# Evaluate
+score = evaluate(ENGLISH_ALPHABET, rules, dictionary)
+score, valid, invalid, breakdown = evaluate_detailed(ENGLISH_ALPHABET, rules, dictionary)
+
+# Greedy initialization (bigram frequencies → Hamiltonian path)
+initial = greedy_init(ENGLISH_ALPHABET, dictionary, window_sizes=[3, 4, 5])
+
+# SA optimization
+best, best_score, history, acc = simulated_annealing(
+    initial=initial,
+    score_fn=lambda p: evaluate(p, rules, dictionary),
+    config=OptimizerConfig(max_iterations=500000),
+)
+
+# Incremental evaluator (Adjacent rules only, O(1) per swap)
+incr = IncrementalEvaluator.from_rules(rules, dictionary, len(ENGLISH_ALPHABET))
+best, best_score, history, acc = simulated_annealing(
+    initial=initial, evaluator=incr,
+    config=OptimizerConfig(max_iterations=500000),
+)
+
+# ILS (SA + perturbation restarts)
+best, best_score, history, _ = iterated_local_search(
+    initial=initial, evaluator=incr,
+    config=OptimizerConfig(max_iterations=500000),
+    perturbation_strength=3, n_perturbations=5,
+)
+
+# Multistart (parallel)
+best, best_score, history, acc = multistart_sa(
+    ENGLISH_ALPHABET,
+    score_fn=lambda p: evaluate(p, rules, dictionary),
+    config=OptimizerConfig(max_iterations=100000),
+    n_restarts=4, parallel=True,
+    rules=rules, dictionary=dictionary,
+)
+
+# Weighted scoring
+weights = load_frequencies("freqs.txt")
+score = evaluate(ENGLISH_ALPHABET, rules, dictionary, weights=weights)
+```
+
+## Algorithm Details
+
+**Simulated Annealing** with:
+- Geometric cooling schedule (T *= cooling_rate)
+- Tabu list with aspiration criterion (override tabu if move improves current score)
+- Plateau detection with scaling limit (`max(1000, max_iterations/100)`) and decaying reheat
+- Greedy bigram initialization (+30% starting score over random)
+- Parallel multistart via ProcessPoolExecutor
+
+**Iterated Local Search**: SA → perturb (k random swaps) → SA → repeat. Budget divided equally across steps. Each step gets a unique random seed with recalculated cooling schedule.
+
+**Incremental evaluation**: O(1) per swap attempt (only affected slots re-evaluated) vs O(n) full evaluation. Supported for Adjacent and Grid rules.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run mypy src/optalph/
+uv run pytest -q
+```
+
+## License
+
+MIT

optalph-1.0.0/PLAN.md

@@ -0,0 +1,78 @@
+# optalph Roadmap
+
+## Done
+
+### v0.1.0–v0.3.0: Core
+- SA/GA/memetic optimization with weighted scoring
+- IncrementalEvaluator (slot-based, snapshot undo, deep clone)
+- Extraction rules: Adjacent, SkipAdjacent, Compose
+- Annotated output, convergence plot, --save JSON
+- tqdm, DAWG optional, English alphabet, auto-detect
+
+### v0.4.0: Grid & Properties
+- GridRule(rows, cols) with 8-directional extraction
+- IncrementalGridEvaluator with _line_slots reverse mapping
+- _IncrementalBase Generic ABC (shared slot management)
+- 200 tests incl 14 hypothesis property tests
+- detect_alphabet() from dictionary file
+
+### v0.5.0: Benchmark-Driven Rewrite
+- **Removed** GA, memetic, adaptive cooling (benchmark-proven inferior)
+- **Fixed** critical tabu_set eviction bug (deque auto-evicts, set never shrunk → 100% saturation)
+- **Fixed** tabu aspiration criterion (global→current best, unblocks improving moves)
+- **Fixed** tabu clear on reheat (frozen search after plateau)
+- **Fixed** ILS seeding (all inner SA got same seed → zero diversity)
+- **Fixed** ILS budget division (each step got full budget → 11× overspend)
+- **Fixed** parallel SA pickle error (pass rules/dict/weights, not closure)
+- **Updated** defaults: T_start=100 (was 1000), cooling=0.9999 (was 0.9995)
+- Benchmark results (English 26-letter, 5 seeds):
+
+| Method | Mean Score | Time |
+|--------|-----------|------|
+| ILS(5) | 19.6 | 4.6s |
+| SA+tabu | 19.2 | 1.6s |
+| SA | 18.2 | 0.9s |
+
+## Next: v0.6.0 — Quality & Polish
+
+### Smart initialization
+- **Effort:** 2-3h
+- **What:** Greedy init — place frequent bigrams adjacent, then SA refines. Could also use letter-pair frequency from dictionary to seed the permutation.
+- **Why:** Random init wastes early SA iterations. Greedy start could 2-3× coverage.
+
+### Dictionary download on demand
+- **Effort:** 1-2h
+- **What:** `load_dictionary(download=True)` — fetch from GitHub URL on first use, cache in `~/.optalph/`. English from dwyl/english-words, Russian from built-in or URL.
+- **Why:** Package can't bundle 35MB data. Users need zero-config dictionary access.
+- **Dep:** `requests` or `urllib` for download
+
+### Better coverage metrics
+- **Effort:** ~1h
+- **What:** Show coverage as % of eligible words (not just raw count). Show "eligible" = words of matching length in dictionary. Show theoretical max (all positions filled).
+- **Why:** "28/25237 (0.1%)" looks bad but max is ~24 positions × words-per-position. Contextual metrics are more meaningful.
+
+## Next: v0.7.0 — Visibility & Distribution
+
+### GitHub repo + CI
+- **Effort:** 1h
+- **What:** Push to GitHub, add GitHub Actions (pytest + mypy + ruff), test coverage badge
+- **Why:** Home for the project, bug reports, PRs
+
+### PyPI publish
+- **Effort:** 30min
+- **What:** `uv publish`, proper classifiers, changelog
+- **Dep:** GitHub repo first
+
+### Streamlit web demo
+- **Effort:** 2-3h
+- **What:** Pick alphabet, choose rules, run SA, show annotated permutation + convergence plot
+- **Why:** ×10 visibility over CLI-only tool
+
+## Backlog
+
+- Result comparison mode (`--compare prev.json`)
+- Custom cooling schedule functions
+- Rich library for terminal output (table, progress, colored)
+- IncrementalEvaluator for SkipAdjacent (complex, low ROI)
+- REST API / HTTP endpoint
+- Word frequency integration with NLTK/norvig data

optalph-1.0.0/README.md

@@ -0,0 +1,208 @@
+# optalph
+
+**Optimize alphabet permutation to maximize dictionary word coverage.**
+
+[![CI](https://github.com/4bstr4ct/optalph/actions/workflows/ci.yml/badge.svg)](https://github.com/4bstr4ct/optalph/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/optalph)](https://pypi.org/project/optalph/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Supports Russian and English alphabets (auto-detected from dictionary), incremental evaluation, 2D grid extraction (Boggle-like), weighted scoring, and parallel multistart.
+
+Requires Python >= 3.10.
+
+## Install
+
+```bash
+pip install optalph
+```
+
+Or with [pipx](https://pypa.github.io/pipx/) (recommended for CLI tools):
+
+```bash
+pipx install optalph
+```
+
+### Optional dependencies
+
+```bash
+# Progress bar
+pip install optalph[tqdm]
+
+# Russian DAWG dictionary (fast, 1.5M word forms)
+pip install optalph[dawg]
+```
+
+## Quick Start
+
+```bash
+# Easiest: download English dictionary automatically
+optalph --download english -w 3 4 5 --iter 500000
+
+# Russian with DAWG dictionary
+optalph -w 3 4 5
+
+# Custom dictionary file
+optalph -w 3 4 5 --dict-file words.txt --no-dawg
+
+# Weighted scoring (frequency file: "word count" per line)
+optalph -w 3 4 5 --freq-file freqs.txt --dict-file words.txt --no-dawg
+
+# 2D Boggle-like grid
+optalph --grid-rows 4 --grid-cols 8 --dict-file words.txt --no-dawg
+```
+
+Alphabet is auto-detected from the dictionary. Use `--alphabet` to override.
+
+### Dictionary Sources
+
+- **`--download english`**: Downloads and caches ~370k English words in `~/.optalph/`
+- **`--download russian`**: Downloads and caches Russian words in `~/.optalph/`
+- **DAWG**: `pymorphy2-dicts-ru` (install via `[dawg]` extra, provides 1.5M Russian word forms)
+- **Custom**: any UTF-8 text file, one word per line
+
+## Optimization Methods
+
+| Method | Flag | Description |
+|--------|------|-------------|
+| SA | `--method sa` (default) | Simulated annealing with tabu list option |
+| ILS | `--method ils` | Iterated local search — SA with perturbation restarts |
+| Multistart | `-r N` | N independent SA runs, best result wins |
+| Parallel | `-r N --parallel` | Multistart with ProcessPoolExecutor |
+
+### Key Parameters
+
+```bash
+--iter N          # Total iterations (default: 500000)
+--t-start T       # Starting temperature (default: 100)
+--cooling R       # Cooling rate (default: 0.9999)
+--tabu            # Enable tabu list (prevents cycling)
+--tabu-tenure N   # Tabu tenure (default: 20)
+--seed N          # Reproducible results
+--incremental     # Use incremental evaluator (faster for large alphabets)
+--ils-steps N     # ILS perturbation steps (default: 10)
+--ils-perturb N   # ILS perturbation strength (default: 3)
+```
+
+## Extraction Rules
+
+- **Adjacent(k)**: Contiguous k-character substrings (e.g. `-w 3` → all 3-letter substrings)
+- **SkipAdjacent(k, step)**: Every `step`-th character in a k-length window (`--skip k step`)
+- **GridRule(rows, cols)**: 2D grid, 8-directional word extraction (`--grid-rows --grid-cols`)
+- Multiple windows are composed: `-w 3 4 5` → Adjacent(3)+Adjacent(4)+Adjacent(5)
+
+## Example Results
+
+### English (26 letters, ~370k words)
+
+```
+$ optalph --download english -w 3 4 5 --iter 500000 --seed 42 --tabu
+
+Best score: 29/25237  (initial: 7, +22)
+Best permutation: jclownqkhumpfgridestabvxyz
+  jclownqkhumpfgridestabvxyz
+  ^^^ jcl
+   ^^^ clo
+   ^^^^ clow
+   ^^^^^ clown
+    ^^^ low
+    ^^^^ lown
+     ^^^ own
+  Words: jcl, clo, clow, clown, low, lown, own, khu, hum, hump, ump, ...
+```
+
+### Russian with weighted scoring (33 letters, ~1.5M forms)
+
+```
+$ optalph -w 3 4 5 --iter 500000 --seed 42 --freq-file ru_50k.txt --tabu
+
+Best score: 129.5  (initial: 12.3, +117.3)
+Best permutation: фбризъцшщёкгспалевыйдячьюхнэтомуж
+  Words: бри, бриз, риз, изъ, щёк, спа, спал, пал, лев, левы, левый, ...
+```
+
+## Library Usage
+
+```python
+from optalph import (
+    evaluate, evaluate_detailed, IncrementalEvaluator,
+    simulated_annealing, iterated_local_search, multistart_sa,
+    greedy_init, build_rules, RUSSIAN_ALPHABET, ENGLISH_ALPHABET,
+    load_dictionary, download_dictionary, load_frequencies,
+    OptimizerConfig, GridRule, IncrementalGridEvaluator,
+)
+
+# Download and load dictionary
+download_dictionary("english")
+dictionary = load_dictionary(download="english", use_dawg=False, min_len=3, max_len=5)
+
+# Build rules
+rules = build_rules(adjacent_windows=[3, 4, 5])
+
+# Evaluate
+score = evaluate(ENGLISH_ALPHABET, rules, dictionary)
+score, valid, invalid, breakdown = evaluate_detailed(ENGLISH_ALPHABET, rules, dictionary)
+
+# Greedy initialization (bigram frequencies → Hamiltonian path)
+initial = greedy_init(ENGLISH_ALPHABET, dictionary, window_sizes=[3, 4, 5])
+
+# SA optimization
+best, best_score, history, acc = simulated_annealing(
+    initial=initial,
+    score_fn=lambda p: evaluate(p, rules, dictionary),
+    config=OptimizerConfig(max_iterations=500000),
+)
+
+# Incremental evaluator (Adjacent rules only, O(1) per swap)
+incr = IncrementalEvaluator.from_rules(rules, dictionary, len(ENGLISH_ALPHABET))
+best, best_score, history, acc = simulated_annealing(
+    initial=initial, evaluator=incr,
+    config=OptimizerConfig(max_iterations=500000),
+)
+
+# ILS (SA + perturbation restarts)
+best, best_score, history, _ = iterated_local_search(
+    initial=initial, evaluator=incr,
+    config=OptimizerConfig(max_iterations=500000),
+    perturbation_strength=3, n_perturbations=5,
+)
+
+# Multistart (parallel)
+best, best_score, history, acc = multistart_sa(
+    ENGLISH_ALPHABET,
+    score_fn=lambda p: evaluate(p, rules, dictionary),
+    config=OptimizerConfig(max_iterations=100000),
+    n_restarts=4, parallel=True,
+    rules=rules, dictionary=dictionary,
+)
+
+# Weighted scoring
+weights = load_frequencies("freqs.txt")
+score = evaluate(ENGLISH_ALPHABET, rules, dictionary, weights=weights)
+```
+
+## Algorithm Details
+
+**Simulated Annealing** with:
+- Geometric cooling schedule (T *= cooling_rate)
+- Tabu list with aspiration criterion (override tabu if move improves current score)
+- Plateau detection with scaling limit (`max(1000, max_iterations/100)`) and decaying reheat
+- Greedy bigram initialization (+30% starting score over random)
+- Parallel multistart via ProcessPoolExecutor
+
+**Iterated Local Search**: SA → perturb (k random swaps) → SA → repeat. Budget divided equally across steps. Each step gets a unique random seed with recalculated cooling schedule.
+
+**Incremental evaluation**: O(1) per swap attempt (only affected slots re-evaluated) vs O(n) full evaluation. Supported for Adjacent and Grid rules.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run mypy src/optalph/
+uv run pytest -q
+```
+
+## License
+
+MIT

optalph-1.0.0/benchmark_results.csv

@@ -0,0 +1,41 @@
+method,config,seed,score,elapsed,iterations,acceptance_rate
+SA,{},42,18.0,0.9331065740007034,500000,0.52283955308961
+SA,{},43,19.0,0.9003044849996513,500000,0.516368255898544
+SA,{},44,18.0,0.909148651000578,500000,0.5180186538398897
+SA,{},45,18.0,0.9672747950007761,500000,0.5158579354824699
+SA,{},46,18.0,0.9556550019988208,500000,0.5199947882170274
+SA+tabu,{},42,19.0,1.6473954120010603,500000,0.2793829502690262
+SA+tabu,{},43,19.0,1.5804396199982875,500000,0.2910714859437751
+SA+tabu,{},44,20.0,1.5668150679994142,500000,0.28163005650563183
+SA+tabu,{},45,19.0,1.5041171130014845,500000,0.28891682513751865
+SA+tabu,{},46,19.0,1.7165438679985527,500000,0.25414203506567806
+SA+incr,{},42,18.0,1.2260328290012694,500000,0.52283955308961
+SA+incr,{},43,19.0,1.1446929390003788,500000,0.516368255898544
+SA+incr,{},44,18.0,1.2415487660000508,500000,0.5180186538398897
+SA+incr,{},45,18.0,1.2080060460011737,500000,0.5158579354824699
+SA+incr,{},46,18.0,1.1524075500001345,500000,0.5199947882170274
+ILS(3),{},42,18.0,3.393292286998985,500000,0.0
+ILS(3),{},43,19.0,3.529312396000023,500000,0.0
+ILS(3),{},44,20.0,3.638003642001422,500000,0.0
+ILS(3),{},45,20.0,3.622072569998636,500000,0.0
+ILS(3),{},46,19.0,3.5928619589994923,500000,0.0
+ILS(5),{},42,20.0,4.7638063819995295,500000,0.0
+ILS(5),{},43,19.0,4.665814296999088,500000,0.0
+ILS(5),{},44,20.0,4.5788373529994715,500000,0.0
+ILS(5),{},45,20.0,4.445144731000255,500000,0.0
+ILS(5),{},46,19.0,4.414251428999705,500000,0.0
+ILS(5)+incr,{},42,20.0,5.8953090720006,500000,0.0
+ILS(5)+incr,{},43,19.0,5.864872490999915,500000,0.0
+ILS(5)+incr,{},44,20.0,5.947618627000338,500000,0.0
+ILS(5)+incr,{},45,20.0,5.740321225999651,500000,0.0
+ILS(5)+incr,{},46,19.0,6.091732259999844,500000,0.0
+"MultiSA(4,seq)",{},42,19.0,3.2937221880001744,2000000,0.5198916383456932
+"MultiSA(4,seq)",{},43,18.0,3.3281649869986722,2000000,0.5206326887371198
+"MultiSA(4,seq)",{},44,18.0,3.495989789000305,2000000,0.520838988479788
+"MultiSA(4,seq)",{},45,19.0,3.4421152000013535,2000000,0.5206598334401025
+"MultiSA(4,seq)",{},46,20.0,3.4699412529989786,2000000,0.5196581939000423
+"MultiSA(4,par)",{},42,19.0,1.2119941180008027,2000000,0.5198916383456932
+"MultiSA(4,par)",{},43,18.0,1.0325349449994974,2000000,0.5206326887371198
+"MultiSA(4,par)",{},44,18.0,1.0071037489997252,2000000,0.520838988479788
+"MultiSA(4,par)",{},45,19.0,0.9964653509996424,2000000,0.5206598334401025
+"MultiSA(4,par)",{},46,20.0,1.0318838949988276,2000000,0.5196581939000423