Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions docs/algorithms/nsgaiii.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ config = (
.pop_size(pop_size)
.crossover("sbx", prob=1.0, eta=30.0)
.mutation("pm", prob="1/n", eta=20.0)
.selection("tournament")
.selection("random")
.reference_directions(divisions=divisions)
.result_mode("population")
.build()
Expand Down Expand Up @@ -57,7 +57,7 @@ python examples/journeys/nsgaiii_dtlz2.py

![NSGA-III final population on three-objective DTLZ2, with a wireframe of the analytical positive unit-sphere Pareto surface.](../assets/algorithms/nsgaiii-dtlz2.svg)

*Actual run: VAMOS 1.0.0, NumPy, seed 42, 91 directions and solutions, 10,000 evaluations. The grey wireframe is analytical, not another optimization run.*
*Actual run: VAMOS 1.0.0, NumPy, seed 42, 91 directions and solutions, 10,000 evaluations. The grey wireframe is analytical, not another optimization run. **Development after 1.4.0:** VAMOS 1.0.0 chose the parents by a tournament on rank and crowding distance; the example now draws them at random (see [variants and their effect](#variants-and-their-effect)), so its final population differs from the illustration's.*

All three objectives are minimized. DTLZ2's analytical Pareto surface satisfies `f1² + f2² + f3² = 1` in the positive octant. The returned vectors approach this trade-off surface; a completed budget does not prove convergence or uniform coverage. The analytical wireframe is used only for interpretation.

Expand Down Expand Up @@ -90,9 +90,16 @@ For explicit reference-direction files, each row must be non-negative, sum to on

### Variants and their effect

Parents are chosen by binary tournament on non-dominated rank and crowding distance, with feasible solutions first when constraints are active, as in NSGA-II and in jMetal's NSGA-III example. Deb and Jain choose parents at random [1], and the constrained version compares constraint violation and picks at random among feasible solutions [2], as pymoo does. `selection("tournament", size=k)` sets the tournament size; NSGA-III reads no other selection setting.
**Development after 1.4.0:** parents are chosen as the configuration says, and never by crowding distance, which is not part of NSGA-III:

**VAMOS 1.2.0:** `constraint_handling` replaces the feasibility-first rule by another of jMetal's constraint-handling techniques, such as epsilon-constrained or stochastic ranking: its fronts take the place of the non-dominated ones in the survival and the tournament, and niching cuts the last front that survives. See [choose a constraint-handling technique](../reference/constraints.md#choose-a-constraint-handling-technique).
| Selection | Parents |
| --- | --- |
| `selection("random")` (the default) | Drawn at random, as Deb and Jain do [1]. With constraints and feasibility first, each parent wins a binary tournament on the constraint violation: feasible beats infeasible, the smaller violation wins, and a tie, such as two feasible solutions, is drawn. This is the mating selection of the constrained version [2] and of pymoo's NSGA-III. |
| `selection("tournament", size=k)` | jMetal's NSGA-III tournament: `k` distinct solutions (2 by default) drawn at random, of which the lowest non-dominated rank wins (feasible solutions first, then by violation), with ties drawn at random. jMetal's `NSGAIIIBuilder` compares the rank and then a niche distance that its replacement never writes, so its ties are drawn too. |

Any other method (`boltzmann`, `ranking`, `sus`, ...) or option raises `ConfigurationError`. VAMOS 1.4.0 and earlier chose parents by a binary tournament on rank and crowding distance, as NSGA-II, whatever the configured selection, `"random"` included. Every NSGA-III run therefore gives other results than with VAMOS 1.4.0 for the same seed. Crowding distance favours the ends of the fronts, a selection pressure that the published algorithm does not have: on ZDT4 with 100 individuals and 25,000 evaluations (seeds 0 to 9, reference point (1.1, 1.1)), the mean hypervolume of the default configuration goes from 0.863 to 0.836.

**VAMOS 1.2.0:** `constraint_handling` replaces the feasibility-first rule by another of jMetal's constraint-handling techniques, such as epsilon-constrained or stochastic ranking: its fronts take the place of the non-dominated ones in the survival and the tournament, and niching cuts the last front that survives. See [choose a constraint-handling technique](../reference/constraints.md#choose-a-constraint-handling-technique). **Development after 1.4.0:** with a technique, `selection("random")` draws the parents at random, and only `selection("tournament")` compares the technique's fronts.

Normalization estimates the nadir point from the hyperplane through the extreme points. When the hyperplane cannot be built, or an intercept lies beyond the worst point found so far in some objective, VAMOS uses the worst point of the first front for every objective, as pymoo up to 0.4 did. pymoo 0.6 replaces only the objectives whose intercept lies beyond the worst point. The paper does not fix this rule, so both are variants, but the normalization differs in those generations.

Expand Down
6 changes: 6 additions & 0 deletions docs/guide/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -340,6 +340,12 @@ negative `--seed`, a `--n-var` or `--n-obj` below 1, a different `--n-obj` or
population a problem runs with (after its `problems.<name>` overrides), and `--track-genealogy` with an algorithm that records no genealogy. It
warns about algorithm-specific flags that the selected algorithm ignores.

**Development after 1.4.0:** NSGA-III selects its parents at random, as
`NSGAIIIConfig.default()` does, and `--selection-pressure` no longer sizes a
tournament for it; a `selection` of `tournament` with its `size` in the
`nsgaiii` block of a config file runs jMetal's NSGA-III tournament (see
[NSGA-III](../algorithms/nsgaiii.md#variants-and-their-effect)).

**VAMOS 1.2.0:** `--track-genealogy` (or `track_genealogy` in a
config file) works with NSGA-II, MOEA/D, SMS-EMOA, NSGA-III, SPEA2, IBEA and
SMPSO; AGE-MOEA and RVEA record no genealogy, so the CLI rejects it with them
Expand Down
15 changes: 10 additions & 5 deletions docs/reference/algorithms.md
Original file line number Diff line number Diff line change
Expand Up @@ -217,10 +217,15 @@ name of Evolver's parameter (`agemoeaII` in Evolver).
These are declared VAMOS choices, not defects; report them when comparing with
published results or with another framework.

- **NSGA-III parents** are chosen by binary tournament on non-dominated rank
and crowding distance (feasibility first under constraints), as in NSGA-II
and in jMetal's NSGA-III example. Deb and Jain (2014) choose parents at
random. See [NSGA-III](../algorithms/nsgaiii.md#variants-and-their-effect).
- **NSGA-III parents:** **Development after 1.4.0:** no longer a departure.
They are drawn at random by default, as Deb and Jain (2014) and pymoo do
(under constraints, by a binary tournament on the violation, as Jain and
Deb's constrained NSGA-III), and `selection("tournament")` is jMetal's
NSGA-III tournament on rank. VAMOS 1.4.0 and earlier always chose them by a
binary tournament on non-dominated rank and crowding distance, as NSGA-II,
whatever the configured selection, so NSGA-III results of those versions
are not results of the published algorithm. See
[NSGA-III](../algorithms/nsgaiii.md#variants-and-their-effect).
- **NSGA-III nadir estimate:** when an intercept of the extreme-point
hyperplane lies beyond the worst point found so far, VAMOS uses the worst
point of the first front for every objective, as pymoo up to 0.4 did; pymoo
Expand Down Expand Up @@ -504,7 +509,7 @@ never compiles problem evaluation.
| Algorithm | Compiled with `engine="numba"` | Stays in NumPy/Python |
| --- | --- | --- |
| NSGA-II | Non-dominated ranking and crowding, survival, tournament selection, SBX, polynomial mutation; the whole one-offspring steady-state step in its supported configuration (below) | Feasibility ordering, archives, steady-state front maintenance outside that configuration |
| NSGA-III | Ranking and crowding, tournament selection, SBX, polynomial mutation | Normalization, association to reference directions, niching (it shuffles with the run generator inside the loop) |
| NSGA-III | Ranking and crowding, tournament selection (**Development after 1.4.0:** where configured, and the violation tournament of random parents under constraints), SBX, polynomial mutation | Random parent draws, normalization, association to reference directions, niching (it shuffles with the run generator inside the loop) |
| MOEA/D | Differential-evolution children, SBX, polynomial mutation, neighbourhood replacement; the whole one-offspring step (see below) | Weight geometry; parent sampling and repair outside the compiled one-offspring step |
| SMS-EMOA | The steady-state step (VAMOS 1.2.0, see below): child variation and clipping, front insertion, two-objective hypervolume contributions, crowding, feasibility-first removal; tournament selection where configured | Parent sampling draws, hypervolume contributions for three or more objectives (MooCore when installed), archives |
| SPEA2 | SBX, polynomial mutation, lexicographic archive truncation | Strength/raw fitness and density (vectorized NumPy) |
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/api/algorithms/nsgaiii.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ emits a `FutureWarning`; both fields are planned for removal in 2.0 (see
`NSGAIIIConfig.default()` does not warn. `mutation_prob_factor` now sets the
mutation probability to `factor / n_var`, as in NSGA-II.

**Development after 1.4.0:** `selection` is `("random", {})`, the default, or
`("tournament", {"size": k})`, and any other method or option raises
`ConfigurationError`; NSGA-III used to run a binary tournament on rank and
crowding distance whatever its selection. See
[variants and their effect](../../../algorithms/nsgaiii.md#variants-and-their-effect).

**Development after 1.4.0:** the file of `reference_directions(path=...)` is
read as MOEA/D's weight files: one direction per line, the components separated
by whitespace or by commas (VAMOS 1.4.0 read commas only, so jMetal's
Expand Down
12 changes: 12 additions & 0 deletions docs/topics/tuning.md
Original file line number Diff line number Diff line change
Expand Up @@ -415,6 +415,18 @@ offset of 0.1, so no assignment reproduced the default configuration; an
assignment without the new parameters still builds that tournament
configuration.

**Development after 1.4.0:** the NSGA-III spaces choose the mating selection,
`random` (the default, Deb and Jain's) or `tournament` (jMetal's NSGA-III
tournament on rank), with `tournament_size` in [2, 10] only for a tournament,
as Evolver's `NSGAIIIDouble` space does. Evolver's space also offers Boltzmann,
ranking and stochastic universal sampling selection, which VAMOS's NSGA-III does
not run. The spaces of VAMOS 1.4.0 offered only `tournament_size`, and NSGA-III
then ran a binary tournament on rank and crowding distance whatever its
selection, so no assignment ran the published algorithm; an assignment with
`tournament_size` and without `selection` still builds a tournament of that
size, which now compares ranks only (see
[NSGA-III](../algorithms/nsgaiii.md#variants-and-their-effect)).

**VAMOS 1.3.0:** the MOEA/D and SMS-EMOA spaces offer what
Evolver's `MOEADDouble` and `SMSEMOADouble` spaces offer, so that a
configuration tuned or published with Evolver is a point of them:
Expand Down
2 changes: 1 addition & 1 deletion examples/journeys/nsgaiii_dtlz2.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ def solve(*, divisions: int = 12, max_evaluations: int = 10_000, seed: int = 42)
.pop_size(pop_size)
.crossover("sbx", prob=1.0, eta=30.0)
.mutation("pm", prob="1/n", eta=20.0)
.selection("tournament")
.selection("random")
.reference_directions(divisions=divisions)
.result_mode("population")
.build()
Expand Down
5 changes: 3 additions & 2 deletions src/vamos/engine/algorithm/_builder_decomposition.py
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,6 @@ def build_nsgaiii_algorithm(
problem: ProblemProtocol,
pop_size: int,
nsgaiii_variation: dict[str, Any] | None,
selection_pressure: int,
track_genealogy: bool = False,
) -> tuple[NSGAIII, AlgorithmConfigProtocol]:
encoding = resolve_problem_encoding(problem)
Expand All @@ -100,10 +99,12 @@ def build_nsgaiii_algorithm(
builder.pop_size(pop_size)
apply_operator_config(builder, method_name="crossover", operator_cfg=var_cfg["crossover"], key="crossover")
apply_operator_config(builder, method_name="mutation", operator_cfg=var_cfg["mutation"], key="mutation")
# Development after 1.4.0: random parents, as NSGAIIIConfig.default(); --selection-pressure sized a
# tournament on rank and crowding distance, which is not NSGA-III's selection.
apply_operator_config(
builder,
method_name="selection",
operator_cfg=var_cfg.get("selection", ("tournament", {"size": selection_pressure})),
operator_cfg=var_cfg.get("selection", ("random", {})),
key="selection",
)
apply_optional_operator_config(
Expand Down
65 changes: 63 additions & 2 deletions src/vamos/engine/algorithm/config/nsgaiii.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,12 @@
from __future__ import annotations

from dataclasses import dataclass
from typing import Any
from typing import Any, Self

from vamos.engine.archive import ExternalArchiveConfig
from vamos.engine.reference_directions import lattice_size
from vamos.foundation.encoding import EncodingLike
from vamos.foundation.exceptions import ConfigurationError

from .base import (
ConstraintModeStr,
Expand Down Expand Up @@ -36,6 +37,43 @@

_REFERENCE_LATTICE_RULE = "since VAMOS 1.2.0, NSGA-III uses the largest reference-direction lattice that fits in pop_size and runs N >= H"

# Development after 1.4.0: NSGA-III's parent selections. "random" is Deb and Jain's (2014), the
# default; "tournament" is jMetal's NSGA-III tournament on rank, with ties decided at random.
NSGAIII_SELECTIONS = ("random", "tournament")


def nsgaiii_selection(selection: object) -> tuple[str, int]:
"""The method of NSGA-III's parent selection and its tournament size (2 for ``"random"``).

Development after 1.4.0: NSGA-III runs ``"random"`` and ``"tournament"`` (with an optional
``size``), and rejects any other method or option instead of running a tournament.

Raises
------
ConfigurationError
For a method other than ``"random"`` and ``"tournament"``, an option of ``"random"``, or an
option of ``"tournament"`` other than ``size``.
"""
if not (isinstance(selection, (tuple, list)) and len(selection) == 2 and isinstance(selection[0], str)):
raise ConfigurationError(f"NSGA-III selection must be a (method, options) pair; got {selection!r}.")
method, options = str(selection[0]).strip().lower(), selection[1]
if not isinstance(options, dict):
raise ConfigurationError(f"NSGA-III selection options must be a mapping; got {options!r}.")
if method not in NSGAIII_SELECTIONS:
raise ConfigurationError(
f"NSGA-III does not support selection {selection[0]!r}: its parent selection is 'random' "
"(Deb and Jain, 2014; the default) or 'tournament' (on rank, as jMetal's NSGA-III)."
)
allowed = {"size"} if method == "tournament" else set()
unexpected = sorted(set(options) - allowed)
if unexpected:
detail = "only 'size'" if allowed else "no options"
raise ConfigurationError(f"NSGA-III's {method} selection takes {detail}; got {', '.join(map(repr, unexpected))}.")
size = options.get("size", 2)
if isinstance(size, bool) or not isinstance(size, int) or size < 1:
raise ConfigurationError(f"NSGA-III's tournament size must be a positive integer; got {size!r}.")
return method, size


@dataclass(frozen=True)
class NSGAIIIConfig(_SerializableConfig):
Expand All @@ -59,6 +97,7 @@ class NSGAIIIConfig(_SerializableConfig):

def __post_init__(self) -> None:
super().__post_init__()
nsgaiii_selection(self.selection)
# ``enforce_ref_dirs`` is true in every default, so ``False`` warns wherever it comes from.
# ``pop_size_auto`` is true in ``default()`` and false otherwise: only the builder method can
# tell that a user set it.
Expand All @@ -76,6 +115,9 @@ def default(
"""
Create a default NSGA-III configuration.

Development after 1.4.0: parents are selected at random, as Deb and Jain (2014); the
default used to be a binary tournament on rank and crowding distance.

Parameters
----------
pop_size
Expand Down Expand Up @@ -106,7 +148,7 @@ def default(
.pop_size(pop_size)
.crossover(crossover[0], **crossover[1])
.mutation(mutation[0], **mutation[1])
.selection("tournament")
.selection("random")
.reference_directions(divisions=divisions)
)
# The stable default keeps ``pop_size_auto=True`` without the warning of the builder method.
Expand Down Expand Up @@ -140,6 +182,25 @@ class _NSGAIIIConfigBuilder(
cfg = NSGAIIIConfig.builder().pop_size(92).crossover("sbx", prob=1.0).build()
"""

def selection(self, method: str, **kwargs: Any) -> Self:
"""Parent selection: ``"random"`` or ``"tournament"`` (with an optional ``size``, 2 by default).

``"random"`` draws the parents at random, as Deb and Jain (2014). With constraint values and
feasibility first (``constraint_mode="feasibility"`` without ``constraint_handling``), each
parent wins a binary tournament on the constraint violation that is decided at random between
two feasible solutions, as the constrained NSGA-III of Jain and Deb (2014) and pymoo's NSGA-III.

``"tournament"`` takes ``size`` solutions at random and keeps the one of the lowest
non-dominated rank (feasible solutions first, then by violation, or the fronts of
``constraint_handling``), with ties decided at random: jMetal's NSGA-III tournament. It does not
use crowding distance.

Development after 1.4.0: other methods and options raise ``ConfigurationError``; before,
every method ran a binary tournament on rank and crowding distance.
"""
nsgaiii_selection((method, kwargs))
return super().selection(method, **kwargs)

def reference_directions(
self,
*,
Expand Down
1 change: 0 additions & 1 deletion src/vamos/engine/algorithm/factory.py
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,6 @@ def build_algorithm(
pop_size=pop_size,
nsgaiii_variation=variations.get("nsgaiii"),
track_genealogy=track_genealogy,
selection_pressure=selection_pressure,
),
"spea2": lambda: build_spea2_algorithm(
kernel=kernel,
Expand Down
3 changes: 2 additions & 1 deletion src/vamos/engine/algorithm/nsgaii/constrained_survival.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@
replacement the technique adapts to that union at the run's progress, the evaluations before the
offspring's over the budget, as jMetal's ``ConstraintHandlingReplacement`` does. VAMOS ranks the
population again for the tournaments, as it does with cdp; jMetal reuses the ranks of the replacement.
NSGA-III ranks its tournaments with :func:`technique_selection_metrics` too.
Development after 1.4.0: NSGA-III's tournament compares the technique's ranks only, without crowding
distance (``nsgaiii.helpers.nsgaiii_parents``).
"""

from __future__ import annotations
Expand Down
Loading