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/rvea.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,8 @@ Evaluations: 400

**VAMOS 1.2.0:** RVEA and AGE-MOEA resolve `"1/n"` like the other algorithms, so `prob="1/n"` is equivalent to `1/12` here.

**Development after 1.4.0:** the population no longer has to be a lattice. `reference_vectors(path=...)` reads the vectors from a file, or from a directory of jMetal's `W{n_obj}D_{pop_size}.dat` files, as MOEA/D and NSGA-III do: with jMetal's `W3D_100.dat`, which VAMOS ships, RVEA runs 100 individuals with three objectives, from the same vectors as MOEA/D and NSGA-III given the same file. `reference_vectors(divisions=H1, inner_divisions=H2)` runs Deb and Jain's two-layer lattice, which gives usual population sizes with many objectives (156 with eight objectives, `H1 = 3` and `H2 = 2`). See [reference and weight vectors](../reference/algorithms.md#reference-and-weight-vectors).

## Interpret the result and its limits

Each `X` row aligns with the same `F` row. This lesson explicitly requests `population` mode, then computes the feasible non-dominated subset separately. All objectives are minimized. A non-dominated row is only non-dominated among the available rows; it need not be Pareto optimal. The retained [observations](../assets/coverage/observations.json) contain the actual arrays and configuration.
Expand Down
13 changes: 13 additions & 0 deletions docs/dev/run_artifact_contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,19 @@ derived from the configuration, so verification rebuilds it like the rest of
the resolved spec; a MOEA/D run stored before it does not match its
reconstruction and is not verified as exact.

**Development after 1.4.0:** MOEA/D's `weight_vectors` record also has the
`source` `two_layer`, with `divisions` and `inner_divisions`. An NSGA-III or
RVEA run whose configuration names a file or directory of vectors (`path` of
`reference_directions` or `reference_vectors`) records it in
`algorithm.resolution.reference_directions` or
`algorithm.resolution.reference_vectors`: `source` is `file`, `file` its name,
and for RVEA `vectors` is their number, the population (NSGA-III's file may
hold fewer directions than individuals; the run's `reference_directions` array
holds them). Runs without a path record nothing new, so their resolved specs,
and those of NSGA-III and RVEA runs stored by VAMOS 1.4.0, are unchanged.

**Development after 1.4.0:** the resolved configuration binds a vector file by content. When a run starts, the `path` of `weight_vectors`, `reference_directions` or `reference_vectors` becomes the file the run reads (a directory becomes its `W{n_obj}D_{pop_size}.dat`) and `sha256` the digest of its vectors; the run, and so exact replay, refuses a file whose vectors have another digest, before any evaluation. The `file` records above are rebuilt from those persisted values alone, never from the filesystem, so a run verifies where its file is absent. A MOEA/D record with `sha256` is `das_dennis` when the digest is that of the lattice of `pop_size` vectors. Runs stored without `sha256` keep the 1.4.0 description, which looks for the file.

## 6. Run manifest

The manifest requires:
Expand Down
15 changes: 15 additions & 0 deletions docs/guide/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -429,6 +429,21 @@ validated as in the Python configurations: an out-of-domain value in any
problem stops the command before any run, and fields that conflict with each
other stop it, with exit code 2, when the configuration is built.

