[ahbaqdadi]

Summary

Add GeneticSearch, a meta-estimator for discrete hyperparameter spaces. It follows the existing search estimator API and uses tournament selection, uniform crossover, mutation, and elitism to evolve candidates. It avoids evaluating duplicate combinations, caps evaluations at the size of the search space, and supports setup, scoring results, prediction, and serialization.

Add focused tests, a benchmark, a reference guide, a tuning guide comparison, MkDocs navigation, and a changelog entry.

Validation

• vendor/bin/phpunit tests/Base/GeneticSearchTest.php --no-progress — 10 tests, 35 assertions
• composer test -- --no-progress — 2,150 tests, 51,343 assertions (38 skipped for optional extensions)
• vendor/bin/phpstan analyse -c phpstan.neon --memory-limit 1G --debug --no-progress — no errors
• composer check — clean
• One-iteration benchmark smoke run — passed

Replaces #526, which GitHub closed when the source branch was renamed from codex/genetic-search to genetic-search.

[Copilot]

🔵 Needs a closer look

Resource serialization validation and type-preserving candidate deduplication require correction.

No open issues 🎉

What changed in this PR

Adds GeneticSearch, a genetic algorithm-based hyperparameter optimizer for discrete search spaces, with tests, benchmarks, documentation, and integration updates.

Changes:

• Implements selection, crossover, mutation, elitism, scoring, and serialization.
• Adds focused tests and a benchmark.
• Updates tuning documentation, navigation, and changelog.

File	Description
tests/​Base/​GeneticSearchTest.php	Functional and validation tests
src/​GeneticSearch.php	Genetic hyperparameter search implementation
mkdocs.yml	Documentation navigation entry
docs/​hyper-parameter-tuning.md	Tuning strategy guidance
docs/​genetic-search.md	Reference documentation
CHANGELOG.md	Unreleased feature entry
benchmarks/​Base/​GeneticSearchBench.php	Performance benchmark

_{Review effort: Lite}

[andrewdalpino]

Very cool @ahbaqdadi! I see you have some experience with genetic algorithms - is this something you came up with yourself?

On the surface the PR looks good, nice and clean, and adheres well to the existing design. I'll take a closer look ASAP.

[ahbaqdadi]

Thanks, @andrewdalpino ! Yes, I have some prior experience with genetic algorithms, and I thought genetic search would be a nice addition to Rubix ML. I adapted the standard approach to fit the project's existing search APIs. I appreciate you taking a closer look, and I'll update the benchmark sizes you pointed out.

[andrewdalpino]

By any chance @ahbaqdadi is there any published literature about this specific technique or is it just a general application of tournament selection, uniform crossover, mutation, and elitism applied to hyper-parameter search?

[ahbaqdadi]

It’s a general application of established genetic algorithm operators to discrete hyperparameter search. I’m not claiming a new GA variant or implementing one particular paper. There is published work on GA-based parameter tuning, such as Huang and Wang (2006), and Ma et al. (2026) describe a similar combination of operators.

[andrewdalpino]

Nice, it's great to see classical machine learning is still alive in 2026!

https://www.mdpi.com/2076-3417/16/13/6734

Does your algorithm follow the one they describe in section 3.2.2? If not, could you describe it in pseudo code or plain English for me?

[ahbaqdadi]

Thanks, Andrew. I cited that paper as an example of the same standard operators, rather than as the specification for this implementation. In plain English, GeneticSearch starts with distinct random combinations from the finite parameter choices and scores them by cross-validation. For each new generation, it keeps the best candidates, selects parents through pairwise tournaments, mixes their parameter choices with uniform crossover, and may mutate each choice to another allowed value. It skips combinations already tried, stopping at the generation limit or when the search space is exhausted. Finally, it trains the best combination on the full dataset. The metric, validator, population size, and rates are configurable, so it does not use the paper’s fixed fraud detection settings.

[andrewdalpino]

Looks good @ahbaqdadi, just one comment about the compatibility() that I think can be improved.