ctrl-freak 0.1.0__tar.gz → 0.2.0__tar.gz

ctrl_freak-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: ctrl-freak
+Version: 0.2.0
+Summary: Pure-numpy genetic algorithm framework for single-objective (GA) and multi-objective (NSGA-II) optimization
+Keywords: genetic-algorithm,evolutionary-algorithm,optimization,multi-objective-optimization,nsga-ii,nsga2,pareto,numpy
+Author: Nicolas Lazaro
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=2.0
+Requires-Dist: joblib>=1.3.0
+Requires-Python: >=3.11
+Project-URL: Changelog, https://github.com/hydrosolutions/ctrl-freak/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://hydrosolutions.github.io/ctrl-freak/
+Project-URL: Homepage, https://github.com/hydrosolutions/ctrl-freak
+Project-URL: Issues, https://github.com/hydrosolutions/ctrl-freak/issues
+Project-URL: Repository, https://github.com/hydrosolutions/ctrl-freak
+Description-Content-Type: text/markdown
+
+# ctrl-freak
+
+[![PyPI](https://img.shields.io/pypi/v/ctrl-freak.svg)](https://pypi.org/project/ctrl-freak/)
+[![Python](https://img.shields.io/pypi/pyversions/ctrl-freak.svg)](https://pypi.org/project/ctrl-freak/)
+[![License](https://img.shields.io/pypi/l/ctrl-freak.svg)](LICENSE)
+
+An extensible genetic algorithm framework for single and multi-objective optimization, built on pure numpy.
+
+## Installation
+
+```bash
+uv add ctrl-freak
+```
+
+or:
+
+```bash
+pip install ctrl-freak
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from ctrl_freak import nsga2, ga
+
+# === Multi-Objective: NSGA-II ===
+def init(rng):
+    return rng.uniform(0, 1, size=5)
+
+def evaluate_multi(x):
+    f1 = x[0]
+    f2 = 1 - np.sqrt(x[0]) + x[1:]@x[1:]
+    return np.array([f1, f2])
+
+def crossover(p1, p2):
+    return (p1 + p2) / 2
+
+def mutate(x):
+    return np.clip(x + np.random.normal(0, 0.1, size=x.shape), 0, 1)
+
+result = nsga2(
+    init=init,
+    evaluate=evaluate_multi,
+    crossover=crossover,
+    mutate=mutate,
+    pop_size=100,
+    n_generations=50,
+    seed=42,
+)
+
+# Extract Pareto front
+pareto_front = result.pareto_front
+print(f"Found {len(pareto_front)} Pareto-optimal solutions")
+
+# === Single-Objective: Standard GA ===
+def evaluate_single(x):
+    return float(np.sum(x ** 2))  # Sphere function
+
+result = ga(
+    init=init,
+    evaluate=evaluate_single,
+    crossover=crossover,
+    mutate=mutate,
+    pop_size=100,
+    n_generations=100,
+    seed=42,
+)
+
+print(f"Best fitness: {result.best[1]:.6f}")
+```
+
+## Features
+
+- Single-objective optimization with `ga()`.
+- Multi-objective optimization with `nsga2()`.
+- Pluggable parent-selection and survival strategies.
+- Pure numpy primitives for Pareto dominance, non-dominated sorting, and crowding distance.
+- Parallel evaluation through `n_workers`.
+
+See the [full documentation](https://hydrosolutions.github.io/ctrl-freak/) for API details, user contracts, examples, and extension points.
+
+## Benchmarks
+
+ctrl-freak ships a validation benchmark suite that checks `ga()` and `nsga2()`
+against pymoo and DEAP on standard problems with known optima. With the genetic
+algorithm held identical across all three libraries (ported SBX, aligned mutation
+and selection, identical evaluation budget), ctrl-freak's results are statistically
+indistinguishable from both baselines on the single-objective error metrics (all
+six functions) and on multi-objective convergence (ZDT1, ZDT2, ZDT3, and DTLZ2). On
+the two hardest problems (ZDT4, ZDT6) none of the three libraries converges at this
+budget, and ctrl-freak is at least as good as both. The goal is parity, not
+superiority.
+
+See the canonical report in [benchmarks/README.md](benchmarks/README.md) and the
+citable [Validation page](https://hydrosolutions.github.io/ctrl-freak/validation/).
+
+## Links
+
+- [Documentation](https://hydrosolutions.github.io/ctrl-freak/)
+- [Changelog](CHANGELOG.md)
+- [License](LICENSE)

ctrl_freak-0.2.0/README.md

@@ -0,0 +1,102 @@
+# ctrl-freak
+
+[![PyPI](https://img.shields.io/pypi/v/ctrl-freak.svg)](https://pypi.org/project/ctrl-freak/)
+[![Python](https://img.shields.io/pypi/pyversions/ctrl-freak.svg)](https://pypi.org/project/ctrl-freak/)
+[![License](https://img.shields.io/pypi/l/ctrl-freak.svg)](LICENSE)
+
+An extensible genetic algorithm framework for single and multi-objective optimization, built on pure numpy.
+
+## Installation
+
+```bash
+uv add ctrl-freak
+```
+
+or:
+
+```bash
+pip install ctrl-freak
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from ctrl_freak import nsga2, ga
+
+# === Multi-Objective: NSGA-II ===
+def init(rng):
+    return rng.uniform(0, 1, size=5)
+
+def evaluate_multi(x):
+    f1 = x[0]
+    f2 = 1 - np.sqrt(x[0]) + x[1:]@x[1:]
+    return np.array([f1, f2])
+
+def crossover(p1, p2):
+    return (p1 + p2) / 2
+
+def mutate(x):
+    return np.clip(x + np.random.normal(0, 0.1, size=x.shape), 0, 1)
+
+result = nsga2(
+    init=init,
+    evaluate=evaluate_multi,
+    crossover=crossover,
+    mutate=mutate,
+    pop_size=100,
+    n_generations=50,
+    seed=42,
+)
+
+# Extract Pareto front
+pareto_front = result.pareto_front
+print(f"Found {len(pareto_front)} Pareto-optimal solutions")
+
+# === Single-Objective: Standard GA ===
+def evaluate_single(x):
+    return float(np.sum(x ** 2))  # Sphere function
+
+result = ga(
+    init=init,
+    evaluate=evaluate_single,
+    crossover=crossover,
+    mutate=mutate,
+    pop_size=100,
+    n_generations=100,
+    seed=42,
+)
+
+print(f"Best fitness: {result.best[1]:.6f}")
+```
+
+## Features
+
+- Single-objective optimization with `ga()`.
+- Multi-objective optimization with `nsga2()`.
+- Pluggable parent-selection and survival strategies.
+- Pure numpy primitives for Pareto dominance, non-dominated sorting, and crowding distance.
+- Parallel evaluation through `n_workers`.
+
+See the [full documentation](https://hydrosolutions.github.io/ctrl-freak/) for API details, user contracts, examples, and extension points.
+
+## Benchmarks
+
+ctrl-freak ships a validation benchmark suite that checks `ga()` and `nsga2()`
+against pymoo and DEAP on standard problems with known optima. With the genetic
+algorithm held identical across all three libraries (ported SBX, aligned mutation
+and selection, identical evaluation budget), ctrl-freak's results are statistically
+indistinguishable from both baselines on the single-objective error metrics (all
+six functions) and on multi-objective convergence (ZDT1, ZDT2, ZDT3, and DTLZ2). On
+the two hardest problems (ZDT4, ZDT6) none of the three libraries converges at this
+budget, and ctrl-freak is at least as good as both. The goal is parity, not
+superiority.
+
+See the canonical report in [benchmarks/README.md](benchmarks/README.md) and the
+citable [Validation page](https://hydrosolutions.github.io/ctrl-freak/validation/).
+
+## Links
+
+- [Documentation](https://hydrosolutions.github.io/ctrl-freak/)
+- [Changelog](CHANGELOG.md)
+- [License](LICENSE)

{ctrl_freak-0.1.0 → ctrl_freak-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrl-freak"
-version = "0.1.0"
+version = "0.2.0"
 description = "Pure-numpy genetic algorithm framework for single-objective (GA) and multi-objective (NSGA-II) optimization"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -49,6 +49,7 @@ build-backend = "uv_build"
 [dependency-groups]
 dev = [
     "deap>=1.4.3",
+    "matplotlib>=3.10.8",
     "pymoo>=0.6.1.6",
     "pytest>=8.3", # tests
     "pytest-cov>=6.2.1",
@@ -92,7 +93,7 @@ possibly-unresolved-reference = "warn"
 # Pytest
 # -----------------------
 [tool.pytest.ini_options]
-pythonpath = ["src"]
+pythonpath = ["src", "."]
 testpaths = ["tests"]
 python_files = ["test_*.py", "*_test.py"]
 python_classes = ["Test*"]

ctrl_freak-0.1.0/PKG-INFO

@@ -1,238 +0,0 @@
-Metadata-Version: 2.4
-Name: ctrl-freak
-Version: 0.1.0
-Summary: Pure-numpy genetic algorithm framework for single-objective (GA) and multi-objective (NSGA-II) optimization
-Keywords: genetic-algorithm,evolutionary-algorithm,optimization,multi-objective-optimization,nsga-ii,nsga2,pareto,numpy
-Author: Nicolas Lazaro
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Science/Research
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Scientific/Engineering :: Mathematics
-Classifier: Operating System :: OS Independent
-Requires-Dist: numpy>=2.0
-Requires-Dist: joblib>=1.3.0
-Requires-Python: >=3.11
-Project-URL: Changelog, https://github.com/hydrosolutions/ctrl-freak/blob/main/CHANGELOG.md
-Project-URL: Documentation, https://hydrosolutions.github.io/ctrl-freak/
-Project-URL: Homepage, https://github.com/hydrosolutions/ctrl-freak
-Project-URL: Issues, https://github.com/hydrosolutions/ctrl-freak/issues
-Project-URL: Repository, https://github.com/hydrosolutions/ctrl-freak
-Description-Content-Type: text/markdown
-
-# ctrl-freak
-
-An extensible genetic algorithm framework for single and multi-objective optimization, built on pure numpy.
-
-## Maintenance Status
-
-🟢 **Active Development**
-
-This repository is part of an ongoing project and actively maintained.
-
----
-
-## Installation
-
-```bash
-uv add ctrl-freak
-```
-
-## Quick Start
-
-```python
-import numpy as np
-from ctrl_freak import nsga2, ga
-
-# === Multi-Objective: NSGA-II ===
-def init(rng):
-    return rng.uniform(0, 1, size=5)
-
-def evaluate_multi(x):
-    f1 = x[0]
-    f2 = 1 - np.sqrt(x[0]) + x[1:]@x[1:]
-    return np.array([f1, f2])
-
-def crossover(p1, p2):
-    return (p1 + p2) / 2
-
-def mutate(x):
-    return np.clip(x + np.random.normal(0, 0.1, size=x.shape), 0, 1)
-
-result = nsga2(
-    init=init,
-    evaluate=evaluate_multi,
-    crossover=crossover,
-    mutate=mutate,
-    pop_size=100,
-    n_generations=50,
-    seed=42,
-)
-
-# Extract Pareto front
-pareto_front = result.pareto_front
-print(f"Found {len(pareto_front)} Pareto-optimal solutions")
-
-# === Single-Objective: Standard GA ===
-def evaluate_single(x):
-    return float(np.sum(x ** 2))  # Sphere function
-
-result = ga(
-    init=init,
-    evaluate=evaluate_single,
-    crossover=crossover,
-    mutate=mutate,
-    pop_size=100,
-    n_generations=100,
-    seed=42,
-)
-
-print(f"Best fitness: {result.best[1]:.6f}")
-```
-
-## Documentation
-
-- [API Usage Guide](docs/usage.md) — Installation, examples, working with results
-- [User Contracts](docs/contracts.md) — Function signatures and responsibilities
-
----
-
-## Design Philosophy
-
-- **Pure numpy** for performance
-- **Functional style** with immutable data structures
-- **User thinks about individuals**, framework handles vectorization via `lift()`
-- **Fail fast** with eager validation
-- **Domain agnostic** — framework handles selection pressure, user handles constraints/bounds
-- **Extensible** via pluggable selection and survival strategies
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  User Domain Layer                                          │
-│  init(), evaluate(), crossover(), mutate()                  │
-│  (per-individual, user-defined)                             │
-└─────────────────────────────────────────────────────────────┘
-                          │ lift()
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Algorithm Layer                                            │
-│  ┌─────────────┐    ┌─────────────┐                         │
-│  │   nsga2()   │    │    ga()     │                         │
-│  │ multi-obj   │    │ single-obj  │                         │
-│  └─────────────┘    └─────────────┘                         │
-│         │                  │                                │
-│         └────────┬─────────┘                                │
-│                  ▼                                          │
-│  ┌───────────────────────────────────────────────────────┐  │
-│  │  Pluggable Strategies                                 │  │
-│  │  Selection: crowded, tournament, roulette             │  │
-│  │  Survival: nsga2, truncation, elitist                 │  │
-│  └───────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Primitives (pure functions)                                │
-│  non_dominated_sort(), crowding_distance(), dominates()     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## API Reference
-
-### Algorithms
-
-```python
-# Multi-objective optimization
-nsga2(init, evaluate, crossover, mutate, pop_size, n_generations,
-      seed=None, callback=None, select='crowded', survive='nsga2',
-      n_workers=1) -> NSGA2Result
-
-# Single-objective optimization
-ga(init, evaluate, crossover, mutate, pop_size, n_generations,
-   seed=None, callback=None, select='tournament', survive='elitist',
-   n_workers=1) -> GAResult
-```
-
-### User Function Contracts
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `init` | `(rng) -> (n_vars,)` | Initialize one random individual |
-| `evaluate` | `(n_vars,) -> (n_obj,)` or `float` | Compute objectives (minimization) |
-| `crossover` | `(n_vars,), (n_vars,) -> (n_vars,)` | Combine two parents into one child |
-| `mutate` | `(n_vars,) -> (n_vars,)` | Perturb an individual |
-
-### Result Types
-
-**NSGA2Result** — Multi-objective optimization result:
-
-- `population: Population` — Final population
-- `rank: np.ndarray` — Pareto front ranks `(n,)` where 0 = optimal
-- `crowding_distance: np.ndarray` — Diversity measure `(n,)`
-- `pareto_front: Population` — Property returning rank-0 individuals
-- `generations: int` — Generations completed
-- `evaluations: int` — Total evaluations
-
-**GAResult** — Single-objective optimization result:
-
-- `population: Population` — Final population
-- `fitness: np.ndarray` — Fitness values `(n,)`
-- `best: tuple[np.ndarray, float]` — Property returning (best_x, best_fitness)
-- `generations: int` — Generations completed
-- `evaluations: int` — Total evaluations
-
-### Data Structures
-
-**Population** — Immutable collection of solutions:
-
-- `x: np.ndarray` — Decision variables `(n, n_vars)`
-- `objectives: np.ndarray | None` — Objective values `(n, n_obj)`
-
-### Selection Strategies
-
-| Name | Function | Use Case |
-|------|----------|----------|
-| `'crowded'` | `crowded_tournament()` | NSGA-II (rank + crowding) |
-| `'tournament'` | `fitness_tournament()` | GA (fitness-based) |
-| `'roulette'` | `roulette_wheel()` | GA (fitness-proportionate) |
-
-### Survival Strategies
-
-| Name | Function | Use Case |
-|------|----------|----------|
-| `'nsga2'` | `nsga2_survival()` | NSGA-II (fronts + crowding) |
-| `'truncation'` | `truncation_survival()` | Keep best k |
-| `'elitist'` | `elitist_survival()` | Preserve elite parents |
-
-### Primitives
-
-| Function | Description |
-|----------|-------------|
-| `dominates(a, b)` | Check if `a` Pareto-dominates `b` |
-| `dominates_matrix(objectives)` | Pairwise dominance matrix |
-| `non_dominated_sort(objectives)` | Assign Pareto front ranks |
-| `crowding_distance(front)` | Compute crowding distances for one front |
-
----
-
-## Benchmarks
-
-Tested against Pymoo and DEAP on ZDT test problems (100 pop, 250 generations, 10 seeds):
-
-| Problem | ctrl-freak | Pymoo | DEAP |
-|---------|------------|-------|------|
-| ZDT1 | 0.8653 ± 0.0011 | 0.8241 ± 0.0255 | **0.8698 ± 0.0002** |
-| ZDT2 | 0.5320 ± 0.0017 | 0.4764 ± 0.0182 | **0.5363 ± 0.0002** |
-| ZDT3 | 1.3224 ± 0.0008 | 1.2836 ± 0.0123 | **1.3275 ± 0.0002** |
-
-ctrl-freak matches DEAP-level hypervolume on ZDT1-3 with low variance. See [full benchmark results](benchmarks/README.md).
-
----

ctrl_freak-0.1.0/README.md

@@ -1,210 +0,0 @@
-# ctrl-freak
-
-An extensible genetic algorithm framework for single and multi-objective optimization, built on pure numpy.
-
-## Maintenance Status
-
-🟢 **Active Development**
-
-This repository is part of an ongoing project and actively maintained.
-
----
-
-## Installation
-
-```bash
-uv add ctrl-freak
-```
-
-## Quick Start
-
-```python
-import numpy as np
-from ctrl_freak import nsga2, ga
-
-# === Multi-Objective: NSGA-II ===
-def init(rng):
-    return rng.uniform(0, 1, size=5)
-
-def evaluate_multi(x):
-    f1 = x[0]
-    f2 = 1 - np.sqrt(x[0]) + x[1:]@x[1:]
-    return np.array([f1, f2])
-
-def crossover(p1, p2):
-    return (p1 + p2) / 2
-
-def mutate(x):
-    return np.clip(x + np.random.normal(0, 0.1, size=x.shape), 0, 1)
-
-result = nsga2(
-    init=init,
-    evaluate=evaluate_multi,
-    crossover=crossover,
-    mutate=mutate,
-    pop_size=100,
-    n_generations=50,
-    seed=42,
-)
-
-# Extract Pareto front
-pareto_front = result.pareto_front
-print(f"Found {len(pareto_front)} Pareto-optimal solutions")
-
-# === Single-Objective: Standard GA ===
-def evaluate_single(x):
-    return float(np.sum(x ** 2))  # Sphere function
-
-result = ga(
-    init=init,
-    evaluate=evaluate_single,
-    crossover=crossover,
-    mutate=mutate,
-    pop_size=100,
-    n_generations=100,
-    seed=42,
-)
-
-print(f"Best fitness: {result.best[1]:.6f}")
-```
-
-## Documentation
-
-- [API Usage Guide](docs/usage.md) — Installation, examples, working with results
-- [User Contracts](docs/contracts.md) — Function signatures and responsibilities
-
----
-
-## Design Philosophy
-
-- **Pure numpy** for performance
-- **Functional style** with immutable data structures
-- **User thinks about individuals**, framework handles vectorization via `lift()`
-- **Fail fast** with eager validation
-- **Domain agnostic** — framework handles selection pressure, user handles constraints/bounds
-- **Extensible** via pluggable selection and survival strategies
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  User Domain Layer                                          │
-│  init(), evaluate(), crossover(), mutate()                  │
-│  (per-individual, user-defined)                             │
-└─────────────────────────────────────────────────────────────┘
-                          │ lift()
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Algorithm Layer                                            │
-│  ┌─────────────┐    ┌─────────────┐                         │
-│  │   nsga2()   │    │    ga()     │                         │
-│  │ multi-obj   │    │ single-obj  │                         │
-│  └─────────────┘    └─────────────┘                         │
-│         │                  │                                │
-│         └────────┬─────────┘                                │
-│                  ▼                                          │
-│  ┌───────────────────────────────────────────────────────┐  │
-│  │  Pluggable Strategies                                 │  │
-│  │  Selection: crowded, tournament, roulette             │  │
-│  │  Survival: nsga2, truncation, elitist                 │  │
-│  └───────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-                          │
-                          ▼
-┌─────────────────────────────────────────────────────────────┐
-│  Primitives (pure functions)                                │
-│  non_dominated_sort(), crowding_distance(), dominates()     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-## API Reference
-
-### Algorithms
-
-```python
-# Multi-objective optimization
-nsga2(init, evaluate, crossover, mutate, pop_size, n_generations,
-      seed=None, callback=None, select='crowded', survive='nsga2',
-      n_workers=1) -> NSGA2Result
-
-# Single-objective optimization
-ga(init, evaluate, crossover, mutate, pop_size, n_generations,
-   seed=None, callback=None, select='tournament', survive='elitist',
-   n_workers=1) -> GAResult
-```
-
-### User Function Contracts
-
-| Function | Signature | Description |
-|----------|-----------|-------------|
-| `init` | `(rng) -> (n_vars,)` | Initialize one random individual |
-| `evaluate` | `(n_vars,) -> (n_obj,)` or `float` | Compute objectives (minimization) |
-| `crossover` | `(n_vars,), (n_vars,) -> (n_vars,)` | Combine two parents into one child |
-| `mutate` | `(n_vars,) -> (n_vars,)` | Perturb an individual |
-
-### Result Types
-
-**NSGA2Result** — Multi-objective optimization result:
-
-- `population: Population` — Final population
-- `rank: np.ndarray` — Pareto front ranks `(n,)` where 0 = optimal
-- `crowding_distance: np.ndarray` — Diversity measure `(n,)`
-- `pareto_front: Population` — Property returning rank-0 individuals
-- `generations: int` — Generations completed
-- `evaluations: int` — Total evaluations
-
-**GAResult** — Single-objective optimization result:
-
-- `population: Population` — Final population
-- `fitness: np.ndarray` — Fitness values `(n,)`
-- `best: tuple[np.ndarray, float]` — Property returning (best_x, best_fitness)
-- `generations: int` — Generations completed
-- `evaluations: int` — Total evaluations
-
-### Data Structures
-
-**Population** — Immutable collection of solutions:
-
-- `x: np.ndarray` — Decision variables `(n, n_vars)`
-- `objectives: np.ndarray | None` — Objective values `(n, n_obj)`
-
-### Selection Strategies
-
-| Name | Function | Use Case |
-|------|----------|----------|
-| `'crowded'` | `crowded_tournament()` | NSGA-II (rank + crowding) |
-| `'tournament'` | `fitness_tournament()` | GA (fitness-based) |
-| `'roulette'` | `roulette_wheel()` | GA (fitness-proportionate) |
-
-### Survival Strategies
-
-| Name | Function | Use Case |
-|------|----------|----------|
-| `'nsga2'` | `nsga2_survival()` | NSGA-II (fronts + crowding) |
-| `'truncation'` | `truncation_survival()` | Keep best k |
-| `'elitist'` | `elitist_survival()` | Preserve elite parents |
-
-### Primitives
-
-| Function | Description |
-|----------|-------------|
-| `dominates(a, b)` | Check if `a` Pareto-dominates `b` |
-| `dominates_matrix(objectives)` | Pairwise dominance matrix |
-| `non_dominated_sort(objectives)` | Assign Pareto front ranks |
-| `crowding_distance(front)` | Compute crowding distances for one front |
-
----
-
-## Benchmarks
-
-Tested against Pymoo and DEAP on ZDT test problems (100 pop, 250 generations, 10 seeds):
-
-| Problem | ctrl-freak | Pymoo | DEAP |
-|---------|------------|-------|------|
-| ZDT1 | 0.8653 ± 0.0011 | 0.8241 ± 0.0255 | **0.8698 ± 0.0002** |
-| ZDT2 | 0.5320 ± 0.0017 | 0.4764 ± 0.0182 | **0.5363 ± 0.0002** |
-| ZDT3 | 1.3224 ± 0.0008 | 1.2836 ± 0.0123 | **1.3275 ± 0.0002** |
-
-ctrl-freak matches DEAP-level hypervolume on ZDT1-3 with low variance. See [full benchmark results](benchmarks/README.md).
-
----