Repository navigation
docs(foundations): add the Foundations learning path - #369
NicolasRodriguezUribe wants to merge 11 commits into
Conversation
Add a Foundations tab, placed after Developer, with Basic, Intermediate and Advanced lessons on multi-objective optimization: problems, Pareto dominance, quality aspects and indicators; NSGA-II in detail (sorting, crowding and tournaments, SBX and polynomial mutation, elitist survival); an in-depth lesson for every other built-in algorithm (SPEA2, MOEA/D, SMS-EMOA, IBEA, SMPSO, NSGA-III, RVEA, AGE-MOEA, CCMO, C-TAEA, ToP, CMOEA-MS); many objectives, constraints and rigorous comparison. Each lesson has interactive figures (dependency-free SVG in docs/javascripts/foundations.js, ported from the NumPy kernel), runnable VAMOS examples with their real output, verbatim source excerpts and references. tests/docs/test_foundations.py checks the navigation, metadata, figures, examples and excerpts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tor changes on main
- A2 NSGA-III: parents are chosen at random by default, as Deb and Jain, or by
jMetal's rank tournament, never by crowding distance; the two-layer lattice
(inner_divisions) and whitespace-separated direction files are generated or
read by VAMOS. The example uses selection("random"), as the algorithm page.
- A1 and A2: record the outputs of the examples with the new selection.
- A3 RVEA: the pymoo and platemo variants, vectors from a file or a two-layer
lattice, and the excerpts of angle_penalized_distances and the adaptation.
- A4 AGE-MOEA: the AGE-MOEA-II variant and its reference.
- I8 MOEA/D: the excerpt of the weight-vector loader.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The changes these lessons describe as "Development after 1.4.0" shipped in VAMOS 1.5.0, whose release turned every other such marker into "VAMOS 1.5.0". The same rule applies here: the markers of A2 NSGA-III, A3 RVEA and A4 AGE-MOEA, the install command and the version the printed outputs come from (all 32 examples print exactly their documented output with 1.5.0), and CTP1 to CTP7, built in since 1.5.0. The comparisons with what 1.4.0 did stay. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The header of foundations.js said that tests/docs/test_foundations.py checks the script's algorithms against VAMOS and MooCore, but that test does not run JavaScript: it checks that every figure a lesson uses is implemented. The comment now says so, and that the sorting, crowding, indicator and Das-Dennis functions were checked by hand: on 60 random sets with two and three objectives, including duplicated rows, the non-dominated ranks, crowding distances, IGD, IGD+, additive epsilon, two-objective hypervolume and its contributions agree with VAMOS's NumPy kernel and MooCore, and the Das-Dennis lattices with VAMOS's. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fa435dc1a3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…the platform With CTP2 and lambda 0.9 the feasible share of Q stays near 0.9, so the last-digit differences between platforms decide whether a generation is in stage A or B: with seed 1, Windows ends in stage A with 26 of 100 feasible, and Linux (tests-full, Python 3.11 to 3.14) in stage B with 100 of 100. The test leaves an optimization's digits free but not its words, and failed on Linux. The example now runs the three cases that print the same on both platforms, digit for digit: CTP2 with lambda 0.5 and MW3 with 0.5 and 0.9. The text keeps the dropped case as the reason a lambda near the share a run settles at makes the stages fragile, and the "lambda matters" limit cites MW3. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The documentation browser check searches "hypervolume" and expects T07 among the first results that Material renders, ten documents per batch. T07 names hypervolume only in its body, so it was already seventh on main, and the Foundations lessons on SMS-EMOA, quality indicators and IBEA pushed it to eleventh. Lowering every Foundations boost to 0.25 and raising T07's to 3 still left it ninth or tenth. "Fix the measurement rule" is the section where T07 defines hypervolume and IGD+; naming them in its heading puts T07 first for "hypervolume", with no boost changes. The anchor becomes #fix-the-measurement-rule-hypervolume-and-igd; nothing in the repository links to the old one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
VAMOS documentation previewhttps://pr-369-vamos-docs-preview.vamos-optimization.workers.dev Built from |
…contributions hvContributions2d dropped every copy of a repeated point, so the neighbour of two equal points got the area the copies cover: 0.32 instead of 0.16 for [[0.2, 0.6], [0.2, 0.6], [0.6, 0.2]] with r = (1, 1). The function now ports the two-objective algorithm of VAMOS's hypervolume_contributions: unique points, a lexicographic sort, the staircase of non-dominated points, and 0 for every copy of a repeated point, which still covers its neighbours. A dominated point stays left out, as in VAMOS and MooCore's hv_contributions with its default ignore_dominated: [[0.1, 0.1], [0.5, 0.5]] gives [0.81, 0]. B4 now states that rule. test_figure_algorithms_agree_with_vamos runs the script with Node.js, when it is installed, and compares the non-dominated ranks, crowding distances, hypervolume and contributions with VAMOS on 23 sets with duplicated, dominated and out-of-box points; it failed on the duplicates before this change. The header of foundations.js says what the test checks. Reported by Codex's review of #369. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: acd209cb55
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
… manifest AGENTS.md asks for executable learning paths in the docs smoke manifest, and the Foundations examples ran only in tests/docs/test_foundations.py. The manifest gains a foundations_* case for each of the 25 lessons with examples. Each case runs every example from the lesson page itself, so the manifest copies no code; a page that uses MooCore skips without it. test_every_page_with_examples_is_a_docs_smoke_case fails if a page with examples is missing from the manifest; it failed before this change. The output comparison stays in test_foundations.py. Reported by Codex's review of #369. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ctangle The scalarization figure of B1 and I6 drew the Tchebycheff contour upward and rightward from its corner (c/w1, c/w2), where max(w1 f1, w2 f2) is greater than c. The contour is now the pure function tchebycheffContour, which returns the upper and right edges of the rectangle where the value is at most c: [[0, c/w2], [c/w1, c/w2], [c/w1, 0]]. test_tchebycheff_contour_is_a_level_set runs it with Node.js and checks that every vertex and segment midpoint has value c for five weights; it failed with the old geometry. Reported by Codex's review of #369. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
@codex review |
|
Codex Review: Didn't find any major issues. Breezy! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Problem
The documentation teaches VAMOS's interface (tutorials, algorithm lessons, reference), but not the ideas behind it. A reader new to multi-objective optimization has no path from "what is a Pareto front?" to "why does NSGA-III need reference directions?" or "how do I compare two algorithms fairly?" inside the VAMOS site.
Change
A Foundations tab, placed after Developer, with an overview and 25 lessons in three levels:
Each lesson has:
docs/javascripts/foundations.js, dependency-free SVG and DOM. The figures are a progressive enhancement: every figure keeps a fallback paragraph, and the text is complete without JavaScript. Points can be dragged, or focused with Tab and moved with the arrow keys, and a readout states the numbers that each figure shows. Styles are indocs/stylesheets/foundations.css.# Excerpt from src/...) of the code that implements the step being explained.Integration:
mkdocs.yml(nav,extra_css,extra_javascript), a pointer from Getting started and from the tutorials index, the documentation architecture and navigation inventories, the visual-identity and home-hero tests that list the site's stylesheets, and two Foundations routes intools/check_docs_browser.py(desktop/mobile Chromium indocs-preview).Commits
docs(foundations): add the Foundations learning path.mainafter 1.4.0, with the NSGA-III, RVEA, AGE-MOEA and weight-vector PRs, anddocs(foundations): follow the NSGA-III, RVEA, AGE-MOEA and weight-vector changes on main: A2 NSGA-III (random parent selection by default, never crowding distance; two-layer lattices; whitespace-separated direction files), A3 RVEA (pymoo/platemovariants, vectors from a file or a two-layer lattice), A4 AGE-MOEA (AGE-MOEA-II), I8 MOEA/D (the weight-vector loader), and the outputs of A1 and A2 with the new selection.mainat 1.5.0 (Release 1.5.0: NSGA-III's parent selection, one source of reference vectors, AGE-MOEA-II and RVEA's PlatEMO variant, CTP and IDTLZ #368), anddocs(foundations): name VAMOS 1.5.0 in the lessons' version notes: since those changes have shipped in 1.5.0, the release's marker rule now applies to these pages as well. Every "Development after 1.4.0" becomes "VAMOS 1.5.0", and so does the install command and the version that the printed outputs come from. CTP1–CTP7 are named as built-in "since VAMOS 1.5.0". Historical comparisons with 1.4.0 stay.docs(foundations): say what the test checks of the figures' algorithms: the header offoundations.jssaid thattests/docs/test_foundations.pychecks the JavaScript algorithms against VAMOS and MooCore, but that test does not run JavaScript. It checks that every figure a lesson uses is implemented. The comment now says that, and the agreement was checked by hand for this PR (see Validation).docs(foundations): leave out the CMOEA-MS run whose stages depend on the platform(after the first CI run, see below).docs(tutorials): name hypervolume and IGD+ in T07's measurement heading(after the first CI run, see below).docs(foundations): count equal points as coverage in the hypervolume contributions(after Codex's review, see below).test(docs): run every Foundations lesson's examples in the docs smoke manifest(after Codex's second review).docs(foundations): draw the Tchebycheff contour along the sublevel rectangle(after Codex's second review).After the first CI run
Two checks failed on Linux, neither of which a Windows run can show:
tests-full(Ubuntu, Python 3.11–3.14): the A9 CMOEA-MS example. With CTP2 and λ = 0.9 the feasible share stays near 0.9, so last-digit differences between platforms decide each generation's stage. With the same seed, Windows ends in stage A with 26 of 100 feasible and Linux in stage B with 100 of 100. The test leaves the digits free but not the words, so "final stage A" against "final stage B" failed. The other three runs print the same on Windows and on all four Linux jobs, digit for digit. The example now runs those three (CTP2 with λ = 0.5, MW3 with λ = 0.5 and 0.9). The text uses the dropped case to show why a λ near the share a run settles at makes the stages fragile, and the "λ matters" limit now cites MW3.docs-preview, browser journey "hypervolume" → T07. Material renders ten documents per batch. Onmain, T07 is the seventh document for "hypervolume": the word appears in its body but in no heading. The Foundations lessons that centre on hypervolume (SMS-EMOA, B4, IBEA) push it to eleventh. Lowering every Foundations boost to 0.25 and raising T07's to 3 still left T07 ninth or tenth, which is not robust. T07's "Fix the measurement rule" section is where it defines hypervolume and IGD+, and naming them in that heading puts T07 first, with no boost changes. Nothing in the repository links to the old anchor.After Codex's review
Codex flagged
hvContributions2dfor leaving out dominated and duplicated points. The two cases differ:[[0.1, 0.1], [0.5, 0.5]], r = (1, 1) →[0.81, 0]): this is what VAMOS'shypervolume_contributionscomputes, by design. Its docstring follows MooCore'signore_dominatedsemantics, and MooCore'shv_contributionsdefault gives the same; the script ports that function. B4 now states the rule: contributions are measured among the non-dominated points, a dominated point contributes 0 and is left out, and you can drag a point behind another to see it.[[0.2, 0.6], [0.2, 0.6], [0.6, 0.2]]). VAMOS gives each copy 0 but keeps one as coverage. The script now ports VAMOS's two-objective algorithm: unique points, a lexicographic sort, the staircase of non-dominated points, and 0 for every copy of a repeated point.tests/docs/test_foundations.pygainstest_figure_algorithms_agree_with_vamos. When Node.js is installed it runs the script and compares its non-dominated ranks, crowding distances, hypervolume and contributions with VAMOS on 23 sets, including duplicated, dominated and out-of-box points. It failed on the duplicates before the fix. The header offoundations.jsnow says what the test checks.After Codex's second review
tests/docs/smoke_manifest.pygains afoundations_*case for each of the 25 lessons with examples. Each case runs every example from the lesson page itself, so no code is copied; a page that uses MooCore skips without it. The output comparison stays intest_foundations.py, whose newtest_every_page_with_examples_is_a_docs_smoke_casefails if a page with examples is missing from the manifest. It failed before the change.tchebycheffContour, which returns the upper and right edges of the rectangle where the value is at most c.test_tchebycheff_contour_is_a_level_setchecks with Node.js that every vertex and segment midpoint has value c for five weights. It failed with the old geometry.Tests
tests/docs/test_foundations.py(new):docs/foundations/exactly once, and the site loads its CSS and JS.[n]is listed.foundations.jsand has a fallback paragraph; every implemented figure is used.# Excerpt from <path>block matches lines of that source file, in order.optimize(...), since a run is repeatable in one environment, not bitwise everywhere.test_figure_algorithms_agree_with_vamos).test_tchebycheff_contour_is_a_level_set).test_every_page_with_examples_is_a_docs_smoke_case);tests/docs/test_docs_smoke.pyruns them (foundations_*).Compatibility
Documentation only: no change to
src/, to public APIs or to dependencies. The new nav tab changes the site structure; no existing page moves. One existing anchor changes: T07's#fix-the-measurement-rulebecomes#fix-the-measurement-rule-hypervolume-and-igd.Validation
All on Windows 11, Python 3.12.3, NumPy 2.4.6, SciPy 1.17.1, MooCore 0.3.2 (the
constraints/ci.txtpins), withPYTHONPATHset to the worktree'ssrc(checked withvamos.__file__).root.VamosFoundations, Node 24) against VAMOS's NumPy kernel and MooCore, 60 random sets with 2 and 3 objectives, some with duplicated rowsignore_dominated=True; the random sets had no duplicates, which is why the duplicate case Codex found was missed), Das-Dennis lattices 4/4ruff checkandruff format --checkon the changed Pythonpython -m compileallon the changed Python;git diff --checkpython tools/check_agent_docs.pypython tools/health.py(includestypecheck.py --scope strictand--scope full)mkdocs build --strictpytest -q -n 4 -p no:cacheprovider -rfEtools/build_release_docs.py --version 1.5.0, thencheck_docs_portal.pyandcheck_docs_site.pyon the previewtools/check_docs_browser.pyon that preview (Playwright 1.65.2, Chromium)pytest -q -n 4 tests/test_check_agent_docs.py tests/architecture/test_docs_and_workflows.py tests/docsmkdocs build --strict; preview, portal, site and browser checks;python tools/health.py;ruffon the testmkdocs build --strict;python tools/health.py;git diff --checkThe full pytest run (11327 passed) is from before the two documentation-only CI fixes; after them the quick tier, the docs build, health and the browser check ran again, as listed. A first
pytest -n autoattempt stopped at collection because Windows ran out of page file while its workers loaded SciPy's DLLs; with-n 4the suite passes.Changelog entry
[Unreleased] → Added
🤖 Generated with Claude Code