Repository navigation
feat(confsearch): docs, export, extend, merge and queue support (P4) - #66
Conversation
…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
left a comment
There was a problem hiding this comment.
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
9c108f2 to
d933986
Compare
… 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).
… 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.
6fe4248 to
079d957
Compare
…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.
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.
2ce8606 to
a22a933
Compare
… 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).
079d957 to
8811715
Compare
…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.
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
left a comment
There was a problem hiding this comment.
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 leavesrun_contextat the newcs_cycleswhile the checkpoint fingerprint still has the old one, so a plainresumeis refused and re-runningextendwould add cycles again. Letresumeapply thecs_cyclesexemption when the last recorded extension is newer than the checkpoint. - The P5 recalibration in
confsearch_suite.pymeasures 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.
a22a933 to
f07142d
Compare
…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.
8811715 to
eb766e1
Compare
…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.
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.
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.
eb766e1 to
54ba7f7
Compare
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.
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-mergeexists onthe 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-levelresults under
history/extension_N/, records the extension inrun_context.json, and resumes with the larger budget. The resume fingerprintexempts only
cs_cycles(section 11.3); every other change is still refused.mliport confsearch merge RUN1 RUN2 ... --output DIR: validates the section11.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.
"calc_type": "confsearch"in both modes(mode A:
structure+adsorbate_indices; mode B:slab+molecule+n_starts), mixing modes / partial mode B / aresumefield fail closed, andbuild_mliport_commandbuildsmliport confsearch run ...argv for bothmodes. The CLI gained every
CS_*flag the queue forwards.validation/science/scripts/confsearch_suite.py: the section 13.3owner-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
mergedoes not recompute refinement: merged rankings use the sourceregistries' quench energies (recorded in
results["merge"]).a GPU); only its system builder and report helpers are covered by CI.
Tests run and results
1598 passed, 33 skipped; integration tests grew to 14 (workflow pipelinewith 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.
cs_quench_fmax) measures: 12 of 15 re-quenches insidecs_dedup_geom_tol = 0.20 A, maximum residual 0.212 A, none leaving thebasin.
Deviations from spec
mergere-ranks by quench energy and reuses no refinement results; section11.4 says refinement results may be reused when the refine settings match, but
the refined geometries are not stored in
search_results.json, so reusingthem would require re-reading each source's
top/directories. It failsclosed instead (no recomputation, explicitly reported in the output).
extendis implemented as a command plus a workflow flag(
allow_cycle_change); the API does not expose it yet, and the capabilitymatrix says so.
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.
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_dictgap) were then fixed against the failing tests.Revision 5 follow-up (review of this PR)
extendvalidates before it archives (spec 11.3): the resume fingerprintis checked first (only
cs_cyclesexempt) and the previous results are movedto
history/extension_N/and recorded after it passes, using the workflowhelpers (
archive_for_extension/record_extension). A refused extension nowleaves
top/,history/andrun_context.jsonuntouched; the recordedcs_cyclesfollows the extension so a second extend still matches.--cycles N(the added count) no longer leaks into the resolvedconfiguration as the total. CLI-level tests cover both the successful
extension (strictly more quenches, new
raw/replica_*/cycle_002) and therefusal.
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.jsonrecords the samesystemblock.merge:<run name>) instead of thereplica + source_index * 1000offset that collided at >= 1000 replicas.confsearch exportuses the P2_export_candidatesignature.P5 real-slab recalibration.
validation/science/scripts/confsearch_suite.pynowre-measures the §13.2 dedup inputs on the campaign's own minima (pairwise
D/|dE|split byG, implied zero-false-merge tolerance, merge fraction atthe 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)
run_context["system"]now records the exact positions of the fixed atoms F(workflow and direct engine runs) and
_comparability_keycompares them, so twoterminations 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.
cs_cyclesexemptionnow substitutes the checkpoint's cycle count (not the context's, which the
crashed extend had already updated) and applies to a plain
resumewhen thecontext 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
extendno longer adds cycles twice.minima/all_minima.extxyz(all statuses) instead of the registryrepresentatives, which were already deduplicated and could never reveal a false
merge; the report adds the status breakdown and states what it measured.
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.