Skip to content

feat(indicators): document and expose the approximate hypervolume, with its seed and method - #363

Merged
NicolasRodriguezUribe merged 1 commit into
mainfrom
feat/public-hv-approx
Nov 19, 2026
Merged

NicolasRodriguezUribe merged 1 commit into
mainfrom
feat/public-hv-approx

Conversation

@NicolasRodriguezUribe

Copy link
Copy Markdown
Contributor

Summary

Makes the approximate hypervolume a documented, public indicator next to the exact one, and passes seed and method through to MooCore (VAMOS-Studio change request U2). VAMOS-Studio computes indicators on request, and the exact hypervolume can take minutes from about six objectives; it can offer the approximation once it is reachable through a documented facade instead of an internal module.

  • Public surface: the experimental vamos.ux.api facade (the one for analysis helpers) now exports HVIndicator (exact, moocore.hypervolume), HVApproxIndicator (moocore.hv_approx), HV_APPROX_METHODS and their IndicatorResult. They are the existing classes of vamos.foundation.quality_indicators, re-exported: no parallel registry, get_indicator("hv_approx", ...) returns the same class, and the internal package exports HV_APPROX_METHODS too. The API snapshot was regenerated with tools/update_public_api_snapshot.py.
  • HVApproxIndicator.compute(front, samples=10_000, seed=None, method=None):
    • seed (an integer, a NumPy Generator or None) and method are passed to moocore.hv_approx; samples keeps its default of 10 000.
    • method is one of HV_APPROX_METHODS = ("Rphi-FWE+", "DZ2019-HW", "DZ2019-MC"), MooCore's methods. An unknown method raises ValueError listing them (MooCore's own message is "Unknown method = {method}", without the value).
    • method=None keeps MooCore's default, read from inspect.signature(moocore.hv_approx): "Rphi-FWE+" since MooCore 0.3.0 and "DZ2019-HW" in 0.2.x (VAMOS allows moocore>=0.2.0, and 0.2.0 has no "Rphi-FWE+"). So the value computed without arguments does not change.
    • details now records samples, seed and the method used, next to reference_point.
  • Docs:
    • docs/topics/analysis.md (the experimental Analysis and Visualization page) gains a section "Hypervolume, exact and approximate": what both indicators take and return, the exact hypervolume's cost from about six objectives with measured times, the three options, the measured accuracy on DTLZ2, and a runnable example (part of the analysis docs smoke, which now also needs MooCore and counts five code blocks).
    • docs/dev/add_metric.md records the exported names and the pass-through in its indicator contract.
    • The class docstring describes the cost, the options and the details.
    • New behaviour is marked Development after 1.4.0:.

Sources: MooCore's hv_approx signature and docstring in the installed 0.3.2 (hv_approx(points, /, ref, *, maximise=False, nsamples=262144, seed=None, method='Rphi-FWE+'); "Rphi-FWE+" and "DZ2019-HW" deterministic, "DZ2019-MC" Monte Carlo from seed) and in the 0.2.0 and 0.3.0 wheels (0.2.0: methods "DZ2019-HW" (default) and "DZ2019-MC"); MooCore's documentation of hv_approx (the integral over the hypersphere of Deng and Zhang, 2019, which all three methods approximate).

Measured on this laptop, MooCore 0.3.2, points near DTLZ2's sphere with reference point 1.1: the exact hypervolume of 2000 points with six objectives took 17 s, 400 with seven 16 s and 200 with eight 32 s; hv_approx with 10 000 samples took 0.01–0.03 s. On 286 points of DTLZ2's front with four objectives, the deterministic methods with 10 000 samples are within 0.04 % of the exact value, and "DZ2019-MC" with 100 000 samples within 0.26 % over seeds 1–10.

Tests

tests/foundation/test_moocore_indicators.py:

  • test_hv_approx_agrees_with_the_exact_hypervolume_on_dtlz2_with_four_objectives: 286 points of DTLZ2's front with four objectives (a Das-Dennis lattice projected onto the sphere), reference point 1.1; the estimate agrees with HVIndicator's exact value within 1 % for the default method and each of the three methods (10 000 samples, or 100 000 for "DZ2019-MC").
  • test_hv_approx_passes_its_seed_to_moocore: with "DZ2019-MC", the same seed gives the same value, another seed another value, and the details record seed and method.
  • test_hv_approx_records_moocores_default_method: without arguments, the details record 10 000 samples, seed None and MooCore's default method, and the value equals moocore.hv_approx with that method.
  • test_hv_approx_rejects_an_unknown_method.
  • test_the_analysis_facade_exports_the_exact_and_the_approximate_hypervolume: vamos.ux.api exports the same classes that get_indicator builds.

tests/docs/test_analysis_docs.py checks the new section; tests/docs/smoke_manifest.py runs its example.

Compatibility

Additive. Four new names in the experimental vamos.ux.api; hv_approx takes two new optional keyword arguments; its value without them is unchanged (MooCore's default method, 10 000 samples); details gains three keys. HV_APPROX_METHODS is new in vamos.foundation.quality_indicators.

Validation

Run from the worktree with PYTHONPATH set to its src (vamos.__file__ checked):

  • python -m pytest -q -n 4 tests/foundation/test_moocore_indicators.py tests/foundation/test_hypervolume_fallback.py tests/architecture/test_public_api_snapshot.py tests/test_public_api_guard.py tests/docs/test_analysis_docs.py tests/docs/test_docs_smoke.py tests/test_import_time_smoke.py tests/integration/test_public_api.py tests/architecture/test_no_facade_imports.py tests/architecture/test_layer_boundaries.py: 84 passed, 4 xfailed (the existing strict xfails of the import-time smoke where MooCore is installed).
  • ruff check and ruff format --check on the changed Python: clean. python -m compileall: clean. git diff --check: clean.
  • python tools/typecheck.py --scope strict and --scope full: 0 diagnostics; ratchet new=0, increased=0.
  • python tools/check_agent_docs.py: passed. python tools/check_repository_hygiene.py: passed.
  • python -m pytest -m "not slow" -n 4 -p no:cacheprovider -rfE: 10847 passed, 253 skipped, 9 xfailed, 2 failed. tests/experiment/test_cli_ablation.py::test_cli_ablation_runs_and_writes_variants is the known failure under xdist on Windows that also fails on untouched main and passes alone. tests/docs/test_cookbook_recipes.py::test_cookbook_python_recipe[15. Verify and reproduce a stored run] failed because a comment in src/vamos/ux/api.py was edited while the tier ran, which changed the source between recording and verifying the run (compatible instead of exact); the whole cookbook module then passed (22 passed), and the targeted tests above were rerun on the final files (119 passed with tests/experiment/test_study_analysis.py and tests/experiment/test_benchmark_reporting.py added).
  • python tools/health.py: all health checks passed (on the final files).
  • mkdocs build --strict: built.

Changelog entry

Added (under [Unreleased])

  • Indicators: the experimental vamos.ux.api exports HVIndicator, HVApproxIndicator, HV_APPROX_METHODS and IndicatorResult, documented in Analysis and Visualization with a note on the exact hypervolume's cost from about six objectives. HVApproxIndicator.compute passes seed and method to moocore.hv_approx (an unknown method raises ValueError; None keeps MooCore's default) and records samples, seed and the method used in details.

Checklist

Architecture health

  • I read the canonical rules in docs/dev/architecture_health.md relevant to this change.
  • I ran the local health command: python tools/health.py.
  • I updated docs/dev/architecture_health.md if I changed guardrails. (No guardrail changed.)

Public API & dependencies

  • Public API changes are intentional; snapshot updated via python tools/update_public_api_snapshot.py if needed. (Four names added to the experimental vamos.ux.api.)
  • No optional/heavy dependencies were added to core [project].dependencies.

Behavior & tests

  • Runtime behavior is unchanged (or explicitly documented as a bugfix). (Defaults unchanged; new options and details only.)
  • Tests pass locally (fast tier, apart from the known Windows/xdist ablation failure noted above).

Changelog

  • CHANGELOG.md is unchanged, and the changelog entry is under a "Changelog entry" heading in this description.

Reports/retention

  • Raw audit/Goal evidence is external or a CI artifact; only durable conclusions are added to maintained docs.
  • Generated output follows docs/dev/repository_hygiene.md and python tools/check_repository_hygiene.py passes.

🤖 Generated with Claude Code

…th its seed and method

HVApproxIndicator (hv_approx), MooCore's hv_approx, was internal and
documented only in docs/dev/add_metric.md, and it passed neither a seed
nor a method to MooCore (VAMOS-Studio request U2). The exact
hypervolume can take minutes from about six objectives, so a tool that
computes indicators on request needs the approximation as a public,
documented indicator.

- The experimental vamos.ux.api exports HVIndicator, HVApproxIndicator,
  HV_APPROX_METHODS and IndicatorResult, the existing classes of
  vamos.foundation.quality_indicators (no parallel registry).
- HVApproxIndicator.compute takes seed (an integer, a Generator or
  None, used by "DZ2019-MC") and method, one of HV_APPROX_METHODS
  ("Rphi-FWE+", "DZ2019-HW", "DZ2019-MC"); an unknown method raises
  ValueError. None keeps MooCore's default, read from hv_approx's
  signature ("Rphi-FWE+" since MooCore 0.3.0, "DZ2019-HW" in 0.2.x), so
  the value without arguments does not change. details records samples,
  seed and the method used.
- docs/topics/analysis.md documents both indicators, the exact
  hypervolume's measured cost from six objectives, the options and the
  accuracy on DTLZ2, with an example that the docs smoke runs.

Tests: on 286 points of DTLZ2's front with four objectives the estimate
is within 1 % of the exact value with every method; with "DZ2019-MC" a
seed gives the same value and another seed another one; the details
record MooCore's default; an unknown method raises; the facade exports
the classes that get_indicator builds.

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-19T00:03:47.693628Z a7ca7ba PR opened
ℹ️ 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.

@github-actions

Copy link
Copy Markdown
Contributor

VAMOS documentation preview

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

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

@NicolasRodriguezUribe
NicolasRodriguezUribe added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit b33c3ad Nov 19, 2026
15 checks passed
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