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
2 changes: 2 additions & 0 deletions docs/algorithms/moead.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,6 +84,8 @@ For two objectives, `MOEADConfig.default(pop_size=100, n_obj=2, ...)` requests 9
- **Packaged weights:** with three or more objectives and a `pop_size` that no complete lattice matches, `MOEADConfig.default(pop_size=...)` and `optimize` use the weight file VAMOS packages for that size, as jMetal does (for example `W3D_100.dat`, so 100 individuals with three objectives work). In VAMOS 1.1.0 this failed with a lattice-size error.
- **Defaults:** the default DE crossover with PBI aggregation is a VAMOS choice; `aggregation("tchebycheff")` with the other defaults reproduces jMetal's MOEA/D-DE.

**Development after 1.4.0:** four objectives and 100 individuals run the packaged `W4D_100.dat`, which held its vectors twice and was skipped, so VAMOS 1.4.0 ran 84 individuals for any population from 100 to 119. Every packaged weight file now loads, also from the command line, and weight files may separate their components by whitespace or commas; see the [configuration reference](../reference/api/algorithms/moead.md).

**VAMOS 1.4.0:** MOEA/D gains the choices of Evolver's MOEA/D, with jMetal's definitions. Each is off by default, and a configuration without them runs as in 1.3.0:

| Choice | How to set it | Values |
Expand Down
4 changes: 3 additions & 1 deletion docs/algorithms/nsgaiii.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,9 @@ For each generation, NSGA-III combines parents and offspring, sorts candidates i
| Result mode | `population` returns all survivors; `non_dominated` filters the selected result source. |
| Budget | Cover initialization and report the exact number of evaluations, rather than assuming a whole number of generations. |

For explicit reference-direction files, each row must be non-negative, sum to one, have one column per objective and match the configured population count. Consult the [configuration reference](../reference/api/algorithms/nsgaiii.md) for the file option.
For explicit reference-direction files, each row must be non-negative, sum to one and have one column per objective, and the population needs at least one individual per row. Consult the [configuration reference](../reference/api/algorithms/nsgaiii.md) for the file option.

**Development after 1.4.0:** `reference_directions(path=...)` reads the file as MOEA/D reads its weight files, with whitespace or commas between the components, so jMetal's weight files, such as the `W3D_100.dat` that VAMOS ships, can be passed as they are; VAMOS 1.4.0 read comma-separated files only. A path that is not an existing file raises `ConfigurationError` when the run starts; VAMOS 1.4.0 generated the lattice instead and saved it at that path.

### Variants and their effect

