Skip to content

fix(nsgaiii): select parents as configured, at random by default - #364

Merged
NicolasRodriguezUribe merged 4 commits into
mainfrom
fix/nsgaiii-random-selection
Nov 19, 2026
Merged

NicolasRodriguezUribe merged 4 commits into
mainfrom
fix/nsgaiii-random-selection

Conversation

@NicolasRodriguezUribe

@NicolasRodriguezUribe NicolasRodriguezUribe commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Item A9 of VAMOS-Studio's change requests (checked on 1.4.0): NSGA-III ignored its configured parent selection.
NSGAIIIConfig accepted any selection, nsgaiii/initialization.py mapped every method other than "tournament" to a
pressure of 2, and NSGAIII._generate_offspring always called kernel.tournament_selection(ranks, crowding, ...): a binary
tournament on rank and crowding distance, as NSGA-II. Crowding distance is not part of NSGA-III. ("random", {}) silently
ran that tournament, and so did the default ("tournament", {}), the command line (sized by --selection-pressure) and every
point of the NSGA-III tuning spaces (which offered only tournament_size). VAMOS's NSGA-III was therefore not the published
algorithm, and a comparison with jMetal's, Evolver's or pymoo's NSGA-III compared another algorithm.

Change

  • selection("random"), the new default (NSGAIIIConfig.default(), the command line, the tuning spaces): parents are
    drawn uniformly at random, as Deb and Jain (2014, Part I). With constraint values and feasibility first
    (constraint_mode="feasibility", no constraint_handling technique), each parent wins a binary tournament on the
    constraint violation, decided at random between two feasible (or equally violated) solutions: the mating selection of
    Jain and Deb's constrained NSGA-III (2014, Part II) and of pymoo's NSGA-III. With constraint_mode="none" or a
    constraint-handling technique, parents are drawn uniformly at random.
  • selection("tournament", size=k) is jMetal's NSGA-III tournament: k distinct candidates (2 by default), the lowest
    rank wins, ties at random. The ranks are the non-dominated fronts with feasible solutions first and infeasible ones
    compared by violation, or the technique's fronts. No crowding distance.
  • Any other method or option raises ConfigurationError (builder method, constructor, from_dict(), and a raw
    configuration mapping given to NSGAIII) instead of being mapped silently to a tournament. NSGAIIIConfig.builder()
    gets its own documented selection() method.
  • Command line: NSGA-III's default selection is random; --selection-pressure no longer sizes NSGA-III's parents and
    is no longer checked against an NSGA-III population. A selection in the nsgaiii block of a config file still sets a
    tournament and its size. The --selection-pressure help said it applied to "NSGA-II/III and SMS-EMOA"; it now names
    NSGA-II and IBEA (SMS-EMOA's command-line default has been random parents, and its builder never read the pressure).
  • Tuning spaces: the six NSGA-III spaces replace the unconditional tournament_size by selection: random (the
    default) or tournament with the conditional tournament_size in [2, 10], as Evolver's NSGAIIIDouble space
    (selection / selectionTournamentSize, exchanged by to_evolver/from_evolver). Evolver's space also offers
    Boltzmann, ranking and SUS, which VAMOS's NSGA-III does not run, so they are not offered. The bridge keeps building a
    tournament of the given size from an assignment of an earlier space (only tournament_size), so
    tests/engine/data/tuning_assignments_1_3_0.json still builds the configurations it built. nsgaiii_constrained
    grows from 60,480 to 120,960 discrete combinations, so, as agemoea_constrained, its exhaustive build moves to the slow
    tier and the fast tier samples it.
  • Internals: nsgaiii.helpers.nsgaiii_parents replaces nsgaiii_selection_metrics and computes what the configured
    selection needs at mating time (nothing for unconstrained random parents, so the extra non-dominated sort per generation
    is gone); NSGAIIIState loses its rank/crowding cache and gains selection_method; build_nsgaiii_algorithm loses its
    selection_pressure argument. All internal.
  • Snapshots, regenerated with their tools only: tools/update_parameter_spaces.py (the six NSGA-III spaces) and
    tools/generate_v1_compatibility_snapshots.py, which rewrote only the frozen value of NSGAIIIConfig.default()'s
    selection ("tournament" to "random"), as the scientific-corrections policy allows for the default of a stable
    configuration.
  • Docs (with **Development after 1.4.0:**): docs/algorithms/nsgaiii.md (tutorial code and the "Variants and their
    effect" section, with a table of the two selections; caption of the 1.0.0 illustration), docs/reference/algorithms.md
    ("Where the variants depart from their references": NSGA-III parents are no longer a departure; the Numba table),
    docs/reference/api/algorithms/nsgaiii.md, docs/topics/tuning.md, docs/guide/cli.md; examples/journeys/nsgaiii_dtlz2.py
    follows the tutorial. tests/reference/baselines.md has the re-measured reference values.

Checks against jMetal and pymoo

  • jMetal, main at 46fb0a61f (the reference VAMOS pins), jmetal-component/.../algorithm/multiobjective/NSGAIIIBuilder.java,
    defaultSelection: new NaryTournamentSelection<>(2, matingPoolSize, new MultiComparator<>(rank, densityEstimator::value))
    with a ReferencePointNicheDistanceEstimator. Its Javadoc says, and the code confirms, that the NSGA-III replacement
    writes its niche distances under other keys (NSGA3_NICHE_DISTANCE in NSGAIIIReplacement, while the estimator reads
    NICHE_DISTANCE), so value() is Double.MAX_VALUE for every solution and the tournament compares ranks only. The
    operator draws distinct candidates (ListUtils.randomSelectionWithoutReplacement) and findBestSolution keeps the
    first of equals, so ties are decided at random. selection("tournament") is this tournament. jmetal-algorithm's classic
    NSGAIII takes its selection from the builder; its NSGAIIIRunner passes BinaryTournamentSelection(RankingAndCrowdingDistanceComparator),
    but the classic algorithm never computes crowding distance (the estimator returns 0.0 for all), so it also compares ranks
    only. Evolver's BaseNSGAIII.createSelection uses jMetal's comparator (rank, then the uncomputed niche distance), its
    default configuration is --selection tournament --selectionTournamentSize 2, and its space offers tournament (size
    2..10), random, Boltzmann, ranking and SUS. Two small differences remain: jMetal's first mating sees no ranks (all -1),
    so it is uniformly random, while VAMOS ranks the initial population; and jMetal's CDP ranking compares two equally
    violated infeasible solutions by dominance, where VAMOS draws.
  • pymoo 0.6.2 (and 0.6.1.6), pymoo/algorithms/moo/nsga3.py: selection=TournamentSelection(func_comp=comp_by_cv_then_random),
    which compares the constraint violation when one of the two is infeasible and otherwise picks one at random: random
    parents on unconstrained problems, and the rule of selection("random") under constraints.
  • Measured (NumPy engine): tests/reference/test_external_conformance.py (NSGA-III on DTLZ2, 3 objectives, against
    pymoo 0.6.2 over 30 seeds) gives a VAMOS mean over seeds 0-9 of 0.7372 against pymoo's 0.7378 (0.08 %; 0.7385 with the
    old tournament; tolerance 3 %). test_dtlz_convergence (DTLZ2, 5,000 evaluations): seed 42 reaches 0.7122 (0.7192
    before; threshold 0.67), seeds 0-9 0.7029-0.7203. On ZDT4 (default configuration, 100 individuals, 25,000 evaluations,
    seeds 0-9, reference point (1.1, 1.1)) the mean hypervolume goes from 0.8631 (sd 0.0045) on origin/main to 0.8356 (sd
    0.0247): the crowding tournament's pressure towards the ends of the front is what made VAMOS's NSGA-III beat jMetal's
    and jMetalPy's on ZDT4 in the studio's calibration study.

Compatibility

  • Changes NSGA-III's results, by default and otherwise (a scientific correction, see
    docs/project/stability-and-versioning.md#scientific-corrections): default runs now select parents at random, and a
    configured ("tournament", ...) now compares ranks only. Every NSGA-III run gives other results than 1.4.0 with the same
    seed (Python API, command line, studies, tuning).
  • Stricter validation: NSGA-III selections other than random and tournament, and options other than a
    tournament's size, raise ConfigurationError; they used to run the crowding tournament silently.
  • Command line: --selection-pressure no longer applies to NSGA-III, so a pressure above an NSGA-III population no
    longer stops the run.
  • Tuning: the NSGA-III spaces gain selection (with tournament_size conditional on it), so seeded draws differ;
    assignments saved from earlier spaces keep building their configurations.
  • The frozen 1.0 snapshot records the new default of NSGAIIIConfig.default(). No public API, field, schema or CLI
    option is added or removed.

Validation

Windows 11, Python 3.12, PYTHONPATH anchored to this worktree.

Command Result
python -m pytest -q tests/engine/test_nsgaiii_selection.py (new: 31 tests) and the targeted set (test_nsgaiii_behavior, test_algorithm_encodings, test_algorithm_registry, test_algorithms_smoke, test_algorithm_problem_matrix, test_engine_trajectory_parity, test_constraint_handling_*, test_genealogy_tracking, tests/reference, tests/compatibility, tests/docs, test_cli_config_validation, run-artifact replay matrix) pass
pytest "tests/engine/test_operator_combo_validation.py::test_all_discrete_combos_build_config[nsgaiii_constrained_real]" (the exhaustive build, now slow tier) and its fast-tier sample 2 passed (27 s)
ruff check and ruff format --check on the changed Python pass
python tools/typecheck.py --scope strict 0 diagnostics, PASS
python tools/typecheck.py --scope full 0 diagnostics, ratchet new=0, increased=0, PASS
python -m compileall on the changed files; git diff --check pass
python tools/check_agent_docs.py pass
python tools/update_parameter_spaces.py --check; python tools/generate_v1_compatibility_snapshots.py --check current
pytest -m "not slow" -n 4 -p no:cacheprovider -rfE (CI fast tier) 10873 passed, 253 skipped, 9 xfailed, 1 failed: tests/experiment/test_cli_ablation.py::test_cli_ablation_runs_and_writes_variants, the known Windows failure under xdist (a study path over 260 characters), which also fails on untouched origin/main and passes alone
python tools/health.py All health checks passed
mkdocs build --strict pass
The first commit's tree on its own (NSGA-III, encodings, space defaults, 1.3.0 assignments, scientific defaults, compatibility, tutorials, CLI validation: 484 passed); the later commits are the validated final tree, up to the reference text of the last one pass
The merge with the current main (baec11a, #360, which merged cleanly) with the NSGA-III, archive, reference and compatibility tests 1248 passed, 18 skipped, 2 xfailed

The slow tier's other exhaustive combination builds were not run.

Changelog entry

[Unreleased] → Fixed

  • NSGA-III selects its parents as configured, and never by crowding distance, which is not part of NSGA-III. It ran a
    binary tournament on rank and crowding distance, as NSGA-II, whatever its selection, so it was not the published
    algorithm. selection("random"), now the default of NSGAIIIConfig.default(), the command line and the tuning spaces,
    draws parents at random, as Deb and Jain (2014); with constraints and feasibility first, each parent wins a binary
    tournament on the constraint violation, decided at random between feasible solutions, as Jain and Deb's constrained
    NSGA-III and pymoo. selection("tournament", size=k) is jMetal's NSGA-III tournament on rank, with ties drawn at random.
    Other selection methods and options raise ConfigurationError. The NSGA-III tuning spaces choose selection, random
    or tournament with tournament_size, as Evolver's, and assignments of earlier spaces still build their tournament;
    --selection-pressure no longer applies to NSGA-III. NSGA-III's results change, by default and with a tournament, so
    experiments run with NSGA-III should be rerun (fix(nsgaiii): select parents as configured, at random by default #364).

🤖 Generated with Claude Code

NSGA-III accepted any selection, but mapped every method but "tournament"
to a pressure of 2 and always mated by a binary tournament on rank and
crowding distance, as NSGA-II: crowding distance is not part of NSGA-III,
and neither the default nor ("random", {}) ran the published algorithm.

selection("random"), now NSGAIIIConfig.default()'s, draws the parents at
random, as Deb and Jain (2014). With constraint values and feasibility
first, each parent wins a binary tournament on the constraint violation,
drawn between feasible solutions, as Jain and Deb's constrained NSGA-III
and pymoo's comp_by_cv_then_random. selection("tournament", size=k) is
jMetal's NSGA-III tournament (NSGAIIIBuilder at 46fb0a61f): the lowest rank
of k distinct candidates wins, with ties drawn at random, since jMetal's
niche distance is never written. Other methods and options raise
ConfigurationError in the builder, the constructor and from_dict, and when
a configuration mapping reaches NSGAIII.

The NSGA-III tuning spaces choose selection, random (the default) or
tournament with tournament_size, as Evolver's NSGAIIIDouble; an assignment
of an earlier space still builds its tournament. nsgaiii_constrained
passes 100 000 discrete combinations, so its exhaustive build moves to the
slow tier. The parameter-space snapshot and the frozen default of
NSGAIIIConfig are regenerated with their tools.

NSGA-III's results change, by default and with a tournament (a scientific
correction).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The command line built NSGA-III with a tournament sized by
--selection-pressure, unlike NSGAIIIConfig.default(). It now selects the
parents at random, and a selection in the nsgaiii block of a config file
still sets a tournament. --selection-pressure no longer applies to NSGA-III
nor is checked against its population; its help names NSGA-II and IBEA,
the algorithms whose default tournament it sizes (SMS-EMOA's command line
never read it).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The DTLZ2 baseline and the conformance with pymoo already configured
selection("random"), which now runs. Measured again: seed 42 reaches
0.7122 (seeds 0 to 9, 0.7029 to 0.7203; threshold 0.67), and the mean over
seeds 0 to 9 is 0.7372 against pymoo's 0.7378 (0.08 %).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-19T00:05:39.149466Z 1e5987d PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

VAMOS documentation preview

https://pr-364-vamos-docs-preview.vamos-optimization.workers.dev

Built from b4a3bb1. Canonical metadata points to the production .org domain; the preview itself remains isolated.

@NicolasRodriguezUribe
NicolasRodriguezUribe added this pull request to the merge queue Nov 19, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 19, 2026
Keeps both notes of the NSGA-III API page: the selection of this branch and
the reference-direction files of #361.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@NicolasRodriguezUribe
NicolasRodriguezUribe added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit 5801139 Nov 19, 2026
15 checks passed
NicolasRodriguezUribe added a commit that referenced this pull request Nov 19, 2026
NSGAIIIConfig.__post_init__ keeps both checks: the reference-direction source
of this branch and the selection of #364.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
NicolasRodriguezUribe added a commit that referenced this pull request Nov 19, 2026
Brings #365's merge of main (NSGA-III selection of #364 and the other pull
requests since), so this branch no longer conflicts with main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant