Skip to content

perf(archive): the unbounded archive merges offered rows when read, with the same rows - #360

Merged
NicolasRodriguezUribe merged 1 commit into
mainfrom
perf/lazy-unbounded-archive
Nov 18, 2026
Merged

NicolasRodriguezUribe merged 1 commit into
mainfrom
perf/lazy-unbounded-archive

Conversation

@NicolasRodriguezUribe

Copy link
Copy Markdown
Contributor

Summary

An unbounded external archive refiltered and deduplicated its whole contents once per generation. On long runs that dominated the run time: over the 200 000 evaluations of an NSGA-II run, the archive alone took 85 s on RCM25 (112 000 archived rows). Profiling showed the time going to np.unique's sort, moocore's is_nondominated over the whole archive, and the copies of the contents. jMetal's archive, which inserts one row at a time, took 620 s on the same stream.

UnboundedArchive now keeps the rows it is offered and merges them in one update when they are needed. The result is the same rows in the same order, so no run changes.

Changes

  • RowBuffer (new components/archive_buffer.py, mixed into _BaseArchive). add(X, F, G) offers rows as update does, without computing the contents.
    • When rows are kept: a buffered archive keeps them while its contents are clean (mutually non-dominated, finite, feasible when it holds constraint values, deduplicated with a zero objective tolerance) and the offered feasible objectives are finite.
    • When they are merged: in one update, when contents(), constraint_values() or update() needs them, or when they outnumber max(PENDING_ROWS, 2 * size), so memory stays bounded and the merges are amortized.
    • Otherwise add updates at once, as before: before the first feasible row, for rows with non-finite feasible objectives, with a positive objective tolerance or decision deduplication, and for bounded archives.
    • Flags: covers_last_input and unchanged_by_last_input keep their meaning, which MOEA/D's update shortcut reads.
  • UnboundedArchive(buffered=True) is the default; buffered=False keeps the eager behaviour.
  • State fields. archive_X and archive_F of AlgorithmState and NSGAIIState are ArchiveRows descriptors. record_archive_rows() offers a generation's rows and marks both fields stale, and the first read merges the archive once. An assignment while stale merges first, so the other field stays current.
  • Algorithms. AGE-MOEA, CCMO, CMOEA-MS, C-TAEA, IBEA, NSGA-II, NSGA-III, RVEA, SMS-EMOA and ToP offer each generation with record_archive_rows; MOEA/D and SPEA2 already went through update_archive, which now uses it.
    • SMPSO still updates at once, because it reads its leaders every step.
    • A live callback in population_archive mode and hypervolume termination read the archive every generation, so they merge every generation: exact, and no slower than before.
  • archive_core.py gives the buffering methods to the new module, which keeps it within the monolith guard's budget.
  • Docs: a note in the algorithm reference, after the unbounded-archive paragraph.

Why one merge gives the same rows

A clean archive's update keeps the feasible non-dominated rows of the archive plus the new rows, in the order they were offered, and the first of equal ones. Rejecting a row because an archived row dominates it, and later dropping that archived row, is transitive: the final set is the non-dominated subset of everything offered, whatever the batches.

Feasibility is the only order-dependent step, through the "least violated rows" rule while no feasible row exists. That is why rows are kept only once the archive holds feasible rows.

Checks

  • tests/engine/test_buffered_archive.py (42 tests):

    • Streams of 3000 rows with 2, 3 and 5 objectives, with and without constraints and NaN rows: coarse values give ties and duplicates, an infeasible start precedes the feasible rows, batch sizes are random from 1 to 120, PENDING_ROWS = 64 forces several merges, and the archive is read in between. Buffered and eager archives give equal contents, order and constraint values.
    • Twelve algorithms on ZDT1 and C1-DTLZ1 with an unbounded archive (NSGA-II, NSGA-III, MOEA/D, SMS-EMOA, SPEA2, IBEA, AGE-MOEA, RVEA, CCMO, C-TAEA, ToP, CMOEA-MS): the same X and F, bit for bit, as with the eager path. On ZDT1 the test also checks that rows were kept for a later merge.
    • Descriptors: every AlgorithmState subclass reads its archive fields through ArchiveRows; first reads, assignments while stale, and bounded archives updating at once.
  • tests/engine/test_moead_archive_update.py: its row counter now counts add as well as update.

  • Recorded streams of 200 000 evaluations (NSGA-II, population 100, as an algorithm offers them):

    Problem Objectives Archive Eager Buffered Same rows and order
    CRE21 2 6 987 4.97 s 0.10 s yes
    RCM08 3 11 782 11.51 s 0.16 s yes
    RCM25 2 112 232 85.40 s 0.28 s yes
    CRE51 5 61 538 hours (est.) 1.0 s the same rows as jMetal's archive and moocore's filter

    These come from the stream benchmark used to build the CRE and RCM reference fronts, where the archive dominated the campaign's time.

Validation

Run on Windows with Python 3.12, following AGENTS.md:

  • Typing: tools/typecheck.py --scope strict and --scope full give 0 diagnostics with ratchet new=0, in a .[dev]-only environment.
  • Health and docs:
    • tools/health.py: all health checks passed, the monolith guard included after the split;
    • mkdocs build --strict: passes;
    • tools/check_agent_docs.py: passes.
  • Lint: ruff, ruff format, compileall and git diff --check pass.
  • Tests: pytest -m "not slow" -n 6: 10 882 passed, 2 failed.
    • The monolith guard is fixed by the split.
    • tests/experiment/test_cli_ablation.py::test_cli_ablation_runs_and_writes_variants is pre-existing: it fails the same way under xdist on Windows on untouched main, and passes alone.
    • After the split: the guard, the buffered-archive and MOEA/D archive tests (99 passed), typing and health pass again.

Changelog entry

[Unreleased] — Changed

  • An unbounded external archive keeps the rows each generation offers and merges them (with moocore's non-dominated filter when moocore is installed) only when the archive is read or the kept rows outnumber twice the archive, instead of refiltering itself every generation.
    • The rows, their order and every result are the same.
    • A run that reads its archive only at the end filters it once: over 200 000 evaluations, 0.28 s instead of 85 s on a 112 000-row archive.
    • UnboundedArchive(buffered=False) keeps the eager updates.

🤖 Generated with Claude Code

…ith the same rows

An unbounded external archive filtered and deduplicated its whole contents
once per generation, so long runs spent most of their time on it (RCM25,
112 000 rows: 85 s of archive in 200 000 evaluations). Once its contents
are clean (feasible, finite, mutually non-dominated, deduplicated with a
zero objective tolerance), UnboundedArchive now keeps the rows each call of
add() offers and merges them in one update, with moocore's non-dominated
filter when moocore is installed, when contents(), constraint_values() or
update() needs them, or when the kept rows outnumber twice the archive.

One merge gives the rows, in the order, of one update per call: a clean
archive keeps the feasible non-dominated rows in the order they were
offered, and the first of equal ones. Before the first feasible row, and
for rows with non-finite feasible objectives, the archive updates at once.

The states' archive_X and archive_F are now ArchiveRows descriptors that
merge the archive on first read, and the algorithms offer each generation
with record_archive_rows(). A run that reads its archive only at the end
filters it once: 0.28 s instead of 85 s on RCM25, 0.16 s instead of 11.5 s
on RCM08, 0.1 s instead of 5 s on CRE21. SMPSO, which reads its leaders
every step, keeps updating at once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 18, 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-18T23:20:59.440039Z 9d52953 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-360-vamos-docs-preview.vamos-optimization.workers.dev

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

@NicolasRodriguezUribe
NicolasRodriguezUribe added this pull request to the merge queue Nov 18, 2026
Merged via the queue into main with commit baec11a Nov 18, 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