Skip to content

feat(confsearch): docs, export, extend, merge and queue support (P4) - #66

Merged
hydrogen1222 merged 6 commits into
mainfrom
confsearch/p4-queue-p5-validation
Oct 26, 2026
Merged

hydrogen1222 merged 6 commits into
mainfrom
confsearch/p4-queue-p5-validation

Conversation

@hydrogen1222

@hydrogen1222 hydrogen1222 commented Oct 25, 2026 •

Copy link
Copy Markdown
Owner

Tracking: #61
Implements spec revision 4, phase P4.

This PR is the P4 phase and contains two local commits: the P3 follow-up
(bilingual docs page + confsearch export) and the P4 work (extend, merge,
queue support). The intermediate branch confsearch/p4-extend-merge exists on
the remote but has no PR of its own; its commit is part of this PR's range. The
P5 validation-campaign script also landed in this range, because it shares the
engine's quench path.

What this does

  • mliport confsearch export RUN [--top-k K] [--window E] [--output DIR]
    re-exports the ranked candidates from a finished run's registry.
  • mliport confsearch extend RUN --cycles N: archives the previous top-level
    results under history/extension_N/, records the extension in
    run_context.json, and resumes with the larger budget. The resume fingerprint
    exempts only cs_cycles (section 11.3); every other change is still refused.
  • mliport confsearch merge RUN1 RUN2 ... --output DIR: validates the section
    11.4 comparability key (model identity including dispersion, task/head/dtype,
    regions, ionic species, bond/dedup/quench/refine settings), refuses
    incomparable runs with the differing keys, re-registers the unique minima in
    source order, consolidates across sources and re-ranks without any new
    calculation
    .
  • Queue support: task files accept "calc_type": "confsearch" in both modes
    (mode A: structure + adsorbate_indices; mode B: slab + molecule +
    n_starts), mixing modes / partial mode B / a resume field fail closed, and
    build_mliport_command builds mliport confsearch run ... argv for both
    modes. The CLI gained every CS_* flag the queue forwards.
  • validation/science/scripts/confsearch_suite.py: the section 13.3
    owner-run (GPU) campaign comparing N placements relaxed without MD against
    confsearch with the same N starts on CH3OH over an LGPS-derived slab, with an
    explicit "workflow behaviour only, no DFT accuracy claim" statement.

What it does NOT do yet

  • merge does not recompute refinement: merged rankings use the source
    registries' quench energies (recorded in results["merge"]).
  • Queue tasks cannot resume/extend/merge a confsearch run (those are commands).
  • The validation campaign was not executed here (it needs a real backend on
    a GPU); only its system builder and report helpers are covered by CI.
  • No TUI entry yet (P5).

Tests run and results

CUDA_VISIBLE_DEVICES="" .venv-dev/bin/python -m pytest -q
CUDA_VISIBLE_DEVICES="" .venv-dev/bin/python -m pytest tests/mliport/mliport/confsearch tests/mliport/mliport/test_confsearch_validation_suite.py -q
.venv-dev/bin/ruff check mliport/mliport tests scripts validation/science/scripts
.venv-dev/bin/ruff format --check mliport/mliport tests scripts validation/science/scripts
.venv-dev/bin/python scripts/check_repository_hygiene.py
  • 1598 passed, 33 skipped; integration tests grew to 14 (workflow pipeline
    with a synthetic model, extend with history archiving and the fingerprint
    exemption, merge of comparable runs including cross-source dedup, refusal of
    incomparable runs, export re-read), plus 5 queue tests and 5 validation-suite
    helper tests.
  • The real-quench calibration variant (egg-crate model at the production
    cs_quench_fmax) measures: 12 of 15 re-quenches inside
    cs_dedup_geom_tol = 0.20 A, maximum residual 0.212 A, none leaving the
    basin.

Deviations from spec

  • merge re-ranks by quench energy and reuses no refinement results; section
    11.4 says refinement results may be reused when the refine settings match, but
    the refined geometries are not stored in search_results.json, so reusing
    them would require re-reading each source's top/ directories. It fails
    closed instead (no recomputation, explicitly reported in the output).
  • extend is implemented as a command plus a workflow flag
    (allow_cycle_change); the API does not expose it yet, and the capability
    matrix says so.
  • A real quench can land slightly beyond the geometric tolerance (measured
    0.212 A vs 0.20 A), which produces a duplicate rather than a false merge —
    exactly the section 9.3 revision 4 preference, documented as a limitation.
  • Tests not written red-first: the queue task support and the validation
    campaign helpers were implemented first and covered by tests in the same
    commit; the extend/merge CLI paths were also implemented before their tests.
    The bugs found by those tests (merge status "failed" with no replicas, the
    registry from_dict gap) were then fixed against the failing tests.

