feat(topology-optimizer): add UCB parent selection to DC MAP-Elites

[janu000]

Summary

Adds configurable parent-selection policies for the DC MAP-Elites optimizer.

Previously, parents were sampled uniformly from occupied repertoire candidates.
This PR preserves that behavior as the default and adds cell-based selection
strategies that can use historical archive-survival feedback.

• Adds parent_selection_mode to BatchedMEParameters, retaining uniform as the default.
• Adds uniform-by-cell, exact UCB, batched UCB, snapshot UCB, exploitation, exploration, and greedy selection policies.
• Records per-cell parent selections and archive-survival successes; UCB rewards offspring that survive repertoire insertion.
• Threads selection feedback through mutation and crossover emissions.
• Adds a configurable parent-selection benchmark, epochwise repertoire snapshots, analysis utilities, and an interactive results notebook.
• Documents the benchmark workflow and removes rendered notebook outputs from version control.

Implementation Notes

UCB ranks occupied cells from empirical archive-survival rate plus an exploration bonus. The policy operates at cell level, then samples an occupied candidate from the selected cell.

The branch preserves previous behavior by default: parent_selection_mode="uniform".

Limitations

• Non-uniform parent selection currently requires distributed=false.
• The checked-in benchmark preset is a short smoke-study configuration: three modes (uniform, ucb_snapshot, greedy), two shared seeds, and five seconds per run. It should not be presented as evidence of final comparative performance.

Validation

uv run pytest \
  packages/topology_optimizer_pkg/tests/benchmark/test_parent_selection_study.py \
  packages/topology_optimizer_pkg/tests/benchmark/test_repertoire_analysis.py \
  packages/topology_optimizer_pkg/tests/dc/genetic_functions/test_initialization.py \
  packages/topology_optimizer_pkg/tests/dc/genetic_functions/test_scoring_functions.py \
  packages/topology_optimizer_pkg/tests/dc/repertoire/test_discrete_map_elites.py \
  packages/topology_optimizer_pkg/tests/dc/repertoire/test_discrete_me_repertoire.py \
  packages/topology_optimizer_pkg/tests/dc/test_ga_helpers.py \
  packages/topology_optimizer_pkg/tests/interfaces/messages/test_commands.py

[Copilot]

🟡 Changes recommended

The newly added benchmark documentation/examples contain incorrect “default” claims and an invalid python -m toop-engine-benchmark... invocation that will fail.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds configurable parent-selection policies (including UCB variants) to the DC MAP-Elites optimizer, with per-cell selection/survival telemetry, benchmark tooling, and supporting analysis utilities.

Changes:

• Introduces parent_selection_mode + UCB/exploit/explore/greedy strategies and threads selection feedback through emitter → repertoire insertion → state updates.
• Adds survival-feedback return type for repertoire insertion and uses it to attribute offspring survival back to selected parent cells.
• Adds a parent-selection benchmark runner, study orchestration, snapshot-based analysis utilities, and expanded test coverage.

File summaries

File	Description
uv.lock	Adds kaleido to the dev lockfile (for Plotly static export tooling).
pyproject.toml	Pins kaleido==0.2.1 in the dev dependency group.
.pre-commit-config.yaml	Limits notebook-cleaning hooks to the new parent-selection results notebook path.
docs/benchmark.md	Documents the parent-selection benchmark workflow, descriptor resolution, and artifacts.
toop-engine-benchmark/configs/parent_selection.yaml	Adds a smoke-study preset config for parent-selection benchmarking.
toop-engine-benchmark/benchmark_parent_selection.py	Adds a Hydra-driven benchmark entrypoint for running the parent-selection study.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/interfaces/messages/dc_params.py	Extends BatchedMEParameters with parent-selection configuration fields.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/repertoire/parent_selection.py	Adds the parent-selection policy implementations (uniform-by-candidate/cell, UCB variants, exploit/explore, greedy).
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/repertoire/discrete_me_repertoire.py	Adds RepertoireAddResult + survival feedback path for repertoire insertion and a genotype gather helper.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/repertoire/discrete_map_elites.py	Threads survival feedback into emitter state update via survived_mask and parent index extra scores.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/genetic_functions/scoring_functions.py	Improves emitter-state serialization for summary output.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/genetic_functions/initialization.py	Wires parent-selection configuration into GA initialization (and blocks non-uniform selection under distributed execution).
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/dc/ga_helpers.py	Adds parent-selection telemetry accumulation and a tracking emitter that records parent indices.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/benchmark/repertoire_analysis.py	Adds 2D projection + aggregation utilities for snapshot-based repertoire analysis.
packages/topology_optimizer_pkg/src/toop_engine_topology_optimizer/benchmark/parent_selection_study.py	Adds the benchmark study runner, preprocessing reuse, snapshot/trajectory recording, and manifest logic.
packages/topology_optimizer_pkg/tests/interfaces/messages/test_commands.py	Adds tests for parent-selection parameter parsing/validation and minor typing cleanup.
packages/topology_optimizer_pkg/tests/dc/test_ga_helpers.py	Adds extensive unit tests for telemetry + all parent-selection modes.
packages/topology_optimizer_pkg/tests/dc/repertoire/test_discrete_me_repertoire.py	Adds tests ensuring survival feedback is correct with/without cell depth.
packages/topology_optimizer_pkg/tests/dc/repertoire/test_discrete_map_elites.py	Adds tests for descriptor index mapping and minor unused-variable cleanup.
packages/topology_optimizer_pkg/tests/dc/genetic_functions/test_scoring_functions.py	Ensures summarize flow works with a non-uniform parent selector.
packages/topology_optimizer_pkg/tests/dc/genetic_functions/test_initialization.py	Adds tests for parent-selection wiring and distributed-mode rejection.
packages/topology_optimizer_pkg/tests/benchmark/test_repertoire_analysis.py	Adds unit tests for repertoire snapshot projection and aggregation.
packages/topology_optimizer_pkg/tests/benchmark/test_parent_selection_study.py	Adds end-to-end/unit tests for benchmark bookkeeping, manifests, and validation.

Review details

• Files reviewed: 23/24 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqube-mccs]

Quality Gate passed

Issues
1 New issue
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
80.2% Coverage on New Code
1.3% Duplication on New Code

See analysis details on SonarQube

[nicow-elia]

Hello Janus,
At first, thanks for the contribution. I would assume the main reason to add all these features is to speed up the DC optimization process. If this is the case, I would like to perform a study first to understand a bit better the runtime behaviour of different parent selection strategies and implications. This is a decent amount of code we will have to maintain and it should be well justified to bring this in. Furthermore, we will have to make a plan how this aligns with a tag-based rework that we plan for the near future.

[janu000]

Hello Janus, At first, thanks for the contribution. I would assume the main reason to add all these features is to speed up the DC optimization process. If this is the case, I would like to perform a study first to understand a bit better the runtime behaviour of different parent selection strategies and implications. This is a decent amount of code we will have to maintain and it should be well justified to bring this in. Furthermore, we will have to make a plan how this aligns with a tag-based rework that we plan for the near future.

Hi Nico, A study is exactly the next step we intended to perform. To support this, I created toop-engine-benchmark/benchmark_parent_selection.py for running benchmarks and notebooks/parent_selection_results.ipynb for analyzing the results.

So far, I have coordinated with @BenjPetr, and we agreed that opening this PR would be the easiest way to run the study on real grids. Since I do not have permission to create a dedicated branch in the repository, I opened the PR against main.

Perhabs it's best if you could change the target branch or create a dedicated branch for it?