Skip to content
Merged
4 changes: 4 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 All @@ -186,6 +188,8 @@ Reference vectors are directions, not target solutions on the DTLZ2 unit sphere.

**VAMOS 1.2.0:** RVEA keeps one solution per reference vector that has any, the one with the smallest angle-penalized distance, as Cheng et al. [1], PlatEMO and pymoo do. Vectors without a solution leave the population, and the result, smaller than `pop_size`; the recorded run above returns 9 rows for its 10 vectors. Parents are drawn by random permutations of the population, as in pymoo (the article only says "random"). Two choices follow pymoo rather than the article: the angle penalty uses M = 1 with two objectives, and the ideal point accumulates across generations. VAMOS 1.1.0 filled the population up to `pop_size` with further solutions taken in vector order, which favoured the vectors listed first, those near (0, …, 0, 1), and drew parents with replacement.

**Development after 1.4.0:** `variant("platemo")` runs the authors' reading instead, that of PlatEMO's `RVEA/EnvironmentalSelection.m` and `ReferenceVectorAdaptation.m`, which jMetal's `RVEAEnvironmentalSelection` follows: M is the number of objectives also with two objectives, so the penalty is `M (t / t_max)^alpha theta / gamma` as published, the objectives are translated by the minimum of each generation's candidates instead of the accumulated ideal point, and the vectors adapt to the range (maximum minus minimum) of the population instead of the nadir point minus the accumulated ideal. The default, `variant("pymoo")`, keeps the results above. Both count `t / t_max` in generations and keep VAMOS's feasibility-first constrained survival and parent selection.

**VAMOS 1.2.0:** with constraints, RVEA's survival keeps feasible solutions first. `constraint_handling` makes it judge feasibility and violation by one of jMetal's constraint-handling techniques: `cdp`, `violated_constraints`, `epsilon_constrained` or `push_pull`. See [choose a constraint-handling technique](../reference/constraints.md#choose-a-constraint-handling-technique).

This run has no constraints. Before using a constrained or discrete problem, check the [capability matrix](../reference/algorithms.md#capability-matrix) and [constraint convention](../reference/constraints.md). Preserve complete runs through the [canonical lifecycle](../guide/run-artifacts.md); the teaching JSON is not a replay bundle.
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
24 changes: 24 additions & 0 deletions docs/reference/algorithms.md
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,16 @@ published results or with another framework.
**VAMOS 1.3.0:** `MOEADConfig.default(variant="de")` gives MOEA/D-DE and
`variant="sbx"` jMetal's MOEA/D with SBX and PBI; VAMOS 2.0 will make
`"de"` the default. See [MOEA/D](../algorithms/moead.md#what-the-configuration-means).
- **RVEA's survival** follows pymoo: with two objectives the angle penalty
uses M = 1, half of the published `M (t / t_max)^alpha theta / gamma`, the
objectives are translated by the ideal point accumulated across
generations, and the vectors adapt to the nadir point minus that ideal.
**Development after 1.4.0:** `RVEAConfig.builder().variant("platemo")`
runs the authors' code in PlatEMO (`RVEA/EnvironmentalSelection.m`), as
jMetal does: M is the number of objectives, two included, the objectives
are translated by the minimum of each generation's candidates, and the
vectors adapt to the population's range. The default stays `"pymoo"`. See
[RVEA](../algorithms/rvea.md#interpret-the-result-and-its-limits).

**VAMOS 1.3.0:** three real-coded mutations scale their steps by
the range of each variable.
Expand Down Expand Up @@ -314,6 +324,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
46 changes: 46 additions & 0 deletions docs/reference/api/algorithms/rvea.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,52 @@ 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`.

**Development after 1.4.0:** `variant` chooses the reading of the survival:
`"pymoo"` (default, the results of VAMOS 1.4.0) or `"platemo"`, the authors'
PlatEMO code and jMetal, with M equal to the number of objectives in the angle
penalty for two objectives too, translation by each generation's minimum and
adaptation to the population's range (see the class below and
[where the variants depart](../../algorithms.md#where-the-variants-depart-from-their-references)).
`to_dict()` leaves out the default, so configurations without it keep their
resolved specification and task id.

::: vamos.algorithms.RVEAConfig
options:
heading_level: 2
Expand Down
Loading