Revision 5 follow-up (review of this PR)

  • extend validates before it archives (spec 11.3): the resume fingerprint
    is checked first (only cs_cycles exempt) and the previous results are moved
    to history/extension_N/ and recorded after it passes, using the workflow
    helpers (archive_for_extension / record_extension). A refused extension now
    leaves top/, history/ and run_context.json untouched; the recorded
    cs_cycles follows the extension so a second extend still matches.
    --cycles N (the added count) no longer leaks into the resolved
    configuration as the total. CLI-level tests cover both the successful
    extension (strictly more quenches, new raw/replica_*/cycle_002) and the
    refusal.
  • Merge key completed (spec 11.4 rev 5): the key now contains the §11.2
    model-identity subset plus the atomic numbers in order, the cell (exact), the
    PBC and the electronic state (charge/spin)
    — index sets alone are not enough,
    because two different slabs can share them. A context that predates this
    revision is refused with a clear message. The engine's direct
    run_context.json records the same system block.
  • Origins carry the source run id (merge:<run name>) instead of the
    replica + source_index * 1000 offset that collided at >= 1000 replicas.
  • confsearch export uses the P2 _export_candidate signature.
  • Docs (EN + ZH) state the calibration's known limitations and point at the
    P5 real-slab recalibration.
  • Validation campaign: validation/science/scripts/confsearch_suite.py now
    re-measures the §13.2 dedup inputs on the campaign's own minima (pairwise
    D/|dE| split by G, implied zero-false-merge tolerance, merge fraction at
    the shipped tolerance, whether it would merge a distinct pair) and reports it in
    the JSON and markdown report.

Confsearch + queue + validation suite on CPU: 246 passed; full suite on the
rebased stack 1632 passed, 33 skipped; lint/format/hygiene clean; CI green.


Revision 6 follow-up (second review of this PR)

  • Merge key includes the fixed-atom positions (spec rev 6 §11.4).
    run_context["system"] now records the exact positions of the fixed atoms F
    (workflow and direct engine runs) and _comparability_key compares them, so two
    terminations cut from one supercell -- same composition, atom order, cell and
    index sets -- can no longer be merged; a context without the field is refused.
    Test: the same everything with one fixed atom moved by 0.25 A is refused.
  • A crashed extend is resumable (spec rev 6 §11.3). The cs_cycles exemption
    now substitutes the checkpoint's cycle count (not the context's, which the
    crashed extend had already updated) and applies to a plain resume when the
    context records an extension covering its own budget. An extend that crashed
    after archiving/recording but before the first new unit therefore resumes, and
    re-running extend no longer adds cycles twice.
  • The dedup recalibration measures every quench record. It reads
    minima/all_minima.extxyz (all statuses) instead of the registry
    representatives, which were already deduplicated and could never reveal a false
    merge; the report adds the status breakdown and states what it measured.
  • Note: the P4 branch was rebuilt during the revision-6 rebase (the P3 logger fix
    is carried inside its commits), so this PR's commit list shows the P4 work in
    three commits plus the queue/validation and recalibration commits.

Confsearch + queue + validation suite on CPU: 248 passed; full suite 1639
passed, 33 skipped
; lint/format/hygiene clean; CI green.

…P4 part 1)

Tracking: #61 (spec revision 4; phases P3 remainder and P4)
Part of the MD-based configuration search feature.

P3 remainder:
- docs/workflows/confsearch.md + .zh.md (identical structure: 7 sections, 5
  code blocks, the same links) covering the v1 scope, the search algorithm, the
  model identity and gradient pre-flight, placement scales, the G-or-D dedup
  rule and its zero-false-merge calibration, the run outputs and the CP2K
  include syntax, resume, and every section 15 caveat (model domain,
  dispersion, frozen-slab bias, fixed cell, geometric guards, dipole
  correction, chemisorption trust). Added to mkdocs.yml nav, to the docs
  contract page list and to the documented CLI smoke list; the workflows index
  (EN + ZH) links it.
- `mliport confsearch export RUN [--top-k K] [--window E] [--output DIR]`
  re-exports the ranked candidates from a finished run's registry (documented:
  it uses the quench representatives, while the original top/ directories hold
  the refined geometries).
- The engine now writes run_context.json when the workflow has not, so a direct
  engine run is self-contained for export/merge.

P4 (part 1):
- `mliport confsearch extend RUN --cycles N`: archives the previous top-level
  results under history/extension_N/, records the extension in
  run_context.json, and resumes with the larger budget. The resume fingerprint
  exempts only cs_cycles (spec 11.3), so any other change is still refused.
- `mliport confsearch merge RUN1 RUN2 ... --output DIR`: validates the section
  11.4 comparability key (model identity including dispersion, task/head/dtype,
  regions, ionic species, bond/dedup/quench/refine settings), refuses
  incomparable runs with the differing keys, re-registers the unique minima in
  source order, consolidates across sources and re-ranks by quench energy
  without any new calculation.
- Capability matrix updated for extend/merge/export.

Tests: 12 -> 14 integration tests (workflow pipeline with a synthetic model,
extend with history archiving and fingerprint exemption, merge of comparable
runs including cross-source dedup, refusal of incomparable runs, export
re-read) plus the bilingual docs contract. Full suite on CPU: 1585 passed,
33 skipped.

