Repository navigation
[DEV MASTER · DO NOT MERGE/CLOSE] MLIP validation roadmap (#75) + confsearch living spec - #61
hydrogen1222 wants to merge 1 commit into
Conversation
Empty commit so GitHub can host the never-merged tracking PR whose description is the living specification for MD-based configuration search. No code, docs or plan files are committed (AGENTS.md rule 9). DATA IMPACT: no scientific record invalidated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017vVRW3uEnhYKFinpvqMysi
§13.2 fingerprint calibration (spec revision 4) — P1 evidenceTracking: #61. This is the calibration required by §9.3/§13.2 revision 4 before P2 may start. It is reproducible from the repository: Pair classes (geometry-labelled, on the repository's LGPS structure
σ sweep (
Tie-break per §13.2 step 4 (maximise the (d) merge fraction, then larger σ) selects σ = 0.20. Shipped defaults: ΔE: this P1 calibration has no calculator, so the |ΔE| ≤ Real-quench variant of class (a) (egg-crate model, quenched at the production Split/merge rates with the shipped defaults: (d) 4/4 merged by Real-slab recalibration (P5): the same campaign that runs the workflow Known limitation: |
…h (P0) Tracking: #61 (spec revision 2, phase P0) Part of the MD-based configuration search feature. What was failing: confsearch (P2) needs exactly the numerical-safety gates MD already enforces (atomic-state validation, finite energy/force checks, raw vs constraint-applied force views, raw-force fmax_abort evaluation, safe-point validation), the NEB energy-force gradient pre-flight, and the NEB model identity record. All three were private to MDRunner/BaseRunner/neb.workflow, so reusing them would have meant copy-paste or behaviour drift. What fixes it: mliport/runners/safety.py now owns the stateless gates; MDRunner and BaseRunner delegate with identical messages and evaluation order. neb.preflight.run_gradient_preflight is generalized to accept >=1 structure via minimum_structures and a PreflightNaming (wording, schema, error class), with NEB defaults reproducing the historical text exactly (still >=2 images). mliport/model_record.build_model_record is the extracted model-identity helper plus the `dispersion` field; NEB calls it with NEBPreparationError and its resume fingerprint is unchanged (it selects identity keys explicitly). DATA IMPACT: no scientific record invalidated. No numerical result changes; the NEB resume fingerprint is provably unchanged by the added `dispersion` field (pinned by test). Existing tests unchanged and green: 1446 passed, 33 skipped (CPU only).
… §5.2) Tracking: #61 (spec revision 5, PR #63 review) Addresses review items 1-3 on #63. - Anchored placement now solves the height against the anchor's **partner set**: the non-ionic slab atoms by default, or exactly the `cs_place_anchor_targets` elements when that option is set. Previously the minimum `q` was taken over every slab atom, so an anchor O could be placed at 1.1x the O+Li radii sum from a lithium: an ionic contact that §8.1/§8.2 then classify as physisorbed, i.e. the "chemisorption-first" start was not chemisorbed. `anchor_partner_indices()` fails closed when the slab has no partner at all (all-ionic slab without targets). - Tests: a Li-terminated slab must bond the O anchor to a sulfur (and the recomputed min q over non-ionic atoms equals `cs_place_anchor_scale`), `cs_place_anchor_targets="Li"` is the explicit opt-in to an ionic partner, and an all-ionic slab without targets is refused. - `fingerprint.py` docstring rewritten for revisions 3-5: ASE discretisation, the withdrawn pre-rev-3 point-sampled formula, the strict per-bin 1e-10 known-answer test that never skips (ASE 3.26 oracle when the ASE 3.29 shim is in place), and the self-image paragraph reworded as a cutoff-boundary effect (images at exactly rcut) rather than an ASE defect. - `placement.py` documents that `min q` is monotone except in the descent branch, where atoms can end up slightly below the slab top. - `options.py` and the calibration test now state the P1 calibration's known limitations (bulk-cell geometry, perturbations instead of quenches, exact rigid images) and point at a real-slab/real-model recalibration as a P5 validation item. DATA IMPACT: no scientific record invalidated. Placement semantics change only for anchored starts on slabs containing ionic species; the shipped defaults and the fingerprint/dedup behaviour are unchanged. Full confsearch suite on CPU: 112 passed.
…ts (P2) Tracking: #61 (spec revision 4, phase P2) Part of the MD-based configuration search feature. What was missing: P1 had no way to run a search - no MD cycles, no quench pipeline, no Metropolis, no checkpointing and no results. What this adds: - quench.py: fixed-cell FIRE on R with only FixAtoms, per-step finite/force gates, quench_failed / quench_not_converged as outcomes, and refine(). - engine.py: the section 7.1 schedule (start quench -> round-robin cycles -> consolidation -> refinement -> ranking), the section 7.2 mobile sets, the section 7.3 cycle (Maxwell-Boltzmann over the mobile DOF with zero fixed momenta, Langevin hold, linear cool ramp with set_temperature every cs_ramp_interval, snapshot frames, per-step safety, early integrity abort, end-of-cycle Metropolis with the uniform draw taken every eligible proposal), the section 7.5 SeedSequence streams, raw/replica_RRR/cycle_CCC output through AsyncMDOutputWriter (unchanged MD_CSV_HEADER) and cycle.json, and the section 7.1 failed_start handling. - checkpoint.py: atomic JSON checkpoints after every unit, resume fingerprint (version, revisions, model, input hashes, regions, seed, every option except output/verbosity), key-level diffing on refusal, and incomplete-attempt archiving that never deletes raw files. - results.py: discovery.csv, saturation diagnostics ("lowest found", never "global minimum"), baseline vs search, the section 8.5 warnings, top-K refinement, ranking in separate refined/unrefined tables, artifacts.json and the section 10.5 exports (POSCAR with selective dynamics, structure.extxyz, cp2k_coord.xyz, cp2k_cell.inc, cp2k_fixed_atoms.inc, minimum.json) with the slab wrapped and the adsorbate made whole under MIC. Tests (spec 13.1/13.2): test-only synthetic calculators (egg-crate with three known sites and exactly known energies, shallow-Morse bond breaking, direct force, non-finite) plus end-to-end tests that the search finds every known minimum to 1e-6 eV, that same-basin quenches merge through G, that fixed atoms never move, that the temperature ramp is the documented linear schedule, that force/non-finite/integrity aborts are recorded and the search continues, that two runs with one seed are identical, that an interrupted run resumed from its checkpoint reproduces the uninterrupted ranking exactly, and that exports re-read equal to the minimum up to lattice translations. DATA IMPACT: no scientific record invalidated. New outputs only. Full suite on CPU: 1569 passed, 33 skipped.
…puts (spec rev 5 §10/§11.1) Tracking: #61 (spec revision 5, PR #64 review) Addresses all six review items on #64. Ranking and refinement (spec 10.1/10.3): - a refinement replaces the quench result only when it converged **and** its classification is still rankable; an unconverged refinement keeps the quench result and is flagged (`refinement_failed`, note `refinement_not_converged`); a refinement that changed to a non-rankable status leaves the ranking entirely with a recorded reason (`refinement_changed_status`); - the refined set is re-deduplicated with the section 9.3 rule through a scratch registry, and a merged entry keeps the summed hit counts, the union of replicas and the earliest first-found record; - ranking and export directories follow the **refined** energy, so `top/rank_001` is the lowest refined structure; - refined and unrefined energies are never interleaved: each table has its own best energy, the export window is relative to the refined best, and `ranking.best_energy_source` says which table the reported best came from. Engine (spec 7.3): - abort frames are never quenched: the observer checks the integrity *before* keeping a snapshot, the force abort raises before the snapshot is kept, and the `except` clause no longer appends the abort frame, so an integrity-abort frame is not quenched twice; - the end-of-cycle frame gets the same early integrity check as the hold-phase snapshots; - `quench()` no longer lets a calculator that raises on a bad geometry escape as an uncaught exception; the outcome is `quench_failed`. Diagnostics (spec 10.2/10.4): - `top_k_never_reached_by_start_quench` now means "no *member* has a start origin" (merged refined entries are checked through all their source ids); - `first_found_fraction` and `best_first_found_fraction` use the unique's `first_found_quench_index`, not the representative's own quench index. Outputs (spec 11.1): - `minima/all_minima.extxyz` now holds every quench result of every status with its provenance (unique id, record id, status, flags, energy, fmax, steps, quench index, cumulative MD ps, origin), and `minima/registry.json` holds the registry. Non-finite energies are omitted from the frame info because extxyz cannot carry NaN. Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers reordering, merging, unconverged refinement, status change, the minima directory and the member-based diagnostics. Full confsearch suite on CPU: 132 passed. DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the `minima/` contents change; runs are re-ranked from their stored quench results.
…P3, partial) Tracking: #61 (spec revision 4, phase P3) Part of the MD-based configuration search feature. What was missing: the P2 engine could only be driven from Python with hand-built starts; no config keys, no CLI, no API and no provenance files. What this adds: - prepare.py: structure loading (multi-frame files and directories), mode A (cs_starts + cs_adsorbate_indices) and mode B (cs_slab/cs_molecule/ cs_n_starts placement), the section 5.1 exact multi-start identity check and the input content hashes used by the resume fingerprint. - workflow.py: model identity (including dispersion), the direct_forces gate, the generalized gradient pre-flight with confsearch wording, the resume fingerprint/refusal, run_context.json, run.log and the engine call. - Config registration (spec 12.3): "confsearch" added to the calc_type choices, IncarConfig.validate and CalculationEngine.VALID_CALC_TYPES; the confsearch scope added to timestep/friction/seed/fmax_abort/charge/spin; all CS_* keys in the schema, BUILTIN_DEFAULTS["confsearch"] (mirroring CS_DEFAULTS) and DEFAULT_DEVICE_BY_CALC_TYPE; the resolver rejects MD-only keys for confsearch instead of ignoring them; `mliport template confsearch` renders the INCAR. - CLI: `mliport confsearch run|place|resume` with --dry-run (validate inputs, regions and budget without loading a model) and placement-only `place` (writes starts/start_XXX.extxyz + POSCAR + placement.json). - API: `mliport.api.run_confsearch` (exported from `mliport`) mirroring the CLI. - Capability matrix: confsearch_user_starts/placement/resume = yes, extend/merge = no (P4), export = partial (exports are written by every run; the standalone re-export command is not implemented yet). - CHANGELOG entry; `scipy`/`matplotlib` added to the dev extra in P1 so the strict ASE OFP known-answer test runs in CI. Not yet done in P3 (reported, not hidden): the bilingual docs page (docs/workflows/confsearch.md + .zh.md, nav and docs-contract entry) and the `confsearch export RUN` re-export command; P4 (extend/merge/queue) and P5 (TUI, validation campaign) are untouched and marked accordingly in the capability matrix. DATA IMPACT: no scientific record invalidated. New entry points and outputs only. Full suite on CPU: 1578 passed, 33 skipped.
…int (spec rev 5 §11) Tracking: #61 (spec revision 5, PR #65 review) Addresses all four review items on #65. - `run.log` is now the existing `LiveRunLogger` (extended with an `append` keyword, default off so the other workflows are unaffected) opened in append mode: it exists from the first line, survives a crash, and a resume or extension adds to the run's history instead of rewriting the file at the end of the run. - `run_context.json` is created once and then updated in place: a resume appends a `resumes[]` entry (timestamp, checkpoint unit index, seed, version) and refreshes `finished_at`; the recorded identity, regions, budget, starts and options are never rebuilt from scratch. - `resolved_config.json` is written for every **new** run by the workflow (both the CLI and the API path go through it), mirroring the CLI emitter (atomic replace, honours `write_resolved_config`); a resume leaves it untouched. - `CalculationEngine.run_confsearch` takes the shared run-directory lock for `resume` too, so two frontends cannot append to one run.log or checkpoint concurrently. - The resume fingerprint now uses the section 11.2 revision 5 **model identity** subset: `model_type, model_sha256, backend_version, framework_versions, task, head_effective, dtype_effective, inference_mode, compile_enabled, direct_forces` plus `dispersion.{method, xc, damping, implementation, version}`. `actual_device_*`, `backend_reported_device`, `model_path`, `model_alias`, `model_source` and `dispersion.device` are excluded, so resuming on another GPU or with a moved copy of an identical checkpoint is allowed; the devices stay recorded in `run_context.json`. Tests: `tests/mliport/mliport/confsearch/test_resume_identity.py` (14 tests) covers the identity subset, the excluded device/path fields, the dispersion sub-keys, refusal on model/dtype/head/inference/task/framework/backend/ direct_forces/dispersion changes, the key-level diff, and the workflow-level append-only run.log / updated run_context / untouched resolved_config.json. DATA IMPACT: no scientific record invalidated. The resume fingerprint becomes less strict (device/path excluded), so a checkpoint written by the previous revision may resume where it previously refused; no computed number changes. Confsearch suite on CPU: 193 passed (with the shared engine/timing tests).
Tracking: #61 (spec revision 5, PR #65 follow-up) Found while adding the CLI-level extend test for the P4 review: `mliport confsearch resume RUN` (and the P4 `extend`) copied `run_context.json`'s `options` straight back into the config layer, but the context records `cs_starts` as a **list** while the config layers carry the `os.pathsep`-joined scalar. The resolver then validated the stringified list (`"['/path/start.extxyz']"`) as a path and refused with "cs_starts: path not found", i.e. no recorded run could be resumed from the CLI. - new `_confsearch_layer_from_context()` converts the recorded starts back to the scalar form and adds the model/device layer; both the resume path and the P4 extend path use it. - regression test: a run created by the workflow is resumed through the CLI (`monkeypatch`ed synthetic backend at the engine seam) and must exit 0 with a `resumes[]` entry recorded. DATA IMPACT: no scientific record invalidated. CLI resume/extend of an existing run directory now works; no computed number changes. Confsearch suite on CPU: 156 passed.
…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.
… 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).
…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.
…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 4, phase P5) Part of the MD-based configuration search feature. What was missing: the TUI could not start a confsearch run at all (the capability matrix recorded `no` for every confsearch TUI column). What this adds: - main screen: a "Configuration Search (CONFSEARCH)" entry, and the template screen plus `mliport template confsearch` can now generate the INCAR template. - configuration screen: a confsearch form with both start modes (Structure File + 0-based Adsorbate Indices for mode A; Slab File + Molecule File + Number of Placed Starts for mode B), cycles, MD-mobile set, high/low temperature, hold/cool durations and exported top-K, plus a note that the ranking reports the lowest minimum found (never a global minimum) and that a one-sided slab needs a dipole correction in the DFT single point. - validation in _save_and_run: mixing mode A and B, a partial mode B, missing paths, non-integer counts, non-finite/negative temperatures and low > high all fail with a notification instead of launching a bad job; mode B names the slab as the structural input so the shared guard still applies. - run screen: the confsearch branch forwards every confsearch option and the mode A/B structural fields to the *shared* `build_mliport_command` helper, so the TUI and `mliport queue submit` cannot drift. - capability matrix: confsearch_user_starts and confsearch_placement are now `yes` for the TUI; resume/extend/merge/export stay `no` with notes (resuming is a command). - docs (EN + ZH): a sentence on the TUI entry and on extend/merge being commands, structure unchanged. Tests: four TUI tests (the main-screen entry, the confsearch form widgets, the mode A and mode B background commands, and the partial-mode-B rejection). Full suite on CPU: 1602 passed, 33 skipped. DATA IMPACT: no scientific record invalidated. New entry point only.
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 (spec revision 4, phase P1) Part of the MD-based configuration search feature. What was missing: mliport/confsearch/ did not exist, so nothing could prepare starts, describe a minimum, or deduplicate quench results. What this adds (calculator-free, synthetic-structure testable): - options.py: frozen ConfsearchOptions with every section 12.3 cross-key rule (mode A/B exclusivity, exact integer step conversions with nearest valid values, break > bond scale, binwidth <= sigma/2, v1 non-goals rejected by name), index_spec.py: the 0-based "0,5,7-9" parser with compression. - regions.py: A/S/F/R resolution, FixScaled/FixCom rejection, cs_fix_below, the +z surface convention, slab contiguity, one-sided adsorption, non-ionic adsorbate connectivity, the H/timestep gate and the section 7.2 mobile sets. - graphs.py: covalent graphs from ase.data.covalent_radii, ionic exclusion, the MD break-scale check, chemisorption flags, slab-rearrangement flags and the section 8.2 status rules in order. - fingerprint.py: focused Oganov-Valle with ASE's discretisation (spec 9.2 revision 3): nbins = ceil(rcut/Delta), bin radius (k+1)Delta, erf bin smearing renormalised to 1, 4 pi r^2 Delta and N_beta/V normalisation, ordered species keys and the section 9.2 weights. - registry.py: delta-E AND (G OR D) matching (spec 9.3 revision 4), the direct geometric identity G with cs_dedup_geom_tol (disabled and recorded when F is empty), smallest (not G, D) selection, per-status registries, representative update and the section 9.5 consolidation pass. - placement.py: centroiding, Shoemake rotations, contact and anchored placement solved by bisection on element-pair covalent-radii ratios, anchor targets, per-reason rejection counts and the recorded placement provenance. Deviations from the letter of section 9.2, both required by section 9.2 itself and documented in the module docstring: - self-image pairs are enumerated explicitly because ASE's neighbor_list returns an orientation-dependent subset of them (48 vs 72 pairs on a 4x4x20 A slab before/after a rigid rotation, while the 350 cross pairs are identical); - pair distances are rounded to 1e-9 A before the bin division because a distance at a decimal multiple of Delta (e.g. a 0.96 A O-H bond) otherwise flips its whole 21-bin smearing window under a rigid rotation. The strict ASE known-answer tests still pass to 1e-10 on non-boundary geometries (per-bin arrays, F_ab == F_ba, collapsed D), and scipy/matplotlib were added to the dev extra so they run in CI instead of skipping. Calibration (spec 13.2 revision 4, geometry-labelled pairs on the repository's LGPS structure, pinned as a regression test): same basin 25 pairs (G), 11 documented false splits (0.20-0.5 A); distinct sites/conformers 63 pairs, min D = 8.5e-4 at sigma = 0.20; equivalent pairs (rigid slab map + CH3 permutation) all merge (D ~ 0). Shipped defaults: cs_fp_sigma = 0.20, cs_dedup_fp_tol = 0.0004 (zero false merges with a factor-2 margin), cs_dedup_geom_tol = 0.20 A. DATA IMPACT: no scientific record invalidated (no existing workflow changed). New defaults are recorded here and in the calibration test; the P2 engine will re-run the same sweep with real quenches at cs_quench_fmax. Full suite on CPU: 1555 passed, 33 skipped.
… §5.2) Tracking: #61 (spec revision 5, PR #63 review) Addresses review items 1-3 on #63. - Anchored placement now solves the height against the anchor's **partner set**: the non-ionic slab atoms by default, or exactly the `cs_place_anchor_targets` elements when that option is set. Previously the minimum `q` was taken over every slab atom, so an anchor O could be placed at 1.1x the O+Li radii sum from a lithium: an ionic contact that §8.1/§8.2 then classify as physisorbed, i.e. the "chemisorption-first" start was not chemisorbed. `anchor_partner_indices()` fails closed when the slab has no partner at all (all-ionic slab without targets). - Tests: a Li-terminated slab must bond the O anchor to a sulfur (and the recomputed min q over non-ionic atoms equals `cs_place_anchor_scale`), `cs_place_anchor_targets="Li"` is the explicit opt-in to an ionic partner, and an all-ionic slab without targets is refused. - `fingerprint.py` docstring rewritten for revisions 3-5: ASE discretisation, the withdrawn pre-rev-3 point-sampled formula, the strict per-bin 1e-10 known-answer test that never skips (ASE 3.26 oracle when the ASE 3.29 shim is in place), and the self-image paragraph reworded as a cutoff-boundary effect (images at exactly rcut) rather than an ASE defect. - `placement.py` documents that `min q` is monotone except in the descent branch, where atoms can end up slightly below the slab top. - `options.py` and the calibration test now state the P1 calibration's known limitations (bulk-cell geometry, perturbations instead of quenches, exact rigid images) and point at a real-slab/real-model recalibration as a P5 validation item. DATA IMPACT: no scientific record invalidated. Placement semantics change only for anchored starts on slabs containing ionic species; the shipped defaults and the fingerprint/dedup behaviour are unchanged. Full confsearch suite on CPU: 112 passed.
…ts (P2) Tracking: #61 (spec revision 4, phase P2) Part of the MD-based configuration search feature. What was missing: P1 had no way to run a search - no MD cycles, no quench pipeline, no Metropolis, no checkpointing and no results. What this adds: - quench.py: fixed-cell FIRE on R with only FixAtoms, per-step finite/force gates, quench_failed / quench_not_converged as outcomes, and refine(). - engine.py: the section 7.1 schedule (start quench -> round-robin cycles -> consolidation -> refinement -> ranking), the section 7.2 mobile sets, the section 7.3 cycle (Maxwell-Boltzmann over the mobile DOF with zero fixed momenta, Langevin hold, linear cool ramp with set_temperature every cs_ramp_interval, snapshot frames, per-step safety, early integrity abort, end-of-cycle Metropolis with the uniform draw taken every eligible proposal), the section 7.5 SeedSequence streams, raw/replica_RRR/cycle_CCC output through AsyncMDOutputWriter (unchanged MD_CSV_HEADER) and cycle.json, and the section 7.1 failed_start handling. - checkpoint.py: atomic JSON checkpoints after every unit, resume fingerprint (version, revisions, model, input hashes, regions, seed, every option except output/verbosity), key-level diffing on refusal, and incomplete-attempt archiving that never deletes raw files. - results.py: discovery.csv, saturation diagnostics ("lowest found", never "global minimum"), baseline vs search, the section 8.5 warnings, top-K refinement, ranking in separate refined/unrefined tables, artifacts.json and the section 10.5 exports (POSCAR with selective dynamics, structure.extxyz, cp2k_coord.xyz, cp2k_cell.inc, cp2k_fixed_atoms.inc, minimum.json) with the slab wrapped and the adsorbate made whole under MIC. Tests (spec 13.1/13.2): test-only synthetic calculators (egg-crate with three known sites and exactly known energies, shallow-Morse bond breaking, direct force, non-finite) plus end-to-end tests that the search finds every known minimum to 1e-6 eV, that same-basin quenches merge through G, that fixed atoms never move, that the temperature ramp is the documented linear schedule, that force/non-finite/integrity aborts are recorded and the search continues, that two runs with one seed are identical, that an interrupted run resumed from its checkpoint reproduces the uninterrupted ranking exactly, and that exports re-read equal to the minimum up to lattice translations. DATA IMPACT: no scientific record invalidated. New outputs only. Full suite on CPU: 1569 passed, 33 skipped.
…puts (spec rev 5 §10/§11.1) Tracking: #61 (spec revision 5, PR #64 review) Addresses all six review items on #64. Ranking and refinement (spec 10.1/10.3): - a refinement replaces the quench result only when it converged **and** its classification is still rankable; an unconverged refinement keeps the quench result and is flagged (`refinement_failed`, note `refinement_not_converged`); a refinement that changed to a non-rankable status leaves the ranking entirely with a recorded reason (`refinement_changed_status`); - the refined set is re-deduplicated with the section 9.3 rule through a scratch registry, and a merged entry keeps the summed hit counts, the union of replicas and the earliest first-found record; - ranking and export directories follow the **refined** energy, so `top/rank_001` is the lowest refined structure; - refined and unrefined energies are never interleaved: each table has its own best energy, the export window is relative to the refined best, and `ranking.best_energy_source` says which table the reported best came from. Engine (spec 7.3): - abort frames are never quenched: the observer checks the integrity *before* keeping a snapshot, the force abort raises before the snapshot is kept, and the `except` clause no longer appends the abort frame, so an integrity-abort frame is not quenched twice; - the end-of-cycle frame gets the same early integrity check as the hold-phase snapshots; - `quench()` no longer lets a calculator that raises on a bad geometry escape as an uncaught exception; the outcome is `quench_failed`. Diagnostics (spec 10.2/10.4): - `top_k_never_reached_by_start_quench` now means "no *member* has a start origin" (merged refined entries are checked through all their source ids); - `first_found_fraction` and `best_first_found_fraction` use the unique's `first_found_quench_index`, not the representative's own quench index. Outputs (spec 11.1): - `minima/all_minima.extxyz` now holds every quench result of every status with its provenance (unique id, record id, status, flags, energy, fmax, steps, quench index, cumulative MD ps, origin), and `minima/registry.json` holds the registry. Non-finite energies are omitted from the frame info because extxyz cannot carry NaN. Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers reordering, merging, unconverged refinement, status change, the minima directory and the member-based diagnostics. Full confsearch suite on CPU: 132 passed. DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the `minima/` contents change; runs are re-ranked from their stored quench results.
…P3, partial) Tracking: #61 (spec revision 4, phase P3) Part of the MD-based configuration search feature. What was missing: the P2 engine could only be driven from Python with hand-built starts; no config keys, no CLI, no API and no provenance files. What this adds: - prepare.py: structure loading (multi-frame files and directories), mode A (cs_starts + cs_adsorbate_indices) and mode B (cs_slab/cs_molecule/ cs_n_starts placement), the section 5.1 exact multi-start identity check and the input content hashes used by the resume fingerprint. - workflow.py: model identity (including dispersion), the direct_forces gate, the generalized gradient pre-flight with confsearch wording, the resume fingerprint/refusal, run_context.json, run.log and the engine call. - Config registration (spec 12.3): "confsearch" added to the calc_type choices, IncarConfig.validate and CalculationEngine.VALID_CALC_TYPES; the confsearch scope added to timestep/friction/seed/fmax_abort/charge/spin; all CS_* keys in the schema, BUILTIN_DEFAULTS["confsearch"] (mirroring CS_DEFAULTS) and DEFAULT_DEVICE_BY_CALC_TYPE; the resolver rejects MD-only keys for confsearch instead of ignoring them; `mliport template confsearch` renders the INCAR. - CLI: `mliport confsearch run|place|resume` with --dry-run (validate inputs, regions and budget without loading a model) and placement-only `place` (writes starts/start_XXX.extxyz + POSCAR + placement.json). - API: `mliport.api.run_confsearch` (exported from `mliport`) mirroring the CLI. - Capability matrix: confsearch_user_starts/placement/resume = yes, extend/merge = no (P4), export = partial (exports are written by every run; the standalone re-export command is not implemented yet). - CHANGELOG entry; `scipy`/`matplotlib` added to the dev extra in P1 so the strict ASE OFP known-answer test runs in CI. Not yet done in P3 (reported, not hidden): the bilingual docs page (docs/workflows/confsearch.md + .zh.md, nav and docs-contract entry) and the `confsearch export RUN` re-export command; P4 (extend/merge/queue) and P5 (TUI, validation campaign) are untouched and marked accordingly in the capability matrix. DATA IMPACT: no scientific record invalidated. New entry points and outputs only. Full suite on CPU: 1578 passed, 33 skipped.
…int (spec rev 5 §11) Tracking: #61 (spec revision 5, PR #65 review) Addresses all four review items on #65. - `run.log` is now the existing `LiveRunLogger` (extended with an `append` keyword, default off so the other workflows are unaffected) opened in append mode: it exists from the first line, survives a crash, and a resume or extension adds to the run's history instead of rewriting the file at the end of the run. - `run_context.json` is created once and then updated in place: a resume appends a `resumes[]` entry (timestamp, checkpoint unit index, seed, version) and refreshes `finished_at`; the recorded identity, regions, budget, starts and options are never rebuilt from scratch. - `resolved_config.json` is written for every **new** run by the workflow (both the CLI and the API path go through it), mirroring the CLI emitter (atomic replace, honours `write_resolved_config`); a resume leaves it untouched. - `CalculationEngine.run_confsearch` takes the shared run-directory lock for `resume` too, so two frontends cannot append to one run.log or checkpoint concurrently. - The resume fingerprint now uses the section 11.2 revision 5 **model identity** subset: `model_type, model_sha256, backend_version, framework_versions, task, head_effective, dtype_effective, inference_mode, compile_enabled, direct_forces` plus `dispersion.{method, xc, damping, implementation, version}`. `actual_device_*`, `backend_reported_device`, `model_path`, `model_alias`, `model_source` and `dispersion.device` are excluded, so resuming on another GPU or with a moved copy of an identical checkpoint is allowed; the devices stay recorded in `run_context.json`. Tests: `tests/mliport/mliport/confsearch/test_resume_identity.py` (14 tests) covers the identity subset, the excluded device/path fields, the dispersion sub-keys, refusal on model/dtype/head/inference/task/framework/backend/ direct_forces/dispersion changes, the key-level diff, and the workflow-level append-only run.log / updated run_context / untouched resolved_config.json. DATA IMPACT: no scientific record invalidated. The resume fingerprint becomes less strict (device/path excluded), so a checkpoint written by the previous revision may resume where it previously refused; no computed number changes. Confsearch suite on CPU: 193 passed (with the shared engine/timing tests).
Tracking: #61 (spec revision 5, PR #65 follow-up) Found while adding the CLI-level extend test for the P4 review: `mliport confsearch resume RUN` (and the P4 `extend`) copied `run_context.json`'s `options` straight back into the config layer, but the context records `cs_starts` as a **list** while the config layers carry the `os.pathsep`-joined scalar. The resolver then validated the stringified list (`"['/path/start.extxyz']"`) as a path and refused with "cs_starts: path not found", i.e. no recorded run could be resumed from the CLI. - new `_confsearch_layer_from_context()` converts the recorded starts back to the scalar form and adds the model/device layer; both the resume path and the P4 extend path use it. - regression test: a run created by the workflow is resumed through the CLI (`monkeypatch`ed synthetic backend at the engine seam) and must exit 0 with a `resumes[]` entry recorded. DATA IMPACT: no scientific record invalidated. CLI resume/extend of an existing run directory now works; no computed number changes. Confsearch suite on CPU: 156 passed.
…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.
交付报告 · 模型支持扩展(spec Rev 2)· 2026-11-14按 #61 模型支持规格 Rev 2 §6 的顺序完成。下面按规格要求的四项汇报;详细逐模型证据在 1. 基线与交付物
模型支持表(摘要)
2. 测试汇总
3. 数值 known-answer 与设备覆盖
4. 新发现的问题与影响
DATA IMPACT: 不使任何既有科学记录失效。没有重写已存证据、阈值或历史报告; 未验证项(明确保留): UMA 的 3 个 profile(无权重)、UMA Nitro(不暴露)、DPA4C |
… row Tracking: #61 (model-support spec §11 task 3, review of #94) What was wrong: the status table listed `uma-s-1.pt` as `unsupported` on both devices. `unsupported` means "known not to load or run, or the adapter cannot express the model's physics; mliport fails closed", but nothing in mliport refuses that checkpoint -- it was simply never checked. What changes: - The row is gone. The prose now says: archived upstream release with a known extensivity bug, not checked by mliport, not recommended; and why `unsupported` would be the wrong word. - NEP89 keeps its row (GPU `verified`, CPU `unsupported`) and now has the paragraph to itself. - Same change in the Chinese page; CHANGELOG updated. DATA IMPACT: no scientific record invalidated. The table loses a row that claimed a refusal mliport does not implement; no verified status moved.
Tracking: #61 (model-support spec §11 task 3, review of #94) The prose in the previous commit described the archived checkpoint, but the table row survived. `unsupported` means "known not to load or run, or the adapter cannot express the model's physics; mliport fails closed", and nothing refuses `uma-s-1.pt` -- it was never checked. The row is gone; the prose keeps the fact (archived upstream, known extensivity bug, not checked, not recommended) and explains why `unsupported` is the wrong word. DATA IMPACT: no scientific record invalidated; no verified status moved.
Tracking: #61 (model-support spec §11 task 2, review of #96) What was wrong: the model-class gate iterated for model in loaded_models if isinstance(loaded_models, list) else [] so a calculator that does not expose a non-empty `models` list silently skipped the check that exists to stop non-energy checkpoints. A proxy or a future mace-torch that renames the attribute would have been accepted unverified. What changes: - A missing, empty or non-list `calculator.models` now raises "Unsupported MACE calculator: ... does not expose a non-empty 'models' list (got <type>), so mliport cannot verify that the checkpoint is a potential-energy model" and leaves no cached calculator. - The attribute-shaped discriminators (`atomic_multipoles_max_l` + `charges_irreps`, `joint_embedding`) now only apply to real `torch.nn.Module` models, and `embedding_specs` must be a non-empty dict. Without that, any object that fabricates attributes (unittest.mock, a dict-like proxy) looked like a MACE-POLAR or MACE-OMOL checkpoint and a legitimate energy model would have been rejected. - Tests: parametrised missing/string/object/empty `models` cases fail closed; a mock that answers every attribute is not misclassified; the existing factory fixtures now provide a real `models` list like mace-torch does. DATA IMPACT: no scientific record invalidated. No previously accepted model changes: real `MACECalculator` instances always expose `.models`.
Tracking: #61 (model-support spec §11 task 4, review of #97) What was missing: the docs said Turing and newer use "cu128 or later" and that the UMA runtime is on cu130, but not that the CUDA 13 wheels require an NVIDIA driver of 580 or newer, and not that Volta stays on cu126 precisely so older drivers keep working. What changes: - `docs/installation.md` (+ `.zh.md`): the GPU-architecture section names the `cu130` driver floor and says a CUDA 13 build is not an alternative for pre-Turing GPUs because it has no kernels below Turing, whatever the driver. - `docs/backends/uma.md` (+ `.zh.md`): the "Runtime pin" bullet says the same in one sentence. - CHANGELOG entry. Verified on the owner's host: driver 580.173.02 runs torch 2.13.0+cu126 on the V100 (sm_70 kernels present in the wheel's arch list). DATA IMPACT: no scientific record invalidated; documentation only.
Tracking: #61 (model-support spec §6.5 + §11 tasks 1 and 5) What changes: - The status table leaves its initial state and carries what was measured on 2026-11-14 on the owner's V100 in the installer-built environments: 17 profiles `verified` on CPU and GPU (15 MACE/DPA/GRACE + the two UMA `uma-s-1p2p1` checkpoints), each with finite energy/force/stress on the 50-atom LGPS cell, a matching recorded identity and the bounded probe (shared calculator, central differences, 10 NVE steps, five-image NEB). - UMA rows filled from §11 task 1: `uma_s_1p2p1_omat` and `uma_s_1p2p1_ft_r2scan_omat` verified on both devices and recorded with `inference_preset: batch`, `nitro_enabled: false`, `tf32_enabled: false`; `--inference-mode turbo` records `multigpu` with `nitro_enabled: false`. The r2SCAN fine-tune's NEB leg is refused by the gradient preflight (energy resolution), which the table states instead of hiding. - `uma_omat` stays `untested`: the local `uma-s-1p2.pt` fails the zip CRC (`PytorchStreamReader ... data/115`), the repository is gated and this host cannot re-fetch it. - The CPU-GPU claim now quotes the measured maxima (6.1e-7 eV/atom, 7.5e-6 eV/Angstrom, `mace_omat_float32`) instead of a rounded "1e-7/1e-5 or better". - Every Evidence cell links the specific #75 comment (runs, deltas, UMA record, NEP89 record) instead of the pull request. DATA IMPACT: no scientific record invalidated. Statuses describe calling the models correctly; no accuracy claim is made and no stored campaign record changed.
Tracking: #61 (model-support spec §11 task 2, follow-up to #96 CI) The new fail-closed check requires `calculator.models` to be a non-empty list, which real `MACECalculator` instances always have. `test_fixes.py` built a bare `Mock()` instead, so the head-forwarding test hit the new error. The fixture now provides `models = [Mock()]`, like the class it stands in for. DATA IMPACT: none; test fixture only.
§11 执行报告 · 2026-11-14按 Rev 3 §11 的任务顺序执行。逐模型证据在新的 #75 评论里:UMA 记录 1. UMA 可调用性检查(#97 运行时)
2. #96 门控加固
3. #94 去掉
|
| PR | 状态 |
|---|---|
| #94 | 更新完成,CI 绿,待 review |
| #96 | 更新完成,CI 绿,待 review |
| #97 | ready for review |
| #99 | 内容完成,CI 绿;rebase 待前三者合并 |
DATA IMPACT: 不使任何既有科学记录失效。新增证据只写进 #75;没有重写历史记录、阈值或
既有报告。uma_omat 的 untested 是“本机模型文件损坏”的如实反映,不是适配器失败。
残余缺口: UMA Nitro 从不执行(设计如此);探针的 NEB 未做鞍点验证;LGPS 只做单点
(探针 32 原子上限);无任何精度结论。
Tracking: #61 (model-support spec §11 task 1, re-check) The earlier `uma-s-1p2.pt` copy had the right size but failed the zip CRC; the owner re-downloaded it and the new file is clean: 315 members pass `testzip()`, and its SHA-256 `ba5c0d912efa…` matches the pinned `uma_omat` profile in `validation/science/model_manifest.json`. Measured on the same host (Tesla V100-SXM2-16GB, driver 580.173.02, fairchem-core 2.25.0 / torch 2.13.0+cu126): - `mliport doctor --task omat --structure li10gep2s12_primitive.vasp` passes on cpu and cuda:0 (E = -216.30181 eV, stress checked); - `validate_runtime.py --task omat --full` passes on both devices (single point, shared calculator, central differences, 10 NVE steps, five-image NEB); - recorded identity `inference_preset: batch`, `nitro_enabled: false`, `tf32_enabled: false`, `compile_enabled: false`; - LGPS CPU-GPU: |dE|/atom 3.60e-09 eV, max |dF| 5.70e-06 eV/A. The table now shows 18 profiles `verified` on CPU and GPU, the Chinese table is translated column by column (dtype and evidence cells were still English), and the Evidence cell points at the re-check record in #75. DATA IMPACT: no scientific record invalidated. The previous "blocked" note stays in #75 as history for the corrupt artifact.
Tracking: #61 (model-support spec §6.5 + §11 tasks 1 and 5) Rebased onto `main` after #94, #96 and #97 merged, so this carries only the status-table change. What changes: - The status table leaves its initial state and carries what was measured on 2026-11-14 on the owner's V100 in the installer-built environments: 18 profiles `verified` on CPU and GPU, each with finite energy/force/stress on the 50-atom LGPS cell, a matching recorded identity and the bounded probe (shared calculator, central differences, 10 NVE steps, five-image NEB). - UMA rows from §11 task 1: `uma_omat`, `uma_s_1p2p1_omat` and `uma_s_1p2p1_ft_r2scan_omat` verified on both devices and recorded with `inference_preset: batch`, `nitro_enabled: false`, `tf32_enabled: false`; `--inference-mode turbo` records `multigpu` with `nitro_enabled: false`. The r2SCAN fine-tune's NEB leg is refused by the gradient preflight (energy resolution), which the table states instead of hiding. `uma_omat` needed the re-uploaded checkpoint: the first copy had the right size but failed the zip CRC; the new file matches the pinned manifest hash `ba5c0d912efa...`. - The CPU-GPU claim quotes the measured maxima (6.1e-7 eV/atom, 7.5e-6 eV/Angstrom, `mace_omat_float32`) instead of a rounded "1e-7/1e-5 or better". - Every Evidence cell links the specific #75 comment (runs, deltas, UMA record, re-check, NEP89 record) instead of the pull request. - The Chinese table is translated column by column; it previously carried the English dtype and evidence cells. DATA IMPACT: no scientific record invalidated. Statuses describe calling the models correctly; no accuracy claim is made and no stored campaign record changed.
补跑:
|
| 项目 | 值 |
|---|---|
| SHA-256 | ba5c0d912efa22dc238e5fb1b5b7f66ee2e68c48c1b95b7cfd7fe1da5938398b |
| 大小 | 2333393167 字节(与上游 checkpoints/uma-s-1p2.pt 一致) |
| 容器完整性 | zipfile.testzip() 全部 315 个成员通过 |
| 与固定 profile 对比 | 与 validation/science/model_manifest.json 里 uma_omat 的 ba5c0d912efa… 完全一致 |
| task list | omat |
之前那份大小相同但 CRC 损坏;新文件干净,属于传输问题而非适配器问题。
检查结果(Tesla V100-SXM2-16GB,驱动 580.173.02,fairchem-core 2.25.0 / torch 2.13.0+cu126)
| 检查 | cpu | cuda:0 |
|---|---|---|
mliport doctor --task omat --structure li10gep2s12_primitive.vasp |
通过,E=-216.30181 eV,应力已检查 | 通过,E=-216.30181 eV |
validate_runtime.py --task omat --full(Cu 夹具) |
通过:单点、共享计算器、中心差分、10 步 NVE、5 image NEB | 通过:同上 |
| 记录身份 | inference_preset: batch、nitro_enabled: false、tf32_enabled: false、compile_enabled: false |
同左,actual_device_type: cuda |
LGPS 上 CPU–GPU:|ΔE|/atom = 3.60e-09 eV,max|ΔF| = 5.70e-06 eV/Å
(CPU -216.30180917 eV,GPU -216.30180899 eV)。
状态变化
uma_omat:untested→ CPU 与 GPU 均verified。- 状态表现有 18 个 profile 在 CPU+GPU 上 verified。
- 证据:新增 [DEV P0 AUDIT · DO NOT MERGE/CLOSE] Living correctness and real-hardware test ledger · master #61 #75 评论 #75 re-check。
- docs(models): record the measured model-support status #99 已按 §11 任务 5 要求 rebase 到最新
main(此时 docs(registry): correct model licenses and publish the support table #94/fix(mace): fail closed on checkpoints that are not potential-energy models #96/feat(uma): move to fairchem-core 2.25.0 and keep Nitro out of reach #97 已合并),现在只包含它自己
的一个 docs 提交(3 个文件,+83/−38,可合并,CI 13 pass)。
全局状态
| PR | 状态 |
|---|---|
| #94 / #96 / #97 | 已合并进 main |
| #99 | rebase 完成,CI 绿,待 review |
DATA IMPACT: 不使任何既有记录失效;此前“文件损坏、not_run”的记录作为历史保留在 #75。
残余缺口(不变): UMA Nitro 永不执行(设计如此);探针 NEB 未做鞍点验证;LGPS 只做单点;
无任何精度结论。
DPA-SSE 支持 · 开发规格(Rev 2 · 2026-11-15)
0. 需求摘要(给人看)
1. Facts to start from (verify each before relying on it)
2. Work, in order2.1
|
DPA-SSE §2.1
|
| 项目 | 值 |
|---|---|
| 原始检查点 | SSE-VASP-dpa2.pt,120922466 字节,sha256 04c34fe24c85af70872569ac39868991a78c7237572111c7e2e0e1c2a7056931 |
| #91 转换后 | SSE-VASP-dpa2-inference.pt,41101267 字节,sha256 8194e51f5050f763e7b5ce450ed12bc9fa5fb57882314d7ee756a8c3ddbb50f4 |
| 模型页面 | https://www.aissquare.com/models/detail?pageType=models&name=SSE-VASP-dpa2 — 文件 SSE-VASP-dpa2.pt,115.32 MB,2024-07-25,发布者 1azyking;共享协议 LGPL-3.0 |
| 数据集页面 | https://www.aissquare.com/datasets/detail?pageType=datasets&name=Solid_State_Electrolyte&id=217 — 20240412-SSE.zip,266.35 MB,2024-04-11,发布者 mchao_shi、Yuzhi Zhang;共享协议 CC BY 4.0 |
| 上游描述 | 15 元素、41 个体系(26 个硫属化合物);DPGEN 主动学习;batch size 1、1e6 步(19 epoch);DPA-2 描述符 repinit rcut 9.0 Å / nsel 120,repformer rcut 4.0 Å / nsel 40;用法示例 dp --pt test -m SSE-VASP-dpa2.pt -s <test_system> |
本地文件大小 120922466 字节 = 115.32 MiB,与模型页面一致。
从检查点里读出的 model_params(不是从文档抄的):
type: standard,descriptor.type: dpa2,fitting_net.type: ener,precision: default- repinit:
rcut 9.0、rcut_smth 8.0、nsel 120、neuron [25, 50, 100]、axis_neuron 12、tebd_dim 8、tebd_input_mode concat、set_davg_zero true、type_one_side false - repformer:
rcut 4.0、rcut_smth 3.5、nsel 40、nlayers 12、g1_dim 128、g2_dim 32、attn1_hidden 128/attn1_nhead 4、attn2_hidden 32/attn2_nhead 4、axis_neuron 4、update_style res_avg、update_residual 1e-3、update_g1_has_conv/grrg/drrd/attn true、update_g2_has_g1g1/attn true、attn2_has_gate true、direct_dist false - fitting:
neuron [240, 240, 240]、resnet_dt true、numb_fparam 0、numb_aparam 0 type_map:118 个元素(完整周期表),atom_exclude_types: []、pair_exclude_types: []
与模型页面写的 rcut/nsel(9.0/120、4.0/40)一致;页面说的 15 元素是训练覆盖,不是 type_map 的宽度。
2. 在固定运行时(deepmd-kit 3.2.1.dev63+g0edeaef56,torch 2.11.0+cu126)上的失败,原样
原始文件(#91 已知的元数据问题,在旧/新运行时上都能重现):
_pickle.UnpicklingError: Weights only load failed. This file can still be loaded, to do so you have two options, do those steps only if you trust the source of the checkpoint.
(1) In PyTorch 2.6, we changed the default value of the `weights_only` argument in `torch.load` from `False` to `True`. Re-running `torch.load` with `weights_only` set to `False` will likely succeed, but it can result in arbitrary code execution. ...
WeightsUnpickler error: Unsupported global: GLOBAL numpy.core.multiarray.scalar was not an allowed global by default.
#91 转换后的文件(元数据已修好,剩下的是网络布局不匹配):
RuntimeError: Error(s) in loading state_dict for ModelWrapper:
size mismatch for model.Default.atomic_model.descriptor.repformers.layers.0.linear1.matrix: copying a param with shape torch.Size([800, 128]) from checkpoint, the shape in current model is torch.Size([640, 128]).
size mismatch for model.Default.atomic_model.descriptor.repformers.layers.0.proj_g1g2.matrix: copying a param with shape torch.Size([128, 32]) from checkpoint, the shape in current model is torch.Size([32, 128]).
... (12 层、每层两个键,共 24 处)
即:linear1.matrix 的输入维从 800 变成 640(每层少了 160 维),proj_g1g2.matrix 的
(g1_dim, g2_dim) 与 (g2_dim, g1_dim) 转置了。没有任何缺失/多余键,只有这两类形状差异。
3. 能原样加载它的运行时
在一次性环境里逐个试(CPU,Python 3.12;uv 建 venv,torch 从 PyTorch CPU index 装):
| deepmd-kit | torch | 结果 |
|---|---|---|
| 3.0.0b0 | 2.3.1 | 失败:TypeError: DescrptDPA2.__init__() got an unexpected keyword argument 'use_tebd_bias'(比检查点旧) |
| 3.0.0b1 / b2 / b3 | 2.3.1 | 原始文件直接 DeepPot 加载成功 |
| 3.0.0b4 | 2.3.1 | 失败:24 处 shape mismatch(布局已改) |
| 3.0.0rc0 / 3.0.0 / 3.0.1 | 2.5.1 | 失败:同样 24 处 shape mismatch |
| 3.0.2 | 2.6.0(wheel 的编译版本) | 与本机 torch 2.5.1 版本不符被拒 |
| 3.0.3 | 2.5.1 | 失败:This deepmd-kit package was compiled with CXX11_ABI_FLAG=1, but PyTorch runtime was compiled with CXX11_ABI_FLAG=0 |
结论:能原样加载的最后一个发布版是 deepmd-kit==3.0.0b3 + torch==2.3.1。
在 b3 上逐张量核对(ModelWrapper.state_dict() vs 检查点 model):
- 模型状态 227 个键,检查点 226 个张量;差别只有非张量的
_extra_state - 缺失的已学参数 0,多余张量 0,形状不一致 0
DeepPot(...).get_rcut() == 9.0,get_type_map()为文件里的 118 元素表- 加载时只有
ast.NameConstant is deprecated这类 Python 3.14 弃用告警,没有跳过参数的警告
4. 参考值
在 b3(float64,CPU)上算了三个结构:LGPS 原胞(仓库里的,50 原子)、Li₂S 常规立方胞
(12 原子)、LiCl 岩盐胞(8 原子),后两个用 ASE 生成、只含训练元素,SHA-256 与完整
E/F/virial 都写在 #75 评论里:
#75 (comment)
摘要:
| 结构 | E (eV) | virial 对角 (eV) |
|---|---|---|
| LGPS 原胞, Li20Ge2P4S24 | -226.088601521 | -8.377595 / -9.159341 / -7.469619 |
| Li₂S 常规胞, Li8S4 | -49.468821625 | -1.997121 / -1.997121 / -1.997121 |
| LiCl 岩盐胞, Li4Cl4 | -30.530082885 | -1.240451 / -1.240451 / -1.240451 |
LGPS 上 max |F| = 0.2996 eV/Å;两个完美晶体力约为 1e-13 / 1e-8 eV/Å,用来检验能量与 virial 通路。
下一步(§2.2 路线选择)
按规格顺序先试转换路线:在 b3 环境里用 deepmd 自己的导出工具(dp --pt freeze 或
dp convert-backend)转出文件,再在固定的 3.2.1 运行时里经 mliport 的 DPA 适配器加载,和上面
三个参考结构比 |ΔE| ≤ 1e-6 eV/atom、max |ΔF| ≤ 1e-5 eV/Å、max |Δvirial| ≤ 1e-5 eV。
只有全部通过才会把它做成 scripts/convert_dpa_checkpoint.py 里的可复现步骤;否则改用
dpa-legacy 运行时 + DPA_RUNTIME。
DPA-SSE §5 执行完成 · 2026-11-15按 Rev 2 §5 实现完毕,PR:#100 §5.1 安全加载
§5.2 版本固定
§5.3 选择
§5.4 带真实力的参考结构新增 Li₂S 常规胞 + 高斯扰动(σ = 0.05 Å, §2.3 可调用性检查(证据:#75)
身份记录: §2.4 文档
§5.5 测试
残余与风险
DATA IMPACT: 不使任何既有科学记录失效。既有 DPA 运行的记录不变;新增的 |
Tracking: #61 (DPA-SSE spec §5), review of #100 1. The strict tensor check can no longer be skipped in the legacy runtime. `_validate_pt_checkpoint` returns quietly when the loader exposes no inspectable torch model; in `.venv-dpa-legacy` that verification is the only guard against a partial or reshaped load, so `DPA_RUNTIME=legacy` now raises unless `checkpoint_tensors_verified` is true. The flag is recorded in `info()`, in the model record and in `IDENTITY_KEYS`, and the real CPU and GPU runs report `checkpoint_tensors_verified: true` (see #75). 2. `dpa-legacy` no longer claims Blackwell: torch 2.3.1+cu121 carries kernels up to sm_90 only, so `blackwell.upstream_supported` is false (like `maxwell`). 3. `dpa_runtime_problems` requires exactly `3.0.0b3` (a local version suffix is allowed); b0 is too old for `use_tebd_bias` and b4+ already changed the repformer layout, so accepting any `3.0.0b*` was wrong. 4. The legacy runtime accepts only `.pt`: any other suffix is refused before loading, and an unreadable model definition is now an error instead of a silent return. Tests: `test_dpa_runtime.py` grows to 20 cases (non-`.pt` refusal, unverified load refusal, exact-pin matrix, Blackwell support flag); the real install/probe still pass. DATA IMPACT: no scientific record invalidated; the legacy runtime simply refuses more unsafe inputs.
[SPEC · 2026-11-15] ASE-only NPT for solid-electrolyte cell equilibration (owner-approved)Tracking / branch policy: This is a plan recorded on permanent #61 (OPEN + DRAFT, DO NOT MERGE/CLOSE). The actual implementation and tests MUST be in a separate mergeable PR targeting Goal and scope (one consolidated delivery)Add experimentally useful isotropic Martyna–Tobias–Klein (MTK) NPT MD to the shared ASE runner for UMA, MACE, GRACE, DPA (including supported DPA variants); existing NVE/NVT unchanged. No native GPUMD, no NEP (even NEP-ASE), no full anisotropic cell, no NPT transport-analysis promises, no automated NPT→NVT pipeline yet. Scientific/engineering contract
Suggested interface and delivery
|
NPT implementation handoff · 2026-11-15 (spec comment above)Implementation: #101, branch Scope delivered in one feature PR: ASE UMA/MACE/GRACE/DPA isotropic MTK NPT; unified schema/CLI/Engine/Python API/TUI; finite pressure/stress/volume/PBC preflight; COM init-only without FixCom; per-frame ASE variable-cell trajectory, NPT provenance, no XDATCAR; mark NPT trajectories ineligible for fixed-cell MSD; EN/ZH usage docs; analytic stress/pressure/error/regression tests. Native GPUMD and NEP unchanged. Evidence status: automated lint / docs / package and pytest CI tracked on #101; check the latest commit status, do not infer physics validity from CI. Real checkpoint/GPU and physically converged T,P cell statistics remain owner local-agent work. Keep #101 draft until local-agent sign-off; #75 is the separate permanent audit ledger. Owner agent gate: pull #101 head; run |
|
NPT follow-up implementation status: Final head: Full test suite on Python 3.10 / 3.11 / 3.12 / 3.13: 2,172 passed, 53 skipped, 0 failed on each version. Ruff lint/format, documentation checks, package builds, wheel install-smoke (3.10–3.13), analysis-backends, and installer-real-nep: PASS. Deploy was skipped because the PR remains Draft; it is not counted as a pass. E1/E2/E3/E5/E6 follow-up fixes and regression tests are included in this head. PR remains Open + Draft until the owner/local agent refreshes its clean No merge performed. #61 and #75 remain permanent Open + Draft records. |
[SPEC · 2026-11-15] 任务文件夹 + INCAR 使用方式改进(owner-approved)Tracking / branch policy: 本条记录在永久 #61(OPEN + DRAFT,DO NOT MERGE/CLOSE)。实际实现与测试必须在单独、可合并、目标为 目标让 mliport 的日常用法收敛为一件事:一个任务文件夹( 不在范围内(不得顺手实现;AGENTS.md 第 10 条)
需求R1 任务文件夹与结果目录
R2
R3 INCAR 模板与支持范围
R4 INCAR 键参考文档(中英)
R5 TUI:新建任务文件夹向导
兼容性与科学约束
验收(必须有自动化测试)
建议交付拆分(各自独立 PR,均回链本评论)
仍属 owner 本地验收、不得声称已通过:真实模型 / GPU 上用任务文件夹跑通 sp、opt、md、confsearch。 Generated by Claude Code |
[进展 · 2026-11-16] 「任务文件夹 + INCAR +
|
| # | 交付 | 覆盖需求 | 依赖 |
|---|---|---|---|
| #104 | INCAR 核心 | R1.1–R1.4、R3.2、R3.3 | 基于 main |
| #105 | models/ 目录约定 |
R2.1–R2.7 | 基于 main |
| #106 | 选项表 + 模板重做 + 键参考文档 | R3.1、R3.4、R4 | 栈在 #104 上 |
| #107 | TUI 新建任务向导 | R5.1–R5.3 | 栈在 #106 上,并合入 #105 |
要点与证据:
- Task folder INCAR core: results/ default, config-before-structure, CONFSEARCH dispatch (R1 + R3.2/R3.3) #104:
run默认输出改为<INCAR 目录>/results/(--output>OUTPUT_DIR> 新默认;OUTPUT_DIR成为声明式路径项,相对 INITCAR 解析;OUTPUT_DIR = .恢复旧行为);配置校验与MODEL_PATH解析提前到读取结构之前;CALC_TYPE = CONFSEARCH与mliport confsearch run共用_run_confsearch_job一段代码(未复制逻辑);新增 5 类型 × 6 后端模板往返测试(31 例)与 13 例任务文件夹测试。 - models/ directory convention for MODEL_PATH: fail-closed lookup, MLIPORT_ROOT, doctor, launchers (R2) #105:
mliport/model_lookup.py实现文件名 →models/查找(一层子目录、同名多命中报错、含分隔符取值行为不变并优先);MLIPORT_ROOT三级推导 + 启动脚本导出 +doctor输出;缺失模型错误列出全部搜索位置与models/现有文件;16 例测试。行为变更:仅写文件名且到处都找不到时现在在解析阶段就明确报错(以前在加载模型时失败),这是 R2.3/R2.4 要求的 fail-closed。 - INCAR option table: generated templates, generated key reference docs (R3.1/R3.4/R4) #106:
OptionSpec增加分组/顺序/模板归属/适用条件/占位符元数据,模板、mliport config schema与新增docs/incar.md(+.zh.md) 共用同一份表(generate_docs.py --check与 40 例结构测试守护);45 个CS_*键与 MTK 链参数改用实现读出的真实一句话说明;MD 模板只写所选恒温器参数并保留注释掉的 NPT 示例。 - TUI new-task wizard + task-folder helper (R5) #107:TUI 首屏改为向导(计算类型 → 结构文件 → 后端 →
models/清单选模型),生成INCAR.mliport+ 结构逐字节副本并显示cd <文件夹> && mliport run;「创建并运行」直接调mliport.cli.main(["run", ...]);旧界面移入「高级」;23 例测试。需要注意:MainScreen不再直接列出计算类型(R5.3 的预期变更),两处旧导航测试已改为在「高级」菜单断言。
明确仍未完成的验收(不得声称已通过):真实模型 / GPU 上用任务文件夹跑通 sp、opt、md、confsearch 属 owner 本地验收;本评论只报告软件测试与文档证据。合并顺序建议 #104 → #105 → #106 → #107(#106/#107 是栈式分支,合并后我会重定基到 main)。
…cher scope
Review findings on the R2 delivery:
- GRACE's MODEL_PATH is a SavedModel *directory*. The lookup only accepted
files, so the documented `--model saved_model` GRACE command started failing
once the value became a name: "Model file 'saved_model' was not found".
`resolve_model_reference` now accepts any existing path (file or directory)
before consulting models/, `lookup_model_file_name` accepts directory
matches, and the listings show a top-level directory that is itself a model.
- `MLIPORT_ROOT` was derived from the parent of any `.venv-<engine>` prefix, and
`.venv` is UMA's environment name but also the name of any project-local
virtualenv: running from `/home/<user>/.venv` would have made `/home/<user>`
the root and silently resolved models out of an unrelated directory. The
derivation now also requires a checkout marker (`models/`, a `bin/mliport-*`
launcher or `mliport/pyproject.toml`), otherwise the root stays unknown and a
bare name fails closed with instructions.
- The generated launchers overwrote an explicitly set `MLIPORT_ROOT`, which
defeated the documented precedence and broke a shared model store. They now
set it only when unset (POSIX `: "${MLIPORT_ROOT:=...}"`, Windows
`if not defined`).
- `MODEL_PATH`'s one-line meaning now states the file/directory and the
local-then-`models/` rule instead of "Path to the model checkpoint/file".
Tests: three new cases (model directory next to the INCAR, model directory found
in models/, venv prefix without a checkout marker) and a launcher case that runs
with `MLIPORT_ROOT` already set. Suite: the models/config/doctor/install tests
are green; ruff clean.
DATA IMPACT: no scientific record invalidated. This restores dropped behaviour
(GRACE directory models) and removes a silent-root failure mode; no default,
unit, PBC semantic, model task/head or dtype changed.
Tracking: #61
…relative Review findings on the R1 delivery: - `OUTPUT_DIR = .` was documented as restoring the old current-directory behaviour, but declaring `output_dir` a path option made "." resolve against the INCAR folder, so the documented escape hatch did not exist: a run from another directory still wrote next to the INCAR. A "."/"./" value is now left unresolved so the CLI resolves it against the working directory, as before. - The same `is_path` change also moved the output of *every* subcommand when `OUTPUT_DIR` came from a `settings.ini`: it was resolved against the settings file instead of the working directory, which the CHANGELOG claimed did not happen. Only an INCAR-declared `OUTPUT_DIR` is now INCAR-relative; every other layer keeps the historical current-directory resolution. Tests: the `.` test now runs from a different working directory (it could not fail before) and a new test pins that a `settings.ini` `OUTPUT_DIR` stays working-directory relative while the INCAR's own value does not. DATA IMPACT: no scientific record invalidated. This narrows the path-resolution change to the one declaration the specification asks for (the INCAR), and restores the pre-existing behaviour for `settings.ini`; no default, unit, PBC semantic, model task/head or dtype changed. Tracking: #61
…eference
Review findings on the R3/R4 delivery:
- The NEB template wrote `NEB_INITIAL = initial.vasp` / `NEB_FINAL =
final.vasp`. Those look like real files but point at nothing, so a created
task folder appeared complete while the INCAR could never run, and the "still
to fill in" report could not see them. They are now the fail-closed
`REQUIRED` placeholder (the round-trip test already fills them); the
round-trip contract is unchanged.
- The model section was still a hand-written key list with a stale claim
("absolute path or path relative to settings.ini", untrue once a name is
looked up in models/ and for an INCAR). Its `MODEL_TYPE`/`MODEL_PATH`
comments now come from the shared option table, so they cannot drift from
`docs/incar.md`.
- The generated key reference printed the internal "always commented" sentinel
as ``CS_MODE = MODE_B`` (a value the validator rejects) and labelled example
values as "required". Sentinel conditions are no longer rendered and example
values are marked as examples.
- The page claimed to list every INCAR key but omitted the batch keys; it now
has a `## Batch` section and generated table, with the same note in both
languages. The Chinese page translates the section headings and states that
the meaning column is the English option table.
- Two assertions could not fail (an ordering check that was true by
construction and a key-set comparison padded with a hardcoded list); they now
check both directions - every templated key is documented and every
documented key is a real option spelling.
Tests: template/defaults assertions updated for the REQUIRED endpoints and the
inline comments; the neutral-template helper now strips the generated comment
before comparing; config, CLI, docs-contract and TUI suites are green; ruff
clean.
DATA IMPACT: no scientific record invalidated. Template *values* for the NEB
endpoints become REQUIRED (they were never resovable), no default, unit, PBC
semantic, model task/head or dtype changed.
Tracking: #61
[进展 · 2026-11-16] 第一轮独立评审已闭环,四份 PR CI 全绿(等待 owner 确认,未合并)对 #104–#107 做了一轮独立评审(逐条比对规格 + 实际跑代码验证,不只读 diff),发现 13 项问题,其中 1 个 blocker、8 个 major,全部已修复并补充/修正了对应测试。要点: #105(
#104(INCAR 核心)—— 修掉两个输出目录缺陷
#106(选项表/模板/文档)
#107(TUI 向导)
当前状态:四份 PR 的 tests 3.10–3.13 / lint / build / docs / installer-real-nep / wheel-install-smoke 全绿;本地 仍然只有 owner 能做的验收(不得声称已通过):真实模型 / GPU 上用任务文件夹跑通 sp、opt、md、confsearch;GRACE 目录模型与 CUDA、 |
[DEV MASTER · PERMANENT OPEN DRAFT · DO NOT MERGE/CLOSE] mliport development coordination
当前状态(2026-11-14 · 已核实)
main@ec28ba3f39fe9aa865e99aebf9c4c2452c72e256(test(neb,confsearch): AUD-007 — pin what checkpoint resume really preserves #82 已合并),GitHub Actions tests / lint / docs / package-build 全绿。CI 全绿只说明所覆盖的软件测试通过,不代表模型物理精度或全部后端 GPU 验收完成。format_version 1/ NEP89 头格式支持。原有双路径开发规范是历史实现依据,不再列为待开发 P0。NEP_RUNTIME=gpumd;此限制已记录,不视为本轮新发现的缺陷。尚无 Na₃PS₄ DFT 精度、应力、ns 级稳定性或其他 GPU 架构证明。下一步(收敛为一个可执行目标)
当前(owner 2026-11-15 决定):使用方式改进——任务文件夹 + INCAR +
models/。 规格:任务文件夹与 INCAR 使用方式改进;代码 PR 须先经 Claude 审阅,未经 owner 确认不得合并。当前:DPA-SSE 支持(owner 2026-11-14 决定)。 让 DPA-SSE 在 CPU 与 V100 上可调用,且与其原始 deepmd 版本的结果一致;不改权重,优先用上游转换,不行再加旧版运行环境。规格:DPA-SSE 支持开发规格;证据写入 #75。
已完成(2026-11-14):模型支持扩展。 #94–#99 已合并:18 个模型配置在 V100 与 CPU 上通过可调用性检查(不含精度评估),状态表见
docs/models.md的 “Model support status”;规格与清单见模型支持开发规格,证据在 #75。下一步由 owner 决定。暂缓(owner 2026-11-14):Na₃PS₄ 小规模 MLIP benchmark。 恢复时按以下既定方案:先设计与复用数据,不立即扩展功能。 优先考虑已有运行基础的 GRACE3、DPA4、NEP89;以统一结构上的 CP2K 单点作为目标参考,比对原子力、相同组成下的相对能量,以及可靠可得时的应力。必须明确 CP2K 与各模型预训练所用 DFT 理论级别可能不同;不比较未经基准处理的绝对总能量,不把跨泛函偏差全部算作 MLIP 拟合错误。先提出最小构型清单、现有数据复用情况和明确的验收标准,未经 owner 授权不启动昂贵 DFT/GPU 批量计算。
**暂缓:**DPA-SSE 兼容性开发按 owner 决定搁置;不自行新增后端、大规模 MD 或微调工作。真实缺陷再用独立小 PR 修复。科学验证证据持续写入 #75,不把 benchmark 计划冒充已完成实验。
历史约束与规范:P0-AUDIT 联合验收矩阵和下面的 confsearch 原始完整规格仍有效;涉及科学定义的变更须先提出冲突、证据及影响,不能静默修改。
保留的原始长期规格:MD-based configuration search(原始正文以下完整保留)
[DEV · DO NOT MERGE] MD-based configuration search for periodic systems — living spec
0. 需求摘要(给人看)
chemisorbed;可指定"锚点原子"(如硫酸根 O)让起点直接以成键距离摆放。摆放距离按两原子共价半径之和的倍数设定,不用单一固定键长。reacted,默认不进排名;只有用户明确要研究表面反应时才放进排名。Li⁺ 等离子换位置不算反应。1. Rules for agents working from this spec
AGENTS.md,CONTRIBUTING.mdanddocs/development.mdfirst. They overrideanything here that conflicts with them; if you find such a conflict, stop and report it
in a comment on this PR.
believe the spec is wrong or underspecified, do not improvise: comment on this PR,
propose the change, and wait for the owner. Accepted changes are folded into this
description with a new spec revision.
smallest implementation; DATA IMPACT section in the commit message; bilingual docs for
anything user-visible; CHANGELOG
Unreleasedentry; CI green.Update the phase checklist (§14) in this description when an implementation PR merges.
The spec lives here only.
model task/head/dtype; never compare absolute energies from different model
identities (AGENTS.md 1–4).
explains where and why it deliberately does not use an upstream component (§6.6, §9.2).
2. Scope
2.1 In scope for v1
adsorbate: one adsorbate molecule (it may contain ionic atoms such as the Li ofLiDS) on one side of a slab, 3D-periodic cell with vacuum along +z.
local minimization ("quench") of selected frames.
random placement of a molecule (one or more conformers) above a slab.
diagnostics, top-K refinement and export for DFT (VASP POSCAR and CP2K-friendly files).
(different machines/seeds) when they are comparable.
2.2 Explicit non-goals for v1 (reject, do not half-implement)
interfaces, multiple adsorbates/coverage, two-sided slabs.
changes the potential energy surface).
references; users do this with existing
opt).A request outside scope must raise a clear error naming the non-goal, not fall back.
2.3 Future modes (design for, do not build)
Keep
cs_modean enum with onlyadsorbateaccepted; structure code so that later modes(
bulk_mobile,melt_quench,interface,multi_adsorbate) can reuse the cycle engine,registry and exports. Do not add stubs or hidden options for them.
3. Scientific basis (why this design)
conformations (gauche/trans barriers ~0.1–0.2 eV) and local reorientations happen on ps
timescales, but hopping of a strongly bound head group between surface sites
(barriers ≳0.5 eV) is rare within a few ps. Site coverage therefore comes from many
independent starts; MD cycles relax and diversify each start. This is the same logic as
heuristic+random placement with ML relaxation and DFT verification of the best few
(AdsorbML), extended by MD-driven basin exploration.
(Kirkpatrick 1983), inherent-structure quenching of MD frames (Stillinger & Weber 1982)
and basin hopping (Wales & Doye 1997); minima hopping (Goedecker 2004) is the closest
MD-based relative. We do not wrap
ase.optimize.minimahopping(see §6.6).melting/reconstructing the surface and keeps distant slab Li from rearranging, which
would otherwise make energy differences reflect slab changes rather than adsorption.
The quench relaxes every atom that is not fixed in the input, so the surface still
responds to the adsorbate.
surface can exceed the energy spread of the candidates. The deliverable is a ranked,
deduplicated candidate set for DFT re-ranking, not a final answer.
References: Kirkpatrick, Gelatt, Vecchi, Science 220, 671 (1983); Stillinger & Weber,
Phys. Rev. A 25, 978 (1982); Wales & Doye, J. Phys. Chem. A 101, 5111 (1997); Goedecker,
J. Chem. Phys. 120, 9911 (2004); Oganov & Valle, J. Chem. Phys. 130, 104504 (2009);
Lan et al., npj Comput. Mater. 9, 172 (2023) (AdsorbML); Pracht, Bohle & Grimme, PCCP 22,
7169 (2020) (CREST, upstream conformers); Shoemake, Graphics Gems III (1992) (uniform
random rotations).
4. Terminology
FixAtomsfrom the input (must be ⊆ S)5. Inputs and preparation
5.1 Mode A — user-prepared starts
directory (read every structure file, sorted by name). Each frame is one start.
cs_adsorbate_indicesis required in mode A. Syntax: comma-separated 0-basedindices and inclusive ranges, e.g.
300-341or0,5,7-9. Document clearly that it is0-based like ASE (CP2K/VMD users count from 1). Log the selected chemical formula.
with
np.array_equalafter reading; no tolerance), PBC, fixed-atom set, andatoms.infocharge/spin if present. Otherwise fail closed listing the first difference.5.2 Mode B — automatic placement
Inputs:
cs_slab(periodic slab),cs_molecule(one or more conformers; multi-frameallowed; all frames must have the same element order; PBC ignored, positions taken as
Cartesian),
cs_n_starts(required, ≥1, no default: it sets the cost).Output atoms = slab atoms (in slab order) followed by molecule atoms (in conformer order);
A is therefore the trailing block and needs no user input.
For each start
k = 0..n-1, using the placement RNG stream (§7.5):normals, normalize (Shoemake), convert to a rotation matrix.
u, v ~ U[0, 1); lateral position =u·a + v·b(a, b in the xy-plane, §5.3).radii sum:
q_ij = d_ij / (r_cov,i + r_cov,j)(MIC;ase.data.covalent_radii). Asingle Å value does not fit all pairs (C–H ≈ 1.1 Å, S–S ≈ 2.05 Å). Solve the z offset
by bisection to 1e-4 Å, starting above the slab top.
min_ij q_ij = cs_place_contact_scale(default 1.5; e.g. O···S 2.57 Å, H···S 2.04 Å) — close contact, not bonded; the
quench decides whether a bond forms.
cs_place_anchorgiven): before step 4,redraw the rotation (step 3) until the lowest-z atom of the rotated molecule is one of
the anchor atoms (rejection sampling keeps orientations uniform under that
condition). Then set the height so that the anchor atom's minimum
qto itspartner set equals
cs_place_anchor_scale(default 1.1, a slightly stretchedbond: the start is already bonded by the §8.1 criterion). The partner set is the
non-ionic slab atoms (ionic species cannot form the covalent bond §8.1 counts as
chemisorption; an O placed at 1.1× the O+Li radii sum is an ionic contact, not a
chemisorbed start). If
cs_place_anchor_targetsis set (element symbols, e.g.P,S),the partner set is the slab atoms of those elements instead — naming an ionic
species there is the explicit way to anchor onto it.
adsorbate–slab pair has
q < cs_place_other_min_scale(default 1.3, i.e. not bonded);in contact placement, any pair has
q < cs_place_contact_scale − 1e-3; the anchortarget condition fails; the self-image or vacuum criterion of §8.4 fails. After
cs_place_max_attempts(default 1000) consecutive rejections, fail closed with therejection counts per reason.
index, quaternion,
u, v, z offset, attempts and rejections per reason, and theresulting minimum distances and
qvalues. Writestarts/start_XXX.extxyzand a POSCAR copy.The slab's own constraints become F. Optionally
cs_fix_below(Å) adds to F every slabatom with
z < z_min(slab) + cs_fix_below; combining it with existing constraints is theunion, recorded.
5.3 Validation common to both modes (fail closed)
pbc == (True, True, True); the task must be a periodic task (existing_prepare_atomsrules).|a_z|, |b_z| < 1e-8 Åandc_z > 0. Otherwise: error explainingthat the surface normal must be +z (do not rotate the cell for the user).
boundary): after
wrap, the largest gap in sorted slab z coordinates (including theperiodic gap) must be the vacuum; the slab occupies one interval. Fail closed otherwise.
z_top= maximum z of slab atoms; the adsorbate centroid must be abovez_top(one-sided adsorption).
FixAtomsconstraints are accepted.FixScaled/FixCartesian(partial selectivedynamics),
FixCom,FixSymmetryor any other constraint: fail closed. F must notintersect A.
connected covalent graph (§8.1). Otherwise fail closed (wrong selection is the most
likely user error).
warnings): a fully free slab can drift or bend.timestep > 1.0fs, fail closed. Default 0.5 fs.6. Calculator and identity gates
forces are not
−∇E, that ranking is not meaningful.direct_forces is True: fail closed unlesscs_allow_direct_forces = true; then recordenergy_gradient_consistency: "not_guaranteed"and add a warning to every result.mliport.neb.preflight) on the firstprepared start before any MD. Phase P0 generalizes it to accept a single structure
(§14); NEB behaviour must not change. Record the evidence as
gradient_preflight.--d3) is allowed and must be part of the model identity (§12): thedispersionrecord fromcalculator.info()enters the comparability key, so a searchwith D3 can never be merged with or compared to one without. (Unlike NEB, which refuses
D3, confsearch supports it from the start because long-chain adsorption is
dispersion-dominated.) Log a note when the model's reference is known to lack
dispersion and D3 is off; do not enable D3 silently.
inference_mode=turbois allowed only if explicitly requested (existing opt-in),recorded, and listed in warnings (reduced precision affects meV-level dedup).
_model_record); P0 extracts it into ashared public helper with identical behaviour for NEB, plus the
dispersionfield.6.6 Why not
ase.optimize.minimahoppingIt writes fixed file names into the working directory, uses the global NumPy RNG, NVE
escape steps without our safety gates, and compares minima with non-periodic
position matching that is not permutation- or image-aware. None of that meets mliport's
provenance and fail-closed contracts. We reuse ASE's Langevin integrator, FIRE optimizer,
Maxwell–Boltzmann initializer and neighbour lists instead.
7. Search algorithm
7.1 Overall schedule
Round-robin (all replicas do cycle 1, then cycle 2, …) gives an anytime result and a
meaningful discovery curve. The start-quench stage also yields the "multi-start
relaxation only" baseline, reported next to the MD-search result (§10.4).
A replica whose start quench is not converged or not
validis markedfailed_startand gets no cycles; the search continues with the others. If no replicasurvives, the search fails.
7.2 MD-mobile set M
cs_md_mobile:adsorbate(default): M = A. Every slab atom is fixed during MD.adsorbate_and_top: M = A ∪ {s ∈ S \ F : z_s ≥ z_top − cs_top_depth} withcs_top_depthdefault 2.0 Å, recomputed from the current minimum at each cycle start.all_free: M = R.During MD, atoms outside M are held with a temporary
FixAtoms(union with F). Thequench always relaxes R. The cell never changes.
7.3 One cycle (replica r, cycle c)
Let
x0= geometry of the replica's current minimum.Atomscopy ofx0, temporary MD constraint per §7.2.MaxwellBoltzmannDistribution(temperature_K=T_high, force_temp=True, rng=md_rng)on the constrained atoms. Verify (test) that fixed atoms get zero momentaand that the instantaneous temperature over free DOF equals
T_high.Langevin(timestep, temperature_K=T_high, friction=friction, rng=md_rng, fixcm=False)forn_holdsteps.fixcmmust be False (fixed atomspresent; mirrors
MDRunner).cs_snapshot_interval_ps > 0, at hold stepsk·n_snapfork ≥ 1andk·n_snap < n_hold, store a detached copy of the frame for quenching.n_coolsteps, updating the target withdyn.set_temperature(temperature_K=T(t))everycs_ramp_intervalsteps (default 10),T(t)linear fromT_hightoT_low. The final frame is the end-of-cycle frame.MDRunner: non-finite energy/forces/positions/momenta abort thecycle; raw force norm
> fmax_abortaborts the cycle (statusmd_force_abort, framesaved). These reuse the helpers extracted in P0.
the adsorbate covalent graph with the break scale (§8.1). A broken bond stops MD
(status
md_integrity_abort).raw/replica_RRR/cycle_CCC/with theexisting
AsyncMDOutputWriter(trajectory + CSV; no XDATCAR/OUTCAR), everycs_save_intervalsteps (default 100) plus snapshot frames and the final frame. TheCSV
phasecolumn isholdorcool; do not changeMD_CSV_HEADER. The targettemperature schedule (step → target K) and the snapshot steps go into
cycle.json.that stopped early quenches only the snapshots taken before it stopped.
mc_rng, using only the end-of-cycle minimumy, andonly if
yis eligible (valid; orreactedwhencs_reaction_policy = include):accept if
E(y) ≤ E(x0); else accept with probabilityexp(−(E(y) − E(x0)) / (k_B·cs_accept_temperature)). Draw the uniform numberevery time an eligible proposal exists (keeps the stream aligned). On acceptance
the current minimum becomes
yitself — its own geometry, not the representative ofthe unique minimum it joined (the replica follows its own path). On rejection, or if
no eligible proposal exists, the current minimum is unchanged.
Step counts:
n_hold = cs_hold_ps·1000/timestep, likewisen_cool,n_snap; each mustbe an integer within 1e-9, else fail closed with the nearest valid values.
7.4 Quench
FIREon R, fixed cell,fmax = cs_quench_fmax(default 0.05 eV/Å),steps = cs_quench_steps(default 2000), FIRE defaults otherwise (recordmaxstep).quench_failed.quench_not_converged. Both are stored, neverranked, never chain states.
E,fmax(on R), steps taken.7.5 Randomness and reproducibility
seed(existing key; auto-generated and recorded when absent, as for MD).ss = np.random.SeedSequence(seed);placement_ss, *replica_ss = ss.spawn(1 + n_replicas); per replicamd_ss, mc_ss = replica_ss[r].spawn(2);generators
np.random.default_rng(...)(PCG64).md_rngdrives Maxwell–Boltzmann draws and Langevin noise;mc_rngdrives Metropolisonly;
placement_rngdrives §5.2 only. Nothing may use the global NumPy RNG.bit_generator.stateof every generator before the next unit ofwork. Same seed + same inputs + CPU deterministic calculator ⇒ bitwise-identical
results, including across interrupt/resume (tested). GPU runs: statistically
reproducible only; say so in docs.
7.6 Defaults (v1, adsorbate mode)
cs_temperature_highcs_temperature_lowcs_hold_pscs_cool_pscs_snapshot_interval_pscs_cyclescs_accept_temperaturetimestepfrictioncs_ramp_intervalcs_save_intervalBefore any model work, log and record a budget summary: replicas, cycles, MD steps
total, quench count upper bound. After the first completed cycle, log measured MD and
quench throughput and an ETA.
8. Classification of every minimum
All distances use MIC. Covalent radii:
ase.data.covalent_radii.8.1 Covalent graph
cs_ionic_species(defaultLi,Na,K,Rb,Cs,Mg,Ca) are excluded fromcovalent graphs. Their coordination may change freely.
d_ij ≤ cs_bond_scale·(r_i + r_j)(default 1.2).adsorbate and slab graphs, else fail closed) or from the conformers and the slab
(mode B; conformers of one molecule must share one adsorbate graph — if they differ,
fail closed: they are different molecules).
d_ij > cs_bond_break_scale·(r_i + r_j)(default 1.5); new bonds are not checkedduring MD.
8.2 Status rules for a converged minimum (first matching rule wins)
fixed_atoms_moved: any atom in F moved (exact comparison) → internal error, abort thewhole search (a bug, not a science outcome).
reacted: any ofbroke).
Record which bonds changed.
Covalent bonds between a non-ionic adsorbate atom and a non-ionic slab atom, with
both graphs intact, are chemisorption, not a reaction: such a minimum is
validwith the flag
chemisorbedand the list of adsorbate–slab bonds (§8.3).desorbed: min adsorbate–slab distance> cs_desorption_distance(default 5.0 Å).image_contact: §8.4 violated.validotherwise.cs_reaction_policy:exclude(default) —reactedminima are archived and neverranked or accepted as chain states;
include— they are ranked and may be chain states,always shown with the
reactedflag and the changed bonds. Useincludeonly to studysurface chemistry on purpose.
8.3 Flags (do not change status)
chemisorbed: at least one adsorbate–slab covalent bond (§8.2); record the bonds as(adsorbate index, slab index, elements, d, q). Otherwise the minimum isphysisorbed. Ranking (§10.1) also reports the best chemisorbed and the bestphysisorbed minimum separately, and their energy difference.
slab_rearranged: some non-ionic free slab atom moved > 1.0 Å from its position in thereplica's start minimum.
far_field_slab_changed: some free slab atom farther than 6.0 Å from every adsorbateatom moved > 0.5 Å from the start minimum — energy differences may then reflect slab
changes rather than adsorption. Count these in diagnostics.
Record per minimum: min adsorbate–slab distance, max slab displacement (ionic and
non-ionic separately), Li coordination of each ionic adsorbate atom (count of neighbours
within 1.2·(r_i+r_j), informational).
8.4 Periodic-image and vacuum criteria
copy of the adsorbate (translations by
n_a·a + n_b·b,(n_a, n_b) ≠ (0, 0)) must be ≥cs_min_image_distance(default 4.0 Å).shifted by
+cmust be ≥cs_min_vacuum_gap(default 8.0 Å).are geometric guards, not proof that the model's receptive field is decoupled.
8.5 Warnings at the end of the search
reactedfraction among quenches > 10 %: "temperature too high or model unreliable forthis chemistry".
desorbed+image_contact> 10 %.quench_not_converged> 5 %.far_field_slab_changedamong the top-K.9. Deduplication
9.1 Comparability (enforced, not assumed)
Within one search, all minima share atom order, cell, F, model identity and electronic
state by construction; assert it at registration (internal error if violated).
9.2 Fingerprint (focused Oganov–Valle, ASE discretization)
Revision 3 replaces the earlier formula, which was internally inconsistent: it divided an
already unit-area (per-Å) Gaussian by Δ and used a different binning from the ASE
reference it was required to match. The fingerprint now uses ASE's
OFPComparatordiscretization exactly, so the known-answer test below can be strict.
ASE's
OFPComparatoris still not called directly: withn_topit fingerprints theadsorbate in isolation (slab atoms are excluded, so adsorption sites are invisible) and it
imports matplotlib at module level. Implement in NumPy, porting the discretization from
the ASE source installed in the environment (
ase.ga.ofp_comparator._take_fingerprints;read it, do not reconstruct it from this text alone):
d_ij < cs_fp_rcut(default 8.0 Å), excluding only the zero-offset self pair — usease.neighborlist.neighbor_list("ijd", atoms, cs_fp_rcut, self_interaction=False)and keep pairs with
i ∈ A.nbins = ceil(rcut/Δ),Δ = cs_fp_binwidth(default 0.02 Å); a pairgoes to bin
k = floor(d_ij/Δ); the bin radius isr_k = (k+1)Δ.k+i,i = −m..m,m = ceil(nsigma·σ/Δ)with nsigma = 4, weights½erf(c(2i+1)) − ½erf(c(2i−1)),c = √2·Δ/(4σ), renormalized to sum to 1;σ = cs_fp_sigma(default from the §13.2 calibration). Handle the array ends exactly as ASE does.4π r_k² Δ; for species pair (α, β)the sum over centres of species α is divided by
n_α(adsorbate atoms of α) and byN_β / V(all atoms of β, cell volume V); thenF_αβ = (…) − 1.α-centred and β-centred fingerprints carry different information.
w_αβ = n_α N_β / Σ n_α' N_β'.D(1,2) = ½ (1 − Σ w F¹·F² / (‖F¹‖ ‖F²‖)),‖F‖ = sqrt(Σ w F·F)(as ASE).whole cell, and relabelling within a species; distinguishes symmetry-inequivalent
adsorption sites and conformers; merges symmetry-equivalent sites of a symmetric slab.
ase.ga.ofp_comparatorneeds scipy and matplotlib, which the CItestjob ([dev]only) does not install today: add
scipy>=1.11andmatplotlib>=3.7(the bounds ofthe
analysisextra) to thedevextra in the P1 PR so the test runs on every CIPython. With A = all atoms:
OFPComparator(rcut, binwidth, sigma, nsigma=4)._take_fingerprints(atoms)to1e-10 absolute; and
F_αβ == F_βαto 1e-10 (symmetry of the full-system RDF);N_t1 N_t2,DequalsOFPComparator._cosine_distanceto 1e-10 on ≥3 structure pairs (an LGPS-derivedcell from
examples/structureswith perturbations, and a slab + molecule cell).The production
Duses the ordered keys/weights above and is not expected to equalASE's unordered
D. Importase.ga.ofp_comparatoronly inside the test module, neverin
mliport/(the production fingerprint must not import scipy or matplotlib). Thetest must not skip in CI.
scientific revision and requires recalibrating
cs_dedup_fp_tol(§9.3).9.3 Matching rule
Error asymmetry (governs every dedup choice). A false merge silently deletes a
distinct candidate — possibly the one DFT would rank first — and overstates saturation. A
false split only produces a duplicate (a wasted DFT job) and understates saturation.
Dedup must therefore be tuned for zero false merges on the calibration set, accepting
some false splits.
A new minimum m matches unique minimum u iff
|E_m − E_u| ≤ cs_dedup_energy_tol(default 0.010 eV per cell) and(
G(m, u)orD(m, u) ≤ cs_dedup_fp_tol).Gis true iff F is non-empty andmax_{i∈A} |r_i^m − r_i^u|_MIC ≤ cs_dedup_geom_tol(default 0.20 Å), atom by atom withthe fixed atom order, no alignment. This is exact here because fixed atoms anchor the
slab (no rigid translation/rotation between minima) and atom order never changes within
a search. It absorbs quench noise on flat basins (soft alkyl modes) that the fingerprint
resolves as differences. If F is empty, G is disabled for the whole search and recorded
in warnings.
permutation-equivalent conformers (e.g. a rotated CH₃, which moves H atoms by ~1.7 Å but
is the same structure). Its tolerance is set by the calibration in §13.2 for zero false
merges — not by eye, and not inside the overlap of the "same" and "different"
distributions.
Compare only against representatives; if several match, take the one with the smallest
(not G, D)(G matches first, then smallest D; ties: lowest id). If none, create a newunique minimum. Shortcut:
|ΔE| > 0.2 eV⇒ no match without computing G or D.cs_dedup_fp_tolandcs_fp_sigmadefaults come out of the P1 calibration (§13.2); postthe evidence as a comment here before P2 starts. Changing any dedup default later bumps
the confsearch scientific revision.
9.4 Registry bookkeeping
Per unique minimum: id, representative (lowest-energy member; updated when a lower member
joins), member list with origin
(replica, cycle, source ∈ {start, snapshot k, end}),hit count, set of replicas, first-found cumulative MD time (ps, summed over the whole
search in execution order) and quench index, status, flags. Registration order is
deterministic (execution order). Each status class has its own registry (
valid,reacted, …); classes never merge.9.5 Consolidation pass
At the end, compare representatives pairwise in ascending energy; merge u_j into u_i
(i < j) when §9.3 matches; repeat until stable. Record merges.
10. Results
10.1 Ranking
Rankable =
validunique minima (plusreactedwith policyinclude). Sort by refinedenergy where refined (§10.3), otherwise quench energy. Report
E,ΔEto the best,ΔE/atom, hit count, number of replicas, first-found time, flags, refinement status.Refined and unrefined entries are shown in separate tables; never interleave energies at
different
fmax.10.2 Saturation diagnostics (no "global minimum" claims)
diagnostics/discovery.csv): one row per quench — cumulative MD ps,quench index, unique valid count, unique valid count within 0.2 eV of the current best,
current best energy.
new_low_minima_last_quarter: unique valid minima within 0.2 eV of the final best firstfound in the last 25 % of quenches.
best_repeatedly_found = (hits ≥ 3 and replicas ≥ 2).10.3 Refinement of top-K
Take the
cs_top_k(default 10) lowest rankable unique minima withincs_export_window(default 0.5 eV) of the best. Re-quench each from its representative with FIRE at
cs_refine_fmax(default 0.02 eV/Å),cs_refine_steps(default 3000), fixed cell,constraints F. Re-classify (a refined minimum can change status) and re-deduplicate the
refined set with §9.3. Unconverged refinement keeps the quench result and is flagged.
A candidate in the refinement window whose refinement did not converge is still
exported (as
top/unrefined_NNN/, its quench geometry and energy, flagged), and awarning names it: a failed refinement must never silently remove a top candidate from
the DFT deliverable. Flags of a refined entry come from the refined classification.
cs_refine = falseskips this step (recorded).10.4 Baseline comparison
Report the best energy after the start-quench stage only (multi-start relaxation, no MD)
next to the final best, and how many final top-K minima were never reached by any start
quench. This tells the user whether the MD cycles added anything.
10.5 Exports for DFT
For each exported rank
top/rank_NNN/:POSCAR(VASP, direct coordinates, selective dynamicsF F Ffor F via the existingwriter; verify the writer does this);
structure.extxyz(with cell, PBC, energy, status, id);cp2k_coord.xyz(plain xyz),cp2k_cell.inc(A,B,Clines in Å) andcp2k_fixed_atoms.inc(LISTwith 1-based indices, ranges compressed asa..b;verify the syntax against the CP2K manual for
&MOTION/&CONSTRAINT/&FIXED_ATOMSandcite it in the docs);
minimum.json(everything in §9.4 and §8).Coordinate convention for exports: slab atoms wrapped into the cell; the adsorbate made
whole (covalent graph BFS under MIC from its first non-ionic atom; ionic adsorbate atoms
placed at the MIC image nearest to their nearest non-ionic adsorbate atom). Energies are
unaffected; tests must prove the exported structure equals the minimum up to lattice
translations.
Docs must state that DFT single points/relaxations of the exports need a dipole
correction for one-sided slabs (the MLIP has no long-range electrostatics).
11. Output layout, provenance, checkpoint/resume, extend, merge
11.1 Run directory
Reuse the existing output-directory claim/lock and overwrite rules;
resumeandextendtake the same run-directory lock. Units as in the rest of mliport (eV, Å, fs, K).resolved_config.jsonis written for every new run, like the other workflows.run.logis a live, append-only log (the existingLiveRunLogger): it exists fromthe first line, survives a crash, and a resume/extend appends to it.
run_context.jsonis created once; later resumes/extensions update it (appendto
resumes[]/extensions[], setfinished_at) and never rebuild it from scratch.minima/all_minima.extxyzholds the geometry of every quench result (allstatuses), so rejected and
reactedstructures can be inspected;minima/registry.jsonholds the registry.
11.2 Checkpoint and resume
checkpoint (reuse
atomic_write_json,canonical_fingerprintfrommliport.neb.io)with: unit index, per-replica state (current minimum id + geometry, status, counters),
all RNG states, registry, discovery rows, cumulative MD time.
CS_SCIENTIFIC_REVISION,CS_CHECKPOINT_SCHEMA_REVISION, model identity, input-structure content hashes,regions, every option except pure output/verbosity settings, seed. Any difference ⇒
refuse with the differing keys.
model_type, model_sha256, backend_version, framework_versions, task, head_effective, dtype_effective, inference_mode, compile_enabled, direct_forcesand, fromdispersion, onlymethod, xc, damping, implementation, version. It excludes where the model ran or wasstored (
actual_device_*,backend_reported_device,model_path,model_alias,model_source,dispersion.device): resuming on another GPU or with a movedcheckpoint of identical content is the same calculation. Devices are still recorded in
run_context.json.interrupted attempt are moved to
raw/.../incomplete_attempt_N/(never deleted;AGENTS.md rule 11).
11.3 Extend
extend RUN --cycles Nadds N cycles to every surviving replica of a completed search.Allowed because it changes only the budget: record the extension (time, N, mliport
version) in
run_context.json["extensions"]; the fingerprint compares everything exceptcs_cycles. Refinement, ranking and exports are recomputed; previous top-level resultsare archived under
history/extension_N/.11.4 Merge
merge RUN1 RUN2 … --output DIRcombines completed searches without new calculations iftheir comparability key is identical: model identity (§11.2 definition), atomic numbers
in order, cell (exact), PBC, F, A, the positions of the fixed atoms F (exact; they never
move, so they identify the slab geometry), electronic state (charge/spin), ionic species, bond and
dedup parameters, quench fmax and refine settings. Index sets alone are not enough: two
different slabs can share them. Exploration parameters (temperatures,
cycles, seeds) may differ and are recorded per source. Re-register all minima in source
order, run §9.5, re-rank. Refinement results are reused only if refine settings match;
otherwise fail closed (no recomputation in merge). Origins carry the source run id.
12. Interfaces
12.1 CLI
A new run requires an explicit
--output. Exit codes via the existingrun_statusmapping: completed → success; completed with warnings → success with warnings printed;
no surviving replica → failed.
12.2 Python API
mliport.api.run_confsearch(...)mirroring the CLI options, returning thesearch_results.jsoncontent as a dict. Place it besiderun_neband follow itsresolution path (
_api_resolve_full).12.3 Configuration keys
Add
"confsearch"tocalc_typechoices,CalculationEngine.VALID_CALC_TYPES,IncarConfig.validate(),DEFAULT_DEVICE_BY_CALC_TYPE,BUILTIN_DEFAULTS(scopeconfsearch),run_status, the resolver and the TUI calc-type lists (TUI phase). Grep for"neb"to find every place NEB was registered and register confsearch the same way.Existing keys reused with the
confsearchscope added:timestep,friction,seed,fmax_abort,charge,spin. Seed auto-generation must apply to confsearch as it doesto MD. New keys (canonical name / INCAR alias uppercase):
cs_modeadsorbateadsorbate}cs_startscs_adsorbate_indicescs_slab,cs_moleculecs_n_startscs_fix_belowcs_md_mobileadsorbateadsorbate,adsorbate_and_top,all_free}cs_top_depthcs_temperature_highcs_temperature_lowcs_hold_ps,cs_cool_pscs_snapshot_interval_pscs_ramp_intervalcs_cyclescs_save_intervalcs_accept_temperaturecs_quench_fmax,cs_quench_stepscs_bond_scale,cs_bond_break_scalecs_ionic_speciesLi,Na,K,Rb,Cs,Mg,Cacs_reaction_policyexcludeexclude,include}cs_desorption_distancecs_min_image_distancecs_min_vacuum_gapcs_place_contact_scalecs_bond_scalecs_place_anchorcs_place_anchor_scalecs_bond_scalecs_place_other_min_scalecs_bond_scalecs_place_anchor_targetscs_place_max_attemptscs_dedup_energy_tolcs_dedup_fp_tolcs_dedup_geom_tolcs_fp_rcut,cs_fp_binwidth,cs_fp_sigmacs_top_k,cs_export_windowcs_refine,cs_refine_fmax,cs_refine_stepscs_allow_direct_forcesCross-key validation (resolver, fail closed): mode A needs starts + indices and forbids
slab/molecule/n_starts; mode B the reverse; low ≤ high; snapshot interval < hold;
integer step conversions; break scale > bond scale;
cs_refine_fmax ≤ cs_quench_fmax.MD-only keys that make no sense here (
ensemble,thermostat,pre_relax*,velocity_policy,com_policy,bussi_*,nhc_*,steps,equilibration_steps,save_interval) must be rejected for confsearch, not ignored.12.4 Capability matrix
Add features (
confsearch_user_starts,confsearch_placement,confsearch_resume,confsearch_extend,confsearch_merge) tovalidation/science/capability_matrix.jsonwith honest
no/partial+ note until each interface supports them (e.g. TUInountil P5; INCAR
nofor resume/extend/merge, which are commands).13. Tests and validation
13.1 Synthetic calculators (CI, CPU, deterministic)
Provide test-only calculators, no backend imports:
3-atom bonded molecule with harmonic bonds and angle) whose energy has an analytic
periodic site term with known site types (top/bridge/hollow-like) and known minima
energies. Used for search, dedup, ranking and saturation tests.
breaks a bond reproducibly with a fixed seed (tests
md_integrity_abort,reacted).direct_forces=True(tests the gate).13.2 Required tests (non-exhaustive minimum)
unit vectors rotated: mean ≈ 0, second moment ≈ I/3 within tolerance for 10⁴ samples);
contact placement reaches
min q = cs_place_contact_scale(1e-4); anchored placement:the anchor is the lowest atom, its
qequalscs_place_anchor_scale, every other pairq ≥ cs_place_other_min_scale, targets respected, orientation distribution uniformunder the condition (compare against brute-force rejection on 10⁴ samples);
image/vacuum rejection works; max-attempt failure reports per-reason counts.
valid+chemisorbed;a broken skeleton bond is
reacted.gives zero momenta to fixed atoms and the exact target temperature over free DOF.
steps.
cs_fp_sigmaandcs_dedup_fp_tol(revision 4 procedure) on theegg-crate model and on one realistic geometry (e.g. a small organic molecule with a
flexible chain on an LGPS-derived slab with a synthetic smooth potential), quenched at
the production
cs_quench_fmax:(a) same: re-quenches of a minimum from perturbations of 0.02–0.1 Å whose result is
within
cs_dedup_geom_tolof the original; perturbations that land > 0.5 Å away area different basin — exclude them from (a) and report how many;
(b) different sites and (c) different conformers: symmetry-inequivalent, verified
max displacement > 0.5 Å and not related by a slab symmetry operation or a
permutation of equivalent atoms;
(d) equivalent: the same minimum mapped by a slab symmetry operation and/or a
permutation of equivalent atoms (CH₃ rotation) — these must merge via D.
cs_fp_sigma ∈ {0.05, 0.10, 0.20}Å (binwidth 0.02 Å, rcut 8 Å).D_tol(σ) = 0.5 · min Dover (b ∪ c) pairs with|ΔE| ≤ cs_dedup_energy_tol(if there are none, over all (b ∪ c) pairs). This gives zerofalse merges with a factor-2 margin. Report the fraction of (d) pairs merged and of
(a) pairs merged by G, by D, or split.
document the residual split rate as a known limitation (duplicates in exports, lower
hit counts — conservative), and do not widen the tolerance into the overlap.
A descriptor change is considered only on evidence from real-model runs (P5).
rates) here.
update, consolidation, no cross-status merging; the calibration set yields zero false
merges with the shipped defaults (kept as a regression test).
RNG stream alignment when proposals are ineligible.
1e-6 eV) and hit counts; baseline vs search reported; exports re-read equal (up to
lattice translations).
compare
search_results.json, registry and raw files to an uninterrupted run (bitwiseon CPU).
when sources are compatible; refusal when not.
continues and statuses are correct.
MDRunnerand NEB behaviour unchanged after the P0 refactors (existing suites green,plus a test pinning the gradient pre-flight result for NEB).
13.3 Real-model validation (owner runs on GPU; not CI)
A campaign script under
validation/science/scripts/(P5) on a small public system,e.g. CH₃OH or H₂O on a slab cut from the repository's LGPS structure, with MACE: compare
(i) N random placements relaxed without MD (baseline) and (ii) confsearch with the same N
starts; report best energies, unique counts and discovery curves. The report must not
claim accuracy against DFT; it checks workflow behaviour. No data/plans committed beyond
what the existing validation layout already permits.
14. Implementation phases (one PR each; update the checkboxes here)
MDRunnerthestateless safety checks (atomic-state validation, finite checks, raw/applied force
views, force-abort evaluation) into a module both MD and confsearch use; generalize
the gradient pre-flight to accept ≥1 structure with NEB still requiring ≥2; extract the
NEB model record into a shared helper including
dispersion. Existing tests unchangedand green; add pinning tests. DATA IMPACT: none.
mliport/confsearch/: options dataclass withvalidation (like
NEBOptions), index-spec parser, regions, covalent graphs and statusrules, fingerprint + registry + consolidation, placement. Fingerprint calibration
posted here.
output, checkpoint/resume, refinement, ranking, diagnostics, exports; synthetic-model
end-to-end tests.
run,place,--dry-run,resume,export)/API,resolved_config.json, artifacts, run status,bilingual docs page
docs/workflows/confsearch.md+.zh.md(nav + docs contract test),capability matrix, CHANGELOG.
extendandmergecommands; queue task support forunattended runs.
Each PR description: link to this PR, the spec revision it implements, what it does not
yet do.
15. Risks and scientific caveats (must appear in the docs page)
organic adsorbate on a sulfide surface poorly; high temperatures amplify this. A high
reactedfraction is a symptom. Always re-rank exports with DFT.reference lacks it.
adsorbate_and_toprelaxes this at the cost of noisier energies (watchfar_field_slab_changed).same model; the tool does not check this.
trustworthy part of the result; DFT must confirm every
chemisorbedcandidate.dipole correction.
16. Decision log
includeonly to study surface chemistry on purpose; ionic rearrangement is not a reactionchemisorbed), notreacted; placement distances use covalent-radii scales; optional anchored placement starts already bonded17. Open questions (answer in comments; folded in as new revisions)
worked example, not the code.
after the first real run (GPU currently busy). For LiDS the natural anchors are the
sulfate O atoms.
Spec revision log
main(refactor(runners): shared safety helpers for MD and confsearch (P0) #62–feat(confsearch): TUI entry (P5) #67); real-model validation campaign (§13.3) and real-slab dedup recalibration still to run on GPU.includes fixed-atom positions.
§11.1 run.log/run_context/resolved_config/minima files; §11.2 model-identity key list;
§11.4 merge key.
cs_dedup_geom_tol;§13.2 calibration redefined (geometry-labelled classes, σ sweep, zero false merges,
equivalent-pair class (d)); rejected: fixed tolerances 0.01/0.025/0.05 chosen inside
the overlap; descriptor change deferred to P5 evidence.
(per-bin arrays and D to 1e-10). The revision-1/2 formula had an extra 1/Δ and a
different binning.
cs_dedup_fp_tolcalibration must use this implementation.optional anchored placement; §8.2/§8.3 adsorbate–slab bonds are
chemisorbed, notreacted; keys and tests updated; open question 2 reworded.https://claude.ai/code/session_017vVRW3uEnhYKFinpvqMysi
Generated by Claude Code