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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/dev/add_problem.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ The CLI scaffold is discoverable with `vamos create-problem --help`.
4. Add packaged reference data under `src/vamos/resources/` only when the problem has an authoritative dataset/front, and verify package-data coverage.
5. Export the class from `vamos.problems` only when direct construction is part of the intentional public API. Named access through `vamos.optimize("key", ...)` does not require a class export.
6. Document dimensions, objective direction, constraints, encoding, and source. Never silently choose dimensions that the `ProblemSpec` marks fixed.
7. **VAMOS 1.5.1:** when an optional package evaluates the problem, as `modact` does the MODAct problems, import it inside the constructor and raise `ImportError` with the install command when it is missing; the registry-wide tests then skip the problem, and `_OPTIONAL_DEPENDENCIES` in `tests/foundation/test_problem_registry.py` names its package. Copy none of the package's code, and test the conversion to VAMOS's conventions with a stub of the package as well as against the package itself.

Use the canonical encoding names `real`, `integer`, `binary`, `permutation`, and `mixed`. For mixed problems, provide the current mixed specification expected by `MixedProblemProtocol` consumers.

Expand Down
2 changes: 1 addition & 1 deletion docs/dev/architecture_health.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ These rules are guardrails for long-term maintainability in a research-oriented
Read before any architectural change.
- Layering and facades: layers depend only in the directions listed in `AGENTS.md`. Public entry points are the curated facades listed in `AGENTS.md`, and `vamos/__init__.py` stays a small facade.
- Import-time purity: importing a module runs only imports, constant and type-alias assignments, function and class definitions, decorators, `if TYPE_CHECKING:` blocks, and `if __name__ == "__main__":` blocks. File IO, dynamic imports, environment reads, and initialization live inside functions or CLI entry points.
- Optional dependencies: core dependencies live in `[project].dependencies`, and heavy or optional libraries only in `[project.optional-dependencies]`. Optional imports are lazy or guarded with `try/except ImportError`, and Panel imports stay in `ux/panel` and the Studio UI. No extra installs another optimization framework and `src/vamos` imports none (`tests/test_pyproject_optional_deps_all.py`, `tests/test_optional_deps_policy.py`); maintainer comparisons under `tools/` and `experiments/` install the frameworks they compare against by name.
- Optional dependencies: core dependencies live in `[project].dependencies`, and heavy or optional libraries only in `[project.optional-dependencies]`. Optional imports are lazy or guarded with `try/except ImportError`, and Panel imports stay in `ux/panel` and the Studio UI. No extra installs another optimization framework and `src/vamos` imports none (`tests/test_pyproject_optional_deps_all.py`, `tests/test_optional_deps_policy.py`); maintainer comparisons under `tools/` and `experiments/` install the frameworks they compare against by name. **VAMOS 1.5.1:** `all` gathers every user extra but `modact`, whose package evaluates the MODAct problems under the GPL-3.0; VAMOS imports it only when such a problem is created and copies none of its code.
- No shims, and recorded debt only shrinks: do not add alternate wrappers for superseded APIs. Fix violations at the source and update call sites. A gate that tolerates existing debt records it in a ratchet, not an allowlist of exempt paths: `tests/architecture/monolith_guard_budget.json`, `tests/architecture/ruff_format_budget.json`, `typing/mypy-baseline.json`, and `release/repository-hygiene-exceptions.json`. Lower a budget or drop a baseline entry when the debt goes; never raise a budget or add a baseline entry to pass a gate. A hygiene exception names its owner, reason, and review condition.
- Health gates and retention: `tools/health.py` runs the gates below, and CI runs the same checkers and test files in its agent-documentation step, architecture step, and typing job. Raw audits, Goal handoffs, and validation logs stay outside the product tree, as described in [Repository hygiene](repository_hygiene.md).
- Run artifacts, typing, and studies follow the [run artifact contract](run_artifact_contract.md), the [typing policy](typing.md), and the [StudyManifest v1 contract](study_manifest_contract.md).
Expand Down
2 changes: 1 addition & 1 deletion docs/guide/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -497,7 +497,7 @@ Install any required [optional extras](installation.md#optional-extras) first.
- Tuning: `vamos tune --instances zdt1,zdt2,zdt3 --algorithm nsgaii --backend optuna --backend-fallback random --split-strategy suite_stratified --budget 5000 --tune-budget 200 --n-jobs -1`
- Ablation plans: `vamos ablation --config configs/ablation.yaml`
- Profiling: `vamos profile --problem zdt1 --engines numpy,numba --budget 2000 --output report/profile.csv`
- Problem zoo: `vamos zoo list`, `vamos zoo info zdt1`, `vamos zoo run zdt1 --algorithm nsgaii --budget 3000`
- Problem zoo: `vamos zoo list`, `vamos zoo info zdt1`, `vamos zoo run zdt1 --algorithm nsgaii --budget 3000`; **VAMOS 1.5.1:** `vamos zoo fetch-fronts` downloads the MODAct reference fronts that VAMOS does not package (see [Downloading the other MODAct fronts](../reference/problems.md#downloading-the-other-modact-fronts))
- Studio (interactive, needs `studio` extra): read the [Studio walkthrough and launcher limitation](studio.md) before starting.

**VAMOS 1.2.0:** `vamos --version` prints the installed version.
Expand Down
8 changes: 8 additions & 0 deletions docs/guide/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ Install only the capability groups you use:
| `tuning` | Optional model-based tuning backends | Experimental |
| `studio` | Panel-based local Studio | Experimental; see [Studio](studio.md) for release limitations |
| `examples` | Dependencies used by selected examples | Depends on the example's interfaces |
| `modact` | **VAMOS 1.5.1:** the authors' `modact` package (GPL-3.0), which evaluates the [MODAct problems](../reference/problems.md#modact-actuator-design-evaluated-by-the-modact-package) | Registered problems; `all` leaves it out |
| `docs` | Documentation toolchain | Developer tooling |
| `dev` | Tests, linting, typing, building, and docs checks | Developer tooling |
| `all` | All optional and development groups | Mixed; does not change interface guarantees |
Expand All @@ -96,6 +97,13 @@ now needs `analysis` and `examples`. `all` installs the user extras (`compute`,
are removed, with `vamos assist` and Studio's Problem Builder, the only parts
of VAMOS that used them. No extra, `all` included, installs an LLM client.

**VAMOS 1.5.1:** the `modact` extra installs the `modact`
package of Picard and Schiffmann, which evaluates the 20 MODAct problems. It is
licensed under the GPL-3.0, unlike VAMOS (MIT), so `all` does not install it:
install the extra, or `python -m pip install modact`, to run those problems.
VAMOS contains none of its code and imports it only when a MODAct problem is
created.

For example:

```bash
Expand Down
113 changes: 111 additions & 2 deletions docs/reference/problems.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
Choose a problem by its **formulation, encoding and dimensions**, then check the
[algorithm compatibility matrix](algorithms.md). This catalog describes the
260 registered problems in VAMOS **1.5.0**; **VAMOS 1.5.0:**
CTP1–CTP7 and IDTLZ1 and IDTLZ2 are new, so 251 become 260. The named selection helpers are
CTP1–CTP7 and IDTLZ1 and IDTLZ2 are new, so 251 become 260; **VAMOS 1.5.1:**
the 20 MODAct problems bring them to 280. The named selection helpers are
[stable public APIs](../project/stability-and-versioning.md). A synthetic or
engineering benchmark is a test model, not a validated model of your application.

Expand All @@ -18,7 +19,7 @@ engineering benchmark is a test model, not a validated model of your application
| Explicit constraint handling | `c1dtlz1`, `mw1` | Emit inequality constraints separately from objectives |
| Binary, integer or mixed operators | `zdt5`, `int_alloc`, `mixed_design` | Small, deterministic examples with explicit encodings |
| Permutation operators | `tsp6`, then `kroa100` | Closed tours with two specified route objectives |
| Application-inspired test functions | RE, RWA, CRE and RCM tables below | Fixed engineering formulations with different encodings and objective counts; CRE and RCM keep their constraints in G |
| Application-inspired test functions | RE, RWA, CRE and RCM tables below; **VAMOS 1.5.1:** MODAct | Fixed engineering formulations with different encodings and objective counts; CRE, RCM and MODAct keep their constraints in G; MODAct needs the `modact` package |
| Expensive model evaluations | `fs_real`, `ml_tuning` | Train a classifier for each candidate; require scikit-learn |

Use `optimize("zdt1", ...)` in Python or `--problem zdt1` in the
Expand Down Expand Up @@ -179,6 +180,8 @@ algorithm with the required constraint support in the [matrix](algorithms.md).

The constrained real-world suites CRE21–CRE51 and RCM01–RCM50 are listed with the
[application-inspired benchmarks](#cre-and-rcm-constrained-real-world-suites).
**VAMOS 1.5.1:** so are the
[MODAct problems](#modact-actuator-design-evaluated-by-the-modact-package).

DC-DTLZ's default constants are those of the authors' implementation (Li et
al., 2019, in the [COLA Laboratory's code][dcdtlz-authors]), which pymoo also
Expand Down Expand Up @@ -643,6 +646,94 @@ equalities).
Feasible designs dominate rows of jMetal's fronts of RCM23, RCM26 and RCM50,
so those are not packaged (see [Reference fronts](#reference-fronts)).

### MODAct: actuator design, evaluated by the modact package

**VAMOS 1.5.1:** the 20 MODAct problems of Picard and Schiffmann
([2021][modact-paper]) design an electro-mechanical actuator, a stepper motor
and three spur-gear stages in a housing. VAMOS does not implement them: each
evaluation calls the authors' [`modact` package][modact], which is GPL-3.0 and
is not part of VAMOS. Install it with `python -m pip install modact`, or with
the `modact` extra of VAMOS, which installs the same package (see
[Installation](../guide/installation.md#optional-extras)). Without it, the
problems are still listed, but creating one raises `ImportError` with that
command.

A key joins the objectives to the constraint level:

| Keys | n / M / G | Objectives, in MODAct's sense | Reference sample |
| --- | --- | --- | --- |
| `modact_cs1`–`modact_cs4` | 20 / 2 / 7, 8, 10, 9 | cost (min), safety factor (max) | 2D, each |
| `modact_ct1`–`modact_ct4` | 20 / 2 / 7, 8, 10, 9 | cost (min), torque excess (max) | 2D, each |
| `modact_cts1`–`modact_cts4` | 20 / 3 / 7, 8, 10, 9 | cost, torque excess, safety factor | None packaged |
| `modact_ctse1`–`modact_ctse4` | 20 / 4 / 7, 8, 10, 9 | those of CTS and efficiency (max) | None packaged |
| `modact_ctsei1`–`modact_ctsei4` | 20 / 5 / 7, 8, 10, 9 | those of CTSE and transmission ratio (min) | None packaged |

- **Constraint levels** (the paper's Table III): level 1 has six gear
constraints and the minimum torque excess, at least -0.001 N·m for CS and
-0.599 N·m for the others; level 2 adds the collisions between parts; level 3
adds the collisions and two limits on the bounding box; level 4 adds the
collisions and the position of the output shaft.
- **Signs:** `F` and `G` are modact's values, multiplied by 1 or -1 with the
package's `weights` and `c_weights`, as pymoo's wrapper does. The objectives
that MODAct maximizes (torque excess, safety factor and efficiency) change
sign, so every column of `F` is minimized; the constraints `g >= 0` change
sign and the constraints `g <= 0` keep it, so `G <= 0` is feasible. A problem
instance holds the factors as `objective_signs` and `constraint_signs`.
- **Variables:** all 20 are real. The motor and each gear's number of teeth are
the integer parts of variables whose fractional parts set the coil's fill
factor and the gear's profile shift, as the paper defines them, so real-coded
operators apply.
- **Cost:** modact evaluates one design at a time, about 20 ms each in the
paper. With modact 1.0.1 on a laptop, a random design took 10 to 30 ms, and
NSGA-II runs of 2000 evaluations about 12 ms per evaluation, so a run of
25 000 evaluations takes 5 to 15 minutes.
- **Reproducibility:** a run's `environment.json` records the installed
version of `modact`, as of every installed distribution, and the problem
instance holds it as `modact_version`. Verification and replay need the
package too.
- **Fronts:** the authors' best-known fronts (see
[Reference fronts](#reference-fronts)) are packaged for CS1–CS4 and CT1–CT4.
The others, 1.4 to 193 MB each, are too large to package;
`vamos zoo fetch-fronts` downloads them (see below).

#### Downloading the other MODAct fronts

**VAMOS 1.5.1:** `vamos zoo fetch-fronts` downloads the best-known fronts of
CTS1–CTS4, CTSE1–CTSE4 and CTSEI1–CTSEI4 from the [Zenodo record][modact-fronts]
(version 1.1.0, CC BY 4.0). Without arguments it takes the three-objective
fronts of CTS1–CTS4 (8.9 MB):

```bash
vamos zoo fetch-fronts
vamos zoo fetch-fronts modact_ctse4 modact_ctsei1
vamos zoo fetch-fronts --all
```

`--all` downloads the twelve, about 730 MB. For each front, the command:

- checks the file's MD5 checksum against the one the record publishes;
- converts it as the packaged fronts are converted: the columns that MODAct
maximizes change sign, each value keeps its digits, and no row is added or
removed;
- writes `modact_<problem>.csv` and the CC BY 4.0 notice
`LICENSE-modact-fronts.txt` in VAMOS's directory of downloaded reference
fronts.

That directory is `reference_fronts` under `VAMOS_DATA_DIR` when that variable
is set, and otherwise:

- `%LOCALAPPDATA%\vamos\reference_fronts` on Windows;
- `~/Library/Application Support/vamos/reference_fronts` on macOS;
- `$XDG_DATA_HOME/vamos/reference_fronts` elsewhere, by default
`~/.local/share/vamos/reference_fronts`.

VAMOS looks for reference fronts there after the packaged ones, so a
downloaded file never replaces a packaged front. The downloaded fronts need no
further step: Studio's catalog lists them, and `--hv-reference-front vamos`
resolves them. A front already in the directory is kept unless you pass
`--force`, and `--output DIR` writes elsewhere. A failed download or checksum
leaves no file behind and exits with code 1.

### Learning and mixed engineering examples

Install `python -m pip install "vamos-optimization[examples]==1.5.0"` for the two
Expand Down Expand Up @@ -750,6 +841,10 @@ files of 1.1.0 (`c1dtlz1.csv` and so on, two-objective) are replaced by
`dtlz1.2d.csv` to `dtlz7.2d.csv`, so a two-objective DTLZ run has an automatic
reference. VAMOS 1.2.0 had none, and VAMOS 1.1.0 returned the three-objective
file.
- **VAMOS 1.5.1:** MODAct CS1–CS4 and CT1–CT4 have the authors'
best-known fronts, `modact_cs1.csv` to `modact_ct4.csv`. `vamos zoo
fetch-fronts` downloads those of the problems with three to five objectives
(see [Downloading the other MODAct fronts](#downloading-the-other-modact-fronts)).
- RE/RWA samples have the dimensions shown above. Their presence does not imply
that every sample point is a certified global Pareto optimum.
- Families marked “None packaged” require a suitable external reference or a
Expand Down Expand Up @@ -786,6 +881,7 @@ regenerates the files marked as regenerated.
| `ctp1`–`ctp7` | **VAMOS 1.5.0:** generated from the paper's definition at g = 1 and on the constraint boundaries, as VAMOS evaluates them. CTP1: the envelope `max(exp(-f1), a_j exp(-b_j f1))`, 1000 points. CTP2–CTP7: the feasible, non-dominated points of the boundary, sampled at 2 000 001 values of `sin(θ) (f2 - e) + cos(θ) f1` and at the zeros of its sine, of the unconstrained front `f2 = 1 - f1` and of the least feasible `f2` at `f1 = 0` and 1, thinned to at most 1000 with the zeros kept: CTP2's 13 segments, the 13 isolated points of CTP3 and CTP4 (the same file), CTP5's first arch and 15 points, CTP6's boundary in `1 <= sin(θ) (f2 - e) + cos(θ) f1 <= 2`, and six pieces of CTP7's unconstrained front with `(0, 1.0446)`, the least feasible point at `f1 = 0`. A feasible design reaches every point (within 1e-6 at the isolated points; see the notes on CTP above) |
| `lircmop1`–`lircmop14`, `dascmop1`–`dascmop9` | jMetal's fronts (`resources/referenceFronts` at commit `1e4b83cae6`), under its MIT notice in `LICENSE-jmetal.txt`; DAS-CMOP8 and DAS-CMOP9 leave out two rows each, which another row dominates |
| `cre21`–`cre25`, `cre31`, `cre32`, `cre51`, `rcm01`–`rcm49` except `rcm17`, `rcm23` and `rcm26` | jMetal's fronts (`resources/referenceFronts` at commit `1e4b83cae6`), unchanged, under `LICENSE-jmetal.txt`; approximations (see the notes on jMetal's CRE and RCM fronts). `cre51` and `rcm11` are the same file |
| `modact_cs1`–`modact_cs4`, `modact_ct1`–`modact_ct4` | **VAMOS 1.5.1:** Picard and Schiffmann's best-known fronts (`<problem>_PF.dat` of [Zenodo record 10.5281/zenodo.3824302][modact-fronts], version 1.1.0), under CC BY 4.0 with the attribution in `LICENSE-modact-fronts.txt`. The second column, which MODAct maximizes, has the opposite sign; the values keep their digits, and no row is added or removed. Approximations (see the notes on MODAct's fronts) |
| `c1dtlz1`–`dc3dtlz3`, `.2d` and `.3d`, `c3dtlz4` included | Regenerated: the feasible, non-dominated part of DTLZ's front (C3-DTLZ1 and C3-DTLZ4: of their constraint boundaries), as VAMOS evaluates it; 1000 points at M = 2 and up to 5050 at M = 3 |
| `zcat*` | Unchanged samples |
| `jmetal-zdt1`–`jmetal-zdt4`, `jmetal-zdt6`, `jmetal-dtlz1`, `jmetal-dtlz2` and `jmetal-dtlz5`–`jmetal-dtlz7`, `.2d` and `.3d` | **VAMOS 1.3.0:** jMetal's fronts (`resources/referenceFronts` at commit `1e4b83cae6`), unchanged, under `LICENSE-jmetal.txt`; the optional `jmetal` source described below. jMetal's DTLZ3 and DTLZ4 files are its DTLZ2 file, so `jmetal-dtlz2` serves the three |
Expand Down Expand Up @@ -879,6 +975,16 @@ Notes on the table:
CRE23 and RCM05 are the same problem with different fronts; each front
dominates 35 to 42 rows of the other, by up to 2e-4 of the range. RCM47's
front is a single point.
- **MODAct's fronts:** **VAMOS 1.5.1:** the authors aggregated
the feasible non-dominated solutions of the external archives of 30 runs of
NSGA-II (NSGA-III for three or more objectives) and 30 of C-TAEA, each of
300 000 evaluations. The files hold objective vectors only, without their
designs, so no test can rebuild a design that reaches a row. No row of the
packaged files is dominated by another; CS2 repeats 17 of its rows. The
fronts of CTS1–CTS4 have 18 808 to 36 661 rows (1.4 to 2.8 MB each), those
of CTSE1–CTSE4 and CTSEI1–CTSEI4 11 to 193 MB each, so they are not
packaged; `vamos zoo fetch-fronts` downloads them. The CTSE4 front, for
example, has 109 150 rows.
- **Replaced samples:** VAMOS 1.1.0 and earlier packaged inaccurate samples for
several regenerated files, so IGD, IGD+, epsilon and normalized HV values
computed with those files are not comparable across versions:
Expand Down Expand Up @@ -936,6 +1042,9 @@ scalable formulations. For a new objective function, follow
[rcm-paper]: https://doi.org/10.1016/j.swevo.2021.100961
[jmetal-cre]: https://github.com/jMetal/jMetal/tree/1e4b83cae6/jmetal-problem/src/main/java/org/uma/jmetal/problem/multiobjective/cre
[jmetal-rcm]: https://github.com/jMetal/jMetal/tree/1e4b83cae6/jmetal-problem/src/main/java/org/uma/jmetal/problem/multiobjective/cec2021
[modact-paper]: https://doi.org/10.1109/TEVC.2020.3020046
[modact]: https://github.com/epfl-lamd/modact
[modact-fronts]: https://doi.org/10.5281/zenodo.3824302
[binary]: https://github.com/vamos-optimization/VAMOS/blob/v1.0.1/src/vamos/foundation/problem/binary.py
[integer]: https://github.com/vamos-optimization/VAMOS/blob/v1.0.1/src/vamos/foundation/problem/integer.py
[mixed]: https://github.com/vamos-optimization/VAMOS/blob/v1.0.1/src/vamos/foundation/problem/mixed.py
Expand Down
Loading