DATA IMPACT: no scientific record invalidated. New outputs and commands only.

@hydrogen1222 hydrogen1222 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Review (spec rev 5) — P4: changes requested

1. confsearch extend via the CLI cannot work — blocking. _cmd_confsearch_extend (cli.py L2618–2690) writes the new cs_cycles into run_context.json["options"] (L2662) before calling the workflow. The workflow's allow_cycle_change path then reads that already-updated value as the "recorded" cycle count, builds the comparison fingerprint with the new count, and compares it with the checkpoint's old count → refused. By then the CLI has already moved search_results.json/top//diagnostics/ to history/ and recorded the extension, so the run is left inconsistent, and repeating the command records a second extension.
The integration test misses this because it calls archive_for_extension/record_extension directly (which do not touch options) and asserts n_quenches >= first_quenches, which also passes when no cycle ran.
Fix: validate the resume (fingerprint with only cs_cycles exempted) first, then archive and record; use the workflow helpers from the CLI instead of re-implementing them; assert strictly more quenches and the new cycle directories; add a CLI-level test (main(["confsearch","extend",...])).

2. Merge comparability key (§11.4 rev 5) — blocking. _comparability_key (cli.py L2699) compares index sets but not atomic numbers, cell, PBC or charge/spin. Two searches on different slabs with the same atom count and index sets merge into one registry and one ranking. Add those fields (from run_context/registry representatives). Conversely, dispersion is compared as a whole dict including device/version, so a CPU-D3 run and a GPU-D3 run cannot merge; use the rev 5 identity subset. Add a refusal test for a different cell with identical index sets.

3. Minor. The replica + source_index * 1000 relabelling silently collides for ≥1000 replicas; store the source run id in the origin as §11.4 says. The validation campaign still runs CH₃OH only; add the real-model dedup recalibration from the P1 review to its report.

🤖 Generated with Claude Code


Generated by Claude Code

… key (spec rev 5 §11.3/§11.4)

Tracking: #61 (spec revision 5, PR #66 review)
Addresses all three review items on #66.

`extend` (spec 11.3):
- the resume fingerprint is validated **first** and the previous results are
  archived/recorded **after** it passes.  The archiving moved from the CLI into
  the workflow (`archive_for_extension` + `record_extension`), so a refused
  extension no longer leaves the run with its results moved to `history/` and no
  new run.  `record_extension` also updates the recorded `cs_cycles`, otherwise
  a second extend would compare against the original budget and refuse.
- `--cycles N` (the *added* count) no longer leaks into the resolved
  configuration as the total: the CLI layer has higher precedence than the INCAR
  layer, so the added value was silently resolving back to the old budget.
- CLI-level tests: an extension adds cycles, archives `history/extension_1/`,
  updates the context and produces strictly more quenches plus a new
  `raw/replica_*/cycle_002`; a refused extension (different model file) leaves
  `top/`, `history/` and `run_context.json` untouched.
- the recorded starts are rebuilt into the config layer through the shared
  `_confsearch_layer_from_context` helper (the context stores a list, the config
  layer a pathsep scalar), which also fixes `mliport confsearch resume RUN`.

`merge` (spec 11.4 revision 5):
- the comparability key now contains the section 11.2 model-identity subset plus
  the **atomic numbers in order, the cell (exact), the PBC and the electronic
  state (charge/spin)**, because index sets alone are not enough -- two
  different slabs can share them.  A source run whose context predates this
  revision is refused with a clear message instead of being compared on index
  sets only.
- origins carry the source run id (`merge:<run name>`); the replica index is no
  longer offset by `source_index * 1000`, which silently collided for >= 1000
  replicas.
- the engine's direct `run_context.json` records the same `system` block, so
  runs created through the API/engine path are mergeable too.
- `run_context.json` gains `system` and `electronic_state` from the workflow.
- tests: a different cell with identical index sets is refused, and a context
  without the `system` block is refused.

`confsearch export` now calls the P2 `_export_candidate` signature (unique id +
payload) instead of the removed `unique=` form.

Docs (EN + ZH): the deduplication section states the calibration's known
limitations (bulk-cell geometry, perturbations instead of quenches, exact rigid
images) and points at the P5 real-slab recalibration.

DATA IMPACT: no scientific record invalidated. Extend now fails closed before
touching a run; merge refuses incomparable runs it previously accepted on index
sets alone. Confsearch suite on CPU: 165 passed (+55 docs-contract).
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
… key (spec rev 5 §11.3/§11.4)

Tracking: #61 (spec revision 5, PR #66 review)
Addresses all three review items on #66.

`extend` (spec 11.3):
- the resume fingerprint is validated **first** and the previous results are
  archived/recorded **after** it passes.  The archiving moved from the CLI into
  the workflow (`archive_for_extension` + `record_extension`), so a refused
  extension no longer leaves the run with its results moved to `history/` and no
  new run.  `record_extension` also updates the recorded `cs_cycles`, otherwise
  a second extend would compare against the original budget and refuse.