**Development after 1.4.0:** RVEA's block takes `reference_vectors`, and
MOEA/D's `weight_vectors` and NSGA-III's `reference_directions` take
`inner_divisions` (see
[reference and weight vectors](../reference/algorithms.md#reference-and-weight-vectors)).
With a weight file, RVEA runs a population that is not a lattice:

```yaml
version: "1"
defaults:
algorithm: rvea
population_size: 100
rvea:
reference_vectors: weights/W3D_100.dat # a file, or a directory of jMetal's W<m>D_<n>.dat files
```

Fields that the config sets elsewhere are rejected:
- `pop_size` and `pop_size_auto`: use `population_size`;
- `offspring_size`: use `offspring_population_size`;
Expand Down
14 changes: 14 additions & 0 deletions docs/reference/algorithms.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,6 +314,20 @@ NSGA-III and RVEA require a population compatible with the configured reference

**VAMOS 1.2.0:** with `pop_size`, `NSGAIIIConfig.default()` uses the complete lattice with the most directions that fit in it, for any number of objectives (four divisions, 70 directions, for 100 individuals and five objectives, which used to fail with six divisions and 210 directions); `RVEAConfig.default()` uses the lattice of exactly `pop_size` vectors and otherwise fails at once naming the nearest valid sizes, such as 91 or 105 for three objectives. Without `pop_size`, both still use 12 divisions for three objectives and 6 for four or more.

### Reference and weight vectors

**Development after 1.4.0:** MOEA/D, NSGA-III and RVEA take their vectors from the same kind of option, as jMetal and Evolver configure them from the same weight files, so that the three algorithms can start from the same vectors: MOEA/D's `weight_vectors`, NSGA-III's `reference_directions` and RVEA's new `reference_vectors`, a mapping (or builder method) with these keys:

| Key | Vectors |
| --- | --- |
| `path` | A file with one vector per line, its components separated by whitespace or commas, or a directory with jMetal's `W{n_obj}D_{pop_size}.dat` files, such as the jMetal files VAMOS ships in `vamos/resources/weights`. A path that does not exist raises `ConfigurationError` before any evaluation; so does a directory without the file, for NSGA-III and RVEA. |
| `divisions` | The complete Das-Dennis lattice of that many divisions, `comb(H + m - 1, m - 1)` vectors with `m` objectives. RVEA's `n_partitions` is the same lattice. |
| `divisions` and `inner_divisions` | Deb and Jain's two-layer lattice: the boundary lattice of `divisions` and the lattice of `inner_divisions` shrunk by half towards the centre of the simplex (`w / 2 + 1 / (2 m)`, as pymoo's multi-layer directions and PlatEMO's `UniformPoint`), boundary rows first. With eight objectives, `divisions=3` and `inner_divisions=2` give 120 + 36 = 156 vectors. A single lattice of few divisions has every vector on the boundary of the simplex when the objectives are many. |

`inner_divisions` needs `divisions` and excludes `path`, and an unknown key raises `ConfigurationError`. A plain string is a `path`. The inside layer must add directions: layers that share one (two objectives with `divisions=4` and `inner_divisions=2`, whose three inside directions are on the boundary lattice) raise `ConfigurationError`, as a repeated vector is a niche that never gets its own individual; Deb and Jain's usual settings never do: when `inner_divisions` is smaller than the number of objectives `m`, every inside direction has a coordinate `1 / (2 m)`, which a boundary layer of fewer than `2 m` divisions does not have. The file or lattice is the population: MOEA/D and RVEA need exactly one individual per vector, NSGA-III at least one. MOEA/D keeps its other rules: with one or two objectives its weights are uniform unless `inner_divisions` is given, a directory without the file gets the lattice of exactly `pop_size` vectors and saves it there with a `RuntimeWarning` (jMetalPy's behaviour), and without options it runs the populations that [`moead_populations`](api/algorithms/moead.md#populations-with-weight-vectors) lists. Files may depart from the simplex by jMetal's rounding (`1e-5`) and are not renormalized.

The resolved spec of a run records where the vectors come from: MOEA/D always, in `algorithm.resolution.weight_vectors`, now also `{"source": "two_layer", "divisions": 3, "inner_divisions": 2, "vectors": 156}`; NSGA-III and RVEA when the configuration names a path, in `algorithm.resolution.reference_directions` (`{"source": "file", "file": "W3D_100.dat"}`) and `algorithm.resolution.reference_vectors` (with `"vectors"`, the population). Their lattices are already stated by the configuration, so a run without a path keeps the resolved spec, and the task id, of VAMOS 1.4.0, and runs and studies stored by 1.4.0 still verify and resume exactly. When a run starts, a `path` is bound to what the run reads: a directory becomes its `W{n_obj}D_{pop_size}.dat`, and `sha256` records the digest of the file's vectors (`sha256:` and the SHA-256 of their shape and float64 values, so a file rewritten with other separators keeps it). The resolved configuration holds both, the records come from it alone, so verification needs neither the file nor the machine it was on, and replay refuses, before any evaluation, a file whose vectors have changed instead of running another experiment. This binds MOEA/D's and NSGA-III's files too, which VAMOS 1.4.0 replayed with whatever the file held; a MOEA/D directory without the file, whose run generates the lattice, is not bound. A `sha256` given in a configuration pins the file in the same way.

### The command line and `optimize`

A top-level `vamos` run and `vamos.optimize` build a run separately, so with the
Expand Down
44 changes: 44 additions & 0 deletions docs/reference/api/algorithms/moead.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,26 @@ when it differs from the sampled one (see [Tuning](../../../topics/tuning.md#pop
With `optimize`, a complete lattice still comes before a packaged file of the
same size, and the populations of the other sizes are unchanged.

**Development after 1.4.0:** `weight_vectors(divisions=H1, inner_divisions=H2)`
runs Deb and Jain's two-layer lattice, the boundary lattice of `H1` divisions
and the lattice of `H2` shrunk by half towards the centre of the simplex, with
`comb(H1 + m - 1, m - 1) + comb(H2 + m - 1, m - 1)` vectors for `m` objectives:
156 with eight objectives, `H1 = 3` and `H2 = 2`, the size of jMetal's
`W8D_156.dat` (which stacks the two lattices without shrinking the inside one,
so it repeats the eight axes). A single lattice with many objectives has every
vector on the boundary of the simplex and grows fast (eight objectives: 120
vectors with 3 divisions, 330 with 4). The resolved spec records
`{"source": "two_layer", "divisions": 3, "inner_divisions": 2, "vectors": 156}`.
NSGA-III's `reference_directions` and RVEA's `reference_vectors` take the same
keys (see [reference and weight vectors](../../algorithms.md#reference-and-weight-vectors)).
A `weight_vectors(path=...)` that does not exist now raises `ConfigurationError`
when the run starts; VAMOS 1.4.0 created it as a directory and saved the
lattice there. A directory that exists but lacks the file still gets the
lattice, saved there with a `RuntimeWarning`. A run binds a weight file by content:
its resolved configuration records the file it read and the `sha256` of its
vectors, and replay refuses the file if they change (see
[reference and weight vectors](../../algorithms.md#reference-and-weight-vectors)).

**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 Expand Up @@ -133,3 +153,27 @@ Use `MOEADConfig.builder()` to obtain the fluent builder; do not import the priv
show_root_heading: false
show_root_full_path: false
show_source: false

## Populations with weight vectors

**Development after 1.4.0:** `moead_populations(n_obj, max_pop_size=1000)`
lists the populations that MOEA/D runs without weight options, as
`MOEADConfig.default(pop_size=...)` and `optimize` build them: every size from
2 with one or two objectives, and with more the sizes of the complete lattices
and of the packaged jMetal files. With four objectives up to 200 they are 4, 10,
20, 35, 56, 84, 100, 120 and 165; with six up to 300, 6, 21, 56, 126 and 252;
with eight up to 400, 8, 36, 120, 156 and 330. Other sizes need a file or a two-layer
lattice.

```python
from vamos.algorithms import moead_populations

print(moead_populations(4, max_pop_size=200)) # (4, 10, 20, 35, 56, 84, 100, 120, 165)
```

::: vamos.algorithms.moead_populations
options:
heading_level: 3
show_root_heading: true
show_root_full_path: false
show_source: false
12 changes: 12 additions & 0 deletions docs/reference/api/algorithms/nsgaiii.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,18 @@ 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.

**Development after 1.4.0:** `reference_directions` takes the keys of MOEA/D's
`weight_vectors` and RVEA's `reference_vectors` (see
[reference and weight vectors](../../algorithms.md#reference-and-weight-vectors)):
`path` may also name a directory, from which NSGA-III reads jMetal's
`W{n_obj}D_{pop_size}.dat` (a directory without it raises), and
`reference_directions(divisions=3, inner_divisions=2)` runs Deb and Jain's
two-layer lattice, 156 directions with eight objectives. The resolved spec of a
run with a path records the file in `algorithm.resolution.reference_directions`,
`{"source": "file", "file": "W3D_100.dat"}`; a run without one keeps the
resolved spec of VAMOS 1.4.0. Study planning still rejects a path, and checks
that `pop_size` covers a two-layer lattice.

::: vamos.algorithms.NSGAIIIConfig
options:
heading_level: 2
Expand Down
37 changes: 37 additions & 0 deletions docs/reference/api/algorithms/rvea.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,43 @@ from vamos.algorithms import RVEAConfig

[Configuration overview](index.md) · [Algorithm contracts](../../algorithms.md) · [Optimization](../optimization.md)

**Development after 1.4.0:** `reference_vectors` gives RVEA the reference
vectors of a file, a directory or a two-layer lattice, with the keys of MOEA/D's
`weight_vectors` and NSGA-III's `reference_directions` (see
[reference vectors](../../algorithms.md#reference-and-weight-vectors)), so that
the three algorithms can start from the same vectors, as jMetal and Evolver
configure them:

```python
from vamos import optimize
from vamos.algorithms import RVEAConfig

config = (
RVEAConfig.builder()
.pop_size(100)
.reference_vectors(path="weights/W3D_100.dat") # a copy of jMetal's file, which VAMOS also ships
.alpha(2.0)
.adapt_freq(0.1)
.crossover("sbx", prob=0.9, eta=30.0)
.mutation("pm", prob="1/n", eta=20.0)
.build()
)
result = optimize("dtlz2", algorithm="rvea", algorithm_config=config, max_evaluations=1000, seed=1)
```

RVEA keeps one individual per vector, so the file must hold `pop_size`
vectors; a directory is searched for `W{n_obj}D_{pop_size}.dat`, and a missing
or mismatching file raises before any evaluation. `n_partitions` is not used
with `reference_vectors`; the builder does not need it and records the
`divisions` (12 for a file). `reference_vectors(divisions=12)` runs the same
lattice as `n_partitions(12)`. `to_dict()` leaves the field out while it is
`None`, so a configuration without it keeps the resolved specification, and the
task id, of VAMOS 1.4.0. The resolved spec of a run with a file records it in
`algorithm.resolution.reference_vectors`, for example
`{"source": "file", "file": "W3D_100.dat", "vectors": 100}`. Study planning
rejects a path, as it does for NSGA-III, and checks that `pop_size` equals the
vectors of `divisions` and `inner_divisions`.

::: vamos.algorithms.RVEAConfig
options:
heading_level: 2
Expand Down
30 changes: 29 additions & 1 deletion src/vamos/algorithms.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@
``available_*`` functions are stable. ``CCMOConfig``, ``CTAEAConfig``, ``ToPConfig`` and
``CMOEAMSConfig`` are new in VAMOS 1.2.0 and not yet covered by the 1.0 compatibility baseline. ``GenericAlgorithmConfig``,
``discover_algorithm_plugins`` and ``resolve_algorithm`` serve custom and
plugin algorithms and are experimental.
plugin algorithms and are experimental. ``moead_populations`` is new after VAMOS
1.4.0 (development) and not yet covered by the 1.0 compatibility baseline.
"""

from __future__ import annotations
Expand Down Expand Up @@ -90,6 +91,32 @@ def available_mutation_methods(encoding: str = "real") -> tuple[str, ...]:
return operator_names("mutation", encoding)


def moead_populations(n_obj: int, *, max_pop_size: int = 1000) -> tuple[int, ...]:
"""Return the populations, up to ``max_pop_size``, for which MOEA/D has weight vectors by default.

MOEA/D gives each individual one weight vector. With one or two objectives every population
from 2 has them (uniform weights). With three or more, a population has them when a complete
Das-Dennis lattice has exactly that many vectors (``comb(H + n_obj - 1, n_obj - 1)`` for ``H``
divisions) or when VAMOS ships jMetal's file ``W{n_obj}D_{size}.dat`` (100 with three or four
objectives, 156 with eight). ``MOEADConfig.default(pop_size=...)`` and ``optimize`` accept exactly
these sizes, and ``vamos tune`` runs the largest one up to the sampled population.

Other populations need explicit weights: ``weight_vectors(path=...)`` with a file, or
``weight_vectors(divisions=H1, inner_divisions=H2)`` with Deb and Jain's two-layer lattice of
``comb(H1 + n_obj - 1, n_obj - 1) + comb(H2 + n_obj - 1, n_obj - 1)`` vectors.

**Development after 1.4.0:** new.

Examples
--------
>>> moead_populations(4, max_pop_size=200)
(4, 10, 20, 35, 56, 84, 100, 120, 165)
"""
from vamos.engine.algorithm.components.weight_vectors import weighted_populations

return weighted_populations(n_obj, max_pop_size)


def resolve_algorithm(name: str) -> AlgorithmBuilder:
"""Return the registered builder for a named algorithm.

Expand Down Expand Up @@ -122,5 +149,6 @@ def resolve_algorithm(name: str) -> AlgorithmBuilder:
"discover_algorithm_plugins",
"available_crossover_methods",
"available_mutation_methods",
"moead_populations",
"resolve_algorithm",
]
5 changes: 5 additions & 0 deletions src/vamos/engine/algorithm/_builder_common.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
from collections.abc import Mapping
from typing import Any, cast

from vamos.engine.algorithm.components.weight_vectors import bind_config_vector_files
from vamos.engine.algorithm.config import AlgorithmConfigProtocol
from vamos.engine.algorithm.registry import resolve_algorithm
from vamos.engine.config.variation import ensure_operator_tuple, resolve_default_variation_config
Expand Down Expand Up @@ -117,8 +118,12 @@ def finalize_algorithm(
kernel: KernelBackend,
block: Mapping[str, Any] | None = None,
handled: tuple[str, ...] = (),
n_obj: int | None = None,
) -> tuple[Any, AlgorithmConfigProtocol]:
cfg_data = apply_block_fields(cast(AlgorithmConfigProtocol, builder.build()), block, handled=handled)
if n_obj is not None:
# Development after 1.4.0: a vector file is bound to the file the run reads and the digest of its vectors.
cfg_data = cast(AlgorithmConfigProtocol, bind_config_vector_files(cfg_data, n_obj))
algo_ctor = resolve_algorithm(algorithm_name)
return algo_ctor(cfg_data.to_dict(), kernel), cfg_data

Expand Down
Loading