Skip to content

docs(foundations): add the Foundations learning path - #369

Open
NicolasRodriguezUribe wants to merge 11 commits into
mainfrom
docs/foundations-learning-path
Open

NicolasRodriguezUribe wants to merge 11 commits into
mainfrom
docs/foundations-learning-path

Conversation

@NicolasRodriguezUribe

@NicolasRodriguezUribe NicolasRodriguezUribe commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

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:

Level Lessons
Basic B1 multi-objective problems · B2 Pareto dominance · B3 quality aspects · B4 quality indicators
Intermediate I1 NSGA-II at a glance · I2 non-dominated sorting · I3 crowding distance and tournaments · I4 SBX and polynomial mutation · I5 elitist survival · I6 beyond NSGA-II · I7 SPEA2 · I8 MOEA/D · I9 SMS-EMOA · I10 IBEA · I11 SMPSO
Advanced A1 many objectives · A2 NSGA-III · A3 RVEA · A4 AGE-MOEA · A5 constraints · A6 CCMO · A7 C-TAEA · A8 ToP · A9 CMOEA-MS · A10 comparing algorithms rigorously

Each lesson has:

  • Interactive figures: 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 in docs/stylesheets/foundations.css.
  • Runnable VAMOS examples through the public facades, each followed by its real output.
  • Verbatim source excerpts (# Excerpt from src/...) of the code that implements the step being explained.
  • Key points and References to the original papers.

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 in tools/check_docs_browser.py (desktop/mobile Chromium in docs-preview).

Commits

  1. docs(foundations): add the Foundations learning path.
  2. A merge of main after 1.4.0, with the NSGA-III, RVEA, AGE-MOEA and weight-vector PRs, and docs(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/platemo variants, 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.
  3. Merge of main at 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), and docs(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.
  4. docs(foundations): say what the test checks of the figures' algorithms: the header of foundations.js said that tests/docs/test_foundations.py checks 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).
  5. docs(foundations): leave out the CMOEA-MS run whose stages depend on the platform (after the first CI run, see below).
  6. docs(tutorials): name hypervolume and IGD+ in T07's measurement heading (after the first CI run, see below).
  7. docs(foundations): count equal points as coverage in the hypervolume contributions (after Codex's review, see below).
  8. test(docs): run every Foundations lesson's examples in the docs smoke manifest (after Codex's second review).
  9. 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. On main, 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 hvContributions2d for leaving out dominated and duplicated points. The two cases differ:

  • A dominated point ([[0.1, 0.1], [0.5, 0.5]], r = (1, 1) → [0.81, 0]): this is what VAMOS's hypervolume_contributions computes, by design. Its docstring follows MooCore's ignore_dominated semantics, and MooCore's hv_contributions default 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.
  • Equal points were a real divergence. The script dropped both copies, so their neighbour's contribution grew (0.32 instead of 0.16 for [[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.py gains test_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 of foundations.js now says what the test checks.

After Codex's second review

  • P1: the learning path in the docs smoke manifest (AGENTS.md: "Put executable learning paths in the docs smoke manifest"). tests/docs/smoke_manifest.py gains a foundations_* 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 in test_foundations.py, whose new test_every_page_with_examples_is_a_docs_smoke_case fails if a page with examples is missing from the manifest. It failed before the change.
  • P2: the Tchebycheff contour in the scalarization figure (B1, I6) was drawn upward and rightward from its corner (c/w₁, c/w₂), where max(w₁f₁, w₂f₂) > c. It is now the pure function tchebycheffContour, which returns the upper and right edges of the rectangle where the value is at most c. test_tchebycheff_contour_is_a_level_set checks 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):

  • The Foundations tab follows Developer, has Overview + Basic/Intermediate/Advanced, lists every page under docs/foundations/ exactly once, and the site loads its CSS and JS.
  • Every page has a description, one title; every lesson has Key points and References, and every cited [n] is listed.
  • Every figure used by a page is implemented in foundations.js and has a fallback paragraph; every implemented figure is used.
  • Every # Excerpt from <path> block matches lines of that source file, in order.
  • Every example runs and prints its documented output: exactly, or with the digits free when it runs optimize(...), since a run is repeatable in one environment, not bitwise everywhere.
  • With Node.js installed, the script's non-dominated sorting, crowding distance, hypervolume and hypervolume contributions agree with VAMOS (test_figure_algorithms_agree_with_vamos).
  • With Node.js installed, the Tchebycheff contour that the scalarization figure draws is a level set of the scalarization (test_tchebycheff_contour_is_a_level_set).
  • Every lesson with examples is a docs smoke case (test_every_page_with_examples_is_a_docs_smoke_case); tests/docs/test_docs_smoke.py runs 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-rule becomes #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.txt pins), with PYTHONPATH set to the worktree's src (checked with vamos.__file__).

Command Result
Every Foundations example run against this branch, output compared exactly (not only its structure, as the test does for runs) 32/32 print exactly their documented output
The JS algorithms (root.VamosFoundations, Node 24) against VAMOS's NumPy kernel and MooCore, 60 random sets with 2 and 3 objectives, some with duplicated rows all agree: non-dominated ranks 60/60 (VAMOS and MooCore), crowding distance 328/328 fronts, IGD, IGD+ and additive epsilon 60/60, 2-D hypervolume and contributions 30/30 (MooCore's default ignore_dominated=True; the random sets had no duplicates, which is why the duplicate case Codex found was missed), Das-Dennis lattices 4/4
ruff check and ruff format --check on the changed Python passed
python -m compileall on the changed Python; git diff --check passed
python tools/check_agent_docs.py passed
python tools/health.py (includes typecheck.py --scope strict and --scope full) all health checks passed
mkdocs build --strict built, no warnings (MkDocs prints only its INFO list of pages outside the nav, all pre-existing)
pytest -q -n 4 -p no:cacheprovider -rfE 11327 passed, 256 skipped, 9 xfailed
After the CI fixes: tools/build_release_docs.py --version 1.5.0, then check_docs_portal.py and check_docs_site.py on the preview passed (158 pages, 14003 links, 789 canonical links)
After the CI fixes: tools/check_docs_browser.py on that preview (Playwright 1.65.2, Chromium) passed: 1440, 390 and 320 px, three journeys, JavaScript disabled; "hypervolume" now lists T07 first
After the CI fixes: every Foundations example compared exactly 32/32
After the CI fixes: pytest -q -n 4 tests/test_check_agent_docs.py tests/architecture/test_docs_and_workflows.py tests/docs 490 passed, 1 skipped
After Codex's review: the same quick tier; mkdocs build --strict; preview, portal, site and browser checks; python tools/health.py; ruff on the test 491 passed, 1 skipped (with the new Node.js test); no warnings; all passed
After the CI fixes: mkdocs build --strict; python tools/health.py; git diff --check built with no warnings; all health checks passed; clean