- `--cycles N` (the *added* count) no longer leaks into the resolved
  configuration as the total: the CLI layer has higher precedence than the INCAR
  layer, so the added value was silently resolving back to the old budget.
- CLI-level tests: an extension adds cycles, archives `history/extension_1/`,
  updates the context and produces strictly more quenches plus a new
  `raw/replica_*/cycle_002`; a refused extension (different model file) leaves
  `top/`, `history/` and `run_context.json` untouched.
- the recorded starts are rebuilt into the config layer through the shared
  `_confsearch_layer_from_context` helper (the context stores a list, the config
  layer a pathsep scalar), which also fixes `mliport confsearch resume RUN`.

`merge` (spec 11.4 revision 5):
- the comparability key now contains the section 11.2 model-identity subset plus
  the **atomic numbers in order, the cell (exact), the PBC and the electronic
  state (charge/spin)**, because index sets alone are not enough -- two
  different slabs can share them.  A source run whose context predates this
  revision is refused with a clear message instead of being compared on index
  sets only.
- origins carry the source run id (`merge:<run name>`); the replica index is no
  longer offset by `source_index * 1000`, which silently collided for >= 1000
  replicas.
- the engine's direct `run_context.json` records the same `system` block, so
  runs created through the API/engine path are mergeable too.
- `run_context.json` gains `system` and `electronic_state` from the workflow.
- tests: a different cell with identical index sets is refused, and a context
  without the `system` block is refused.

`confsearch export` now calls the P2 `_export_candidate` signature (unique id +
payload) instead of the removed `unique=` form.

Docs (EN + ZH): the deduplication section states the calibration's known
limitations (bulk-cell geometry, perturbations instead of quenches, exact rigid
images) and points at the P5 real-slab recalibration.

DATA IMPACT: no scientific record invalidated. Extend now fails closed before
touching a run; merge refuses incomparable runs it previously accepted on index
sets alone. Confsearch suite on CPU: 165 passed (+55 docs-contract).
…mpaign (spec rev 5 §13.2)

Tracking: #61 (spec revision 5, PR #66 review)

The PR #63/#66 review asked for the real-slab/real-model dedup recalibration
that the P1 calibration could not provide (it used CH3OH in the LGPS bulk cell,
perturbations instead of quenches and exact rigid images).

`validation/science/scripts/confsearch_suite.py` now computes it from the
campaign's own results:

- loads the finished search's registry, takes the rankable representatives and
  measures every pair's focused-fingerprint distance `D`, `|dE|` and MIC RMS
  displacement;
- splits the pairs by the geometric rule `G` (same basin vs distinct);
- reports min/median/max per class, the **implied zero-false-merge tolerance**
  `0.5 * min D` over the distinct pairs, how many same-basin pairs `D` alone
  would merge at the shipped `cs_dedup_fp_tol`, and whether the shipped
  tolerance would have merged a distinct pair;
- writes it into `confsearch_validation.json` and a "Dedup recalibration"
  section of `CONFSEARCH_VALIDATION.md`, with the interpretation that `G`
  carries same-basin merging and that widening the tolerance needs this
  evidence.

Tests: `tests/mliport/mliport/test_confsearch_validation_suite.py` grew to 7
tests, covering the distributions, the implied tolerance identity, the
merge-fraction bookkeeping and the single-minimum case.

DATA IMPACT: no scientific record invalidated. Validation-report content only;
the shipped tolerances are unchanged (this is the evidence to change them).
Confsearch + queue + validation suite on CPU: 246 passed.
@hydrogen1222
hydrogen1222 force-pushed the confsearch/p4-queue-p5-validation branch from 6fe4248 to 079d957 Compare October 25, 2026 16:32
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…mpaign (spec rev 5 §13.2)

Tracking: #61 (spec revision 5, PR #66 review)

The PR #63/#66 review asked for the real-slab/real-model dedup recalibration
that the P1 calibration could not provide (it used CH3OH in the LGPS bulk cell,
perturbations instead of quenches and exact rigid images).

`validation/science/scripts/confsearch_suite.py` now computes it from the
campaign's own results:

- loads the finished search's registry, takes the rankable representatives and
  measures every pair's focused-fingerprint distance `D`, `|dE|` and MIC RMS
  displacement;
- splits the pairs by the geometric rule `G` (same basin vs distinct);
- reports min/median/max per class, the **implied zero-false-merge tolerance**
  `0.5 * min D` over the distinct pairs, how many same-basin pairs `D` alone
  would merge at the shipped `cs_dedup_fp_tol`, and whether the shipped
  tolerance would have merged a distinct pair;
- writes it into `confsearch_validation.json` and a "Dedup recalibration"
  section of `CONFSEARCH_VALIDATION.md`, with the interpretation that `G`
  carries same-basin merging and that widening the tolerance needs this
  evidence.