Expand Down
21 changes: 21 additions & 0 deletions docs/reference/api/algorithms/moead.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,27 @@ lattice by about `1e-16`, so a tool that reads the file can drift from VAMOS wit
the same seed. `vamos tune` records the population a trial ran
when it differs from the sampled one (see [Tuning](../../../topics/tuning.md#populations-that-depend-on-the-number-of-objectives)).

**Development after 1.4.0:** every weight file that VAMOS ships loads, from
`optimize` and from the packaged directory that the command line passes as
`weight_vectors(path=...)`. Fourteen of the 31 did not:

- `W4D_100.dat` held its 100 vectors twice, as the jMetalPy file it comes from
(jMetal has no such file), so VAMOS skipped it, and MOEA/D with four
objectives and 100 to 119 individuals ran the 84 vectors of the next smaller
lattice; it now runs the file's 100 vectors, and the command line, which
failed, runs them too.
- `W4D_165.dat` is comma-separated in jMetal, whose own reader expects
whitespace; VAMOS ships it space-separated, and reads either separator in
every weight file.
- jMetal rounds its files: the rows of `W3D_500.dat` to `W3D_1200.dat` and of
`W5D_1000.dat` to `W5D_2500.dat` sum to one within `2e-6`, and `W3D_136.dat`
has components of `-5e-17`. A file's rows may now depart from the simplex by
`1e-5` (`1e-6` before), and a negative component within it reads as zero; the
rows are not renormalized, so a file that loaded before gives the same vectors.

With `optimize`, a complete lattice still comes before a packaged file of the
same size, and the populations of the other sizes are unchanged.

**VAMOS 1.4.0:** the options of Evolver's MOEA/D. Each is off by
default, so a configuration that leaves them out runs exactly as in VAMOS 1.3.0.

Expand Down
8 changes: 8 additions & 0 deletions docs/reference/api/algorithms/nsgaiii.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,14 @@ 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:** 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
`W3D_100.dat` failed), every row non-negative and summing to one within the
rounding of jMetal's files (`1e-5`). A path that is not an existing file raises
`ConfigurationError` when the run starts; VAMOS 1.4.0 generated the lattice
instead and saved it at that path.

::: vamos.algorithms.NSGAIIIConfig
options:
heading_level: 2
Expand Down
6 changes: 6 additions & 0 deletions docs/topics/tuning.md
Original file line number Diff line number Diff line change
Expand Up @@ -847,6 +847,12 @@ built. The `effective` record compares with that fixed population: with
`--pop-size 150` and three objectives, every MOEA/D trial records
`{"pop_size": 136}`.

**Development after 1.4.0:** with four objectives and a `pop_size` from 100
to 119, MOEA/D runs the 100 vectors of the packaged `W4D_100.dat`, which VAMOS
1.4.0 skipped because the file held them twice: it ran 84 individuals, the
lattice of six divisions. A saved assignment with such a population now builds
100 individuals; the other populations are unchanged.

`optuna` and `bohb_optuna` suggest parents before the parameters that depend on
them, whatever their declaration order, and record only active suggestions in
`trial.params`. `smac3` and `bohb` receive the dependencies as ConfigSpace
Expand Down
65 changes: 45 additions & 20 deletions src/vamos/engine/algorithm/components/weight_vectors.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,31 @@
import numpy as np

from vamos.engine.reference_directions import FloatArray, das_dennis, largest_lattice_divisions, lattice_size
from vamos.foundation.exceptions import ConfigurationError

# How far a weight file may depart from the simplex through rounding: jMetal's files round each component, so
# their rows sum to 1 only within about 2e-6, and a few components that should be zero are about -5e-17.
_ROUNDING_TOLERANCE = 1e-5


def read_weight_vectors(path: str, n_obj: int) -> FloatArray:
"""Read the weight vectors of a file, one per line, with ``n_obj`` components each.

The components are separated by whitespace or by commas: jMetal's weight files use spaces, except
``W4D_165.dat``, and NSGA-III's reference-direction files have been comma-separated. Every component
must be non-negative and every row must sum to 1, both within the rounding of jMetal's files (1e-5);
a negative component within that rounding reads as 0. The rows are returned as they are, not
renormalized. A path that is not a file raises :class:`~vamos.exceptions.ConfigurationError`.

**Development after 1.4.0:** commas and whitespace in every file, and the rounding tolerance of 1e-5
(1e-6 before, without the negative rounding).
"""
if not os.path.isfile(path):
raise ConfigurationError(
f"Weight vector file '{path}' does not exist or is not a file.",
suggestion="Pass the path of an existing file, one weight vector per line.",
)
return _validated_weights(_load_weights(path), n_obj)


def load_or_generate_weight_vectors(
Expand All @@ -17,8 +42,9 @@ def load_or_generate_weight_vectors(
mode: str = "auto",
) -> FloatArray:
"""
Load weight vectors from CSV if available, otherwise generate a simplex-lattice
design and persist it when a path is provided.
Load weight vectors from a file if available, otherwise generate a simplex-lattice
design and persist it when a path is provided. Files are read by
:func:`read_weight_vectors`, with whitespace or commas between the components.

mode="auto" generates the complete Das-Dennis lattice: with ``divisions``, all of
its vectors; without, the largest lattice with at most ``pop_size`` vectors. The
Expand All @@ -32,8 +58,7 @@ def load_or_generate_weight_vectors(
if mode == "jmetalpy":
return _load_or_generate_jmetalpy_weights(pop_size, n_obj, path, divisions)
if path and os.path.exists(path):
weights = _load_weights(path, delimiter=",")
_assert_valid_weights(weights, n_obj)
weights = read_weight_vectors(path, n_obj)
if weights.shape[0] != pop_size:
raise ValueError(
f"Weight file '{path}' contains {weights.shape[0]} vectors but pop_size={pop_size} requires exactly that many."
Expand All @@ -49,13 +74,12 @@ def load_or_generate_weight_vectors(
return weights


def _load_weights(path: str, delimiter: str | None = ",") -> FloatArray:
if delimiter is None:
arr = np.loadtxt(path)
else:
arr = np.loadtxt(path, delimiter=delimiter)
arr = np.atleast_2d(arr).astype(float, copy=False)
return arr
def _load_weights(path: str) -> FloatArray:
"""The rows of a weight file whose components are separated by whitespace or commas."""
with open(path, encoding="utf-8") as handle:
text = handle.read()
arr = np.loadtxt(io.StringIO(text.replace(",", " ")), ndmin=2)
return np.asarray(arr, dtype=float)


def _load_or_generate_jmetalpy_weights(pop_size: int, n_obj: int, path: str | None, divisions: int | None) -> FloatArray:
Expand All @@ -76,8 +100,7 @@ def _load_or_generate_jmetalpy_weights(pop_size: int, n_obj: int, path: str | No
if packaged is not None:
return packaged
if weight_path is not None and os.path.exists(weight_path):
weights = _load_weights(weight_path, delimiter=None)
_assert_valid_weights(weights, n_obj)
weights = read_weight_vectors(weight_path, n_obj)
if weights.shape[0] != pop_size:
raise ValueError(f"Expected {pop_size} weight vectors in '{weight_path}', got {weights.shape[0]}.")
return weights
Expand Down Expand Up @@ -212,11 +235,11 @@ def _packaged_weights(n_obj: int, pop_size: int) -> FloatArray | None:
path = weight_path(f"W{n_obj}D_{pop_size}.dat")
except ValueError:
return None
weights = _load_weights(str(path), delimiter=None)
weights = _load_weights(str(path))
if weights.shape != (pop_size, n_obj):
return None
weights = _validated_weights(weights, n_obj)
normalized: FloatArray = weights / weights.sum(axis=1, keepdims=True)
_assert_valid_weights(normalized, n_obj)
return normalized


Expand All @@ -229,17 +252,19 @@ def _resolve_jmetalpy_weight_path(path: str | None, n_obj: int, pop_size: int) -
return os.path.join(path, filename)


def _assert_valid_weights(weights: FloatArray, n_obj: int) -> None:
def _validated_weights(weights: FloatArray, n_obj: int) -> FloatArray:
"""``weights`` with the negative rounding of a zero component set to 0, or ``ValueError`` off the simplex."""
if weights.ndim != 2:
raise ValueError("Weight matrix must be 2D.")
if weights.shape[1] != n_obj:
raise ValueError(f"Expected weight vectors with {n_obj} columns, got {weights.shape[1]}.")
if np.any(weights < 0.0):
if not np.all(np.isfinite(weights)):
raise ValueError("Weight vectors must be finite.")
if np.any(weights < -_ROUNDING_TOLERANCE):
raise ValueError("Weight vectors must be non-negative.")
rows_sum = weights.sum(axis=1)
# Allow very small numerical drift
if np.any(np.abs(rows_sum - 1.0) > 1e-6):
if np.any(np.abs(weights.sum(axis=1) - 1.0) > _ROUNDING_TOLERANCE):
raise ValueError("Each weight vector must sum to 1.")
return np.asarray(np.maximum(weights, 0.0), dtype=float)


def _generate_weights(pop_size: int, n_obj: int, divisions: int | None, *, strict: bool = False) -> FloatArray:
Expand Down
11 changes: 11 additions & 0 deletions src/vamos/engine/algorithm/config/nsgaiii.py
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,17 @@ def reference_directions(
path: str | None = None,
divisions: int | None = None,
) -> _NSGAIIIConfigBuilder:
"""The reference directions: a file, or the complete Das-Dennis lattice of ``divisions``.

``path`` names a file with one direction per line, its components separated by whitespace or
by commas, such as jMetal's weight files (``W3D_100.dat``, which VAMOS ships). Without either,
NSGA-III runs the complete lattice with the most directions that fit in ``pop_size``. The
population needs at least one individual per direction.

**Development after 1.4.0:** the file may use whitespace as well as commas, and a ``path``
that is not a file raises :class:`~vamos.exceptions.ConfigurationError` when the run starts;
VAMOS 1.4.0 read commas only, and generated the lattice and saved it at a missing path.
"""
self._cfg["reference_directions"] = {"path": path, "divisions": divisions}
return self

Expand Down
21 changes: 7 additions & 14 deletions src/vamos/engine/algorithm/nsgaiii/initialization.py
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@

from __future__ import annotations

import os
from typing import TYPE_CHECKING, Any

import numpy as np
Expand All @@ -22,7 +21,7 @@
from vamos.engine.algorithm.components.population import initialize_evaluated_population
from vamos.engine.algorithm.components.termination import parse_termination, validate_initial_budget
from vamos.engine.algorithm.components.utils import resolve_bounds_array
from vamos.engine.algorithm.components.weight_vectors import load_or_generate_weight_vectors
from vamos.engine.algorithm.components.weight_vectors import load_or_generate_weight_vectors, read_weight_vectors
from vamos.engine.algorithm.config.base import normalize_constraint_mode
from vamos.engine.archive.factory import resolve_external_archive, setup_archive
from vamos.engine.operators.policies.nsgaiii import build_variation_operators
Expand Down Expand Up @@ -124,16 +123,10 @@ def initialize_nsgaiii_run(
dir_cfg = config.get("reference_directions", {}) or {}
ref_path = dir_cfg.get("path")
ref_divisions = dir_cfg.get("divisions")
if ref_path and os.path.exists(ref_path):
ref_dirs = np.loadtxt(ref_path, delimiter=",")
ref_dirs = np.atleast_2d(ref_dirs).astype(float, copy=False)
if ref_dirs.ndim != 2 or ref_dirs.shape[1] != n_obj:
raise ValueError("Reference directions file has invalid shape.")
if np.any(ref_dirs < 0.0):
raise ValueError("Reference directions must be non-negative.")
row_sums = ref_dirs.sum(axis=1)
if np.any(np.abs(row_sums - 1.0) > 1e-6):
raise ValueError("Each reference direction must sum to 1.")
if ref_path:
# Development after 1.4.0: the file is read as MOEA/D reads its weights, with whitespace or commas
# between the components, and a path that is not a file raises instead of generating a lattice there.
ref_dirs = read_weight_vectors(str(ref_path), n_obj)
source = f"NSGA-III reference directions in '{ref_path}' ({ref_dirs.shape[0]})"
elif ref_divisions is not None:
source = f"NSGA-III reference directions for divisions={ref_divisions}"
Expand All @@ -145,14 +138,14 @@ def initialize_nsgaiii_run(
f"{source} ({n_directions}) need pop_size >= {n_directions} (pop_size={pop_size}). "
"Increase pop_size or choose fewer reference directions."
)
ref_dirs = load_or_generate_weight_vectors(pop_size, n_obj, path=ref_path, divisions=ref_divisions)
ref_dirs = load_or_generate_weight_vectors(pop_size, n_obj, divisions=ref_divisions)
source = f"{source} ({ref_dirs.shape[0]})"
else:
if n_obj >= 2 and pop_size < n_obj:
raise ValueError(
f"NSGA-III needs pop_size >= n_obj={n_obj} for its smallest reference-direction lattice (pop_size={pop_size})."
)
ref_dirs = load_or_generate_weight_vectors(pop_size, n_obj, path=ref_path, divisions=None)
ref_dirs = load_or_generate_weight_vectors(pop_size, n_obj, divisions=None)
source = f"NSGA-III reference directions ({ref_dirs.shape[0]})"
if ref_dirs.shape[0] > pop_size:
raise ValueError(
Expand Down
Loading
Loading