Implement NSGA-III for many-objective optimization

[luishpmendes]

Summary

This PR adds an implementation of the NSGA-III many-objective evolutionary algorithm to pagmo2, following Deb and Jain (2014).

It supersedes #569 and continues the original work by @pmslavin. The implementation has been rebased onto the current master branch, completed, documented, and expanded with correctness fixes and comprehensive tests.

NSGA-III retains the non-dominated sorting mechanism of NSGA-II but replaces crowding-distance-based environmental selection with reference-direction association and niching, making it more suitable for problems with many objectives.

Main changes

• Add the public pagmo::nsga3 algorithm.
• Integrate NSGA-III into the pagmo2 build system and umbrella header.
• Add Das–Dennis reference-direction generation.
• Support both single-layer and two-layer reference-direction sets.
• Add reference-direction association and niching selection.
• Implement objective translation, extreme-point detection, intercept estimation, and normalization.
• Support continuous and mixed-integer box-bounded problems.
• Support pagmo batch fitness evaluators through set_bfe().
• Add configurable random mating, matching the original NSGA-III paper.
• Add optional NSGA-II-style binary-tournament mating.
• Add optional inter-generational memory for the ideal and extreme points.
• Add verbosity, logging, seed management, serialization, and algorithm metadata.
• Add Doxygen and Sphinx documentation.

Improvements over #569

This version addresses several correctness, robustness, and reproducibility issues present in the original draft:

• Rebased the implementation onto the current pagmo2 master.
• Moved NSGA-III implementation details and reference-point utilities into pagmo::detail.
• Corrected duplicate extreme-point detection to compare complete vectors with a numerical tolerance.
• Corrected fallback normalization to use maxima in the translated objective space.
• Replaced the original fragile linear-system solver with Gaussian elimination using partial pivoting and singularity detection.
• Added safeguards for zero, negative, and non-finite intercepts.
• Removed dependence on global random state.
• Routed all stochastic operations through the algorithm-local random engine.
• Corrected generation numbers in verbosity output and logs.
• Completed serialization of all behavior-affecting configuration and state, including the random engine and optional memory.
• Store retained extreme points in the original objective coordinates so they remain valid when the ideal point changes.
• Generate reference directions once per evolution rather than once per generation.
• Allow the population size to equal the number of reference directions, as required by the configurations presented in the original paper.
• Add overflow and excessive-allocation checks for reference-direction generation.
• Validate constructor arguments, problem properties, population size, and batch-evaluator output.
• Ensure repeated one-generation evolutions are reproducible with a single multi-generation evolution when the same state is preserved.

Reference directions

The implementation supports the Das–Dennis systematic construction:

[
H = \binom{M + p - 1}{p},
]

where (M) is the number of objectives and (p) is the number of divisions.

For problems with many objectives, the implementation also supports the two-layer construction described by Deb and Jain. This allows configurations such as:

Objectives	Outer divisions	Inner divisions	Directions	Population
3	12	0	91	92
5	6	0	210	212
8	3	2	156	156
10	3	2	275	276
15	2	1	135	136

Mating selection

The default behavior follows Section IV-F of the original paper and selects mating parents randomly.

An optional NSGA-II-style binary tournament based on non-domination rank and crowding distance is also available through the random_mating constructor argument. This alternative is documented as a deliberate deviation from the original algorithm.

Tests

Two test executables are added:

• tests/nsga3.cpp

  • reference-direction generation;
  • two-layer reference directions;
  • normalization and intercept calculation;
  • singular and degenerate normalization cases;
  • reference-direction association and niching;
  • deterministic random behavior;
  • logging and verbosity;
  • serialization and state preservation;
  • memory mode;
  • batch fitness evaluation;
  • constructor, problem, and population validation;
  • continuous and mixed-integer evolution.

• tests/nsga3_quality.cpp

  • fixed-seed quality regressions on DTLZ1, DTLZ2, and DTLZ4;
  • tests with 3, 5, and 8 objectives;
  • two-layer reference directions;
  • random and tournament mating;
  • population-size and evaluation-count invariants;
  • finite and bounded solutions;
  • non-dominated population fraction;
  • reference-direction coverage;
  • distance to the analytical Pareto front;
  • inverted generational distance;
  • seed reproducibility and sensitivity.

The quality-test thresholds are intentionally conservative and are intended to detect algorithmic regressions rather than small seed-dependent variations.

Scope

This PR is limited to the C++ pagmo2 implementation of standard NSGA-III.

The following are intentionally outside its scope:

• pygmo Python bindings;
• U-NSGA-III;
• externally supplied arbitrary reference directions;
• support for constrained or stochastic problems.

Python bindings can be addressed in a separate pygmo PR after the C++ API has been reviewed and accepted.

Reference

K. Deb and H. Jain, “An Evolutionary Many-Objective Optimization Algorithm Using Reference-Point-Based Nondominated Sorting Approach, Part I: Solving Problems With Box Constraints,” IEEE Transactions on Evolutionary Computation, vol. 18, no. 4, pp. 577–601, 2014.

DOI: 10.1109/TEVC.2013.2281535

[Copilot]

Pull request overview

This PR introduces NSGA-III as a new many-objective evolutionary algorithm in pagmo2, including its reference-direction machinery, normalization pipeline, build integration, documentation, and a comprehensive test suite.

Changes:

• Add the public pagmo::nsga3 algorithm implementation, including logging, serialization, optional memory mode, and optional batch fitness evaluation support.
• Add NSGA-III internals under pagmo::detail (reference-direction generation, association/niching, normalization utilities).
• Add extensive unit + quality regression tests, plus Sphinx/Doxygen documentation and CMake integration.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/nsga3.cpp	Adds a broad unit test suite for NSGA-III internals and algorithm behavior (reproducibility, selection, normalization, serialization, BFE).
tests/nsga3_quality.cpp	Adds deterministic quality/regression tests over DTLZ problems with bounds on convergence/spread metrics.
tests/CMakeLists.txt	Registers the new nsga3 and nsga3_quality test targets.
src/detail/reference_point.cpp	Implements reference-direction generation (Das–Dennis, two-layer), and reference-point association/niching utilities.
src/detail/nsga3_impl.cpp	Implements Gaussian elimination + normalization pipeline + NSGA-III environmental selection.
src/algorithms/nsga3.cpp	Implements the pagmo::nsga3 algorithm evolve loop (mating modes, BFE path, memory mode, logging, validation).
include/pagmo/pagmo.hpp	Exposes NSGA-III through the umbrella header.
include/pagmo/detail/reference_point.hpp	Declares reference-point data structure and reference-direction generation APIs (detail).
include/pagmo/detail/nsga3_impl.hpp	Declares NSGA-III detail utilities (normalization, selection, numeric helpers).
include/pagmo/algorithms/nsga3.hpp	Declares the public pagmo::nsga3 API and provides detailed Doxygen documentation.
doc/sphinx/docs/cpp/cpp_docs.rst	Adds NSGA-III to the Sphinx C++ algorithm index.
doc/sphinx/docs/cpp/algorithms/nsga3.rst	Adds a Sphinx page that hooks the Doxygen class docs for pagmo::nsga3.
CMakeLists.txt	Adds new NSGA-III source files to the library build.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.