Tests: `tests/mliport/mliport/test_confsearch_validation_suite.py` grew to 7
tests, covering the distributions, the implied tolerance identity, the
merge-fraction bookkeeping and the single-minimum case.

DATA IMPACT: no scientific record invalidated. Validation-report content only;
the shipped tolerances are unchanged (this is the evidence to change them).
Confsearch + queue + validation suite on CPU: 246 passed.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
Tracking: #61 (spec revision 5, PR #67 review)

The #67 review asked for a re-check after #63-#66 changed the option set.  The
TUI form exposes only mode A/B starts, cycles, the MD-mobile set, temperatures,
hold/cool durations and top-K, none of which changed semantics in revision 5;
anchored placement (whose partner set did change, section 5.2) is not exposed in
the TUI, and the live append-only `run.log` from section 11.1 makes the run
screen's progress tailing strictly better.

The existing TUI test now also pins the wording the review cares about: the
caveat note keeps "never a global minimum" and the dipole-correction advice, and
the mode note keeps the 0-based ASE convention and states that mode B is
placement rather than user starts.

Full suite on CPU: 1632 passed, 33 skipped; ruff check/format and the repository
hygiene check are clean.

DATA IMPACT: no scientific record invalidated. Test-only change.
@hydrogen1222
hydrogen1222 force-pushed the confsearch/p3-integration branch from 2ce8606 to a22a933 Compare October 25, 2026 16:44
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
… key (spec rev 5 §11.3/§11.4)

Tracking: #61 (spec revision 5, PR #66 review)
Addresses all three review items on #66.

`extend` (spec 11.3):
- the resume fingerprint is validated **first** and the previous results are
  archived/recorded **after** it passes.  The archiving moved from the CLI into
  the workflow (`archive_for_extension` + `record_extension`), so a refused
  extension no longer leaves the run with its results moved to `history/` and no
  new run.  `record_extension` also updates the recorded `cs_cycles`, otherwise
  a second extend would compare against the original budget and refuse.
- `--cycles N` (the *added* count) no longer leaks into the resolved
  configuration as the total: the CLI layer has higher precedence than the INCAR
  layer, so the added value was silently resolving back to the old budget.
- CLI-level tests: an extension adds cycles, archives `history/extension_1/`,
  updates the context and produces strictly more quenches plus a new
  `raw/replica_*/cycle_002`; a refused extension (different model file) leaves
  `top/`, `history/` and `run_context.json` untouched.
- the recorded starts are rebuilt into the config layer through the shared
  `_confsearch_layer_from_context` helper (the context stores a list, the config
  layer a pathsep scalar), which also fixes `mliport confsearch resume RUN`.

`merge` (spec 11.4 revision 5):
- the comparability key now contains the section 11.2 model-identity subset plus
  the **atomic numbers in order, the cell (exact), the PBC and the electronic
  state (charge/spin)**, because index sets alone are not enough -- two
  different slabs can share them.  A source run whose context predates this
  revision is refused with a clear message instead of being compared on index
  sets only.
- origins carry the source run id (`merge:<run name>`); the replica index is no
  longer offset by `source_index * 1000`, which silently collided for >= 1000
  replicas.
- the engine's direct `run_context.json` records the same `system` block, so
  runs created through the API/engine path are mergeable too.
- `run_context.json` gains `system` and `electronic_state` from the workflow.
- tests: a different cell with identical index sets is refused, and a context
  without the `system` block is refused.

`confsearch export` now calls the P2 `_export_candidate` signature (unique id +
payload) instead of the removed `unique=` form.

Docs (EN + ZH): the deduplication section states the calibration's known
limitations (bulk-cell geometry, perturbations instead of quenches, exact rigid
images) and points at the P5 real-slab recalibration.

DATA IMPACT: no scientific record invalidated. Extend now fails closed before
touching a run; merge refuses incomparable runs it previously accepted on index
sets alone. Confsearch suite on CPU: 165 passed (+55 docs-contract).
@hydrogen1222
hydrogen1222 force-pushed the confsearch/p4-queue-p5-validation branch from 079d957 to 8811715 Compare October 25, 2026 16:45
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…mpaign (spec rev 5 §13.2)

Tracking: #61 (spec revision 5, PR #66 review)

The PR #63/#66 review asked for the real-slab/real-model dedup recalibration
that the P1 calibration could not provide (it used CH3OH in the LGPS bulk cell,
perturbations instead of quenches and exact rigid images).

`validation/science/scripts/confsearch_suite.py` now computes it from the
campaign's own results:

- loads the finished search's registry, takes the rankable representatives and
  measures every pair's focused-fingerprint distance `D`, `|dE|` and MIC RMS
  displacement;
- splits the pairs by the geometric rule `G` (same basin vs distinct);
- reports min/median/max per class, the **implied zero-false-merge tolerance**
  `0.5 * min D` over the distinct pairs, how many same-basin pairs `D` alone
  would merge at the shipped `cs_dedup_fp_tol`, and whether the shipped
  tolerance would have merged a distinct pair;