The 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 auto attempt stopped at collection because Windows ran out of page file while its workers loaded SciPy's DLLs; with -n 4 the suite passes.

Changelog entry

[Unreleased] → Added

  • Documentation: the Foundations learning path, a new tab with Basic, Intermediate and Advanced lessons on multi-objective optimization: problems, Pareto dominance, quality aspects and indicators; NSGA-II step by step; SPEA2, MOEA/D, SMS-EMOA, IBEA, SMPSO, NSGA-III, RVEA, AGE-MOEA, CCMO, C-TAEA, ToP and CMOEA-MS; many objectives, constraints and rigorous comparison. Each lesson has interactive figures, runnable VAMOS examples with their output, verbatim source excerpts and references.

🤖 Generated with Claude Code

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>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-19T22:00:04.018442Z e356753 Manual request
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread docs/javascripts/foundations.js Resolved
…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>
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

VAMOS documentation preview

https://pr-369-vamos-docs-preview.vamos-optimization.workers.dev

Built from e356753. Canonical metadata points to the production .org domain; the preview itself remains isolated.

…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>
@NicolasRodriguezUribe

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread docs/javascripts/foundations.js Resolved
Comment thread tests/docs/test_foundations.py Resolved
… 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>
@NicolasRodriguezUribe

Copy link
Copy Markdown
Contributor Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Breezy!

Reviewed commit: e3567536d7

ℹ️ 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".

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant