diff --git a/docs/algorithms/rvea.md b/docs/algorithms/rvea.md index f1da5ac3d..1d77b0aa1 100644 --- a/docs/algorithms/rvea.md +++ b/docs/algorithms/rvea.md @@ -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. @@ -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. diff --git a/docs/dev/run_artifact_contract.md b/docs/dev/run_artifact_contract.md index 5db36972a..da90805f8 100644 --- a/docs/dev/run_artifact_contract.md +++ b/docs/dev/run_artifact_contract.md @@ -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: diff --git a/docs/guide/cli.md b/docs/guide/cli.md index a398479a7..784332dd9 100644 --- a/docs/guide/cli.md +++ b/docs/guide/cli.md @@ -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 WD_.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`; diff --git a/docs/reference/algorithms.md b/docs/reference/algorithms.md index fd8472f47..01ff2ee97 100644 --- a/docs/reference/algorithms.md +++ b/docs/reference/algorithms.md @@ -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. @@ -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 diff --git a/docs/reference/api/algorithms/moead.md b/docs/reference/api/algorithms/moead.md index 4259c5a61..00bf3199a 100644 --- a/docs/reference/api/algorithms/moead.md +++ b/docs/reference/api/algorithms/moead.md @@ -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. @@ -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 diff --git a/docs/reference/api/algorithms/nsgaiii.md b/docs/reference/api/algorithms/nsgaiii.md index 15517280a..ae3146ae9 100644 --- a/docs/reference/api/algorithms/nsgaiii.md +++ b/docs/reference/api/algorithms/nsgaiii.md @@ -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 diff --git a/docs/reference/api/algorithms/rvea.md b/docs/reference/api/algorithms/rvea.md index 042cdd704..f47345469 100644 --- a/docs/reference/api/algorithms/rvea.md +++ b/docs/reference/api/algorithms/rvea.md @@ -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 diff --git a/src/vamos/algorithms.py b/src/vamos/algorithms.py index 9b9bff1c8..46fd1b1a2 100644 --- a/src/vamos/algorithms.py +++ b/src/vamos/algorithms.py @@ -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 @@ -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. @@ -122,5 +149,6 @@ def resolve_algorithm(name: str) -> AlgorithmBuilder: "discover_algorithm_plugins", "available_crossover_methods", "available_mutation_methods", + "moead_populations", "resolve_algorithm", ] diff --git a/src/vamos/engine/algorithm/_builder_common.py b/src/vamos/engine/algorithm/_builder_common.py index 414237a03..9826837ef 100644 --- a/src/vamos/engine/algorithm/_builder_common.py +++ b/src/vamos/engine/algorithm/_builder_common.py @@ -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 @@ -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 diff --git a/src/vamos/engine/algorithm/_builder_decomposition.py b/src/vamos/engine/algorithm/_builder_decomposition.py index 1c2deccbd..27e86fdf5 100644 --- a/src/vamos/engine/algorithm/_builder_decomposition.py +++ b/src/vamos/engine/algorithm/_builder_decomposition.py @@ -11,6 +11,7 @@ resolve_problem_encoding, resolve_variation_config, ) +from vamos.engine.algorithm.components.weight_vectors import vector_source from vamos.engine.algorithm.config import AlgorithmConfigProtocol, MOEADConfig, NSGAIIIConfig, RVEAConfig from vamos.engine.algorithm.config.rvea import rvea_partitions_for_population from vamos.foundation.kernel.backend import KernelBackend @@ -76,7 +77,14 @@ def build_moead_algorithm( builder.track_genealogy(True) return cast( "tuple[MOEAD, AlgorithmConfigProtocol]", - finalize_algorithm(algorithm_name="moead", builder=builder, kernel=kernel, block=moead_overrides, handled=_MOEAD_BUILDER_FIELDS), + finalize_algorithm( + algorithm_name="moead", + builder=builder, + kernel=kernel, + block=moead_overrides, + handled=_MOEAD_BUILDER_FIELDS, + n_obj=problem.n_obj, + ), ) @@ -118,7 +126,7 @@ def build_nsgaiii_algorithm( builder.track_genealogy(True) return cast( "tuple[NSGAIII, AlgorithmConfigProtocol]", - finalize_algorithm(algorithm_name="nsgaiii", builder=builder, kernel=kernel, block=nsgaiii_variation), + finalize_algorithm(algorithm_name="nsgaiii", builder=builder, kernel=kernel, block=nsgaiii_variation, n_obj=problem.n_obj), ) @@ -140,8 +148,15 @@ def build_rvea_algorithm( builder = RVEAConfig.builder() builder.pop_size(pop_size) partitions = rvea_overrides.get("n_partitions") - # RVEA needs one reference vector per individual: derive the lattice from the population unless it is given. - builder.n_partitions(int(partitions) if partitions is not None else rvea_partitions_for_population(pop_size, problem.n_obj)) + vectors = vector_source(rvea_overrides.get("reference_vectors"), field="reference_vectors") + if vectors: + # Development after 1.4.0: the reference vectors of a file, a directory or a two-layer lattice. + builder.reference_vectors(**cast("dict[str, Any]", vectors)) + if partitions is not None: + builder.n_partitions(int(partitions)) + elif not vectors: + # RVEA needs one reference vector per individual: derive the lattice from the population unless it is given. + builder.n_partitions(rvea_partitions_for_population(pop_size, problem.n_obj)) builder.alpha(float(rvea_overrides.get("alpha", 2.0))) builder.adapt_freq(rvea_overrides["adapt_freq"] if "adapt_freq" in rvea_overrides else 0.1) apply_operator_config(builder, method_name="crossover", operator_cfg=var_cfg["crossover"], key="crossover") @@ -156,7 +171,12 @@ def build_rvea_algorithm( return cast( "tuple[RVEA, AlgorithmConfigProtocol]", finalize_algorithm( - algorithm_name="rvea", builder=builder, kernel=kernel, block=rvea_overrides, handled=("n_partitions", "alpha", "adapt_freq") + algorithm_name="rvea", + builder=builder, + kernel=kernel, + block=rvea_overrides, + handled=("n_partitions", "alpha", "adapt_freq", "reference_vectors"), + n_obj=problem.n_obj, ), ) diff --git a/src/vamos/engine/algorithm/components/vector_files.py b/src/vamos/engine/algorithm/components/vector_files.py new file mode 100644 index 000000000..2e0878a62 --- /dev/null +++ b/src/vamos/engine/algorithm/components/vector_files.py @@ -0,0 +1,232 @@ +"""Files of weight and reference vectors: reading, options, content binding and run records. + +MOEA/D's ``weight_vectors``, NSGA-III's ``reference_directions`` and RVEA's ``reference_vectors`` share +these helpers through :mod:`vamos.engine.algorithm.components.weight_vectors`. + +Development after 1.4.0: new module. +""" + +import dataclasses +import hashlib +import io +import os +import re +from collections.abc import Mapping +from difflib import get_close_matches +from numbers import Integral +from typing import Any + +import numpy as np + +from vamos.engine.reference_directions import FloatArray +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) + + +_VECTOR_SOURCE_KEYS = ("path", "divisions", "inner_divisions", "sha256") +_DIGEST_PATTERN = r"sha256:[0-9a-f]{64}" + + +def vector_source(value: object, *, field: str = "reference vectors") -> dict[str, int | str | None] | None: + """The options of a weight- or reference-vector source, checked. + + MOEA/D's ``weight_vectors``, NSGA-III's ``reference_directions`` and RVEA's ``reference_vectors`` + take ``None``, a path, or a mapping with these keys: + + - ``path``: a file with one vector per line, or a directory with jMetal's ``W{n_obj}D_{pop_size}.dat`` + files; + - ``divisions``: the complete Das-Dennis lattice of that many divisions; + - ``inner_divisions``: with ``divisions``, Deb and Jain's two-layer lattice (see + :func:`~vamos.engine.reference_directions.two_layer_lattice`). It needs ``divisions`` and excludes ``path``; + - ``sha256``: with ``path``, the digest of the vectors the file must hold (:func:`vector_digest`). A run + records it, with the file that ``path`` names, so that replay runs the same vectors + (:func:`bind_vector_file`). + + A path becomes ``{"path": path, "divisions": None}``. A mapping keeps the keys it has, so a configuration + serializes as before, except ``inner_divisions=None``, which is left out. An unknown key, a path that is + not a string, a count that is not a positive integer, or ``inner_divisions`` without ``divisions`` or with + ``path`` raises :class:`~vamos.exceptions.ConfigurationError`. + + Development after 1.4.0: new; VAMOS 1.4.0 ignored unknown keys. + """ + if value is None: + return None + if isinstance(value, (str, os.PathLike)): + return {"path": os.fspath(value), "divisions": None} + if not isinstance(value, Mapping): + raise ConfigurationError(f"{field} must be a mapping with path, divisions and inner_divisions, or a path; got {value!r}.") + unknown = [key for key in value if key not in _VECTOR_SOURCE_KEYS] + if unknown: + hints = "".join( + f" Did you mean '{match[0]}'?" for key in unknown if (match := get_close_matches(str(key), _VECTOR_SOURCE_KEYS, n=1)) + ) + raise ConfigurationError(f"Unknown {field} key(s): {', '.join(map(repr, unknown))}.{hints}") + source: dict[str, int | str | None] = dict(value) + path = source.get("path") + if path is not None: + if not isinstance(path, (str, os.PathLike)): + raise ConfigurationError(f"{field} path must be a string path or None; got {path!r}.") + source["path"] = str(os.fspath(path)) + for key in ("divisions", "inner_divisions"): + count = source.get(key) + if count is not None and (isinstance(count, bool) or not isinstance(count, Integral) or int(count) < 1): + raise ConfigurationError(f"{field} {key} must be a positive integer or None; got {count!r}.") + digest = source.get("sha256") + if digest is not None and (not isinstance(digest, str) or not re.fullmatch(_DIGEST_PATTERN, digest)): + raise ConfigurationError(f"{field} sha256 must be 'sha256:' and 64 lower-case hexadecimal digits; got {digest!r}.") + if digest is not None and source.get("path") is None: + raise ConfigurationError(f"{field} sha256 is the digest of the vectors of a file: it needs path.") + if source.get("inner_divisions") is None: + source.pop("inner_divisions", None) + elif source.get("divisions") is None: + raise ConfigurationError(f"{field} inner_divisions needs divisions, the boundary layer of the two-layer lattice.") + elif source.get("path") is not None: + raise ConfigurationError(f"{field} takes a file or a lattice: inner_divisions excludes path.") + return source + + +def vector_digest(vectors: FloatArray) -> str: + """The digest that binds a run to the vectors it read: ``sha256:`` and the SHA-256 of their shape and values. + + The values are the float64 vectors that :func:`read_weight_vectors` returns, so a file rewritten with + other separators or number formats keeps its digest. Development after 1.4.0: new. + """ + array = np.ascontiguousarray(vectors, dtype=" FloatArray: + if sha256 is not None and vector_digest(weights) != sha256: + raise ConfigurationError( + f"Weight vector file '{file}' no longer holds the vectors this configuration records ({sha256}).", + suggestion="Restore the file that the run read, or remove sha256 from the configuration to run the file's current vectors.", + ) + return weights + + +def bind_vector_file(source: object, n_obj: int, pop_size: int) -> object: + """``source`` with its ``path`` resolved to the file that a run reads and the ``sha256`` of its vectors. + + A directory becomes its ``W{n_obj}D_{pop_size}.dat``. A source without a path, one that already has a + digest, or a path whose file does not exist (MOEA/D then generates the lattice; NSGA-III and RVEA raise + when the run starts) is returned unchanged. The resolved specification then records which file the run + read and the digest of its vectors: verification rebuilds the record from them without the file, and + replay refuses a file whose vectors have changed. Development after 1.4.0: new. + """ + if not isinstance(source, Mapping) or not source.get("path") or source.get("sha256") is not None: + return source + path = str(source["path"]) + file = path if os.path.isfile(path) else os.path.join(path, f"W{n_obj}D_{pop_size}.dat") + if not os.path.isfile(file): + return source + return {**source, "path": file, "sha256": vector_digest(read_weight_vectors(file, n_obj))} + + +VECTOR_SOURCE_FIELDS = ("weight_vectors", "reference_directions", "reference_vectors") +"""The configuration fields that name the vectors of MOEA/D, NSGA-III and RVEA.""" + + +def bind_config_vector_files(config: Any, n_obj: int) -> Any: + """A configuration dataclass with each vector file bound by :func:`bind_vector_file`. + + MOEA/D's ``weight_vectors`` with one or two objectives are uniform and read no file, so they stay as + they are. Development after 1.4.0: new. + """ + if not dataclasses.is_dataclass(config) or isinstance(config, type): + return config + pop_size = getattr(config, "pop_size", None) + if not isinstance(pop_size, int) or isinstance(pop_size, bool): + return config + changes: dict[str, object] = {} + for name in VECTOR_SOURCE_FIELDS: + if not hasattr(config, name) or (name == "weight_vectors" and n_obj <= 2): + continue + value = getattr(config, name) + bound = bind_vector_file(value, n_obj, pop_size) + if bound is not value: + changes[name] = bound + return dataclasses.replace(config, **changes) if changes else config + + +def existing_weight_file(path: str, n_obj: int, pop_size: int) -> str: + """The weight file that ``path`` names: itself, or ``W{n_obj}D_{pop_size}.dat`` in the directory ``path``. + + A path that does not exist, or a directory without that file, raises + :class:`~vamos.exceptions.ConfigurationError`. Development after 1.4.0: new. + """ + if os.path.isfile(path): + return path + name = f"W{n_obj}D_{pop_size}.dat" + if os.path.isdir(path): + file = os.path.join(path, name) + if os.path.isfile(file): + return file + raise ConfigurationError( + f"Weight vector directory '{path}' has no {name} for {n_obj} objectives and pop_size={pop_size}.", + suggestion="Add the file, name the file itself, or choose a population that the directory has a file for.", + ) + raise ConfigurationError( + f"Weight vector path '{path}' does not exist.", + suggestion="Pass an existing file, one vector per line, or a directory with jMetal's WD_.dat files.", + ) + + +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 describe_vector_file(path: str, *, vectors: int | None = None) -> dict[str, object]: + """The record of NSGA-III's or RVEA's vectors from ``path``: ``{"source": "file", "file": name}``. + + ``name`` is the name of the file in ``path``, which :func:`bind_vector_file` resolves when the run starts, + and ``vectors``, when given, the number of vectors. The record comes from the configuration alone: + verification rebuilds it from a stored configuration without the file, which may be absent or on + another machine. Development after 1.4.0: new. + """ + record: dict[str, object] = {"source": "file", "file": os.path.basename(os.path.normpath(path))} + if vectors is not None: + record["vectors"] = vectors + return record + + +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 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.") + 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) diff --git a/src/vamos/engine/algorithm/components/weight_vectors.py b/src/vamos/engine/algorithm/components/weight_vectors.py index 696893cf7..aaac87e3d 100644 --- a/src/vamos/engine/algorithm/components/weight_vectors.py +++ b/src/vamos/engine/algorithm/components/weight_vectors.py @@ -1,37 +1,36 @@ import io import os +import re import stat import warnings +from numbers import Integral import numpy as np -from vamos.engine.reference_directions import FloatArray, das_dennis, largest_lattice_divisions, lattice_size +from vamos.engine.algorithm.components.vector_files import ( + VECTOR_SOURCE_FIELDS, + _checked_digest, + _load_weights, + _validated_weights, + bind_config_vector_files, + bind_vector_file, + describe_vector_file, + existing_weight_file, + read_weight_vectors, + vector_digest, + vector_source, +) +from vamos.engine.reference_directions import ( + FloatArray, + das_dennis, + largest_lattice_divisions, + lattice_size, + two_layer_lattice, + two_layer_shared, + two_layer_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( pop_size: int, @@ -40,49 +39,90 @@ def load_or_generate_weight_vectors( path: str | None = None, divisions: int | None = None, mode: str = "auto", + inner_divisions: int | None = None, + sha256: str | None = None, ) -> FloatArray: """ - 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. + The weight (reference) vectors of MOEA/D, NSGA-III and RVEA: those of a file, or a simplex-lattice design. + + With ``sha256``, the vectors read from the file must have that digest (:func:`vector_digest`), or + :class:`~vamos.exceptions.ConfigurationError` is raised before any evaluation: a run records the digest of + the vectors it read, so that replay never runs other vectors from a file that has changed. + + ``path`` names a file, read by :func:`read_weight_vectors` with whitespace or commas between the + components, or a directory with jMetal's ``W{n_obj}D_{pop_size}.dat`` files. ``divisions`` gives the + complete Das-Dennis lattice and, with ``inner_divisions``, Deb and Jain's two-layer lattice + (:func:`~vamos.engine.reference_directions.two_layer_lattice`). A lattice is never truncated. + + mode="auto" (NSGA-III): the file, which must exist and may hold any number of vectors (NSGA-III checks + that ``pop_size`` covers them); without one, the lattice of ``divisions``, or the largest lattice with at + most ``pop_size`` vectors, so the result can have fewer rows than ``pop_size``. - 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 - lattice is never truncated, so the result can have fewer rows than ``pop_size``. + mode="exact" (RVEA): one vector per individual. The file must exist and hold ``pop_size`` vectors, and + a lattice must have exactly ``pop_size`` vectors. - mode="jmetalpy" enforces jMetalPy-style behavior: + mode="jmetalpy" (MOEA/D) enforces jMetalPy-style behavior: - n_obj == 2: uniform weights of size pop_size - n_obj > 2: load W{n_obj}D_{pop_size}.dat when available, otherwise generate an exact Das-Dennis lattice and reject incompatible sizes. + + Development after 1.4.0: mode "exact", directories and ``inner_divisions`` in every mode, and a path + that does not exist raises :class:`~vamos.exceptions.ConfigurationError` in every mode. Mode "auto" + no longer generates a lattice for a missing file and saves it there, and MOEA/D no longer creates a + missing directory; it still saves the lattice in an existing directory that lacks the file. """ + if mode not in ("auto", "exact", "jmetalpy"): + raise ValueError(f"Unknown weight vector mode {mode!r}; expected 'auto', 'exact' or 'jmetalpy'.") + if inner_divisions is not None: + return _two_layer_weights(pop_size, n_obj, path, divisions, inner_divisions, exact=mode != "auto") if mode == "jmetalpy": - return _load_or_generate_jmetalpy_weights(pop_size, n_obj, path, divisions) - if path and os.path.exists(path): - 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." - ) + return _load_or_generate_jmetalpy_weights(pop_size, n_obj, path, divisions, sha256) + if path: + file = existing_weight_file(path, n_obj, pop_size) + weights = _checked_digest(read_weight_vectors(file, n_obj), file, sha256) + if mode == "exact" and weights.shape[0] != pop_size: + raise ValueError(f"Weight file '{file}' holds {weights.shape[0]} vectors, but pop_size={pop_size} needs one per individual.") return weights + return _generate_weights(pop_size, n_obj, divisions, strict=mode == "exact") - weights = _generate_weights(pop_size, n_obj, divisions) +def _two_layer_weights( + pop_size: int, n_obj: int, path: str | None, divisions: int | None, inner_divisions: int, *, exact: bool +) -> FloatArray: + """Deb and Jain's two-layer lattice; with ``exact``, it must have ``pop_size`` vectors.""" if path: - os.makedirs(os.path.dirname(path), exist_ok=True) - np.savetxt(path, weights, delimiter=",") + raise ConfigurationError("Weight vectors come from a file or a lattice: inner_divisions excludes path.") + if divisions is None: + raise ConfigurationError("inner_divisions needs divisions, the boundary layer of the two-layer lattice.") + count = two_layer_size(n_obj, int(divisions), int(inner_divisions)) + if exact and count != pop_size: + raise ValueError( + f"The two-layer lattice of divisions={divisions} and inner_divisions={inner_divisions} has {count} vectors " + f"for n_obj={n_obj}, but pop_size={pop_size} needs one per individual." + ) + check_two_layers(n_obj, int(divisions), int(inner_divisions)) + return two_layer_lattice(n_obj, int(divisions), int(inner_divisions)) - return weights +def check_two_layers(n_obj: int, divisions: int, inner_divisions: int) -> None: + """Raise :class:`~vamos.exceptions.ConfigurationError` when the inside layer repeats boundary directions. -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) + A repeated vector is a niche that never gets an individual of its own, and RVEA's angle to its nearest + other vector would be zero. Development after 1.4.0: new. + """ + shared = two_layer_shared(n_obj, divisions, inner_divisions) + if shared: + raise ConfigurationError( + f"The two-layer lattice of divisions={divisions} and inner_divisions={inner_divisions} repeats {shared} " + f"direction(s) for n_obj={n_obj}: the inside layer must add directions that the boundary layer does not have.", + suggestion="Choose other divisions or inner_divisions: with inner_divisions < n_obj and divisions < 2 n_obj " + "the layers share none (8 objectives: divisions=3, inner_divisions=2).", + ) -def _load_or_generate_jmetalpy_weights(pop_size: int, n_obj: int, path: str | None, divisions: int | None) -> FloatArray: +def _load_or_generate_jmetalpy_weights( + pop_size: int, n_obj: int, path: str | None, divisions: int | None, sha256: str | None = None +) -> FloatArray: if n_obj < 2: return np.ones((pop_size, 1), dtype=float) if n_obj == 2: @@ -93,6 +133,9 @@ def _load_or_generate_jmetalpy_weights(pop_size: int, n_obj: int, path: str | No vals = np.linspace(0.0, 1.0, pop_size, dtype=float) return np.column_stack([vals, 1.0 - vals]) + if path and not os.path.exists(path): + # Development after 1.4.0: a path that does not exist is an error; MOEA/D used to create it as a directory. + existing_weight_file(path, n_obj, pop_size) weight_path = _resolve_jmetalpy_weight_path(path, n_obj, pop_size) if weight_path is None and divisions is None and _exact_divisions(pop_size, n_obj) is None: # No complete lattice has pop_size vectors: use the jMetal weights VAMOS ships for it, if any. @@ -100,11 +143,17 @@ 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 = read_weight_vectors(weight_path, n_obj) + weights = _checked_digest(read_weight_vectors(weight_path, n_obj), weight_path, sha256) if weights.shape[0] != pop_size: raise ValueError(f"Expected {pop_size} weight vectors in '{weight_path}', got {weights.shape[0]}.") return weights + if sha256 is not None: + # The digest records the vectors of a file that a run read: generating the lattice instead would run others. + raise ConfigurationError( + f"Weight vector file '{weight_path}' that this configuration records ({sha256}) does not exist.", + suggestion="Restore the file that the run read, or remove sha256 from the configuration.", + ) weights = _generate_weights(pop_size, n_obj, divisions=divisions, strict=True) if weight_path is not None: saved = False @@ -145,6 +194,8 @@ def describe_weight_vectors( *, path: str | None = None, divisions: int | None = None, + inner_divisions: int | None = None, + sha256: str | None = None, ) -> dict[str, object]: """Where MOEA/D's weight vectors for ``pop_size`` come from, as a run artifact records it. @@ -157,9 +208,27 @@ def describe_weight_vectors( A run whose ``path`` lacks the file generates the lattice and saves it there, so a file that holds exactly that lattice is still ``das_dennis``: the description does not depend on whether an earlier run has written it. + + Development after 1.4.0: ``two_layer`` with its ``divisions`` and ``inner_divisions``. With ``sha256``, + the digest that :func:`bind_vector_file` records with the file a run read, the description comes from + the configuration alone, without the file: ``das_dennis`` when the digest is that of the lattice of + ``pop_size`` vectors (a lattice that an earlier run saved), else ``file``. """ + if inner_divisions is not None: + if divisions is None: + raise ValueError("inner_divisions needs divisions, the boundary layer of the two-layer lattice.") + count = two_layer_size(n_obj, int(divisions), int(inner_divisions)) + if count != pop_size: + raise ValueError(f"The two-layer lattice for n_obj={n_obj} has {count} vectors, not pop_size={pop_size}.") + check_two_layers(n_obj, int(divisions), int(inner_divisions)) + return {"source": "two_layer", "divisions": int(divisions), "inner_divisions": int(inner_divisions), "vectors": pop_size} if n_obj <= 2: return {"source": "uniform", "vectors": pop_size} + if path and sha256 is not None: + exact = _exact_divisions(pop_size, n_obj) + if exact is not None and (divisions is None or int(divisions) == exact) and vector_digest(das_dennis(n_obj, exact)) == sha256: + return {"source": "das_dennis", "divisions": exact, "vectors": pop_size} + return {"source": "file", "file": os.path.basename(path), "vectors": pop_size} weight_path = _resolve_jmetalpy_weight_path(path, n_obj, pop_size) if weight_path is None and divisions is None and _exact_divisions(pop_size, n_obj) is None: if _packaged_weights(n_obj, pop_size) is not None: @@ -173,6 +242,37 @@ def describe_weight_vectors( return {"source": "das_dennis", "divisions": int(divisions), "vectors": pop_size} +def weighted_populations(n_obj: int, max_pop_size: int) -> tuple[int, ...]: + """The populations, up to ``max_pop_size``, for which MOEA/D has weight vectors without options. + + Every population from 2 with one or two objectives; with more, the sizes of the complete Das-Dennis + lattices and of the packaged jMetal files ``W{n_obj}D_{size}.dat``. This is + :func:`vamos.algorithms.moead_populations`. Development after 1.4.0: new. + """ + if isinstance(n_obj, bool) or not isinstance(n_obj, Integral) or n_obj < 1: + raise ConfigurationError(f"n_obj must be a positive integer; got {n_obj!r}.") + if isinstance(max_pop_size, bool) or not isinstance(max_pop_size, Integral) or max_pop_size < 1: + raise ConfigurationError(f"max_pop_size must be a positive integer; got {max_pop_size!r}.") + if n_obj <= 2: + return tuple(range(2, int(max_pop_size) + 1)) + sizes: set[int] = set() + divisions = 1 + while (size := lattice_size(int(n_obj), divisions)) <= max_pop_size: + sizes.add(size) + divisions += 1 + sizes.update(size for size in _packaged_sizes(int(n_obj)) if size <= max_pop_size and _packaged_weights(int(n_obj), size) is not None) + return tuple(sorted(sizes)) + + +def _packaged_sizes(n_obj: int) -> list[int]: + """The populations of the jMetal weight files that VAMOS ships for ``n_obj`` objectives.""" + from importlib import resources + + pattern = re.compile(rf"W{n_obj}D_(\d+)\.dat") + names = (entry.name for entry in resources.files("vamos.resources").joinpath("weights").iterdir()) + return sorted(int(match.group(1)) for name in names if (match := pattern.fullmatch(name))) + + def _holds_saved_lattice(path: str, pop_size: int, n_obj: int, divisions: int | None) -> bool: """Whether the weight file holds exactly the Das-Dennis lattice that a run saves there when the file is missing. @@ -252,21 +352,6 @@ def _resolve_jmetalpy_weight_path(path: str | None, n_obj: int, pop_size: int) - return os.path.join(path, filename) -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 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.") - 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: if n_obj < 2: # Degenerate single-objective: return uniform weights. @@ -295,3 +380,20 @@ def _choose_exact_divisions(pop_size: int, n_obj: int) -> int: "Choose a compatible pop_size or provide an explicit weight vector file." ) divisions += 1 + + +__all__ = [ + "VECTOR_SOURCE_FIELDS", + "bind_config_vector_files", + "bind_vector_file", + "check_two_layers", + "describe_vector_file", + "describe_weight_vectors", + "existing_weight_file", + "largest_weighted_population", + "load_or_generate_weight_vectors", + "read_weight_vectors", + "vector_digest", + "vector_source", + "weighted_populations", +] diff --git a/src/vamos/engine/algorithm/config/moead.py b/src/vamos/engine/algorithm/config/moead.py index 493f6d831..3e69dcfa4 100644 --- a/src/vamos/engine/algorithm/config/moead.py +++ b/src/vamos/engine/algorithm/config/moead.py @@ -6,6 +6,7 @@ from math import comb from typing import Any, Literal, TypeAlias, overload +from vamos.engine.algorithm.components.weight_vectors import vector_source from vamos.engine.algorithm.moead.subproblems import normalize_subproblem_order from vamos.engine.algorithm.moead.update_criteria import normalize_subproblem_update_criterion from vamos.engine.archive import ExternalArchiveConfig @@ -79,6 +80,12 @@ class MOEADConfig(_SerializableConfig): See :mod:`vamos.engine.algorithm.moead.aggregation` and :mod:`vamos.engine.operators.policies.moead` for the definitions. + + **Development after 1.4.0:** ``weight_vectors`` takes ``inner_divisions`` with ``divisions``, Deb and + Jain's two-layer lattice, which gives usual populations with many objectives (156 vectors with eight + objectives, 3 and 2 divisions), and NSGA-III's ``reference_directions`` and RVEA's ``reference_vectors`` + take the same keys. :func:`vamos.algorithms.moead_populations` lists the populations that have weights + without options. """ pop_size: int @@ -105,6 +112,7 @@ class MOEADConfig(_SerializableConfig): def __post_init__(self) -> None: super().__post_init__() + object.__setattr__(self, "weight_vectors", vector_source(self.weight_vectors, field="weight_vectors")) criterion = normalize_subproblem_update_criterion(self.subproblem_update_criterion) if criterion is not None and criterion[0] != "feasibility_rules" and self.constraint_mode == "none": raise ValueError(f"subproblem_update_criterion {criterion[0]!r} needs constraint_mode 'feasibility'.") @@ -266,8 +274,27 @@ def aggregation(self, method: str, **kwargs: Any) -> _MOEADConfigBuilder: self._cfg["aggregation"] = (method, kwargs) return self - def weight_vectors(self, *, path: str | None = None, divisions: int | None = None) -> _MOEADConfigBuilder: - self._cfg["weight_vectors"] = {"path": path, "divisions": divisions} + def weight_vectors( + self, + *, + path: str | None = None, + divisions: int | None = None, + inner_divisions: int | None = None, + ) -> _MOEADConfigBuilder: + """The weight vectors: a file or directory, a lattice, or by default the lattice or packaged file of ``pop_size``. + + ``path`` names 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; a directory without the file gets + the lattice of exactly ``pop_size`` vectors, saved there with a ``RuntimeWarning``. ``divisions`` + gives the complete Das-Dennis lattice. MOEA/D needs exactly one vector per individual. + + **Development after 1.4.0:** ``inner_divisions`` with ``divisions`` gives 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, for any number of objectives; a ``path`` that does not exist + raises :class:`~vamos.exceptions.ConfigurationError` when the run starts, where VAMOS 1.4.0 created + the directory. + """ + self._cfg["weight_vectors"] = vector_source({"path": path, "divisions": divisions, "inner_divisions": inner_divisions}) return self def use_numba_variation(self, enabled: bool = True) -> _MOEADConfigBuilder: diff --git a/src/vamos/engine/algorithm/config/nsgaiii.py b/src/vamos/engine/algorithm/config/nsgaiii.py index f251119d1..81489f947 100644 --- a/src/vamos/engine/algorithm/config/nsgaiii.py +++ b/src/vamos/engine/algorithm/config/nsgaiii.py @@ -5,6 +5,7 @@ from dataclasses import dataclass from typing import Any, Self +from vamos.engine.algorithm.components.weight_vectors import vector_source from vamos.engine.archive import ExternalArchiveConfig from vamos.engine.reference_directions import lattice_size from vamos.foundation.encoding import EncodingLike @@ -97,6 +98,7 @@ class NSGAIIIConfig(_SerializableConfig): def __post_init__(self) -> None: super().__post_init__() + object.__setattr__(self, "reference_directions", vector_source(self.reference_directions, field="reference_directions")) 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 @@ -206,8 +208,9 @@ def reference_directions( *, path: str | None = None, divisions: int | None = None, + inner_divisions: int | None = None, ) -> _NSGAIIIConfigBuilder: - """The reference directions: a file, or the complete Das-Dennis lattice of ``divisions``. + """The reference directions: a file or directory, 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, @@ -217,8 +220,12 @@ def reference_directions( **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. + ``path`` may also name a directory with jMetal's ``W{n_obj}D_{pop_size}.dat`` files, as MOEA/D's + ``weight_vectors``, and ``inner_divisions`` with ``divisions`` gives 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 (156 directions with eight objectives, 3 and 2 divisions). """ - self._cfg["reference_directions"] = {"path": path, "divisions": divisions} + self._cfg["reference_directions"] = vector_source({"path": path, "divisions": divisions, "inner_divisions": inner_divisions}) return self def enforce_ref_dirs(self, enabled: bool = True) -> _NSGAIIIConfigBuilder: diff --git a/src/vamos/engine/algorithm/config/rvea.py b/src/vamos/engine/algorithm/config/rvea.py index dcbe9c23b..17d4e0176 100644 --- a/src/vamos/engine/algorithm/config/rvea.py +++ b/src/vamos/engine/algorithm/config/rvea.py @@ -4,9 +4,10 @@ from dataclasses import dataclass from math import comb -from typing import Any, ClassVar +from typing import Any, ClassVar, Literal, TypeAlias, cast from vamos.engine.algorithm.components.constraint_handling import PAIRWISE_TECHNIQUES +from vamos.engine.algorithm.components.weight_vectors import vector_source from vamos.engine.archive import ExternalArchiveConfig from vamos.engine.reference_directions import lattice_size from vamos.foundation.encoding import EncodingLike @@ -37,6 +38,17 @@ ) from .types import RepairConfigValue +RVEAVariant: TypeAlias = Literal["pymoo", "platemo"] +_RVEA_VARIANTS = ("pymoo", "platemo") + + +def normalize_rvea_variant(value: object) -> RVEAVariant: + """RVEA's survival variant in lower case, or ``ConfigurationError``. Development after 1.4.0: new.""" + name = value.strip().lower() if isinstance(value, str) else None + if name not in _RVEA_VARIANTS: + raise ConfigurationError(f"RVEA variant must be one of {', '.join(map(repr, _RVEA_VARIANTS))}; got {value!r}.") + return cast(RVEAVariant, name) + def rvea_partitions_for_population(pop_size: int, n_obj: int) -> int: """Return the Das-Dennis partitions whose lattice has exactly ``pop_size`` vectors. @@ -75,6 +87,40 @@ def rvea_partitions_for_population(pop_size: int, n_obj: int) -> int: @dataclass(frozen=True) class RVEAConfig(_SerializableConfig): + """Configuration of RVEA. + + RVEA keeps one individual per reference vector, so ``pop_size`` must equal their number. By + default the vectors are the complete Das-Dennis lattice of ``n_partitions``. + + **Development after 1.4.0:** ``reference_vectors`` takes the vectors from elsewhere, with the + keys of MOEA/D's ``weight_vectors`` and NSGA-III's ``reference_directions``: + + - ``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 (``W3D_100.dat`` runs 100 individuals with three objectives). The file must exist + and hold ``pop_size`` vectors; + - ``divisions``: the lattice of that many divisions, as ``n_partitions``; + - ``divisions`` and ``inner_divisions``: Deb and Jain's two-layer lattice, the boundary layer of + ``divisions`` and an inside layer of ``inner_divisions`` (see + :func:`~vamos.engine.reference_directions.two_layer_lattice`). + + With ``reference_vectors``, ``n_partitions`` is not used. ``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. + + **Development after 1.4.0:** ``variant`` chooses between the two readings of the survival. + ``"pymoo"``, the default and VAMOS's RVEA so far, follows pymoo: with two objectives the angle + penalty uses M = 1, the objectives are translated by the ideal point accumulated across + generations, and the vectors adapt to the nadir point minus that ideal point. ``"platemo"`` + follows the authors' code in PlatEMO (``RVEA/EnvironmentalSelection.m`` and + ``ReferenceVectorAdaptation.m``) and jMetal's ``RVEAEnvironmentalSelection``: M is the number of + objectives, two included, so the penalty is ``M (t / t_max)^alpha theta / gamma`` for every + number of objectives, the objectives are translated by the minimum of the candidates of each + generation, and the vectors adapt to the range (maximum minus minimum) of the population. Both + keep VAMOS's progress ``t / t_max`` in generations, its feasibility-first constrained survival + and its parent selection. ``to_dict()`` leaves out the default. + """ + pop_size: int n_partitions: int alpha: float @@ -91,14 +137,28 @@ class RVEAConfig(_SerializableConfig): # Fields added after 1.0 go last, so that the constructor keeps the positions of its parameters. constraint_handling: tuple[str, dict[str, float]] | None = None live_callback_mode: LiveCallbackMode = "population" + reference_vectors: dict[str, int | str | None] | None = None + variant: RVEAVariant = "pymoo" #: The techniques that judge the violation of a single solution, the only ones this algorithm takes. constraint_handling_techniques: ClassVar[tuple[str, ...]] = PAIRWISE_TECHNIQUES def __post_init__(self) -> None: super().__post_init__() + object.__setattr__(self, "reference_vectors", vector_source(self.reference_vectors, field="reference_vectors")) + object.__setattr__(self, "variant", normalize_rvea_variant(self.variant)) if self.track_genealogy: _warn_without_effect("RVEA", "track_genealogy", "RVEA records no genealogy", stacklevel=3) + def to_dict(self) -> dict[str, object]: + payload = super().to_dict() + # Development after 1.4.0: a configuration without reference_vectors is serialized as in VAMOS 1.4.0. + if payload.get("reference_vectors") is None: + payload.pop("reference_vectors", None) + # Development after 1.4.0: so is a configuration with the default variant. + if payload.get("variant") == "pymoo": + payload.pop("variant", None) + return payload + @classmethod def default( cls, @@ -173,6 +233,34 @@ def n_partitions(self, value: int) -> _RVEAConfigBuilder: self._cfg["n_partitions"] = value return self + def reference_vectors( + self, + *, + path: str | None = None, + divisions: int | None = None, + inner_divisions: int | None = None, + ) -> _RVEAConfigBuilder: + """**Development after 1.4.0:** the reference vectors: a file or directory, or a lattice. + + ``path`` names 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; the file must exist + and hold ``pop_size`` vectors. Without it, ``divisions`` gives the lattice, and with + ``inner_divisions`` Deb and Jain's two-layer lattice. ``n_partitions`` is then not needed: + without it, the configuration records ``divisions``, or 12 for a file. + """ + self._cfg["reference_vectors"] = vector_source({"path": path, "divisions": divisions, "inner_divisions": inner_divisions}) + return self + + def variant(self, value: RVEAVariant) -> _RVEAConfigBuilder: + """**Development after 1.4.0:** the reading of RVEA's survival, ``"pymoo"`` (default) or ``"platemo"``. + + ``"platemo"`` follows the authors' PlatEMO code and jMetal: M is the number of objectives in the + angle penalty also with two objectives, the objectives are translated by the minimum of each + generation's candidates, and the vectors adapt to the population's range. See :class:`RVEAConfig`. + """ + self._cfg["variant"] = normalize_rvea_variant(value) + return self + def alpha(self, value: float) -> _RVEAConfigBuilder: self._cfg["alpha"] = float(value) return self @@ -182,15 +270,17 @@ def adapt_freq(self, value: float | None) -> _RVEAConfigBuilder: return self def build(self) -> RVEAConfig: - _require_fields( - self._cfg, - ("pop_size", "n_partitions", "alpha", "crossover", "mutation"), - "RVEA", + vectors = self._cfg.get("reference_vectors") + # With reference vectors, n_partitions is not used: it defaults to their divisions, or to 12 for a file. + required = ( + ("pop_size", "alpha", "crossover", "mutation") if vectors else ("pop_size", "n_partitions", "alpha", "crossover", "mutation") ) + _require_fields(self._cfg, required, "RVEA") _validate_operators(self._cfg) + default_partitions = vectors.get("divisions") if vectors and vectors.get("divisions") is not None else 12 return RVEAConfig( pop_size=self._cfg["pop_size"], - n_partitions=self._cfg.get("n_partitions", 12), + n_partitions=self._cfg.get("n_partitions", default_partitions), alpha=float(self._cfg.get("alpha", 2.0)), adapt_freq=self._cfg.get("adapt_freq", 0.1), crossover=self._cfg["crossover"], @@ -204,4 +294,6 @@ def build(self) -> RVEAConfig: result_mode=self._cfg.get("result_mode", "non_dominated"), external_archive=self._cfg.get("external_archive"), live_callback_mode=self._cfg.get("live_callback_mode", "population"), + reference_vectors=vectors, + variant=self._cfg.get("variant", "pymoo"), ) diff --git a/src/vamos/engine/algorithm/factory.py b/src/vamos/engine/algorithm/factory.py index c9c727789..29d257a52 100644 --- a/src/vamos/engine/algorithm/factory.py +++ b/src/vamos/engine/algorithm/factory.py @@ -1,6 +1,7 @@ from __future__ import annotations from collections.abc import Callable, Mapping +from typing import cast from vamos.engine.algorithm.builders import ( build_agemoea_algorithm, @@ -17,6 +18,7 @@ build_spea2_algorithm, build_top_algorithm, ) +from vamos.engine.algorithm.components.weight_vectors import bind_config_vector_files from vamos.engine.algorithm.config import GenericAlgorithmConfig from vamos.engine.algorithm.config.types import AlgorithmConfigProtocol from vamos.engine.algorithm.registry import resolve_algorithm @@ -76,6 +78,8 @@ def build_algorithm( if algorithm_config is not None: algo_ctor = resolve_algorithm(algorithm_key) + # Development after 1.4.0: a vector file is bound to the file the run reads and the digest of its vectors. + algorithm_config = cast(AlgorithmConfigProtocol, bind_config_vector_files(algorithm_config, problem.n_obj)) return algo_ctor(dict(algorithm_config.to_dict()), kernel), algorithm_config builders: dict[str, Callable[[], tuple[object, AlgorithmConfigProtocol]]] = { diff --git a/src/vamos/engine/algorithm/moead/initialization.py b/src/vamos/engine/algorithm/moead/initialization.py index 3fc6b8a4e..232135faf 100644 --- a/src/vamos/engine/algorithm/moead/initialization.py +++ b/src/vamos/engine/algorithm/moead/initialization.py @@ -326,6 +326,8 @@ def _weights(cfg: Mapping[str, Any], pop_size: int, n_obj: int) -> tuple[NDArray path=weight_cfg.get("path"), divisions=weight_cfg.get("divisions"), mode="jmetalpy", + inner_divisions=weight_cfg.get("inner_divisions"), + sha256=weight_cfg.get("sha256"), ) weights_safe = np.where(weights == 0, ZERO_WEIGHT_EPS, weights) weight_norms = np.linalg.norm(weights, axis=1) diff --git a/src/vamos/engine/algorithm/nsgaiii/initialization.py b/src/vamos/engine/algorithm/nsgaiii/initialization.py index c0a29db4d..4ffe3a2d3 100644 --- a/src/vamos/engine/algorithm/nsgaiii/initialization.py +++ b/src/vamos/engine/algorithm/nsgaiii/initialization.py @@ -21,12 +21,12 @@ 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, read_weight_vectors +from vamos.engine.algorithm.components.weight_vectors import load_or_generate_weight_vectors, vector_source from vamos.engine.algorithm.config.base import normalize_constraint_mode from vamos.engine.algorithm.config.nsgaiii import nsgaiii_selection from vamos.engine.archive.factory import resolve_external_archive, setup_archive from vamos.engine.operators.policies.nsgaiii import build_variation_operators -from vamos.engine.reference_directions import lattice_size +from vamos.engine.reference_directions import lattice_size, two_layer_size from vamos.foundation.encoding import EncodingLike, normalize_encoding from .state import NSGAIIIState @@ -113,25 +113,32 @@ def initialize_nsgaiii_run( # Reference directions: a file, the complete lattice for the configured divisions, or, without # either, the complete Das-Dennis lattice with the most directions that fit in pop_size. The # population needs at least one individual per direction (N >= H, as Deb and Jain, jMetal and pymoo). - dir_cfg = config.get("reference_directions", {}) or {} + dir_cfg = vector_source(config.get("reference_directions"), field="reference_directions") or {} ref_path = dir_cfg.get("path") ref_divisions = dir_cfg.get("divisions") + ref_inner = dir_cfg.get("inner_divisions") 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) + # Development after 1.4.0: the file, or W{n_obj}D_{pop_size}.dat in a directory, is read as MOEA/D + # reads its weights, with whitespace or commas between the components, and a path that does not + # exist raises instead of generating a lattice there. + ref_dirs = load_or_generate_weight_vectors(pop_size, n_obj, path=str(ref_path), sha256=_digest(dir_cfg.get("sha256"))) 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}" + lattice = f"divisions={ref_divisions}" if ref_inner is None else f"divisions={ref_divisions} and inner_divisions={ref_inner}" + source = f"NSGA-III reference directions for {lattice}" if n_obj >= 2: # Reject from the binomial count: an oversized lattice can need gigabytes. - n_directions = lattice_size(n_obj, int(ref_divisions)) + n_directions = ( + lattice_size(n_obj, int(ref_divisions)) if ref_inner is None else two_layer_size(n_obj, int(ref_divisions), int(ref_inner)) + ) if n_directions > pop_size: raise ValueError( 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, divisions=ref_divisions) + ref_dirs = load_or_generate_weight_vectors( + pop_size, n_obj, divisions=int(ref_divisions), inner_divisions=None if ref_inner is None else int(ref_inner) + ) source = f"{source} ({ref_dirs.shape[0]})" else: if n_obj >= 2 and pop_size < n_obj: @@ -213,6 +220,11 @@ def initialize_nsgaiii_run( return state, live_cb, eval_strategy, max_eval, hv_tracker +def _digest(value: object) -> str | None: + """The recorded ``sha256`` of the vectors of a file, ``None`` without one.""" + return value if isinstance(value, str) else None + + def initialize_population( encoding: EncodingLike, pop_size: int, diff --git a/src/vamos/engine/algorithm/rvea/rvea.py b/src/vamos/engine/algorithm/rvea/rvea.py index 31abe2260..bd4e13b7c 100644 --- a/src/vamos/engine/algorithm/rvea/rvea.py +++ b/src/vamos/engine/algorithm/rvea/rvea.py @@ -27,7 +27,9 @@ parse_termination, validate_initial_budget, ) +from vamos.engine.algorithm.components.weight_vectors import load_or_generate_weight_vectors, vector_source from vamos.engine.algorithm.config.base import normalize_constraint_mode +from vamos.engine.algorithm.config.rvea import normalize_rvea_variant from vamos.engine.archive.factory import resolve_external_archive, setup_archive from vamos.engine.config.variation import ( ensure_operator_tuple, @@ -79,6 +81,33 @@ def _das_dennis(n_partitions: int, n_obj: int) -> np.ndarray[Any, Any]: return ref_dirs +def _reference_vectors(spec: object, pop_size: int, n_obj: int, n_partitions: int) -> np.ndarray[Any, Any]: + """RVEA's reference vectors, one per individual: the lattice of ``n_partitions``, or those of ``reference_vectors``. + + Development after 1.4.0: ``reference_vectors`` names a file or directory, read as MOEA/D's and NSGA-III's + files, or a two-layer lattice. Its ``divisions`` alone give the same lattice as ``n_partitions``. + """ + source = vector_source(spec, field="reference_vectors") or {} + path, divisions, inner = source.get("path"), source.get("divisions"), source.get("inner_divisions") + if path is not None or inner is not None: + return load_or_generate_weight_vectors( + pop_size, + n_obj, + path=None if path is None else str(path), + divisions=None if divisions is None else int(divisions), + inner_divisions=None if inner is None else int(inner), + mode="exact", + sha256=None if source.get("sha256") is None else str(source.get("sha256")), + ) + partitions = n_partitions if divisions is None else int(divisions) + ref_dirs = _generate_reference_vectors(n_obj, partitions) + if ref_dirs.shape[0] != pop_size: + raise ValueError( + f"RVEA requires pop_size == #ref_dirs for partitions={partitions} (pop_size={pop_size}, ref_dirs={ref_dirs.shape[0]})." + ) + return ref_dirs + + def _calc_V(ref_dirs: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]: norms = np.linalg.norm(ref_dirs, axis=1, keepdims=True) norms[norms == 0.0] = 1.0 @@ -243,11 +272,7 @@ def initialize( else: max_gen = max(1, int(math.ceil((max_evals - pop_size) / pop_size))) - ref_dirs = _generate_reference_vectors(n_obj, n_partitions) - if ref_dirs.shape[0] != pop_size: - raise ValueError( - f"RVEA requires pop_size == #ref_dirs for partitions={n_partitions} (pop_size={pop_size}, ref_dirs={ref_dirs.shape[0]})." - ) + ref_dirs = _reference_vectors(self.cfg.get("reference_vectors"), pop_size, n_obj, n_partitions) validate_initial_budget(max_evals, pop_size, "RVEA") V = _calc_V(ref_dirs) gamma = _calc_gamma(V) @@ -315,6 +340,7 @@ def initialize( alpha=alpha, adapt_interval=adapt_interval, n_obj=n_obj, + variant=normalize_rvea_variant(self.cfg.get("variant", "pymoo")), result_mode=result_mode, live_callback_mode=str(self.cfg.get("live_callback_mode", "population")), hv_tracker=setup_hv_tracker(hv_config, self.kernel), @@ -422,6 +448,7 @@ def tell(self, eval_result: Any, problem: ProblemProtocol | None = None) -> bool st.max_gen, st.alpha, st.constraint_mode, + st.variant, ) if survivors.size == 0: raise RuntimeError("RVEA selected no survivors from a non-empty population.") @@ -434,10 +461,17 @@ def tell(self, eval_result: Any, problem: ProblemProtocol | None = None) -> bool record_archive_rows(st, st.X, st.F, st.G) # Periodic reference-vector adaptation - if st.adapt_interval is not None and st.generation % st.adapt_interval == 0 and st.nadir is not None: - scale = np.maximum(st.nadir - st.ideal, 1e-64) - st.V = _calc_V(_calc_V(st.ref_dirs) * scale) - st.gamma = _calc_gamma(st.V) + if st.adapt_interval is not None and st.generation % st.adapt_interval == 0: + # Development after 1.4.0: the "platemo" variant scales the vectors by the population's range, + # as PlatEMO's ReferenceVectorAdaptation and jMetal; "pymoo" by the nadir minus the accumulated ideal. + scale: np.ndarray[Any, Any] | None = None + if st.variant == "platemo": + scale = np.ptp(st.F, axis=0) + elif st.nadir is not None: + scale = st.nadir - st.ideal + if scale is not None: + st.V = _calc_V(_calc_V(st.ref_dirs) * np.maximum(scale, 1e-64)) + st.gamma = _calc_gamma(st.V) st.pending_offspring = None st.generation += 1 diff --git a/src/vamos/engine/algorithm/rvea/state.py b/src/vamos/engine/algorithm/rvea/state.py index dca939a08..8f6486e7a 100644 --- a/src/vamos/engine/algorithm/rvea/state.py +++ b/src/vamos/engine/algorithm/rvea/state.py @@ -44,6 +44,8 @@ class RVEAState(AlgorithmState): alpha: float = 2.0 adapt_interval: int | None = None n_obj: int = 2 + # Development after 1.4.0: "pymoo" (default) or "platemo", the reading of the survival (see RVEAConfig). + variant: str = "pymoo" def build_rvea_result( diff --git a/src/vamos/engine/algorithm/rvea/survival.py b/src/vamos/engine/algorithm/rvea/survival.py index f20760431..d07ff0bf2 100644 --- a/src/vamos/engine/algorithm/rvea/survival.py +++ b/src/vamos/engine/algorithm/rvea/survival.py @@ -9,6 +9,39 @@ from vamos.foundation.constraints.utils import compute_violation, is_feasible +def angle_penalized_distances( + F: np.ndarray[Any, Any], + origin: np.ndarray[Any, Any], + V: np.ndarray[Any, Any], + gamma: np.ndarray[Any, Any], + n_gen: int, + n_max_gen: int, + alpha: float, + variant: str = "pymoo", +) -> tuple[np.ndarray[Any, Any], np.ndarray[Any, Any], np.ndarray[Any, Any]]: + """The niche, the angle penalty and the APD of each row of ``F``, translated by ``origin``. + + The penalty is ``M (t / t_max)^alpha theta / gamma``, where ``theta`` is the angle to the nearest + reference vector and ``gamma`` that vector's smallest angle to another. ``M`` is the number of + objectives, except with two objectives in the ``"pymoo"`` variant, where it is 1, as in pymoo. + """ + n_obj = F.shape[1] + F_shift = F - origin + dist_to_origin = np.linalg.norm(F_shift, axis=1) + dist_to_origin[dist_to_origin < 1e-64] = 1e-64 + F_prime = F_shift / dist_to_origin[:, None] + + cos_theta = np.clip(F_prime @ V.T, -1.0, 1.0) + acute_angle = np.arccos(cos_theta) + niches = acute_angle.argmin(axis=1) + + M = float(n_obj) if n_obj > 2 or variant == "platemo" else 1.0 + progress = (n_gen / n_max_gen) ** alpha + theta = acute_angle[np.arange(F.shape[0]), niches] + penalty = M * progress * (theta / gamma[niches]) + return niches, penalty, dist_to_origin * (1.0 + penalty) + + def apd_survival( F: np.ndarray[Any, Any], V: np.ndarray[Any, Any], @@ -18,34 +51,25 @@ def apd_survival( n_gen: int, n_max_gen: int, alpha: float, + variant: str = "pymoo", ) -> tuple[np.ndarray[Any, Any], np.ndarray[Any, Any], np.ndarray[Any, Any] | None]: """Select survivors using RVEA's angle-penalized distance criterion. One survivor per non-empty reference vector, the one with the smallest APD, as in Cheng et al. (2016), PlatEMO and pymoo; vectors without a solution leave the population smaller - than ``n_survive``. As in pymoo, two objectives use M = 1 in the penalty and the ideal point - accumulates across generations. + than ``n_survive``. The ``"pymoo"`` variant, the default, follows pymoo: two objectives use + M = 1 in the penalty, and the objectives are translated by the ideal point accumulated across + generations. The ``"platemo"`` variant follows the authors' code in PlatEMO + (``RVEA/EnvironmentalSelection.m``) and jMetal: M is the number of objectives, two included, + and the objectives are translated by the minimum of the candidates. Both return the + accumulated ideal point. """ if F.size == 0: return np.empty(0, dtype=int), ideal, None - n_obj = F.shape[1] ideal = np.minimum(F.min(axis=0), ideal) - - F_shift = F - ideal - dist_to_ideal = np.linalg.norm(F_shift, axis=1) - dist_to_ideal[dist_to_ideal < 1e-64] = 1e-64 - F_prime = F_shift / dist_to_ideal[:, None] - - cos_theta = np.clip(F_prime @ V.T, -1.0, 1.0) - acute_angle = np.arccos(cos_theta) - niches = acute_angle.argmin(axis=1) - - M = float(n_obj) if n_obj > 2 else 1.0 - progress = (n_gen / n_max_gen) ** alpha - theta = acute_angle[np.arange(F.shape[0]), niches] - penalty = M * progress * (theta / gamma[niches]) - apd = dist_to_ideal * (1.0 + penalty) + origin = F.min(axis=0) if variant == "platemo" else ideal + niches, _penalty, apd = angle_penalized_distances(F, origin, V, gamma, n_gen, n_max_gen, alpha, variant) order = np.lexsort((np.arange(F.shape[0]), apd, niches)) sorted_niches = niches[order] @@ -69,10 +93,11 @@ def constraint_aware_apd_survival( n_max_gen: int, alpha: float, constraint_mode: str, + variant: str = "pymoo", ) -> tuple[np.ndarray[Any, Any], np.ndarray[Any, Any], np.ndarray[Any, Any] | None]: """Apply feasibility-first ordering and APD diversity among feasible points.""" if G is None or constraint_mode == "none": - return apd_survival(F, V, gamma, ideal, n_survive, n_gen, n_max_gen, alpha) + return apd_survival(F, V, gamma, ideal, n_survive, n_gen, n_max_gen, alpha, variant) feasible = is_feasible(G, n=G.shape[0]) feasible_idx = np.flatnonzero(feasible) @@ -87,6 +112,7 @@ def constraint_aware_apd_survival( n_gen, n_max_gen, alpha, + variant, ) return np.asarray(feasible_idx[local], dtype=int), updated_ideal, nadir @@ -107,4 +133,4 @@ def constraint_aware_apd_survival( return survivors, updated_ideal, nadir -__all__ = ["apd_survival", "constraint_aware_apd_survival"] +__all__ = ["angle_penalized_distances", "apd_survival", "constraint_aware_apd_survival"] diff --git a/src/vamos/engine/config/variation.py b/src/vamos/engine/config/variation.py index f70415c34..b6771bdb5 100644 --- a/src/vamos/engine/config/variation.py +++ b/src/vamos/engine/config/variation.py @@ -39,6 +39,9 @@ class VariationOverrides(TypedDict, total=False): c2: float vmax_fraction: float n_partitions: int + # Development after 1.4.0: RVEA's reference vectors and NSGA-III's reference directions. + reference_vectors: Mapping[str, object] | str + reference_directions: Mapping[str, object] | str alpha: float adapt_freq: float diff --git a/src/vamos/engine/reference_directions.py b/src/vamos/engine/reference_directions.py index 01dab53bd..4b1ffe660 100644 --- a/src/vamos/engine/reference_directions.py +++ b/src/vamos/engine/reference_directions.py @@ -6,7 +6,7 @@ from __future__ import annotations -from math import comb +from math import comb, lcm import numpy as np import numpy.typing as npt @@ -69,4 +69,61 @@ def fill(depth: int, remaining: int) -> None: return weights -__all__ = ["das_dennis", "largest_lattice_divisions", "lattice_size"] +def two_layer_size(n_obj: int, divisions: int, inner_divisions: int) -> int: + """Return the number of directions of a two-layer lattice: both complete lattices. + + Development after 1.4.0: new. + """ + return lattice_size(n_obj, divisions) + lattice_size(n_obj, inner_divisions) + + +def two_layer_lattice(n_obj: int, divisions: int, inner_divisions: int) -> FloatArray: + """Return Deb and Jain's two-layer reference directions, one per row. + + With many objectives a lattice of few divisions has every direction on the boundary of the + simplex, and one more division multiplies the directions. Deb and Jain (2014) add an inside + layer instead: the boundary layer is the complete lattice of ``divisions`` and the + inside layer the complete lattice of ``inner_divisions`` shrunk by half towards the centre of + the simplex, ``w / 2 + 1 / (2 n_obj)``, as pymoo's multi-layer directions with scaling 0.5 and + PlatEMO's ``UniformPoint`` do. The boundary rows come first, each layer in the order of + :func:`das_dennis`. Eight objectives with ``divisions=3`` and ``inner_divisions=2`` give + 120 + 36 = 156 directions. + + The inside layer must add directions that the boundary layer does not have: two objectives with + ``divisions=4`` and ``inner_divisions=2`` would repeat all three inside directions, and a repeated + direction is a niche that never gets its own individual. Such settings raise ``ValueError`` (see + :func:`two_layer_shared`). + + Development after 1.4.0: new. + """ + shared = two_layer_shared(n_obj, divisions, inner_divisions) + if shared: + raise ValueError( + f"The inside layer of inner_divisions={inner_divisions} repeats {shared} of the directions of the boundary layer " + f"of divisions={divisions} for n_obj={n_obj}; choose layers that share no direction." + ) + return np.asarray(np.vstack(_two_layers(n_obj, divisions, inner_divisions)), dtype=float) + + +def two_layer_shared(n_obj: int, divisions: int, inner_divisions: int) -> int: + """Return how many directions of the inside layer the boundary layer already has. + + Every coordinate of either layer is a multiple of ``1 / lcm(divisions, 2 inner_divisions n_obj)``, + so the layers are compared exactly on that grid. A two-layer lattice needs 0. + + Development after 1.4.0: new. + """ + boundary, inside = _two_layers(n_obj, divisions, inner_divisions) + grid = lcm(divisions, 2 * inner_divisions * n_obj) + boundary_points = {tuple(row) for row in np.rint(boundary * grid).astype(np.int64).tolist()} + return sum(tuple(row) in boundary_points for row in np.rint(inside * grid).astype(np.int64).tolist()) + + +def _two_layers(n_obj: int, divisions: int, inner_divisions: int) -> tuple[FloatArray, FloatArray]: + """The boundary layer and the inside layer, shrunk by half towards the centre of the simplex.""" + boundary = das_dennis(n_obj, divisions) + inside = np.asarray(das_dennis(n_obj, inner_divisions) * 0.5 + 0.5 / n_obj, dtype=float) + return boundary, inside + + +__all__ = ["das_dennis", "largest_lattice_divisions", "lattice_size", "two_layer_lattice", "two_layer_shared", "two_layer_size"] diff --git a/src/vamos/experiment/_optimize_inputs.py b/src/vamos/experiment/_optimize_inputs.py index d67c8a830..2cf117712 100644 --- a/src/vamos/experiment/_optimize_inputs.py +++ b/src/vamos/experiment/_optimize_inputs.py @@ -4,8 +4,10 @@ import dataclasses from collections.abc import Mapping +from typing import cast from vamos.engine.algorithm.catalog import ENABLED_ALGORITHMS +from vamos.engine.algorithm.components.weight_vectors import bind_config_vector_files from vamos.engine.algorithm.config import GenericAlgorithmConfig from vamos.engine.algorithm.config.defaults import config_algorithm from vamos.engine.algorithm.config.types import AlgorithmConfigProtocol @@ -102,4 +104,14 @@ def with_archive_seed(algorithm_config: AlgorithmConfigProtocol, seed: int) -> A return dataclasses.replace(algorithm_config, external_archive=resolved) -__all__ = ["check_algorithm_config", "check_budget", "check_problem_arguments", "with_archive_seed"] +def with_run_inputs(algorithm_config: AlgorithmConfigProtocol, seed: int, n_obj: int) -> AlgorithmConfigProtocol: + """``algorithm_config`` as the run uses it and records it: its archive seed and its vector files resolved. + + Development after 1.4.0: a weight- or reference-vector file is bound to the file the run reads and the + digest of its vectors (:func:`~vamos.engine.algorithm.components.weight_vectors.bind_config_vector_files`), + so that replay refuses a file whose vectors have changed. + """ + return cast(AlgorithmConfigProtocol, bind_config_vector_files(with_archive_seed(algorithm_config, seed), n_obj)) + + +__all__ = ["check_algorithm_config", "check_budget", "check_problem_arguments", "with_archive_seed", "with_run_inputs"] diff --git a/src/vamos/experiment/artifacts/specs.py b/src/vamos/experiment/artifacts/specs.py index 0654aca28..1e912176b 100644 --- a/src/vamos/experiment/artifacts/specs.py +++ b/src/vamos/experiment/artifacts/specs.py @@ -11,7 +11,7 @@ from importlib import metadata as importlib_metadata from typing import Any -from vamos.engine.algorithm.components.weight_vectors import describe_weight_vectors +from vamos.engine.algorithm.components.weight_vectors import describe_vector_file, describe_weight_vectors from vamos.experiment.time_limit import parse_time_limit from vamos.foundation.problem.builder import FunctionalProblem from vamos.foundation.problem.registry import get_problem_specs, make_problem_selection @@ -213,20 +213,36 @@ def _algorithm_component(inputs: RunSpecInputs, config: Mapping[str, object], po # Which weight vectors MOEA/D runs: a Das-Dennis lattice, a jMetal file or uniform weights. weights = config.get("weight_vectors") options = weights if isinstance(weights, Mapping) else {} - path, divisions = options.get("path"), options.get("divisions") + path, divisions, inner = options.get("path"), options.get("divisions"), options.get("inner_divisions") + digest = options.get("sha256") try: descriptor["resolution"]["weight_vectors"] = describe_weight_vectors( pop_size, inputs.n_obj, path=path if isinstance(path, str) else None, - divisions=divisions if isinstance(divisions, int) and not isinstance(divisions, bool) else None, + divisions=_optional_int(divisions), + inner_divisions=_optional_int(inner), + sha256=digest if isinstance(digest, str) else None, ) except ValueError: # A size without weights fails when the run starts, so a study plans the task and records its failure. logging.getLogger(__name__).debug("No MOEA/D weight vectors to record for pop_size=%s", pop_size, exc_info=True) + vector_field = _VECTOR_FIELDS.get(inputs.algorithm) + if vector_field is not None and pop_size is not None: + # Development after 1.4.0: the file that NSGA-III's or RVEA's vectors come from. The configuration + # already states a lattice, so only a path is recorded, and a run without one keeps its 1.4.0 spec. The + # record comes from the stored configuration alone, never from the file. + vectors = config.get(vector_field) + path = vectors.get("path") if isinstance(vectors, Mapping) else None + if isinstance(path, str) and path: + descriptor["resolution"][vector_field] = describe_vector_file(path, vectors=pop_size if inputs.algorithm == "rvea" else None) return descriptor +# The option that names the reference vectors of NSGA-III and RVEA. +_VECTOR_FIELDS = {"nsgaiii": "reference_directions", "rvea": "reference_vectors"} + + def _operators(config: Mapping[str, object], *, encoding: str, n_var: int, algorithm: str) -> dict[str, Any]: operators: dict[str, Any] = {} for role in ("crossover", "mutation", "selection"): diff --git a/src/vamos/experiment/study/planning.py b/src/vamos/experiment/study/planning.py index db6328259..32a945910 100644 --- a/src/vamos/experiment/study/planning.py +++ b/src/vamos/experiment/study/planning.py @@ -2,13 +2,14 @@ from __future__ import annotations +import dataclasses from collections.abc import Mapping, Sequence from dataclasses import dataclass from itertools import product -from math import comb -from typing import Any +from typing import Any, cast from vamos.engine.algorithm.catalog import ENABLED_ALGORITHMS, WEIGHT_VECTOR_POPULATIONS, initial_evaluations, minimum_violation +from vamos.engine.algorithm.components.weight_vectors import bind_vector_file from vamos.engine.algorithm.config.base import ReferenceDirectionPopulationError from vamos.experiment.artifacts.models import deep_freeze, deep_thaw from vamos.experiment.artifacts.resolved_reconstruction import is_reconstructable_evaluation_backend @@ -21,6 +22,7 @@ from .errors import DuplicateStudyTaskError, InvalidStudySpecError, StudyError, UnresolvedStudyTaskError from .identity import compute_plan_id, compute_task_digest, compute_task_id from .models import SCHEMA_VERSION, PlanTask, ResolvedStudyPlan, StudySpec +from .reference_planning import validate_nsgaiii_reference_directions, validate_rvea_reference_directions from .serialization import document_self_hash @@ -190,15 +192,22 @@ def _resolved_algorithm_config( override_pop_size = overrides.get("pop_size") if isinstance(override_pop_size, int) and not isinstance(override_pop_size, bool): config_pop_size = override_pop_size + # Development after 1.4.0: RVEA's reference_vectors set its vectors, so its default does not derive a + # lattice from the population, which then need not be a lattice; the planning checks below compare them. + own_vectors = algorithm.lower() == "rvea" and overrides.get("reference_vectors") is not None built = _build_algorithm_config( algorithm, - pop_size=config_pop_size, + pop_size=None if own_vectors else config_pop_size, n_var=n_var, n_obj=n_obj, encoding=encoding, ) config = dict(built.to_dict()) - unknown = sorted(set(overrides) - set(config)) + if own_vectors and config_pop_size is not None: + config["pop_size"] = config_pop_size + # A field that to_dict() leaves out at its default is still a field. + known = set(config) | _config_fields(built) + unknown = sorted(set(overrides) - known) if unknown: raise UnresolvedStudyTaskError( operation="resolve study plan", @@ -209,9 +218,21 @@ def _resolved_algorithm_config( action="Remove unknown algorithm configuration fields; no study directory was published.", ) config.update(overrides) + pop_size = config.get("pop_size") + if algorithm.lower() == "moead" and n_obj > 2 and isinstance(pop_size, int): + # Development after 1.4.0: a weight file that exists is bound to its digest, which the run checks. + config["weight_vectors"] = bind_vector_file(config.get("weight_vectors"), n_obj, pop_size) return config +def _config_fields(config: object) -> set[str]: + """The fields of a configuration dataclass, or none for another configuration.""" + try: + return {field.name for field in dataclasses.fields(cast(Any, config))} + except TypeError: + return set() + + def _algorithm_overrides(spec: StudySpec, requested: str, resolved: str) -> dict[str, Any]: configs = spec.algorithm_configs or {} raw = configs.get(requested, configs.get(resolved, {})) @@ -269,9 +290,9 @@ def _validate_execution_shape( action="Increase max_evaluations or reduce the population; no study directory was published.", ) if algorithm.lower() == "nsgaiii": - _validate_nsgaiii_reference_directions(config, population=population, n_obj=n_obj, candidate=candidate) + validate_nsgaiii_reference_directions(config, population=population, n_obj=n_obj, index=candidate.index) if algorithm.lower() == "rvea": - _validate_rvea_reference_directions(config, population=population, n_obj=n_obj, candidate=candidate) + validate_rvea_reference_directions(config, population=population, n_obj=n_obj, index=candidate.index) return population @@ -294,72 +315,6 @@ def _reject_below_minimum( ) -def _validate_nsgaiii_reference_directions(config: Mapping[str, Any], *, population: int, n_obj: int, candidate: _Candidate) -> None: - raw = config.get("reference_directions") - if not isinstance(raw, Mapping): - raise UnresolvedStudyTaskError( - operation="resolve study plan", - reason="INVALID_REFERENCE_DIRECTIONS", - field=f"$.matrix[{candidate.index}].algorithm_config.reference_directions", - expected="object with path=null and positive integer divisions", - actual=type(raw).__name__, - action="Use generated built-in reference directions; planning never reads an external source path.", - ) - path = raw.get("path") - divisions = raw.get("divisions") - if path is not None: - raise UnresolvedStudyTaskError( - operation="resolve study plan", - reason="UNSAFE_REFERENCE_DIRECTIONS", - field=f"$.matrix[{candidate.index}].algorithm_config.reference_directions.path", - expected="null (built-in generated reference directions)", - actual="external path", - action="Remove the reference-direction path; planning never follows external scientific inputs.", - ) - if isinstance(divisions, bool) or not isinstance(divisions, int) or divisions < 1: - raise UnresolvedStudyTaskError( - operation="resolve study plan", - reason="INVALID_REFERENCE_DIRECTIONS", - field=f"$.matrix[{candidate.index}].algorithm_config.reference_directions.divisions", - expected="positive integer", - actual=divisions, - action="Choose a positive reference-direction division count.", - ) - expected = comb(divisions + n_obj - 1, n_obj - 1) - if population < expected: - raise UnresolvedStudyTaskError( - operation="resolve study plan", - reason="REFERENCE_DIRECTION_POPULATION_MISMATCH", - field=f"$.matrix[{candidate.index}].pop_size", - expected=f">= {expected} for n_obj={n_obj} and divisions={divisions}", - actual=population, - action="Use at least the reference-direction count as pop_size or choose fewer divisions.", - ) - - -def _validate_rvea_reference_directions(config: Mapping[str, Any], *, population: int, n_obj: int, candidate: _Candidate) -> None: - partitions = config.get("n_partitions") - if isinstance(partitions, bool) or not isinstance(partitions, int) or partitions < 1: - raise UnresolvedStudyTaskError( - operation="resolve study plan", - reason="INVALID_REFERENCE_DIRECTIONS", - field=f"$.matrix[{candidate.index}].algorithm_config.n_partitions", - expected="positive integer", - actual=partitions, - action="Choose a positive RVEA reference-vector partition count.", - ) - expected = comb(partitions + n_obj - 1, n_obj - 1) - if population != expected: - raise UnresolvedStudyTaskError( - operation="resolve study plan", - reason="REFERENCE_DIRECTION_POPULATION_MISMATCH", - field=f"$.matrix[{candidate.index}].pop_size", - expected=f"{expected} for n_obj={n_obj} and n_partitions={partitions}", - actual=population, - action="Use the reference-vector count as pop_size or choose compatible n_partitions.", - ) - - def _validate_resolved_components(resolved: Mapping[str, Any], *, candidate: _Candidate) -> None: component_fields: list[tuple[str, object]] = [ ("problem", resolved.get("problem")), diff --git a/src/vamos/experiment/study/reference_planning.py b/src/vamos/experiment/study/reference_planning.py new file mode 100644 index 000000000..b2396f1d6 --- /dev/null +++ b/src/vamos/experiment/study/reference_planning.py @@ -0,0 +1,138 @@ +"""Study planning checks of the reference directions of NSGA-III and the reference vectors of RVEA. + +Planning never reads an external source of vectors: a path is rejected, and a lattice must fit the +population (NSGA-III needs at least one individual per direction, RVEA exactly one per vector). +""" + +from __future__ import annotations + +from collections.abc import Mapping +from math import comb +from typing import Any + +from vamos.engine.reference_directions import two_layer_shared + +from .errors import UnresolvedStudyTaskError + + +def validate_nsgaiii_reference_directions(config: Mapping[str, Any], *, population: int, n_obj: int, index: int) -> None: + raw = config.get("reference_directions") + if not isinstance(raw, Mapping): + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="INVALID_REFERENCE_DIRECTIONS", + field=f"$.matrix[{index}].algorithm_config.reference_directions", + expected="object with path=null and positive integer divisions", + actual=type(raw).__name__, + action="Use generated built-in reference directions; planning never reads an external source path.", + ) + path = raw.get("path") + divisions = raw.get("divisions") + if path is not None: + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="UNSAFE_REFERENCE_DIRECTIONS", + field=f"$.matrix[{index}].algorithm_config.reference_directions.path", + expected="null (built-in generated reference directions)", + actual="external path", + action="Remove the reference-direction path; planning never follows external scientific inputs.", + ) + if isinstance(divisions, bool) or not isinstance(divisions, int) or divisions < 1: + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="INVALID_REFERENCE_DIRECTIONS", + field=f"$.matrix[{index}].algorithm_config.reference_directions.divisions", + expected="positive integer", + actual=divisions, + action="Choose a positive reference-direction division count.", + ) + inner = _inner_divisions(raw, "reference_directions", index, divisions=divisions, n_obj=n_obj) + expected = comb(divisions + n_obj - 1, n_obj - 1) + (0 if inner is None else comb(inner + n_obj - 1, n_obj - 1)) + lattice = f"divisions={divisions}" if inner is None else f"divisions={divisions} and inner_divisions={inner}" + if population < expected: + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="REFERENCE_DIRECTION_POPULATION_MISMATCH", + field=f"$.matrix[{index}].pop_size", + expected=f">= {expected} for n_obj={n_obj} and {lattice}", + actual=population, + action="Use at least the reference-direction count as pop_size or choose fewer divisions.", + ) + + +def _inner_divisions(raw: Mapping[str, Any], field: str, index: int, *, divisions: int, n_obj: int) -> int | None: + """Development after 1.4.0: the inside layer of a two-layer lattice, ``None`` without one. + + An inside layer that repeats directions of the boundary layer is rejected, as the run would reject it. + """ + inner = raw.get("inner_divisions") + if inner is not None and (isinstance(inner, bool) or not isinstance(inner, int) or inner < 1): + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="INVALID_REFERENCE_DIRECTIONS", + field=f"$.matrix[{index}].algorithm_config.{field}.inner_divisions", + expected="positive integer or null", + actual=inner, + action="Choose a positive division count for the inside layer, or leave it out.", + ) + shared = 0 if inner is None or n_obj < 2 else two_layer_shared(n_obj, divisions, inner) + if shared: + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="INVALID_REFERENCE_DIRECTIONS", + field=f"$.matrix[{index}].algorithm_config.{field}.inner_divisions", + expected=f"an inside layer that shares no direction with the boundary layer of divisions={divisions}", + actual=f"inner_divisions={inner} repeats {shared} direction(s) for n_obj={n_obj}", + action="Choose other divisions or inner_divisions.", + ) + return inner + + +def validate_rvea_reference_directions(config: Mapping[str, Any], *, population: int, n_obj: int, index: int) -> None: + vectors = config.get("reference_vectors") + if vectors is not None and not isinstance(vectors, Mapping): + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="INVALID_REFERENCE_DIRECTIONS", + field=f"$.matrix[{index}].algorithm_config.reference_vectors", + expected="object with path=null and positive integer divisions, or null", + actual=type(vectors).__name__, + action="Use generated built-in reference vectors; planning never reads an external source path.", + ) + vectors = vectors or {} + if vectors.get("path") is not None: + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="UNSAFE_REFERENCE_DIRECTIONS", + field=f"$.matrix[{index}].algorithm_config.reference_vectors.path", + expected="null (built-in generated reference vectors)", + actual="external path", + action="Remove the reference-vector path; planning never follows external scientific inputs.", + ) + # Development after 1.4.0: reference_vectors.divisions takes the place of n_partitions. + use_divisions = vectors.get("divisions") is not None + partitions = vectors.get("divisions") if use_divisions else config.get("n_partitions") + if isinstance(partitions, bool) or not isinstance(partitions, int) or partitions < 1: + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="INVALID_REFERENCE_DIRECTIONS", + field=f"$.matrix[{index}].algorithm_config." + ("reference_vectors.divisions" if use_divisions else "n_partitions"), + expected="positive integer", + actual=partitions, + action="Choose a positive RVEA reference-vector partition count.", + ) + inner = _inner_divisions(vectors, "reference_vectors", index, divisions=partitions, n_obj=n_obj) + expected = comb(partitions + n_obj - 1, n_obj - 1) + (0 if inner is None else comb(inner + n_obj - 1, n_obj - 1)) + lattice = f"n_partitions={partitions}" if inner is None else f"divisions={partitions} and inner_divisions={inner}" + if population != expected: + raise UnresolvedStudyTaskError( + operation="resolve study plan", + reason="REFERENCE_DIRECTION_POPULATION_MISMATCH", + field=f"$.matrix[{index}].pop_size", + expected=f"{expected} for n_obj={n_obj} and {lattice}", + actual=population, + action="Use the reference-vector count as pop_size or choose compatible n_partitions.", + ) + + +__all__ = ["validate_nsgaiii_reference_directions", "validate_rvea_reference_directions"] diff --git a/src/vamos/experiment/unified.py b/src/vamos/experiment/unified.py index baaa98dc9..929a4bc4f 100644 --- a/src/vamos/experiment/unified.py +++ b/src/vamos/experiment/unified.py @@ -18,7 +18,7 @@ from vamos.engine.algorithm.catalog import minimum_violation from vamos.engine.algorithm.config.types import AlgorithmConfigProtocol, AlgorithmName, EngineName -from vamos.experiment._optimize_inputs import check_algorithm_config, check_budget, check_problem_arguments, with_archive_seed +from vamos.experiment._optimize_inputs import check_algorithm_config, check_budget, check_problem_arguments, with_run_inputs from vamos.experiment.artifacts.specs import RunSpecInputs, build_run_specs, custom_problem_code, is_registry_problem from vamos.experiment.auto import _compute_max_evaluations, _compute_pop_size, _resolve_problem, _select_algorithm from vamos.experiment.optimization_result import OptimizationResult, StudyResult @@ -402,7 +402,7 @@ def _run_single( f"Conflicting pop_size: pop_size={pop_size} but algorithm_config.pop_size={cfg_pop_size_int}. " "Set pop_size on algorithm_config (single source of truth)." ) - algo_cfg = with_archive_seed(algorithm_config, seed) + algo_cfg = with_run_inputs(algorithm_config, seed, n_obj) algo_cfg_dict = dict(algo_cfg.to_dict()) resolved_pop_size = algo_cfg_dict.get("pop_size") diff --git a/tests/architecture/public_api_snapshot.json b/tests/architecture/public_api_snapshot.json index 9008a1249..90ec53daa 100644 --- a/tests/architecture/public_api_snapshot.json +++ b/tests/architecture/public_api_snapshot.json @@ -56,6 +56,7 @@ "available_crossover_methods", "available_mutation_methods", "discover_algorithm_plugins", + "moead_populations", "resolve_algorithm" ], "vamos.api": [ diff --git a/tests/engine/test_constraint_handling_algorithms.py b/tests/engine/test_constraint_handling_algorithms.py index 48b68b6bf..d89b32ab7 100644 --- a/tests/engine/test_constraint_handling_algorithms.py +++ b/tests/engine/test_constraint_handling_algorithms.py @@ -115,6 +115,9 @@ def test_constraint_handling_follows_the_fields_of_1_0(config_class: Any) -> Non added = ["constraint_handling"] if config_class is NSGAIIConfig else ["constraint_handling", "live_callback_mode"] if config_class is AGEMOEAConfig: added.append("variant") # Development after 1.4.0: AGE-MOEA-II + if config_class is RVEAConfig: + added.append("reference_vectors") # Development after 1.4.0: vectors from a file or a two-layer lattice + added.append("variant") # Development after 1.4.0: the PlatEMO/jMetal reading of the survival assert names[position:] == added assert fields[position].default is None diff --git a/tests/engine/test_reference_vector_sources.py b/tests/engine/test_reference_vector_sources.py new file mode 100644 index 000000000..254d4256d --- /dev/null +++ b/tests/engine/test_reference_vector_sources.py @@ -0,0 +1,457 @@ +"""MOEA/D, NSGA-III and RVEA take their vectors from one kind of option: a file, a directory or a lattice.""" + +from __future__ import annotations + +import dataclasses +from math import comb +from pathlib import Path +from typing import Any + +import numpy as np +import pytest + +import vamos +from vamos.algorithms import MOEADConfig, NSGAIIIConfig, RVEAConfig, moead_populations +from vamos.engine.algorithm.components.weight_vectors import load_or_generate_weight_vectors, read_weight_vectors, vector_digest +from vamos.engine.algorithm.moead import MOEAD +from vamos.engine.algorithm.nsgaiii import NSGAIII +from vamos.engine.algorithm.rvea import RVEA +from vamos.engine.reference_directions import das_dennis, two_layer_lattice, two_layer_shared, two_layer_size +from vamos.exceptions import ConfigurationError, RunArtifactError +from vamos.foundation.kernel.numpy_backend import NumPyKernel +from vamos.foundation.problem.dtlz import DTLZ2Problem +from vamos.resources import weight_path + +Source = dict[str, Any] + + +def _moead(pop_size: int, source: Source) -> MOEADConfig: + return ( + MOEADConfig.builder() + .pop_size(pop_size) + .neighbor_size(20) + .delta(0.9) + .replace_limit(2) + .crossover("sbx", prob=0.9, eta=20.0) + .mutation("pm", prob="1/n", eta=20.0) + .aggregation("tchebycheff") + .weight_vectors(**source) + .build() + ) + + +def _nsgaiii(pop_size: int, source: Source) -> NSGAIIIConfig: + return ( + NSGAIIIConfig.builder() + .pop_size(pop_size) + .crossover("sbx", prob=0.9, eta=30.0) + .mutation("pm", prob="1/n", eta=20.0) + .selection("tournament") + .reference_directions(**source) + .build() + ) + + +def _rvea(pop_size: int, source: Source) -> RVEAConfig: + return ( + RVEAConfig.builder() + .pop_size(pop_size) + .reference_vectors(**source) + .alpha(2.0) + .adapt_freq(0.1) + .crossover("sbx", prob=0.9, eta=30.0) + .mutation("pm", prob="1/n", eta=20.0) + .build() + ) + + +def _start(algorithm: str, pop_size: int, n_obj: int, source: Source) -> np.ndarray: + """The vectors each algorithm starts from, after its initial population is evaluated.""" + problem = DTLZ2Problem(n_var=n_obj + 9, n_obj=n_obj) + termination = ("max_evaluations", 2 * pop_size) + kernel = NumPyKernel() + if algorithm == "moead": + moead = MOEAD(_moead(pop_size, source).to_dict(), kernel=kernel) + moead.initialize(problem, termination, seed=1) + assert moead._st is not None + return np.asarray(moead._st.weights) + if algorithm == "nsgaiii": + nsgaiii = NSGAIII(_nsgaiii(pop_size, source).to_dict(), kernel=kernel) + nsgaiii.initialize(problem, termination, seed=1) + assert nsgaiii.state is not None + return np.asarray(nsgaiii.state.ref_dirs) + rvea = RVEA(_rvea(pop_size, source).to_dict(), kernel=kernel) + rvea.initialize(problem, termination, seed=1) + assert rvea.state is not None + return np.asarray(rvea.state.ref_dirs) + + +ALGORITHMS = ("moead", "nsgaiii", "rvea") + + +@pytest.mark.parametrize(("n_obj", "pop_size"), [(3, 100), (8, 156)]) +@pytest.mark.parametrize("by", ["file", "directory"]) +def test_the_three_algorithms_start_from_the_same_jmetal_file(n_obj: int, pop_size: int, by: str) -> None: + file = weight_path(f"W{n_obj}D_{pop_size}.dat") + path = str(file) if by == "file" else str(file.parent) + expected = read_weight_vectors(str(file), n_obj) + + for algorithm in ALGORITHMS: + np.testing.assert_array_equal(_start(algorithm, pop_size, n_obj, {"path": path}), expected, err_msg=algorithm) + + +def test_the_three_algorithms_start_from_the_same_two_layer_lattice() -> None: + expected = two_layer_lattice(8, 3, 2) + + for algorithm in ALGORITHMS: + np.testing.assert_array_equal(_start(algorithm, 156, 8, {"divisions": 3, "inner_divisions": 2}), expected, err_msg=algorithm) + + +def test_layers_that_repeat_directions_are_rejected() -> None: + # Two objectives, 4 and 2 divisions: the three inside directions (1/4, 3/4), (1/2, 1/2) and (3/4, 1/4) are + # all on the boundary lattice, so the eight rows would hold five directions. + assert two_layer_shared(2, 4, 2) == 3 + assert two_layer_shared(8, 3, 2) == 0 and two_layer_shared(10, 2, 1) == 0 + with pytest.raises(ValueError, match="repeats 3"): + two_layer_lattice(2, 4, 2) + + +@pytest.mark.parametrize("algorithm", ALGORITHMS) +def test_every_algorithm_rejects_layers_that_repeat_directions(algorithm: str) -> None: + shared = two_layer_shared(3, 3, 3) + assert shared > 0 + + with pytest.raises(ConfigurationError, match=f"repeats {shared}"): + _start(algorithm, two_layer_size(3, 3, 3), 3, {"divisions": 3, "inner_divisions": 3}) + + +_FIELDS = {"moead": "weight_vectors", "nsgaiii": "reference_directions", "rvea": "reference_vectors"} +_BUILD = {"moead": _moead, "nsgaiii": _nsgaiii, "rvea": _rvea} + + +@pytest.mark.parametrize("algorithm", ALGORITHMS) +def test_a_run_records_its_vector_file_by_content_and_verifies_without_it(algorithm: str, tmp_path: Path) -> None: + file = tmp_path / "custom.csv" + vectors = np.loadtxt(weight_path("W3D_91.dat")) + np.savetxt(file, vectors, delimiter=",") + config = _BUILD[algorithm](91, {"path": str(tmp_path / "custom.csv")}) + result = vamos.optimize("dtlz2", algorithm=algorithm, algorithm_config=config, n_obj=3, max_evaluations=182, seed=1, engine="numpy") + resolved = result.meta["run_artifact_resolved_spec"]["algorithm"] + field = _FIELDS[algorithm] + + assert resolved["config"][field]["sha256"] == vector_digest(read_weight_vectors(str(file), 3)) + assert resolved["resolution"][field]["file"] == "custom.csv" + source = vamos.save_result(result, tmp_path / "source") + + # Rewritten with spaces, the file holds the same vectors: the digest is that of the values, and replay is exact. + np.savetxt(file, vectors) + assert vamos.reproduce(source.root, output=tmp_path / "same").exact is True + + # Moved away or on another machine: verification rebuilds the record from the stored configuration alone. + file.rename(tmp_path / "moved.csv") + assert vamos.verify_run(source.root).effective_replayability == "exact" + + # Other vectors of the same shape: replay refuses them before any evaluation instead of running another experiment. + np.savetxt(file, das_dennis(3, 12)[::-1]) + with pytest.raises(RunArtifactError, match="ConfigurationError"): + vamos.reproduce(source.root, output=tmp_path / "other") + + +def test_a_directory_is_recorded_as_the_file_the_run_read() -> None: + directory = str(weight_path("W3D_100.dat").parent) + result = vamos.optimize( + "dtlz2", algorithm="rvea", algorithm_config=_rvea(100, {"path": directory}), n_obj=3, max_evaluations=200, seed=1 + ) + vectors = result.meta["run_artifact_resolved_spec"]["algorithm"]["config"]["reference_vectors"] + + assert vectors["path"] == str(weight_path("W3D_100.dat")) + assert vectors["sha256"] == vector_digest(read_weight_vectors(str(weight_path("W3D_100.dat")), 3)) + + +def test_a_recorded_digest_is_checked_and_needs_a_path(tmp_path: Path) -> None: + file = tmp_path / "W3D_91.dat" + np.savetxt(file, np.loadtxt(weight_path("W3D_91.dat"))) + wrong = "sha256:" + "0" * 64 + + for algorithm in ALGORITHMS: + config = dataclasses.replace(_BUILD[algorithm](91, {"divisions": 12}), **{_FIELDS[algorithm]: {"path": str(file), "sha256": wrong}}) + with pytest.raises(ConfigurationError, match="no longer holds"): + vamos.optimize("dtlz2", algorithm=algorithm, algorithm_config=config, n_obj=3, max_evaluations=182, seed=1) + with pytest.raises(ConfigurationError, match="needs path"): + dataclasses.replace(_rvea(91, {"divisions": 12}), reference_vectors={"divisions": 12, "sha256": wrong}) + with pytest.raises(ConfigurationError, match="64 lower-case"): + dataclasses.replace(_rvea(91, {"divisions": 12}), reference_vectors={"path": str(file), "sha256": "abc"}) + + +def test_study_planning_rejects_layers_that_repeat_directions() -> None: + from vamos.experiment.study.errors import UnresolvedStudyTaskError + + size = two_layer_size(3, 3, 3) + spec = vamos.StudySpec( + problems=["dtlz2"], + algorithms=["rvea"], + seeds=[0], + pop_size=size, + n_obj=3, + max_evaluations=2 * size, + engine="numpy", + algorithm_configs={"rvea": {"reference_vectors": {"divisions": 3, "inner_divisions": 3}}}, + ) + + with pytest.raises(UnresolvedStudyTaskError, match="INVALID_REFERENCE_DIRECTIONS"): + vamos.plan_study(spec) + + +def test_a_two_layer_lattice_of_eight_objectives_has_the_size_of_jmetals_file() -> None: + lattice = two_layer_lattice(8, 3, 2) + + assert two_layer_size(8, 3, 2) == 156 == len(lattice) == len(np.loadtxt(weight_path("W8D_156.dat"))) + np.testing.assert_allclose(lattice.sum(axis=1), 1.0, atol=1e-12) + np.testing.assert_array_equal(lattice[:120], das_dennis(8, 3)) + np.testing.assert_allclose(lattice[120:], das_dennis(8, 2) / 2 + 1 / 16, atol=1e-15) + # The inside layer lies off the boundary; jMetal's file stacks the two lattices unshrunk, so it repeats the axes. + assert lattice[120:].min() >= 1 / 16 - 1e-15 + assert len(np.unique(lattice, axis=0)) == 156 + + +@pytest.mark.parametrize("algorithm", ALGORITHMS) +def test_a_missing_path_raises_before_any_evaluation(algorithm: str, tmp_path: Path) -> None: + missing = tmp_path / "missing" / "W3D_91.dat" + + with pytest.raises(ConfigurationError, match="does not exist"): + _start(algorithm, 91, 3, {"path": str(missing)}) + assert not missing.parent.exists() + + +@pytest.mark.parametrize("algorithm", ["nsgaiii", "rvea"]) +def test_a_directory_without_the_file_raises(algorithm: str, tmp_path: Path) -> None: + with pytest.raises(ConfigurationError, match=r"W3D_91\.dat"): + _start(algorithm, 91, 3, {"path": str(tmp_path)}) + + +def test_moead_keeps_saving_the_lattice_in_a_directory_without_the_file(tmp_path: Path) -> None: + with pytest.warns(RuntimeWarning, match="Generated and saved"): + weights = _start("moead", 91, 3, {"path": str(tmp_path)}) + + np.testing.assert_array_equal(np.loadtxt(tmp_path / "W3D_91.dat"), weights) + + +@pytest.mark.parametrize("algorithm", ["moead", "rvea"]) +def test_a_file_with_another_number_of_vectors_raises(algorithm: str) -> None: + with pytest.raises(ValueError, match="100"): + _start(algorithm, 91, 3, {"path": str(weight_path("W3D_100.dat"))}) + + +def test_rvea_runs_100_individuals_with_three_objectives_from_jmetals_file() -> None: + config = _rvea(100, {"path": str(weight_path("W3D_100.dat"))}) + + result = vamos.optimize("dtlz2", algorithm="rvea", algorithm_config=config, n_obj=3, max_evaluations=500, seed=1, engine="numpy") + + assert result.data["evaluations"] == 500 + assert result.meta["run_artifact_resolved_spec"]["population"]["initial_size"] == 100 + assert config.n_partitions == 12 # not used with reference_vectors + + +def test_rvea_divisions_are_the_lattice_of_n_partitions() -> None: + by_partitions = RVEAConfig.default(pop_size=91, n_obj=3) + by_vectors = dataclasses.replace(by_partitions, reference_vectors={"divisions": 12}) + + first = vamos.optimize("dtlz2", algorithm="rvea", algorithm_config=by_partitions, max_evaluations=300, seed=3, engine="numpy") + second = vamos.optimize("dtlz2", algorithm="rvea", algorithm_config=by_vectors, max_evaluations=300, seed=3, engine="numpy") + + np.testing.assert_array_equal(first.F, second.F) + + +@pytest.mark.parametrize( + ("value", "message"), + [ + ({"path": None, "divisons": 3}, "divisons"), + ({"divisions": 0}, "positive integer"), + ({"divisions": True}, "positive integer"), + ({"inner_divisions": 2}, "needs divisions"), + ({"path": "W3D_100.dat", "divisions": 3, "inner_divisions": 2}, "file or a lattice"), + ({"path": 3}, "path"), + (12, "mapping"), + ], +) +@pytest.mark.parametrize("build", [_moead, _nsgaiii, _rvea]) +def test_invalid_vector_options_are_rejected_when_the_configuration_is_built(build: Any, value: Any, message: str) -> None: + config = build(91, {"divisions": 12}) + field = {"MOEADConfig": "weight_vectors", "NSGAIIIConfig": "reference_directions", "RVEAConfig": "reference_vectors"} + + with pytest.raises(ConfigurationError, match=message): + dataclasses.replace(config, **{field[type(config).__name__]: value}) + + +def test_a_path_string_is_a_path_and_configurations_round_trip(tmp_path: Path) -> None: + path = str(weight_path("W3D_100.dat")) + rvea = dataclasses.replace(RVEAConfig.default(pop_size=91, n_obj=3), reference_vectors=path) + + assert rvea.reference_vectors == {"path": path, "divisions": None} + for config in (rvea, _moead(156, {"divisions": 3, "inner_divisions": 2}), _nsgaiii(156, {"divisions": 3, "inner_divisions": 2})): + assert type(config).from_dict(config.to_dict()) == config + + +def test_configurations_without_the_new_options_serialize_as_before() -> None: + # VAMOS 1.4.0's to_dict(): no reference_vectors for RVEA, no inner_divisions in the other two. + assert "reference_vectors" not in RVEAConfig.default(n_obj=3).to_dict() + assert NSGAIIIConfig.default(n_obj=3).to_dict()["reference_directions"] == {"path": None, "divisions": 12} + assert MOEADConfig.default(n_obj=3).to_dict()["weight_vectors"] == {"path": None, "divisions": 12} + assert NSGAIIIConfig.builder().pop_size(10).crossover("sbx").mutation("pm").selection("tournament").build().reference_directions == {} + + +def _resolved(algorithm: str, config: Any, n_obj: int, budget: int) -> dict[str, Any]: + result = vamos.optimize( + "dtlz2", algorithm=algorithm, algorithm_config=config, n_obj=n_obj, max_evaluations=budget, seed=1, engine="numpy" + ) + return dict(result.meta["run_artifact_resolved_spec"]["algorithm"]["resolution"]) + + +def test_the_resolved_spec_records_a_file_and_a_two_layer_lattice() -> None: + path = str(weight_path("W3D_100.dat")) + + assert _resolved("nsgaiii", _nsgaiii(100, {"path": path}), 3, 200)["reference_directions"] == {"source": "file", "file": "W3D_100.dat"} + assert _resolved("rvea", _rvea(100, {"path": path}), 3, 200)["reference_vectors"] == { + "source": "file", + "file": "W3D_100.dat", + "vectors": 100, + } + assert _resolved("moead", _moead(156, {"divisions": 3, "inner_divisions": 2}), 8, 312)["weight_vectors"] == { + "source": "two_layer", + "divisions": 3, + "inner_divisions": 2, + "vectors": 156, + } + # A lattice is stated by the configuration: NSGA-III and RVEA keep the resolution of VAMOS 1.4.0. + assert _resolved("nsgaiii", NSGAIIIConfig.default(pop_size=91, n_obj=3), 3, 182) == {"contract_version": 1} + assert _resolved("rvea", RVEAConfig.default(pop_size=91, n_obj=3), 3, 182) == {"contract_version": 1} + + +@pytest.mark.parametrize( + ("algorithm", "config", "n_obj"), + [ + ("rvea", _rvea(100, {"path": str(weight_path("W3D_100.dat"))}), 3), + ("nsgaiii", _nsgaiii(100, {"path": str(weight_path("W3D_91.dat").parent)}), 3), + ("moead", _moead(156, {"divisions": 3, "inner_divisions": 2}), 8), + ("rvea", _rvea(156, {"divisions": 3, "inner_divisions": 2}), 8), + ], +) +def test_runs_with_the_new_options_replay_exactly(algorithm: str, config: Any, n_obj: int, tmp_path: Path) -> None: + result = vamos.optimize("dtlz2", algorithm=algorithm, algorithm_config=config, n_obj=n_obj, max_evaluations=2 * config.pop_size, seed=1) + source = vamos.save_result(result, tmp_path / "source") + + assert vamos.verify_run(source.root).effective_replayability == "exact" + assert vamos.reproduce(source.root, output=tmp_path / "replay").exact is True + + +def test_the_command_line_builder_reads_rvea_reference_vectors() -> None: + from vamos.engine.algorithm.factory import build_algorithm + from vamos.foundation.core.experiment_config import ExperimentConfig + + problem = DTLZ2Problem(n_var=12, n_obj=3) + config = ExperimentConfig(population_size=100) + variations = {"rvea": {"reference_vectors": str(weight_path("W3D_100.dat"))}} + + algorithm, resolved = build_algorithm("rvea", "numpy", problem, config, variations=variations) + result = algorithm.run(problem, termination=("max_evaluations", 200), seed=1) + + file = str(weight_path("W3D_100.dat")) + assert resolved.reference_vectors == {"path": file, "divisions": None, "sha256": vector_digest(read_weight_vectors(file, 3))} + assert result["evaluations"] == 200 + + +def test_study_planning_checks_rvea_reference_vectors() -> None: + def plan(pop_size: int, config: dict[str, Any]) -> Any: + spec = vamos.StudySpec( + problems=["dtlz2"], + algorithms=["rvea"], + seeds=[0], + pop_size=pop_size, + n_obj=8, + max_evaluations=2 * pop_size, + engine="numpy", + algorithm_configs={"rvea": config}, + ) + return vamos.plan_study(spec) + + from vamos.experiment.study.errors import UnresolvedStudyTaskError + + planned = plan(156, {"reference_vectors": {"divisions": 3, "inner_divisions": 2}}) + assert planned.valid + assert planned.plan.tasks[0].resolved_run_spec["population"]["initial_size"] == 156 + with pytest.raises(UnresolvedStudyTaskError, match="REFERENCE_DIRECTION_POPULATION_MISMATCH"): + plan(150, {"reference_vectors": {"divisions": 3, "inner_divisions": 2}}) + with pytest.raises(UnresolvedStudyTaskError, match="UNSAFE_REFERENCE_DIRECTIONS"): + plan(156, {"reference_vectors": {"path": str(weight_path("W8D_156.dat"))}}) + + +def test_study_planning_checks_an_nsgaiii_two_layer_lattice() -> None: + from vamos.experiment.study.errors import UnresolvedStudyTaskError + + def plan(pop_size: int) -> Any: + directions = {"path": None, "divisions": 3, "inner_divisions": 2} + spec = vamos.StudySpec( + problems=["dtlz2"], + algorithms=["nsgaiii"], + seeds=[0], + pop_size=pop_size, + n_obj=8, + max_evaluations=2 * pop_size, + engine="numpy", + algorithm_configs={"nsgaiii": {"reference_directions": directions}}, + ) + return vamos.plan_study(spec) + + assert plan(160).valid + with pytest.raises(UnresolvedStudyTaskError, match=">= 156"): + plan(150) + + +def test_moead_populations_lists_the_lattices_and_the_packaged_files() -> None: + assert moead_populations(3, max_pop_size=110) == (3, 6, 10, 15, 21, 28, 36, 45, 55, 66, 78, 91, 100, 105) + assert moead_populations(4, max_pop_size=200) == (4, 10, 20, 35, 56, 84, 100, 120, 165) + assert moead_populations(8, max_pop_size=200) == (8, 36, 120, 156) + assert moead_populations(2, max_pop_size=5) == (2, 3, 4, 5) + assert moead_populations(20, max_pop_size=1000) == (20, 210) + + +@pytest.mark.parametrize("n_obj", range(4, 21)) +def test_the_populations_listed_for_4_to_20_objectives_run(n_obj: int) -> None: + sizes = moead_populations(n_obj, max_pop_size=300) + + assert sizes and sizes[0] == n_obj + for size in sizes: + assert load_or_generate_weight_vectors(size, n_obj, mode="jmetalpy").shape == (size, n_obj) + assert MOEADConfig.default(pop_size=size, n_obj=n_obj).pop_size == size + smallest = sizes[0] + result = vamos.optimize("dtlz2", algorithm="moead", pop_size=smallest, n_obj=n_obj, max_evaluations=2 * smallest, seed=1) + assert result.data["evaluations"] == 2 * smallest + + +def test_moead_runs_a_two_layer_lattice_that_no_single_lattice_has() -> None: + # Ten objectives: single lattices have 10, 55, 220 and 715 vectors; two layers of 2 and 1 divisions give 65. + assert 65 not in moead_populations(10) + config = _moead(comb(11, 9) + 10, {"divisions": 2, "inner_divisions": 1}) + + result = vamos.optimize("dtlz2", algorithm="moead", algorithm_config=config, n_obj=10, max_evaluations=130, seed=1) + + np.testing.assert_array_equal(result.data["weights"], two_layer_lattice(10, 2, 1)) + + +def test_a_study_binds_an_existing_moead_weight_file(tmp_path: Path) -> None: + file = tmp_path / "W3D_15.dat" + np.savetxt(file, das_dennis(3, 4)[::-1]) + spec = vamos.StudySpec( + problems=["dtlz2"], + algorithms=["moead"], + seeds=[0], + pop_size=15, + n_obj=3, + max_evaluations=30, + engine="numpy", + algorithm_configs={"moead": {"weight_vectors": {"path": str(tmp_path), "divisions": None}}}, + ) + + weights = vamos.plan_study(spec).plan.tasks[0].resolved_run_spec["algorithm"]["config"]["weight_vectors"] + + assert weights == {"path": str(file), "divisions": None, "sha256": vector_digest(read_weight_vectors(str(file), 3))} diff --git a/tests/engine/test_rvea_variant.py b/tests/engine/test_rvea_variant.py new file mode 100644 index 000000000..2af9df777 --- /dev/null +++ b/tests/engine/test_rvea_variant.py @@ -0,0 +1,111 @@ +"""RVEA's survival in pymoo's reading (the default) and in the authors' PlatEMO code, as jMetal (``variant``).""" + +from __future__ import annotations + +import dataclasses +from pathlib import Path + +import numpy as np +import pytest + +import vamos +from vamos.algorithms import RVEAConfig +from vamos.engine.algorithm.rvea.rvea import _calc_gamma, _calc_V, _generate_reference_vectors +from vamos.engine.algorithm.rvea.survival import angle_penalized_distances, apd_survival +from vamos.exceptions import ConfigurationError + + +def _penalty(variant: str, F: np.ndarray, t: int, t_max: int, alpha: float) -> tuple[np.ndarray, np.ndarray, np.ndarray]: + V = _calc_V(_generate_reference_vectors(2, 9)) + gamma = _calc_gamma(V) + niches, penalty, _apd = angle_penalized_distances(F, F.min(axis=0), V, gamma, t, t_max, alpha, variant) + return niches, penalty, gamma + + +def _angle(F: np.ndarray, V: np.ndarray, niches: np.ndarray) -> np.ndarray: + shifted = F - F.min(axis=0) + unit = shifted / np.linalg.norm(shifted, axis=1, keepdims=True) + return np.arccos(np.clip(np.sum(unit * V[niches], axis=1), -1.0, 1.0)) + + +@pytest.mark.parametrize(("variant", "M"), [("platemo", 2.0), ("pymoo", 1.0)]) +def test_with_two_objectives_the_penalty_is_m_times_progress_times_the_relative_angle(variant: str, M: float) -> None: + rng = np.random.default_rng(4) + F = rng.random((30, 2)) + 0.1 + t, t_max, alpha = 7, 20, 2.0 + V = _calc_V(_generate_reference_vectors(2, 9)) + + niches, penalty, gamma = _penalty(variant, F, t, t_max, alpha) + + theta = _angle(F, V, niches) + np.testing.assert_allclose(penalty, M * (t / t_max) ** alpha * theta / gamma[niches], rtol=1e-12, atol=1e-15) + + +def test_with_three_objectives_both_variants_use_m_objectives() -> None: + rng = np.random.default_rng(5) + F = rng.random((40, 3)) + 0.1 + V = _calc_V(_generate_reference_vectors(3, 4)) + gamma = _calc_gamma(V) + + _, pymoo, _ = angle_penalized_distances(F, F.min(axis=0), V, gamma, 3, 10, 2.0, "pymoo") + _, platemo, _ = angle_penalized_distances(F, F.min(axis=0), V, gamma, 3, 10, 2.0, "platemo") + + np.testing.assert_array_equal(pymoo, platemo) + + +def test_platemo_translates_by_the_candidates_minimum_and_pymoo_by_the_accumulated_ideal() -> None: + rng = np.random.default_rng(6) + F = rng.random((20, 3)) + 1.0 + V = _calc_V(_generate_reference_vectors(3, 3)) + gamma = _calc_gamma(V) + ideal = np.zeros(3) # accumulated from an earlier generation, below every candidate + + pymoo, pymoo_ideal, _ = apd_survival(F, V, gamma, ideal, 10, 2, 10, 2.0, "pymoo") + platemo, platemo_ideal, _ = apd_survival(F, V, gamma, ideal, 10, 2, 10, 2.0, "platemo") + + np.testing.assert_array_equal(pymoo_ideal, platemo_ideal) # both keep the accumulated ideal + niches, _, apd = angle_penalized_distances(F, F.min(axis=0), V, gamma, 2, 10, 2.0, "platemo") + expected = sorted(int(np.flatnonzero(niches == niche)[np.argmin(apd[niches == niche])]) for niche in np.unique(niches)) + assert sorted(platemo.tolist()) == expected + assert sorted(pymoo.tolist()) != sorted(platemo.tolist()) + + +def _config(variant: str | None, pop_size: int = 100) -> RVEAConfig: + config = RVEAConfig.default(pop_size=pop_size, n_obj=2) + return config if variant is None else dataclasses.replace(config, variant=variant) + + +def test_the_default_is_pymoos_reading_and_keeps_its_results() -> None: + assert RVEAConfig.default(n_obj=2).variant == "pymoo" + assert "variant" not in RVEAConfig.default(n_obj=2).to_dict() + + default = vamos.optimize("zdt1", algorithm="rvea", algorithm_config=_config(None), max_evaluations=2000, seed=2, engine="numpy") + pymoo = vamos.optimize("zdt1", algorithm="rvea", algorithm_config=_config("pymoo"), max_evaluations=2000, seed=2, engine="numpy") + platemo = vamos.optimize("zdt1", algorithm="rvea", algorithm_config=_config("platemo"), max_evaluations=2000, seed=2, engine="numpy") + + np.testing.assert_array_equal(default.F, pymoo.F) + assert platemo.data["evaluations"] == 2000 + assert default.F.shape != platemo.F.shape or not np.array_equal(default.F, platemo.F) + + +def test_the_variant_is_validated_serialized_and_replayed(tmp_path: Path) -> None: + with pytest.raises(ConfigurationError, match="variant"): + _config("jmetal") + builder = ( + RVEAConfig.builder() + .pop_size(91) + .n_partitions(12) + .alpha(2.0) + .adapt_freq(0.1) + .crossover("sbx", prob=0.9, eta=30.0) + .mutation("pm", prob="1/n", eta=20.0) + .variant("platemo") + ) + config = builder.build() + assert config.to_dict()["variant"] == "platemo" + assert RVEAConfig.from_dict(config.to_dict()) == config + + result = vamos.optimize("dtlz2", algorithm="rvea", algorithm_config=config, max_evaluations=364, seed=1) + source = vamos.save_result(result, tmp_path / "source") + assert vamos.verify_run(source.root).effective_replayability == "exact" + assert vamos.reproduce(source.root, output=tmp_path / "replay").exact is True diff --git a/tests/experiment/test_cli_api_parity.py b/tests/experiment/test_cli_api_parity.py index ef28d478a..ce8a6aa72 100644 --- a/tests/experiment/test_cli_api_parity.py +++ b/tests/experiment/test_cli_api_parity.py @@ -62,6 +62,8 @@ # the resolved weight vectors record; with two objectives both run uniform weights. PROBLEM_DIFFERENCES: dict[tuple[str, str], dict[str, tuple[object, object]]] = { ("moead", "dtlz2"): { + # Development after 1.4.0: the command line records the packaged file it read and the digest of its vectors. + "algorithm.config.weight_vectors.sha256": (VARIES, ABSENT), "algorithm.resolution.weight_vectors.source": ("file", "das_dennis"), "algorithm.resolution.weight_vectors.file": (VARIES, ABSENT), "algorithm.resolution.weight_vectors.divisions": (ABSENT, VARIES),