- writes it into `confsearch_validation.json` and a "Dedup recalibration"
  section of `CONFSEARCH_VALIDATION.md`, with the interpretation that `G`
  carries same-basin merging and that widening the tolerance needs this
  evidence.

Tests: `tests/mliport/mliport/test_confsearch_validation_suite.py` grew to 7
tests, covering the distributions, the implied tolerance identity, the
merge-fraction bookkeeping and the single-minimum case.

DATA IMPACT: no scientific record invalidated. Validation-report content only;
the shipped tolerances are unchanged (this is the evidence to change them).
Confsearch + queue + validation suite on CPU: 246 passed.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
Tracking: #61 (spec revision 5, PR #67 review)

The #67 review asked for a re-check after #63-#66 changed the option set.  The
TUI form exposes only mode A/B starts, cycles, the MD-mobile set, temperatures,
hold/cool durations and top-K, none of which changed semantics in revision 5;
anchored placement (whose partner set did change, section 5.2) is not exposed in
the TUI, and the live append-only `run.log` from section 11.1 makes the run
screen's progress tailing strictly better.

The existing TUI test now also pins the wording the review cares about: the
caveat note keeps "never a global minimum" and the dipole-correction advice, and
the mode note keeps the 0-based ASE convention and states that mode B is
placement rather than user starts.

Full suite on CPU: 1632 passed, 33 skipped; ruff check/format and the repository
hygiene check are clean.

DATA IMPACT: no scientific record invalidated. Test-only change.

@hydrogen1222 hydrogen1222 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Second review (spec rev 6) — P4: one should-fix, two minor

First-review items resolved: extend validates before archiving (with a CLI-level test asserting strictly more quenches and a refused extension leaving the run untouched), merge key with numbers/cell/PBC/charge-spin, source run id in origins.

Should fix (spec rev 6 §11.4): two slabs with the same composition, atom order, cell and index sets but different geometry (e.g. two terminations cut from one supercell) still pass the key. Add the positions of the fixed atoms F (exact) to run_context["system"] and to _comparability_key; test: same everything but one fixed atom moved → refused.

Minor:

  • Extend crash window: after archive_for_extension + record_extension, a crash before the first new unit leaves run_context at the new cs_cycles while the checkpoint fingerprint still has the old one, so a plain resume is refused and re-running extend would add cycles again. Let resume apply the cs_cycles exemption when the last recorded extension is newer than the checkpoint.
  • The P5 recalibration in confsearch_suite.py measures pairs among registry representatives, which are already deduplicated, so it cannot reveal a false merge. Measure over all quench records (minima/all_minima.extxyz) instead.

🤖 Generated with Claude Code


Generated by Claude Code

…shed extend (spec rev 6 §11.4/§11.3)

Tracking: #61 (spec revision 6, second review of PR #66)

- **Merge key (spec 11.4 rev 6)**: `run_context["system"]` now records the exact
  positions of the fixed atoms F (workflow and direct engine runs) and
  `_comparability_key` compares them, so two terminations cut from one supercell
  -- same composition, atom order, cell and index sets -- can no longer be
  merged. A context without the field is refused with the "does not record"
  message. Test: the same everything with one fixed atom moved by 0.25 A is
  refused.
- **Extend crash window (spec 11.3 rev 6)**: the `cs_cycles` exemption now
  substitutes the **checkpoint's** cycle count (not the context's, which the
  crashed extend had already updated) and applies to a plain `resume` when the
  context records an extension covering its own budget. An extend that crashed
  after archiving/recording but before the first new unit is therefore
  resumable, and re-running `extend` no longer adds cycles twice. Test: archive +
  record an extension, then resume without `allow_cycle_change` -> accepted, no
  second extension recorded.

DATA IMPACT: no scientific record invalidated. Merging becomes stricter
(fixed-atom geometry must match); a crashed extension resumes instead of being
refused. Confsearch + docs-contract suite on CPU: 222 passed.
…n (P4 done, P5 part 1)

Tracking: #61 (spec revision 4; phases P4 remainder and P5)
Part of the MD-based configuration search feature.

P4 remainder - queue support (spec section 14 P4):
- task files accept "calc_type": "confsearch" in both modes: mode A is
  `structure` + `adsorbate_indices`, mode B is `slab` + `molecule` + `n_starts`;
  mixing the two, partial mode-B fields and a `resume` field fail closed (the
  message points at `mliport confsearch resume`, which is a command).
- the CLI gained every CS_* flag the queue needs to forward (`--cycles`,
  `--md-mobile`, `--temperature-high/low`, `--hold-ps`, `--cool-ps`,
  `--snapshot-interval-ps`, `--ramp-interval`, `--save-interval`,
  `--accept-temperature`, `--top-depth`, `--fix-below`, `--quench-fmax/steps`,
  `--bond-scale`, `--bond-break-scale`, `--ionic-species`, `--reaction-policy`,
  `--desorption-distance`, `--min-image-distance`, `--min-vacuum-gap`,
  `--place-*`, `--dedup-*`, `--fp-*`, `--top-k`, `--export-window`,
  `--refine/--no-refine`, `--allow-direct-forces/--no-...`, `--refine-fmax/steps`),
  and `build_mliport_command` builds `mliport confsearch run ...` argv for both
  modes.

P5 part 1 - validation campaign script (spec section 13.3, owner-run on GPU):
- validation/science/scripts/confsearch_suite.py cuts a fixed slab from the
  repository's LGPS structure (one contiguous slab, vacuum across c, F non-empty)
  and runs CH3OH on it twice through the product: N random placements relaxed
  without MD (`--cycles 0`, the multi-start baseline) and confsearch with the
  same N starts and seed, then reports best energies, unique counts, hit counts
  and the discovery curve plus an explicit "workflow behaviour only, no DFT
  accuracy claim" statement. CI checks the system builder and the report
  helpers; the campaign itself needs a real backend.
- The TUI entry is still missing and remains `no` in the capability matrix.

Calibration (spec 13.2 revision 4): the sweep now also runs the *real* quench
variant of class (a) with the egg-crate model at the production
cs_quench_fmax. Measured: re-quench residuals stay inside
cs_dedup_geom_tol = 0.20 A for 12 of 15 perturbations and reach at most 0.21 A,
so the residual 3 are documented duplicates (a false split, which the section
9.3 revision 4 rule explicitly prefers over a false merge); none leaves the
basin.

Docs: the configuration page lists confsearch as a calc type and its start
keys; the development layout lists the new package (EN + ZH, same structure).

DATA IMPACT: no scientific record invalidated. New commands, tests and docs
only. Full suite on CPU: 1598 passed, 33 skipped.
Tracking: #61 (spec revision 6, second review of PR #66)

The campaign's dedup recalibration measured pairwise distances among the
**registry representatives**, which are already deduplicated, so it could never
reveal a false merge (the failure mode the tolerance exists to prevent).

`_dedup_recalibration` now reads `minima/all_minima.extxyz` (every quench record,
all statuses), rebuilds lightweight records from the frame provenance, and
reports:

- the quench-record status breakdown, so the reader sees how much of the sample
  is usable;
- `D` / `|dE|` / RMS-displacement distributions split by the geometric rule `G`
  over all pairs (same-basin pairs now include the duplicates within a basin,
  which is exactly what a false merge would collapse);
- the implied zero-false-merge tolerance from the pairs `G` does not match,
  the merge fraction at the shipped tolerance, and whether the shipped tolerance
  would merge a distinct pair.

The markdown report states what it was measured over.  Tests: the recalibration
test now asserts `n_minima == len(all_minima.extxyz frames)`, that the pair count
is the full pairwise count and that the status breakdown covers every frame.

DATA IMPACT: no scientific record invalidated. Validation-report content only;
shipped tolerances unchanged. Confsearch + queue + validation suite on CPU: 248
passed.
@hydrogen1222
hydrogen1222 force-pushed the confsearch/p3-integration branch from a22a933 to f07142d Compare October 26, 2026 03:12
hydrogen1222 added a commit that referenced this pull request Oct 26, 2026
…shed extend (spec rev 6 §11.4/§11.3)

Tracking: #61 (spec revision 6, second review of PR #66)

- **Merge key (spec 11.4 rev 6)**: `run_context["system"]` now records the exact
  positions of the fixed atoms F (workflow and direct engine runs) and
  `_comparability_key` compares them, so two terminations cut from one supercell
  -- same composition, atom order, cell and index sets -- can no longer be
  merged. A context without the field is refused with the "does not record"
  message. Test: the same everything with one fixed atom moved by 0.25 A is
  refused.
- **Extend crash window (spec 11.3 rev 6)**: the `cs_cycles` exemption now
  substitutes the **checkpoint's** cycle count (not the context's, which the
  crashed extend had already updated) and applies to a plain `resume` when the
  context records an extension covering its own budget. An extend that crashed
  after archiving/recording but before the first new unit is therefore
  resumable, and re-running `extend` no longer adds cycles twice. Test: archive +
  record an extension, then resume without `allow_cycle_change` -> accepted, no
  second extension recorded.

DATA IMPACT: no scientific record invalidated. Merging becomes stricter
(fixed-atom geometry must match); a crashed extension resumes instead of being
refused. Confsearch + docs-contract suite on CPU: 222 passed.
@hydrogen1222
hydrogen1222 force-pushed the confsearch/p4-queue-p5-validation branch from 8811715 to eb766e1 Compare October 26, 2026 03:13
hydrogen1222 added a commit that referenced this pull request Oct 26, 2026
…mpaign (spec rev 5 §13.2)

Tracking: #61 (spec revision 5, PR #66 review)

The PR #63/#66 review asked for the real-slab/real-model dedup recalibration
that the P1 calibration could not provide (it used CH3OH in the LGPS bulk cell,
perturbations instead of quenches and exact rigid images).

`validation/science/scripts/confsearch_suite.py` now computes it from the
campaign's own results:

- loads the finished search's registry, takes the rankable representatives and
  measures every pair's focused-fingerprint distance `D`, `|dE|` and MIC RMS
  displacement;
- splits the pairs by the geometric rule `G` (same basin vs distinct);
- reports min/median/max per class, the **implied zero-false-merge tolerance**
  `0.5 * min D` over the distinct pairs, how many same-basin pairs `D` alone
  would merge at the shipped `cs_dedup_fp_tol`, and whether the shipped
  tolerance would have merged a distinct pair;
- writes it into `confsearch_validation.json` and a "Dedup recalibration"
  section of `CONFSEARCH_VALIDATION.md`, with the interpretation that `G`
  carries same-basin merging and that widening the tolerance needs this
  evidence.

Tests: `tests/mliport/mliport/test_confsearch_validation_suite.py` grew to 7
tests, covering the distributions, the implied tolerance identity, the
merge-fraction bookkeeping and the single-minimum case.

DATA IMPACT: no scientific record invalidated. Validation-report content only;
the shipped tolerances are unchanged (this is the evidence to change them).
Confsearch + queue + validation suite on CPU: 246 passed.
hydrogen1222 added a commit that referenced this pull request Oct 26, 2026
Tracking: #61 (spec revision 6, second review of PR #66)

The campaign's dedup recalibration measured pairwise distances among the
**registry representatives**, which are already deduplicated, so it could never
reveal a false merge (the failure mode the tolerance exists to prevent).

`_dedup_recalibration` now reads `minima/all_minima.extxyz` (every quench record,
all statuses), rebuilds lightweight records from the frame provenance, and
reports:

- the quench-record status breakdown, so the reader sees how much of the sample
  is usable;
- `D` / `|dE|` / RMS-displacement distributions split by the geometric rule `G`
  over all pairs (same-basin pairs now include the duplicates within a basin,
  which is exactly what a false merge would collapse);
- the implied zero-false-merge tolerance from the pairs `G` does not match,
  the merge fraction at the shipped tolerance, and whether the shipped tolerance
  would merge a distinct pair.

The markdown report states what it was measured over.  Tests: the recalibration
test now asserts `n_minima == len(all_minima.extxyz frames)`, that the pair count
is the full pairwise count and that the status breakdown covers every frame.

DATA IMPACT: no scientific record invalidated. Validation-report content only;
shipped tolerances unchanged. Confsearch + queue + validation suite on CPU: 248
passed.
hydrogen1222 added a commit that referenced this pull request Oct 26, 2026
Tracking: #61 (spec revision 5, PR #67 review)

The #67 review asked for a re-check after #63-#66 changed the option set.  The
TUI form exposes only mode A/B starts, cycles, the MD-mobile set, temperatures,
hold/cool durations and top-K, none of which changed semantics in revision 5;
anchored placement (whose partner set did change, section 5.2) is not exposed in
the TUI, and the live append-only `run.log` from section 11.1 makes the run
screen's progress tailing strictly better.

The existing TUI test now also pins the wording the review cares about: the
caveat note keeps "never a global minimum" and the dipole-correction advice, and
the mode note keeps the 0-based ASE convention and states that mode B is
placement rather than user starts.

Full suite on CPU: 1632 passed, 33 skipped; ruff check/format and the repository
hygiene check are clean.

DATA IMPACT: no scientific record invalidated. Test-only change.
@hydrogen1222
hydrogen1222 force-pushed the confsearch/p4-queue-p5-validation branch from eb766e1 to 54ba7f7 Compare October 26, 2026 03:18
hydrogen1222 added a commit that referenced this pull request Oct 26, 2026
Tracking: #61 (spec revision 5, PR #67 review)

The #67 review asked for a re-check after #63-#66 changed the option set.  The
TUI form exposes only mode A/B starts, cycles, the MD-mobile set, temperatures,
hold/cool durations and top-K, none of which changed semantics in revision 5;
anchored placement (whose partner set did change, section 5.2) is not exposed in
the TUI, and the live append-only `run.log` from section 11.1 makes the run
screen's progress tailing strictly better.

The existing TUI test now also pins the wording the review cares about: the
caveat note keeps "never a global minimum" and the dipole-correction advice, and
the mode note keeps the 0-based ASE convention and states that mode B is
placement rather than user starts.

Full suite on CPU: 1632 passed, 33 skipped; ruff check/format and the repository
hygiene check are clean.

DATA IMPACT: no scientific record invalidated. Test-only change.
Base automatically changed from confsearch/p3-integration to main October 26, 2026 04:17
@hydrogen1222
hydrogen1222 marked this pull request as ready for review October 26, 2026 04:17
@hydrogen1222
hydrogen1222 merged commit 4a164b1 into main Oct 26, 2026
13 checks passed
@hydrogen1222
hydrogen1222 deleted the confsearch/p4-queue-p5-validation branch October 26, 2026 04:17
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