Skip to content

[DEV MASTER · DO NOT MERGE/CLOSE] MLIP validation roadmap (#75) + confsearch living spec - #61

Draft
hydrogen1222 wants to merge 1 commit into
mainfrom
dev/confsearch-spec
Draft

hydrogen1222 wants to merge 1 commit into
mainfrom
dev/confsearch-spec

Conversation

@hydrogen1222

@hydrogen1222 hydrogen1222 commented Oct 24, 2026 •

Copy link
Copy Markdown
Owner

最新决策(2026-11-17,覆盖下方过期的“当前/下一步”叙述):功能冻结,转入尽可能全面的测试、缺陷修复和稳定化。 最新已核对 main = 449ec9a;#101、#104、#105、#106、#107 均已合并。唯一执行清单:PR #75 Rev 10 全覆盖验收与稳定化执行单;复用其旧 §4–10 全量矩阵并执行 Rev 10 的新增测试(INCAR/models/TUI/Isotropic MTK、Issue #102、真实后端、分析、容错、文档、release gate)。不新增算法或功能;DPA-SSE 等过去的候选工作在未获新授权前一律不启动;昂贵 GPU/HPC/DFT/权重下载仍按 #75 资源门禁管理。此条为当前生效决策,下方 2026-11-14 的进度和规格作为历史完整保留。#61 / #75 始终 Open + Draft、不合并/关闭。

进度同步(2026-11-18,不改历史规格):功能冻结状态不变;main 已推进到 fb2935c730118bcaa86ede6154ac10c512f46677(#108/#109 已合并)。Rev 10 第二阶段(多材料 / 全工作流 / 无人值守)执行完毕,结果见 #75 执行结果评论。新增两个未合并的缺陷修复 Draft PR:#110(P1:numpy bool 导致未收敛的 OPT 被记为 completed/exit 0/batch success)、#111(P2:R10-F01 NPT 非法组合在创建目录与加载模型之后才拒绝);两者 12/12 checks SUCCESS。受阻/未执行:MLIP-vs-DFT 对照(无合格标签)、NEP89 原生 GPUMD(缺 libnvJitLink.so.12)、官方 T5/T6 套件(预算/耗时)。Na₃PS₄ 电导率与 GEMDAT 跳跃仅有 10 ps 采样,结论为 INCONCLUSIVE,不得当作材料结论。DPA-SSE、Fully flexible NPT 等未获授权的工作未启动。#61 / #75 保持 Open + Draft。

[DEV MASTER · PERMANENT OPEN DRAFT · DO NOT MERGE/CLOSE] mliport development coordination

Owner rules retained. PR #61 是 mliport 唯一长期开发总入口;保持 Open + Draft、零代码变更、不得合并/关闭。实际代码/测试一律单独开 PR 到 main 并回链 #61;PR #75 保存逐文件审计、测试证据及残余风险,也不得合并/关闭。下方原始 confsearch 规格与历史决策保留,不以当前进度更新替代规范。

当前状态(2026-11-14 · 已核实)

下一步(收敛为一个可执行目标)

当前(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

This PR is never merged and never closed. It is the single, continuously updated
requirements document for the configuration-search feature. Code does not land on
this branch: every implementation step is its own PR against main that links back
here (Tracking: #61). The branch only carries an empty commit so GitHub can
host the PR.

Spec revision: 6 · 2026-10-25 (see the revision log at the end)


0. 需求摘要(给人看)

  • 做什么:在周期性体系里,用分子动力学(MD)做构象/构型搜索,找到低能结构,并给出一份可以直接交给 DFT(CP2K/VASP)复核的候选清单。
  • v1 只做一件事:单个分子在 slab 表面上的吸附构型(典型例子:LiDS 吸附在 LPSC 表面)。分子构象、吸附位点、取向一起搜。
  • 怎么搜:多个起点(手工给的结构 + 程序随机摆放) × 每个起点若干轮"升温—保温—降温—淬火(局部优化)"循环;淬火得到的极小值按能量和结构指纹去重、排序。
  • 晶胞:全程固定晶胞(NVT)。slab 有真空层,不做变胞。
  • 化学吸附优先:分子与表面形成共价键(骨架完好)算正常的化学吸附构型,参与排名并标记 chemisorbed;可指定"锚点原子"(如硫酸根 O)让起点直接以成键距离摆放。摆放距离按两原子共价半径之和的倍数设定,不用单一固定键长。
  • 分子"变了"就剔除:分子共价骨架(C–H、C–C、C–O、S–O 等)断键/成键的结构单独存档、标记 reacted,默认不进排名;只有用户明确要研究表面反应时才放进排名。Li⁺ 等离子换位置不算反应。
  • 诚实报告:不宣称"找到全局最小",只报告"目前找到的最低",并给出它被找到了几次、被几个独立起点找到、搜索是否饱和等证据。MLIP 排名只是筛选,最终要 DFT 复核。
  • 以后再做:体相 Li/空位排布、非晶熔融淬火、界面、多分子/覆盖度、NPT、副本交换。

1. Rules for agents working from this spec

  1. Read AGENTS.md, CONTRIBUTING.md and docs/development.md first. They override
    anything here that conflicts with them; if you find such a conflict, stop and report it
    in a comment on this PR.
  2. Execute this spec literally. Where it says "must", there is no latitude. Where you
    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.
  3. One logical change per PR, in the phase order of §14. Each PR: red test first, then the
    smallest implementation; DATA IMPACT section in the commit message; bilingual docs for
    anything user-visible; CHANGELOG Unreleased entry; CI green.
  4. Never push to this PR's branch, never mark it ready for review, never merge or close it.
    Update the phase checklist (§14) in this description when an implementation PR merges.
  5. Do not commit this spec, agent briefs or plans into the repository (AGENTS.md rule 9).
    The spec lives here only.
  6. Scientific correctness over speed; fail closed; never silently change units, PBC,
    model task/head/dtype; never compare absolute energies from different model
    identities (AGENTS.md 1–4).
  7. Prefer ASE/upstream algorithms (integrators, optimizers, neighbour lists). This spec
    explains where and why it deliberately does not use an upstream component (§6.6, §9.2).

2. Scope

2.1 In scope for v1

  • Mode adsorbate: one adsorbate molecule (it may contain ionic atoms such as the Li of
    LiDS) on one side of a slab, 3D-periodic cell with vacuum along +z.
  • Exploration by Langevin NVT MD at fixed cell, with a temperature schedule, followed by
    local minimization ("quench") of selected frames.
  • Two ways to obtain starts, combinable: user-prepared start structures, and automatic
    random placement of a molecule (one or more conformers) above a slab.
  • Chemical-integrity classification of every minimum, deduplication, ranking, saturation
    diagnostics, top-K refinement and export for DFT (VASP POSCAR and CP2K-friendly files).
  • Checkpoint/resume; extend a finished search with more cycles; merge independent runs
    (different machines/seeds) when they are comparable.
  • Interfaces: Python API, direct CLI, INCAR-style keys; queue and TUI in later phases.

2.2 Explicit non-goals for v1 (reject, do not half-implement)

  • NPT or any variable-cell MD; variable-cell refinement (a slab cell must stay fixed).
  • Bulk modes (mobile-ion arrangement, substitutional ordering), amorphous melt-quench,
    interfaces, multiple adsorbates/coverage, two-sided slabs.
  • Replica exchange, metadynamics, bias potentials, restraints or walls (any term that
    changes the potential energy surface).
  • Free energies, Boltzmann populations, adsorption energies (needs separately computed
    references; users do this with existing opt).
  • Gas-phase conformer generation (users bring conformers, e.g. from CREST/xtb).
  • Molecular (non-periodic) tasks.

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_mode an enum with only adsorbate accepted; 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)

  • MD explores locally, multi-start covers globally. At 400–600 K, chain
    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.
  • Anneal–quench cycles with Metropolis restarts combine simulated annealing
    (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).
  • Freezing the slab during hot MD (default) lets the adsorbate be heated without
    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.
  • The ranking is a screening. MLIP energy errors for adsorption on an off-distribution
    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

Term Meaning
start one prepared initial structure (user-given or placed)
replica the search chain that begins at one start; replicas are independent
cycle one heat–hold–cool MD segment of a replica followed by its quenches
snapshot an MD frame taken during the hold phase for quenching
quench local minimization of a frame at fixed cell
minimum the structure returned by a converged quench, plus its classification
unique minimum a cluster of minima judged identical by §9; represented by its lowest member
hit one minimum assigned to a unique minimum
A adsorbate atom indices
S slab atom indices (all atoms not in A)
F fixed atoms: FixAtoms from the input (must be ⊆ S)
R relax set = all atoms not in F (used by every quench)
M MD-mobile set (§7.2); atoms outside M are held fixed during MD only
current minimum the replica's Markov-chain state between cycles

5. Inputs and preparation

5.1 Mode A — user-prepared starts

  • One or more structure paths; a path may be a multi-frame file (extxyz/traj) or a
    directory (read every structure file, sorted by name). Each frame is one start.
  • cs_adsorbate_indices is required in mode A. Syntax: comma-separated 0-based
    indices and inclusive ranges, e.g. 300-341 or 0,5,7-9. Document clearly that it is
    0-based like ASE (CP2K/VMD users count from 1). Log the selected chemical formula.
  • Every start must have identical: atom count and element order, cell (exact, compared
    with np.array_equal after reading; no tolerance), PBC, fixed-atom set, and
    atoms.info charge/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-frame
allowed; 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):

  1. Pick a conformer uniformly at random; record its index.
  2. Centre the conformer at its centroid (unweighted mean of positions).
  3. Apply a uniform random rotation: draw a quaternion from four independent standard
    normals, normalize (Shoemake), convert to a rotation matrix.
  4. Draw fractional in-plane coordinates u, v ~ U[0, 1); lateral position =
    u·a + v·b (a, b in the xy-plane, §5.3).
  5. Height. All placement distances are element-pair aware, in units of the covalent
    radii sum: q_ij = d_ij / (r_cov,i + r_cov,j) (MIC; ase.data.covalent_radii). A
    single Å 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.
    • Contact placement (no anchor given): 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.
    • Anchored placement (chemisorption-first, cs_place_anchor given): 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 q to its
      partner set equals cs_place_anchor_scale (default 1.1, a slightly stretched
      bond: 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_targets is 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.
  6. Reject and redraw (steps 1–5) if: in anchored placement, any non-anchor
    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 anchor
    target condition fails; the self-image or vacuum criterion of §8.4 fails. After
    cs_place_max_attempts (default 1000) consecutive rejections, fail closed with the
    rejection counts per reason.
  7. Record per start: placement kind (contact/anchored), anchor atom used, conformer
    index, quaternion, u, v, z offset, attempts and rejections per reason, and the
    resulting minimum distances and q values. Write starts/start_XXX.extxyz and a POSCAR copy.

The slab's own constraints become F. Optionally cs_fix_below (Å) adds to F every slab
atom with z < z_min(slab) + cs_fix_below; combining it with existing constraints is the
union, recorded.

5.3 Validation common to both modes (fail closed)

  • pbc == (True, True, True); the task must be a periodic task (existing
    _prepare_atoms rules).
  • Surface geometry: |a_z|, |b_z| < 1e-8 Å and c_z > 0. Otherwise: error explaining
    that the surface normal must be +z (do not rotate the cell for the user).
  • The slab must be contiguous in z inside the cell (no atoms wrapped across the c
    boundary): after wrap, the largest gap in sorted slab z coordinates (including the
    periodic 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 above z_top
    (one-sided adsorption).
  • Only FixAtoms constraints are accepted. FixScaled/FixCartesian (partial selective
    dynamics), FixCom, FixSymmetry or any other constraint: fail closed. F must not
    intersect A.
  • A must be non-empty, must not be all atoms, and the non-ionic part of A must form one
    connected covalent graph (§8.1). Otherwise fail closed (wrong selection is the most
    likely user error).
  • If F is empty, warn (recorded in warnings): a fully free slab can drift or bend.
  • Timestep: if any H is in M and timestep > 1.0 fs, fail closed. Default 0.5 fs.

6. Calculator and identity gates

  1. One model instance for the entire search (load once, as NEB does).
  2. Requires energy and forces. Stress is not used.
  3. Energy–force consistency. Minima are force-converged points ranked by energy; if
    forces are not −∇E, that ranking is not meaningful.
    • If the calculator reports direct_forces is True: fail closed unless
      cs_allow_direct_forces = true; then record
      energy_gradient_consistency: "not_guaranteed" and add a warning to every result.
    • Otherwise run the existing gradient pre-flight (mliport.neb.preflight) on the first
      prepared 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.
  4. DFT-D3 (--d3) is allowed and must be part of the model identity (§12): the
    dispersion record from calculator.info() enters the comparability key, so a search
    with 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.
  5. UMA inference_mode=turbo is allowed only if explicitly requested (existing opt-in),
    recorded, and listed in warnings (reduced precision affects meV-level dedup).
  6. Model record: reuse the NEB model record (_model_record); P0 extracts it into a
    shared public helper with identical behaviour for NEB, plus the dispersion field.

6.6 Why not ase.optimize.minimahopping

It 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

prepare starts → model + pre-flight → stage "start_quench": quench every start
→ for cycle c = 1..cs_cycles:
      for replica r = 0..n-1 (round-robin, skip finished/failed replicas):
          run cycle (r, c); register its minima; checkpoint
→ consolidation pass (§9.5) → refinement of top-K (§10.3) → ranking, exports, diagnostics

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 valid is marked
failed_start and gets no cycles; the search continues with the others. If no replica
survives, 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} with
    cs_top_depth default 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). The
quench always relaxes R. The cell never changes.

7.3 One cycle (replica r, cycle c)

Let x0 = geometry of the replica's current minimum.

  1. Build a fresh Atoms copy of x0, temporary MD constraint per §7.2.
  2. Velocities: MaxwellBoltzmannDistribution(temperature_K=T_high, force_temp=True, rng=md_rng) on the constrained atoms. Verify (test) that fixed atoms get zero momenta
    and that the instantaneous temperature over free DOF equals T_high.
  3. Hold: ASE Langevin(timestep, temperature_K=T_high, friction=friction, rng=md_rng, fixcm=False) for n_hold steps. fixcm must be False (fixed atoms
    present; mirrors MDRunner).
  4. Snapshots: if cs_snapshot_interval_ps > 0, at hold steps k·n_snap for
    k ≥ 1 and k·n_snap < n_hold, store a detached copy of the frame for quenching.
  5. Cool: continue the same integrator for n_cool steps, updating the target with
    dyn.set_temperature(temperature_K=T(t)) every cs_ramp_interval steps (default 10),
    T(t) linear from T_high to T_low. The final frame is the end-of-cycle frame.
  6. Per-step safety, as in MDRunner: non-finite energy/forces/positions/momenta abort the
    cycle; raw force norm > fmax_abort aborts the cycle (status md_force_abort, frame
    saved). These reuse the helpers extracted in P0.
  7. Early integrity check: at every snapshot time and at the end-of-cycle frame, check
    the adsorbate covalent graph with the break scale (§8.1). A broken bond stops MD
    (status md_integrity_abort).
  8. Raw data: write the MD segment losslessly to raw/replica_RRR/cycle_CCC/ with the
    existing AsyncMDOutputWriter (trajectory + CSV; no XDATCAR/OUTCAR), every
    cs_save_interval steps (default 100) plus snapshot frames and the final frame. The
    CSV phase column is hold or cool; do not change MD_CSV_HEADER. The target
    temperature schedule (step → target K) and the snapshot steps go into cycle.json.
  9. Quench, in this order: snapshots (chronological), then the end-of-cycle frame. A cycle
    that stopped early quenches only the snapshots taken before it stopped.
  10. Classify (§8) and register (§9) each minimum in that order.
  11. Metropolis update with mc_rng, using only the end-of-cycle minimum y, and
    only if y is eligible (valid; or reacted when cs_reaction_policy = include):
    accept if E(y) ≤ E(x0); else accept with probability
    exp(−(E(y) − E(x0)) / (k_B·cs_accept_temperature)). Draw the uniform number
    every time an eligible proposal exists (keeps the stream aligned). On acceptance
    the current minimum becomes y itself — its own geometry, not the representative of
    the unique minimum it joined (the replica follows its own path). On rejection, or if
    no eligible proposal exists, the current minimum is unchanged.
  12. Checkpoint (§11).

Step counts: n_hold = cs_hold_ps·1000/timestep, likewise n_cool, n_snap; each must
be an integer within 1e-9, else fail closed with the nearest valid values.

7.4 Quench

  • ASE FIRE on R, fixed cell, fmax = cs_quench_fmax (default 0.05 eV/Å),
    steps = cs_quench_steps (default 2000), FIRE defaults otherwise (record maxstep).
  • The input frame's velocities are dropped. Constraints during quench: F only.
  • Non-finite values or force abort during a quench: minimum status quench_failed.
  • Not converged within the budget: status quench_not_converged. Both are stored, never
    ranked, never chain states.
  • After convergence record E, fmax (on R), steps taken.

7.5 Randomness and reproducibility

  • Master seed: 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 replica md_ss, mc_ss = replica_ss[r].spawn(2);
    generators np.random.default_rng(...) (PCG64).
  • md_rng drives Maxwell–Boltzmann draws and Langevin noise; mc_rng drives Metropolis
    only; placement_rng drives §5.2 only. Nothing may use the global NumPy RNG.
  • Checkpoints store bit_generator.state of every generator before the next unit of
    work. 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)

Key Default Note
cs_temperature_high 500 K with frozen slab; raise with care
cs_temperature_low 300 K end of cooling ramp
cs_hold_ps 2.0
cs_cool_ps 2.0
cs_snapshot_interval_ps 0.5 3 snapshots per hold (0.5, 1.0, 1.5 ps)
cs_cycles 5 per replica
cs_accept_temperature 500 K Metropolis
timestep 0.5 fs confsearch-scoped default
friction 0.01 fs⁻¹ strong coupling so T follows the ramp; confsearch-scoped
cs_ramp_interval 10 steps
cs_save_interval 100 steps raw MD frames

Before 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

  • Ionic species cs_ionic_species (default Li,Na,K,Rb,Cs,Mg,Ca) are excluded from
    covalent graphs. Their coordination may change freely.
  • Bond between non-ionic atoms i, j if d_ij ≤ cs_bond_scale·(r_i + r_j) (default 1.2).
  • Reference graphs: from the prepared start (mode A; all starts must give the same
    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).
  • During MD (early check, §7.3 step 7) a reference bond counts as broken only if
    d_ij > cs_bond_break_scale·(r_i + r_j) (default 1.5); new bonds are not checked
    during MD.

8.2 Status rules for a converged minimum (first matching rule wins)

  1. fixed_atoms_moved: any atom in F moved (exact comparison) → internal error, abort the
    whole search (a bug, not a science outcome).

  2. reacted: any of

    • adsorbate graph (non-ionic A) differs from reference (bond lost, gained, or moved);
    • the non-ionic slab graph differs from the slab reference graph (e.g. a PS₄ unit
      broke).
      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 valid
    with the flag chemisorbed and the list of adsorbate–slab bonds (§8.3).

  3. desorbed: min adsorbate–slab distance > cs_desorption_distance (default 5.0 Å).

  4. image_contact: §8.4 violated.

  5. valid otherwise.

cs_reaction_policy: exclude (default) — reacted minima are archived and never
ranked or accepted as chain states; include — they are ranked and may be chain states,
always shown with the reacted flag and the changed bonds. Use include only to study
surface 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 is
    physisorbed. Ranking (§10.1) also reports the best chemisorbed and the best
    physisorbed minimum separately, and their energy difference.

  • slab_rearranged: some non-ionic free slab atom moved > 1.0 Å from its position in the
    replica's start minimum.

  • far_field_slab_changed: some free slab atom farther than 6.0 Å from every adsorbate
    atom 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

  • Self-image: the minimum distance between an adsorbate atom and any atom of a periodic
    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 Å).
  • Vacuum: the minimum distance between any adsorbate atom and any slab atom of the image
    shifted by +c must be ≥ cs_min_vacuum_gap (default 8.0 Å).
  • Record both values for every minimum and for the starts. Docs must explain that these
    are geometric guards, not proof that the model's receptive field is decoupled.

8.5 Warnings at the end of the search

  • reacted fraction among quenches > 10 %: "temperature too high or model unreliable for
    this chemistry".
  • desorbed + image_contact > 10 %.
  • quench_not_converged > 5 %.
  • Any far_field_slab_changed among 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 OFPComparator
discretization exactly
, so the known-answer test below can be strict.

ASE's OFPComparator is still not called directly: with n_top it fingerprints the
adsorbate 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):

  • Centres: atoms in A. Neighbours: all atoms (A and S), all periodic images with
    d_ij < cs_fp_rcut (default 8.0 Å), excluding only the zero-offset self pair — use
    ase.neighborlist.neighbor_list("ijd", atoms, cs_fp_rcut, self_interaction=False)
    and keep pairs with i ∈ A.
  • Bins as in ASE: nbins = ceil(rcut/Δ), Δ = cs_fp_binwidth (default 0.02 Å); a pair
    goes to bin k = floor(d_ij/Δ); the bin radius is r_k = (k+1)Δ.
  • Smearing as in ASE: the binned pair is spread over bins 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.
  • Normalization as in ASE: each bin is divided by 4π r_k² Δ; for species pair (α, β)
    the sum over centres of species α is divided by n_α (adsorbate atoms of α) and by
    N_β / V (all atoms of β, cell volume V); then F_αβ = (…) − 1.
  • Keys: ordered pairs (α ∈ species(A), β ∈ species(all)) — with A ≠ all atoms,
    α-centred and β-centred fingerprints carry different information.
  • Weights w_αβ = n_α N_β / Σ n_α' N_β'.
  • Distance D(1,2) = ½ (1 − Σ w F¹·F² / (‖F¹‖ ‖F²‖)), ‖F‖ = sqrt(Σ w F·F) (as ASE).
  • Properties to test: invariant to lattice translations, rigid rotation/reflection of the
    whole cell, and relabelling within a species; distinguishes symmetry-inequivalent
    adsorption sites and conformers; merges symmetry-equivalent sites of a symmetric slab.
  • Known-answer test against ASE (strict, always run in CI). Importing
    ase.ga.ofp_comparator needs scipy and matplotlib, which the CI test job ([dev]
    only) does not install today: add scipy>=1.11 and matplotlib>=3.7 (the bounds of
    the analysis extra) to the dev extra in the P1 PR so the test runs on every CI
    Python. With A = all atoms:
    • for every unordered key (t1 ≤ t2 by atomic number) the per-bin arrays equal
      OFPComparator(rcut, binwidth, sigma, nsigma=4)._take_fingerprints(atoms) to
      1e-10 absolute; and F_αβ == F_βα to 1e-10 (symmetry of the full-system RDF);
    • collapsing to unordered keys with ASE's weights N_t1 N_t2, D equals
      OFPComparator._cosine_distance to 1e-10 on ≥3 structure pairs (an LGPS-derived
      cell from examples/structures with perturbations, and a slab + molecule cell).
      The production D uses the ordered keys/weights above and is not expected to equal
      ASE's unordered D. Import ase.ga.ofp_comparator only inside the test module, never
      in mliport/ (the production fingerprint must not import scipy or matplotlib). The
      test must not skip in CI.
  • Any later change to binning, smearing, normalization or keys bumps the confsearch
    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) or D(m, u) ≤ cs_dedup_fp_tol ).

  • G — direct geometric identity. G is true iff F is non-empty and
    max_{i∈A} |r_i^m − r_i^u|_MIC ≤ cs_dedup_geom_tol (default 0.20 Å), atom by atom with
    the 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.
  • D — fingerprint (§9.2). Needed for what G cannot see: symmetry-equivalent sites and
    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 new
unique minimum. Shortcut: |ΔE| > 0.2 eV ⇒ no match without computing G or D.

cs_dedup_fp_tol and cs_fp_sigma defaults come out of the P1 calibration (§13.2); post
the 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 = valid unique minima (plus reacted with policy include). Sort by refined
energy where refined (§10.3), otherwise quench energy. Report E, ΔE to 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)

  • Discovery curve (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.
  • For the best minimum: hit count, distinct replicas, first-found fraction of the search.
  • new_low_minima_last_quarter: unique valid minima within 0.2 eV of the final best first
    found in the last 25 % of quenches.
  • best_repeatedly_found = (hits ≥ 3 and replicas ≥ 2).
  • Wording in outputs/docs: "lowest found", never "global minimum".

10.3 Refinement of top-K

Take the cs_top_k (default 10) lowest rankable unique minima within cs_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 a
warning 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 = false skips 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 dynamics F F F for F via the existing
    writer; verify the writer does this);
  • structure.extxyz (with cell, PBC, energy, status, id);
  • cp2k_coord.xyz (plain xyz), cp2k_cell.inc (A, B, C lines in Å) and
    cp2k_fixed_atoms.inc (LIST with 1-based indices, ranges compressed as a..b;
    verify the syntax against the CP2K manual for &MOTION/&CONSTRAINT/&FIXED_ATOMS and
    cite 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

RUN/
  resolved_config.json
  run.log
  run_context.json        identity: model record (+dispersion), input hashes, seeds,
                          regions A/S/F, budgets, gradient_preflight, scientific revision
  search_results.json     schema "mliport.confsearch-results/1": status, ranking,
                          diagnostics, baseline, warnings
  artifacts.json          manifest of files, formats, sizes, units
  starts/                 start_XXX.extxyz + POSCAR + placement.json (mode B)
  raw/replica_RRR/cycle_CCC/   trajectory.traj, md.csv, cycle.json (status, steps, temps)
  minima/all_minima.extxyz     every quench result incl. rejected, with info fields
  minima/registry.json         unique minima per status class
  diagnostics/discovery.csv
  top/rank_NNN/...             §10.5
  checkpoints/                 see 11.2

Reuse the existing output-directory claim/lock and overwrite rules; resume and
extend take the same run-directory lock. Units as in the rest of mliport (eV, Å, fs, K).

  • resolved_config.json is written for every new run, like the other workflows.
  • run.log is a live, append-only log (the existing LiveRunLogger): it exists from
    the first line, survives a crash, and a resume/extend appends to it.
  • run_context.json is created once; later resumes/extensions update it (append
    to resumes[] / extensions[], set finished_at) and never rebuild it from scratch.
  • minima/all_minima.extxyz holds the geometry of every quench result (all
    statuses), so rejected and reacted structures can be inspected; minima/registry.json
    holds the registry.

11.2 Checkpoint and resume

  • After the start-quench stage and after every (replica, cycle) unit: atomic JSON
    checkpoint (reuse atomic_write_json, canonical_fingerprint from mliport.neb.io)
    with: unit index, per-replica state (current minimum id + geometry, status, counters),
    all RNG states, registry, discovery rows, cumulative MD time.
  • Resume fingerprint (like NEB): mliport version, 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 identity (used here and in §11.4) = model_type, model_sha256, backend_version, framework_versions, task, head_effective, dtype_effective, inference_mode, compile_enabled, direct_forces and, from dispersion, only
    method, xc, damping, implementation, version. It excludes where the model ran or was
    stored (actual_device_*, backend_reported_device, model_path, model_alias,
    model_source, dispersion.device): resuming on another GPU or with a moved
    checkpoint of identical content is the same calculation. Devices are still recorded in
    run_context.json.
  • Resuming re-runs the interrupted unit from its checkpointed RNG state. Raw files of the
    interrupted attempt are moved to raw/.../incomplete_attempt_N/ (never deleted;
    AGENTS.md rule 11).

11.3 Extend

extend RUN --cycles N adds 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 except
cs_cycles. Refinement, ranking and exports are recomputed; previous top-level results
are archived under history/extension_N/.

11.4 Merge

merge RUN1 RUN2 … --output DIR combines completed searches without new calculations if
their 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

mliport confsearch run   [STARTS...] --adsorbate-indices SPEC | --slab S --molecule M --n-starts N
                         --model ... --model-type ... --task ... --output DIR [options]
mliport confsearch place --slab S --molecule M --n-starts N --output DIR [--seed]
                         (placement only, no model: writes starts/ for inspection)
mliport confsearch run   ... --dry-run   (validate inputs, regions, budget; no model)
mliport confsearch resume RUN
mliport confsearch extend RUN --cycles N
mliport confsearch merge RUN1 RUN2 ... --output DIR
mliport confsearch export RUN [--top-k K] [--window E]   (re-export from results)

A new run requires an explicit --output. Exit codes via the existing run_status
mapping: 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 the
search_results.json content as a dict. Place it beside run_neb and follow its
resolution path (_api_resolve_full).

12.3 Configuration keys

Add "confsearch" to calc_type choices, CalculationEngine.VALID_CALC_TYPES,
IncarConfig.validate(), DEFAULT_DEVICE_BY_CALC_TYPE, BUILTIN_DEFAULTS (scope
confsearch), 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 confsearch scope added: timestep, friction, seed,
fmax_abort, charge, spin. Seed auto-generation must apply to confsearch as it does
to MD. New keys (canonical name / INCAR alias uppercase):

Key Type Default Bounds / choices
cs_mode str adsorbate {adsorbate}
cs_starts path — file or directory (mode A; CLI positional)
cs_adsorbate_indices str — required in mode A
cs_slab, cs_molecule path — mode B
cs_n_starts int — (required in B) ≥1
cs_fix_below float Å unset >0
cs_md_mobile str adsorbate {adsorbate,adsorbate_and_top,all_free}
cs_top_depth float Å 2.0 >0
cs_temperature_high float K 500 >0
cs_temperature_low float K 300 >0, ≤ high
cs_hold_ps, cs_cool_ps float 2.0, 2.0 >0
cs_snapshot_interval_ps float 0.5 ≥0, < hold
cs_ramp_interval int steps 10 ≥1
cs_cycles int 5 ≥0 (0 = start-quench baseline only)
cs_save_interval int steps 100 ≥1
cs_accept_temperature float K 500 >0
cs_quench_fmax, cs_quench_steps float, int 0.05, 2000 >0, ≥1
cs_bond_scale, cs_bond_break_scale float 1.2, 1.5 >1; break > bond
cs_ionic_species str Li,Na,K,Rb,Cs,Mg,Ca element symbols
cs_reaction_policy str exclude {exclude,include}
cs_desorption_distance float Å 5.0 >0
cs_min_image_distance float Å 4.0 >0
cs_min_vacuum_gap float Å 8.0 >0
cs_place_contact_scale float 1.5 > cs_bond_scale
cs_place_anchor str unset 0-based indices within the molecule file; mode B only
cs_place_anchor_scale float 1.1 >0, ≤ cs_bond_scale
cs_place_other_min_scale float 1.3 > cs_bond_scale
cs_place_anchor_targets str unset element symbols present in the slab
cs_place_max_attempts int 1000 ≥1
cs_dedup_energy_tol float eV 0.010 >0
cs_dedup_fp_tol float from §13.2 calibration >0, <1
cs_dedup_geom_tol float Å 0.20 >0
cs_fp_rcut, cs_fp_binwidth, cs_fp_sigma float Å 8.0, 0.02, from §13.2 (candidates 0.05/0.10/0.20) >0; binwidth ≤ σ/2
cs_top_k, cs_export_window int, float eV 10, 0.5 ≥1, >0
cs_refine, cs_refine_fmax, cs_refine_steps bool, float, int true, 0.02, 3000
cs_allow_direct_forces bool false

Cross-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) to validation/science/capability_matrix.json
with honest no/partial + note until each interface supports them (e.g. TUI no
until P5; INCAR no for resume/extend/merge, which are commands).


13. Tests and validation

13.1 Synthetic calculators (CI, CPU, deterministic)

Provide test-only calculators, no backend imports:

  • Egg-crate slab model: a rigid periodic "slab" plus a small "adsorbate" (e.g. a
    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.
  • Bond-breaking model: a Morse-bonded molecule with a shallow well so that hot MD
    breaks a bond reproducibly with a fixed seed (tests md_integrity_abort, reacted).
  • Direct-force mock: reports direct_forces=True (tests the gate).

13.2 Required tests (non-exhaustive minimum)

  • Input validation: every fail-closed rule in §5.3, §6, §12.3 has a test.
  • Placement: deterministic with seed; rotation uniformity (statistical test on random
    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 q equals cs_place_anchor_scale, every other pair
    q ≥ cs_place_other_min_scale, targets respected, orientation distribution uniform
    under the condition (compare against brute-force rejection on 10⁴ samples);
    image/vacuum rejection works; max-attempt failure reports per-reason counts.
  • Classification: an adsorbate–slab bond with intact graphs is valid + chemisorbed;
    a broken skeleton bond is reacted.
  • Regions: M per mode; fixed atoms never move during MD or quench; MB initialization
    gives zero momenta to fixed atoms and the exact target temperature over free DOF.
  • Temperature ramp: target temperature sequence equals the linear schedule at update
    steps.
  • Fingerprint invariances and discrimination (§9.2), OFP known-answer when available.
  • Calibration of cs_fp_sigma and cs_dedup_fp_tol (revision 4 procedure) on the
    egg-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:
    1. Pair classes, labelled by geometry, not by construction:
      (a) same: re-quenches of a minimum from perturbations of 0.02–0.1 Å whose result is
      within cs_dedup_geom_tol of the original; perturbations that land > 0.5 Å away are
      a 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.
    2. Sweep cs_fp_sigma ∈ {0.05, 0.10, 0.20} Å (binwidth 0.02 Å, rcut 8 Å).
    3. For each σ: D_tol(σ) = 0.5 · min D over (b ∪ c) pairs with |ΔE| ≤ cs_dedup_energy_tol (if there are none, over all (b ∪ c) pairs). This gives zero
      false merges with a factor-2 margin. Report the fraction of (d) pairs merged and of
      (a) pairs merged by G, by D, or split.
    4. Default σ = the one maximizing the (d) merge fraction; ties → larger σ.
    5. If (d) cannot be fully merged at any σ, keep the zero-false-merge tolerance anyway,
      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).
    6. Post the table (σ, min/max of each class's D and ΔE, chosen D_tol, merge/split
      rates) here.
  • Dedup: G and D paths each tested; G disabled when F is empty; matching, representative
    update, consolidation, no cross-status merging; the calibration set yields zero false
    merges with the shipped defaults (kept as a regression test).
  • Metropolis: acceptance decisions for a fixed RNG reproduce a hand-computed sequence;
    RNG stream alignment when proposals are ineligible.
  • End-to-end on the egg-crate model: finds all known minima with correct energies (to
    1e-6 eV) and hit counts; baseline vs search reported; exports re-read equal (up to
    lattice translations).
  • Resume equivalence: interrupt after each possible unit (start stage, mid-search), resume,
    compare search_results.json, registry and raw files to an uninterrupted run (bitwise
    on CPU).
  • Extend and merge: fingerprint checks, merged ranking equals a single run over the union
    when sources are compatible; refusal when not.
  • Abort paths: force abort, non-finite, integrity abort, quench not converged; the search
    continues and statuses are correct.
  • MDRunner and 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)

  • P0 — shared helpers, zero behaviour change. Extract from MDRunner the
    stateless 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 unchanged
    and green; add pinning tests. DATA IMPACT: none.
  • P1 — core library, no calculator. mliport/confsearch/: options dataclass with
    validation (like NEBOptions), index-spec parser, regions, covalent graphs and status
    rules, fingerprint + registry + consolidation, placement. Fingerprint calibration
    posted here.
  • P2 — search engine. Cycles, MD segments, quench, Metropolis, RNG streams, raw
    output, checkpoint/resume, refinement, ranking, diagnostics, exports; synthetic-model
    end-to-end tests.
  • P3 — integration. Schema/defaults/resolver/INCAR/engine/CLI (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.
  • P4 — extend, merge, queue. extend and merge commands; queue task support for
    unattended runs.
  • P5 — TUI and validation campaign. TUI entry; validation script and report.

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)

  • Model domain: foundation models trained on inorganic bulk (e.g. OMat) may describe an
    organic adsorbate on a sulfide surface poorly; high temperatures amplify this. A high
    reacted fraction is a symptom. Always re-rank exports with DFT.
  • Dispersion decides lying-flat vs standing alkyl chains; use D3 when the model's
    reference lacks it.
  • Freezing the slab during MD biases exploration toward the initial surface structure;
    adsorbate_and_top relaxes this at the cost of noisier energies (watch
    far_field_slab_changed).
  • Fixed cell: the slab's in-plane lattice must already be the relaxed bulk lattice of the
    same model; the tool does not check this.
  • Finite search: "lowest found" with saturation evidence, not a proof of a global minimum.
  • Chemisorption bonds formed by an MLIP on a surface it was not trained on are the least
    trustworthy part of the result; DFT must confirm every chemisorbed candidate.
  • Short-range MLIPs have no long-range electrostatics; DFT of one-sided slabs needs a
    dipole correction.

16. Decision log

Rev Decision By
1 v1 scope: single adsorbate on a slab owner
1 Fixed cell throughout; no NPT; no variable-cell refinement for slabs owner (fixed cell + optional post-processing chosen; post-processing is fixed-cell for slabs by physics)
1 Starts: user-prepared and automatic placement, combinable owner
1 Molecules whose covalent skeleton changed are excluded from ranking by default; include only to study surface chemistry on purpose; ionic rearrangement is not a reaction owner
1 Algorithm, defaults, dedup and outputs as specified above spec author
6 Second review: in-window unrefined candidates are exported and warned about; merge key adds fixed-atom positions spec author
5 Review of PRs #62–#67: anchor partner = non-ionic slab atoms; model identity excludes device/path; merge key adds atomic numbers, cell, PBC, charge/spin; live append-only run.log, updated (not rebuilt) run_context, resolved_config.json, all_minima.extxyz spec author
4 Dedup tuned for zero false merges; geometric identity G added (fixed slab + fixed atom order); σ and D tolerance from a labelled calibration sweep; no tolerance inside the D overlap spec author (owner delegated algorithms)
3 Fingerprint uses ASE OFP discretization exactly (bins (k+1)Δ, erf smearing of binned pairs, ordered keys for A-centred use); strict ASE known-answer test; earlier formula withdrawn as inconsistent owner (option B) / spec author
2 Chemisorption first: adsorbate–slab covalent bonds with intact skeletons are valid (chemisorbed), not reacted; placement distances use covalent-radii scales; optional anchored placement starts already bonded owner (request) / spec author (values)

17. Open questions (answer in comments; folded in as new revisions)

  1. Which model/task will the first real use (LiDS@LPSC) use? This affects the docs'
    worked example, not the code.
  2. Placement scales (1.5 contact, 1.1 anchor, 1.3 others) are first guesses; revisit
    after the first real run (GPU currently busy). For LiDS the natural anchors are the
    sulfate O atoms.

Spec revision log

  • 1 (2026-10-24) — initial specification.
  • 6.1 (2026-10-26) — status: P0–P5 merged to 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.
  • 6 (2026-10-25) — §10.3 export of candidates whose refinement failed; §11.4 merge key
    includes fixed-atom positions.
  • 5 (2026-10-25) — clarifications found in the P0–P5 review: §5.2 anchor partner set;
    §11.1 run.log/run_context/resolved_config/minima files; §11.2 model-identity key list;
    §11.4 merge key.
  • 4 (2026-10-24) — §9.3 matching = ΔE ∧ (G ∨ D); new 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.
  • 3 (2026-10-24) — §9.2 rewritten: ASE OFP discretization, strict known-answer test
    (per-bin arrays and D to 1e-10). The revision-1/2 formula had an extra 1/Δ and a
    different binning. cs_dedup_fp_tol calibration must use this implementation.
  • 2 (2026-10-24) — chemisorption-first: §5.2 placement by covalent-radii scales with
    optional anchored placement; §8.2/§8.3 adsorbate–slab bonds are chemisorbed, not
    reacted; keys and tests updated; open question 2 reworded.

https://claude.ai/code/session_017vVRW3uEnhYKFinpvqMysi


Generated by Claude Code

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
@hydrogen1222

hydrogen1222 commented Oct 25, 2026 •

Copy link
Copy Markdown
Owner Author

§13.2 fingerprint calibration (spec revision 4) — P1 evidence

Tracking: #61. This is the calibration required by §9.3/§13.2 revision 4 before P2 may start. It is reproducible from the repository: tests/mliport/mliport/confsearch/test_fingerprint_calibration.py prints and asserts this table (CPU only, no backend).

Pair classes (geometry-labelled, on the repository's LGPS structure examples/structures/li10gep2s12_primitive.vasp with a CH3OH-like adsorbate; binwidth 0.02 Å, rcut 8 Å, 25 same-basin / 63 distinct / 4 equivalent pairs):

class definition measured
(a) same basin perturbation ≤ cs_dedup_geom_tol (0.20 Å) 25 pairs; 11 further perturbations land in 0.20–0.50 Å (documented splits, reported below)
(b) different sites adsorbate above each of the 24 S atoms, two heights part of the 63 distinct pairs
(c) different conformers O–H torsions + rigid rotations part of the 63 distinct pairs
(d) equivalent rigid slab symmetry map of the whole structure, and CH3/permutation-equivalent conformers 4 pairs, all D ≈ 0

σ sweep (D_tol(σ) = 0.5 · min D over (b ∪ c), i.e. zero false merges with a factor-2 margin):

σ (Å) min D (b ∪ c) max D (b ∪ c) D_tol = 0.5·min (d) merged
0.05 0.00145 0.10447 0.00072 100 %
0.10 0.00139 0.12051 0.00069 100 %
0.20 0.00085 0.31072 0.00043 100 %

Tie-break per §13.2 step 4 (maximise the (d) merge fraction, then larger σ) selects σ = 0.20. Shipped defaults: cs_fp_sigma = 0.20, cs_dedup_fp_tol = 0.0004 (≤ 0.5 · 0.00085, so zero false merges with margin), cs_dedup_geom_tol = 0.20 Å.

ΔE: this P1 calibration has no calculator, so the |ΔE| ≤ cs_dedup_energy_tol filter could not be applied and the fallback of §13.2 step 3 ("if there are none, over all (b ∪ c) pairs") was used for every pair.

Real-quench variant of class (a) (egg-crate model, quenched at the production cs_quench_fmax = 0.05 eV/Å, added with the P2 engine): 12 of 15 re-quenches land inside cs_dedup_geom_tol = 0.20 Å and are merged by G; the maximum residual is 0.212 Å, so 3 pairs become documented duplicates (false splits) and none leaves the basin. Per §13.2 step 5 the tolerance is not widened into the overlap: false splits only cost a DFT job, false merges would delete a candidate.

Split/merge rates with the shipped defaults: (d) 4/4 merged by D; (a) 25/25 merged by G plus 11/36 documented splits; (b ∪ c) 0 false merges by construction (D_tol = half the smallest distinct distance).

Real-slab recalibration (P5): the same campaign that runs the workflow
validation (validation/science/scripts/confsearch_suite.py) now re-measures
this table on the campaign's own minima — pairwise D/|dE| split by G, the
implied zero-false-merge tolerance from the distinct pairs, and whether the
shipped tolerance would have merged a distinct pair. The bulk-cell limitations
above are also stated in docs/workflows/confsearch.md ("Calibration limits").

Known limitation: D is a radial descriptor, so the "same basin" and "different site" distributions overlap for laterally similar sites; G (fixed slab + fixed atom order) carries the same-basin merging, and cs_dedup_energy_tol = 0.010 eV remains the primary discriminator. This is the §9.3 revision 4 decision, not an oversight.

hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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).
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
… §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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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).
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…P4 part 1)

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

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

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

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

DATA IMPACT: no scientific record invalidated. New outputs and commands only.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
… key (spec rev 5 §11.3/§11.4)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DATA IMPACT: no scientific record invalidated. Test-only change.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
… §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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…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).
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
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.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…P4 part 1)

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

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

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

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

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

Copy link
Copy Markdown
Owner Author

交付报告 · 模型支持扩展(spec Rev 2)· 2026-11-14

按 #61 模型支持规格 Rev 2 §6 的顺序完成。下面按规格要求的四项汇报;详细逐模型证据在
#75 评论。

1. 基线与交付物

  • 基线: main@ec28ba3f39fe9aa865e99aebf9c4c2452c72e256。
  • 实现 PR(均为 Draft,回链本条):
    # 分支 规格条款
    docs(registry): correct model licenses and publish the support table #94 docs/registry-corrections §6.1 许可证更正、五个后端、模型支持状态表骨架
    feat(validation): make the callable check usable on CPU and on any structure #95 feat/runtime-probe-cpu-gpu §6.2 validate_runtime.py 支持 CPU/任意结构
    fix(mace): fail closed on checkpoints that are not potential-energy models #96 fix/mace-model-class-gate §6.3 MACE 非能量模型 fail closed
    feat(uma): move to fairchem-core 2.25.0 and keep Nitro out of reach #97 feat/uma-runtime-upgrade §6.4 fairchem-core 2.25.0 / torch 2.13.0,Nitro 不暴露
    fix(dpa): accept a lossless dtype widening when loading a checkpoint #98 fix/dpa-lossless-dtype-widening §5 发现的适配器缺陷(small fix PR)
    docs(models): record the measured model-support status #99 docs/model-support-status §6.5 用实测结果更新状态表(stacked)
  • 路径与算法变化:
    • mliport/mliport/install/compatibility.py:UMA → fairchem-core 2.25.0 / torch 2.13.0;
      FRAMEWORK_PYTHON 增 torch 2.13.0;_torch_modern_cuda 增 2.13.0 → cu130(Volta 仍 cu126)。
    • mliport/mliport/calculators/uma.py:INFERENCE_PRESETS = {default: batch, turbo: multigpu},
      拒绝任何启用 nitro 的预设;info() 增加 inference_preset/tf32_enabled/nitro_enabled。
    • mliport/mliport/calculators/mace_calc.py:unsupported_mace_model_reason()(MDP / POLAR / OMOL 判别)。
    • mliport/mliport/calculators/dpa_calc.py:tensor_load_verdict(),仅接受严格加宽的 dtype。
    • mliport/mliport/model_record.py:记录 inference_preset/nitro_enabled/tf32_enabled。
    • scripts/validate_runtime.py:--device/--structure/--task、证据编号按设备类型、
      DPA/GRACE 进程隔离预检、NEB 端点 relax、report schema /2。
    • validation/science/model_manifest.json:三个许可证更正。
    • 文档:docs/models*.md、docs/index*.md、docs/validation*.md、docs/backends/{mace,uma,dpa}*.md、
      docs/installation*.md(生成)、CHANGELOG.md。
  • 配置接口: 无新增用户可见选项;--inference-mode 仍为 default|turbo,但语义固定为
    “上游 batch / 上游 multigpu”,且记录实际生效预设。

模型支持表(摘要)

结论 模型
CPU + GPU verified(15 个 profile) mace_omat、mace_omat_float32、mace_matpes_r2scan、mace_mh1_omat_pbe、mace_mh1_matpes_r2scan、grace_omat、grace_omat_fp64、grace_3l_omat_large_ft_am、grace_2l_smax_omat_large、dpa_omat、dpa31_sse_pbe、dpa31_sse_pbesol、dpa4_neo_omat、dpa4_air_omat、dpa4_plus_omat
untested(运行时已就绪,无法取权重) uma_omat、uma_s_1p2p1_omat、uma_s_1p2p1_ft_r2scan_omat
不变 nep89_gpumd(GPU verified / CPU unsupported)、uma_s_1pt(两端 unsupported)

2. 测试汇总

  • 核心测试(集成分支):2116 passed, 48 skipped(基线 2077 passed);ruff check/ruff format --check 全绿。
  • 真实运行(V100,driver 580.173.02):
    • mliport doctor 单点:15 个模型 × {cpu, cuda:0},LGPS 50 原子晶胞,全部通过,stress_checked=True。
    • scripts/validate_runtime.py --full:15 个模型 × {cpu, cuda:0} = 30 次,
      单点/共享计算器/中心差分力/10 步 NVE/5 image NEB 全部 passed。
    • CPU–GPU 一致性:50 原子晶胞上 |ΔE|/atom ≤ 6.1e-07 eV、max|ΔF| ≤ 7.5e-06 eV/Å;
      float64 模型 ~1e-15。均在规格阈值内,未触发 flag。
  • 版本:mace-torch 0.3.16/torch 2.8.0+cu126;deepmd-kit 3.2.1.dev63+g0edeaef56/torch 2.11.0+cu126;
    tensorpotential 0.6.0/TF 2.20.0;fairchem-core 2.25.0/torch 2.13.0+cu126;mliport 2.0.0b4。
  • 未运行(not_run):UMA 任何计算(facebook/UMA 需授权,本机无 token,HTTP 401);
    NEP89 CPU(上游格式限制);NEB 鞍点验证(saddle_validation: not_performed)。

3. 数值 known-answer 与设备覆盖

  • 覆盖:SP(全部 15 个,CPU+GPU)、共享计算器、中心差分力(≤32 原子 Cu 夹具)、10 步 NVE、
    5 image NEB(固定晶胞、端点 relax)。
  • 相对/绝对一致性见上表;MACE float64 的 CPU–GPU 差异在 1e-14 量级,float32/model-defined
    在 1e-8–6e-7 eV/atom 量级。
  • 明确没有做的事:精度评估、benchmark、长 MD、变胞、DFT 复核。

4. 新发现的问题与影响

  1. DPA-3.1 在 pinned DPA4 运行时上无法加载(atomic_model.out_bias dtype 加宽被判为
    “tensor changed”)。→ fix(dpa): accept a lossless dtype widening when loading a checkpoint #98 修复:只接受严格加宽且数值逐位相同,并写入 migrations;
    仍拒绝降精度/改形状/改数值。
  2. fairchem 2.22+ 把 Nitro 变成上游默认、删除 turbo,直接升级会让 mliport 的 default
    悄悄降精度并在 Ampere+ 上选中 Nitro。→ feat(uma): move to fairchem-core 2.25.0 and keep Nitro out of reach #97 显式映射到上游 batch/multigpu 并拒绝 nitro,
    同时把生效预设写进身份记录。
  3. 检查工具自身的缺陷:GRACE 在 CPU 上被传入 GPU 专用选项;DPA/GRACE 需要
    CUDA_VISIBLE_DEVICES 进程隔离;NEB 端点未收敛导致检查自身失败。→ feat(validation): make the callable check usable on CPU and on any structure #95 修复。
  4. 既有风险(未扩大):scripts/validate_runtime.py 在 main 上完全不可用(导入失效),
    说明此前没有 CI 覆盖该脚本;现已加测试。架构审计快照
    (validation/compatibility/gpu_architecture_theory.json,2026-09-14)仍记录 DPA torch 2.10
    与 UMA torch 2.8 的二进制证据,早于本轮 DPA 2.11 与 UMA 2.13 变更,需要单独的审计 PR 刷新。
    docs/models.md 中 UMA 行保持 untested 是本轮证据如实反映,不是遗漏。

DATA IMPACT: 不使任何既有科学记录失效。没有重写已存证据、阈值或历史报告;
fairchem 2.21.0 上的旧 UMA 结果保留并注明只对那套运行时有效。

未验证项(明确保留): UMA 的 3 个 profile(无权重)、UMA Nitro(不暴露)、DPA4C .pt2、
DPA-SSE、GRACE 不确定度、MACE-POLAR/MDP/OMOL 物理(一律拒绝)、NEP89 CPU、50 原子结构上的
FD/MD/NEB(探针 32 原子上限,该结构只做单点)、NEB 是否真正鞍点。

hydrogen1222 added a commit that referenced this pull request Nov 14, 2026
… 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.
hydrogen1222 added a commit that referenced this pull request Nov 14, 2026
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.
hydrogen1222 added a commit that referenced this pull request Nov 14, 2026
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`.
hydrogen1222 added a commit that referenced this pull request Nov 14, 2026
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.
hydrogen1222 added a commit that referenced this pull request Nov 14, 2026
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.
hydrogen1222 added a commit that referenced this pull request Nov 14, 2026
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.
@hydrogen1222

Copy link
Copy Markdown
Owner Author

§11 执行报告 · 2026-11-14

按 Rev 3 §11 的任务顺序执行。逐模型证据在新的 #75 评论里:UMA 记录
6878717708,
完整 CPU–GPU 差值表 6878720684,
前一轮 MACE/DPA/GRACE 记录 6877006841。

1. UMA 可调用性检查(#97 运行时)

Profile 文件 SHA-256 task list CPU GPU 身份记录
uma_s_1p2p1_omat b2673b85…d5ce omat 通过(LGPS 单点、--full 探针全过) 通过 inference_preset: batch、nitro_enabled: false、tf32_enabled: false
uma_s_1p2p1_ft_r2scan_omat c2fdf4f2…bbab omat 单点/力/10 步 NVE 通过;NEB 被梯度预检拒绝 同左 同上
uma_omat 45893aa3…42642 无法读取 失败(文件损坏) 失败(文件损坏) —
  • LGPS 上的 CPU–GPU 差值:uma_s_1p2p1_omat 1.03e-08 eV/atom、3.40e-06 eV/Å;
    uma_s_1p2p1_ft_r2scan_omat 4.57e-08 eV/atom、4.11e-06 eV/Å。
  • --inference-mode turbo(GPU 单点):inference_preset: multigpu、nitro_enabled: false、
    tf32_enabled: true、compile_enabled: true。
  • uma-s-1p2.pt 本机文件损坏(不是 mliport 缺陷):
    PytorchStreamReader failed reading file data/115: invalid header or archive is corrupted;
    zipfile.testzip() 报 inference_ckpt_stage2/data/114 CRC 不符。文件大小与上游一致
    (2333393167 字节),说明是传输损坏;facebook/UMA 是 gated 仓库,本机 HTTP 401 无法重下。
    按 §1 rule 9 记录并停止,不做任何 reshape/改名/重新导出。请用有权限的账号重下后我再补跑。
  • uma_s_1p2p1_ft_r2scan_omat 的 NEB 拒绝是正确的 fail-closed:
    NEBGradientConsistencyError: ... an energy resolution too coarse to discriminate the derivative (noise allowance 1.62 eV/A)。r²SCAN 总能量约 -1.8e5 eV(Cu 4 原子夹具),float32 下
    1e-3 Å 位移的能量差落在噪声里。单点/力/MD 正常,NEB 对该模型+精度标记为 unsupported。

2. #96 门控加固

  • calculator.models 缺失、为空或不是 list 时不再静默跳过,直接报错并清空缓存(新测试覆盖
    4 种情况)。
  • 属性型判别(atomic_multipoles_max_l/charges_irreps、joint_embedding)只对真正的
    torch.nn.Module 生效,embedding_specs 必须是字典;否则会回答任意属性的 mock/代理会被
    误判成 POLAR/OMOL 而拒绝合法模型。
  • CI: 13 pass。

3. #94 去掉 uma-s-1.pt 行

  • 状态表里已删除该行;文末用文字说明:上游归档版本、有已知广延性缺陷、未检查、不推荐,
    并解释为什么 unsupported 是错的词(unsupported 表示 mliport 会拒绝,而没有任何东西拒绝它)。
  • CI: 13 pass。

4. #97 驱动要求文档

  • docs/installation.md(+zh) 与 docs/backends/uma.md(+zh):Turing 及以上的 cu130 wheel
    需要 NVIDIA 驱动 ≥ 580;Volta 继续 cu126,老驱动可用;CUDA 13 构建对 Turing 以下没有意义。
  • 与最新 main 合并、保留两段 changelog、CI 绿后已标记 ready for review。

5. #99 状态表

状态

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 原子上限);无任何精度结论。

hydrogen1222 added a commit that referenced this pull request Nov 14, 2026
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.
hydrogen1222 added a commit that referenced this pull request Nov 14, 2026
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.
@hydrogen1222

Copy link
Copy Markdown
Owner Author

补跑:uma_omat(重新上传的 uma-s-1p2.pt)· 2026-11-14

模型文件

项目 值
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)。

状态变化

全局状态

PR 状态
#94 / #96 / #97 已合并进 main
#99 rebase 完成,CI 绿,待 review

DATA IMPACT: 不使任何既有记录失效;此前“文件损坏、not_run”的记录作为历史保留在 #75。

残余缺口(不变): UMA Nitro 永不执行(设计如此);探针 NEB 未做鞍点验证;LGPS 只做单点;
无任何精度结论。

hydrogen1222 commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner Author

DPA-SSE 支持 · 开发规格(Rev 2 · 2026-11-15)

Normative spec, kept as a comment on #61 and linked from the #61 description. Implementation
PRs go against main, open as Draft, say Tracking: #61 (DPA-SSE spec) with a link to this
comment, and wait for review. Evidence goes to #75. Revisions edit this comment in place.
All rules of the model-support spec §1 apply (no weights or run outputs in git; read facts
from the artifact; never change units/PBC/head/dtype silently; record failures verbatim).

0. 需求摘要(给人看)

  • 目标: 让 DPA-SSE(SSE-VASP-dpa2.pt,来自 AIS Square)在 mliport 里 CPU 和 V100 都能正确调用,而且算出来的结果和它原本对应的 deepmd 版本一致。
  • 现在的问题: 它是 DPA-2 架构的老检查点。fix(dpa): convert trusted NumPy-scalar training checkpoints to safe inference .pt #91 已经解决了元数据里 NumPy 标量的问题,但当前固定的 deepmd 3.2.1 读它时网络参数形状对不上。
  • 绝不做: 手工改形状、改名、补缺失参数或重新初始化权重来“让它加载”。
  • 做法: 先找出能原样加载它的旧版 deepmd,用旧版算一组参考值。然后二选一,按下面的顺序:
    1. 上游自带的转换: 用旧版 deepmd 自己的导出功能(freeze / convert-backend)转成新版能读的格式,在当前环境加载,结果和参考值一致才算通过。不用多维护一个环境。
    2. 旧版运行环境: 转换结果对不上,就给 DPA-SSE 单独建一个旧版 deepmd 环境,运行时显式选择,做法类似 NEP_RUNTIME。
  • 适用范围: DPA-SSE 只用硫化物电解质训练,泛函是 VASP PBEsol。论文列出的元素里没有 C 和 H,不适合 LiDS 这类有机分子吸附。它适合 LGPS、LPSC、掺杂 Li₂S 这类体相硫化物。

1. Facts to start from (verify each before relying on it)

Fact Source
DPA-SSE uses the DPA-2 framework; repinit cutoff 9.0 Å, 12 repformer layers, 4 attention heads, fitting net 3 × 240. arXiv 2406.18263
Training set: sulfide electrolytes (LGPS-like and argyrodites), "15 elements"; compositions named contain Li, S, P, Ge, Sn, Si, Ga, Sb, As, Cl, Br, I. Labels: VASP PAW, PBEsol, 600 eV, KSPACING 0.3. same
Models and data are published on AIS Square (Solid_State_Electrolyte). same
On main, scripts/convert_dpa_checkpoint.py (#91) turns the training checkpoint into a weights_only=True-loadable .pt without changing tensors; the converted file still fails on the pinned deepmd 3.2.1 because the current network layout differs. CHANGELOG.md, docs/backends/dpa.md
dp convert-backend INPUT OUTPUT converts between backends; its docs show .pb → .pth and .pb → .dp. Whether it accepts a training .pt and whether newer releases deserialize older DPA-2 serializations is not documented: find out by trying. DeePMD-kit CLI

2. Work, in order

2.1 dpa-sse-provenance — investigation, no product code

Report everything below as one #61 reply before writing product code.

  1. SHA-256 of the original file and of the fix(dpa): convert trusted NumPy-scalar training checkpoints to safe inference .pt #91-converted file; the AIS Square source URL and
    the license shown there; model_params (descriptor type and sizes, type_map, rcut,
    precision) read from the checkpoint.
  2. The exact failure on the pinned runtime: missing/unexpected keys and shape mismatches,
    verbatim.
  3. Find the original runtime: the released deepmd-kit version (try 3.0.0 pre-releases and
    3.0.x first; the DPA-2 Zenodo deepmd-pytorch-devel snapshot only if no release works) that
    loads the checkpoint with no missing or unexpected keys, no shape change and no warnings
    about skipped parameters. Use throwaway venvs, CPU only. Record the deepmd-kit, torch and
    Python versions.
  4. Reference values in that runtime, float64, CPU: energy, forces and virial for
    examples/structures/li10gep2s12_primitive.vasp and two more repository structures that
    contain only elements from §1's training list (record their SHA-256). Store them in the
    [DEV P0 AUDIT · DO NOT MERGE/CLOSE] Living correctness and real-hardware test ledger · master #61 #75 evidence comment, not in git.

Stop and report if step 3 finds no release that loads the file unmodified.

2.2 Route choice (automatic, by evidence)

Conversion route, tried first. In the original runtime, export the model with deepmd's
own tools (dp --pt freeze to .pth, or dp convert-backend to .dp and then to .pth in
the pinned runtime). Load the result through mliport's DPA adapter on the pinned runtime and
compare with the references. It passes only if, on every reference structure, on CPU and on
GPU: |ΔE| ≤ 1e-6 eV/atom, max |ΔF| ≤ 1e-5 eV/Å, max |Δvirial| ≤ 1e-5 eV.

If it passes, implement it as a documented, reproducible conversion:

  • Extend scripts/convert_dpa_checkpoint.py (do not add a second script) with a
    legacy-export step. It creates or reuses a throwaway environment pinned to the original
    runtime, runs the upstream export, and writes .conversion.json with the input and output
    SHA-256, both runtime versions, the export command and the reference deltas.
  • Keep the existing --i-trust-this-file gate.

Legacy runtime route, only if conversion fails the tolerance or cannot load.

  • Add an installer target dpa-legacy → .venv-dpa-legacy, pinned to the original
    deepmd-kit and a torch build with an sm_70 wheel (+cu126 or older), extending
    install/compatibility.py tables rather than bypassing them.
  • Select it explicitly with DPA_RUNTIME=legacy (default current), mirroring
    NEP_RUNTIME; never pick it from the file name or by trying both.
  • Record dpa_runtime, deepmd-kit and torch versions in the model identity and provenance.
  • Refuse any workflow or option the legacy runtime cannot honor (for example the DPA4/DPA4C
    paths), with a clear message.

Either way: no tensor reshaping, renaming, re-keying, cropping or initialization in mliport
code, and no patching of upstream.

2.3 dpa-sse-callable-check

The model-support spec §5 for label dpa_sse on cpu and cuda:0: mliport doctor
single point, scripts/validate_runtime.py --full, identity read-out, and CPU–GPU deltas.
Add the agreement with the §2.1 references. Use structures within the training elements;
the probe's built-in Cu cell is outside DPA-SSE's chemistry, so run the probe via
--structure on a small cell of training elements only (≤ 32 atoms, e.g. the Li₂S
conventional cell written with ASE; record its SHA-256, do not commit it).

2.4 dpa-sse-docs

5. Route decision and implementation requirements (Rev 2 · 2026-11-15)

Decision: legacy runtime route. Evidence (#61 report, #75 references): deepmd-kit
3.0.0b3 + torch 2.3.1 loads the original checkpoint with 226/226 tensors matched and no
missing, extra or reshaped tensors; both conversion attempts fail on 3.2.1 (frozen .pth:
unknown charge_spin argument; convert-backend: KeyError: 'g1_out_mlp'). The legacy
environment on V100 reproduces the CPU references (|ΔE|/atom ≤ 2.5e-11, max |ΔF| ≤ 4.9e-7,
max |Δvirial| ≤ 4.5e-7). No owner stop is needed; continue with §2.2's legacy bullets plus:

  1. Safe loading. At run time the legacy runtime loads the fix(dpa): convert trusted NumPy-scalar training checkpoints to safe inference .pt #91-converted file
    (weights_only=True), never the original training checkpoint, which needs unsafe
    unpickling. Prove that the converted file reproduces the original's references in the
    legacy runtime (expected bit-identical: tensors are identical). The original is only
    touched once, by the existing trust-gated converter.
  2. Pins. .venv-dpa-legacy: Python 3.12 at most (torch 2.3.1 has no newer wheels),
    torch==2.3.1+cu121 on GPU hosts (sm_70 included), deepmd-kit==3.0.0b3 exactly. The
    docs say this is an upstream pre-release, chosen because it is the release whose network
    layout matches the checkpoint.
  3. Selection. DPA_RUNTIME=legacy|current, default current. No automatic fallback in
    either direction. In legacy, refuse DPA-3.x, DPA4 and DPA4C models and any checkpoint
    that does not load with zero missing, extra or reshaped tensors, with a message that names
    the runtime to use instead.
  4. References with real forces. Add one rattled cell to the references (Li₂S
    conventional cell, Gaussian displacements σ = 0.05 Å, fixed seed; record the seed and
    SHA-256): the two perfect crystals have forces ~1e-13 and do not test the force path. Use
    this cell for the probe in §2.3.
  5. Tests. CPU tests with stubs for runtime selection, refusal paths and identity fields
    (dpa_runtime, deepmd-kit and torch versions). No weights in CI.

3. Non-goals

Fine-tuning, distillation, change-bias, other DPA-2 checkpoints, LAMMPS, accuracy
benchmarks, and adding DPA-SSE to the scientific validation manifest.

4. Checklist

Revision log

  • 2 (2026-11-15) — §5: legacy runtime route chosen by evidence; safe-loading, pins, selection, rattled reference cell and test requirements.
  • 1 (2026-11-14) — initial spec, at the owner's request to add DPA-SSE support.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GYQHUBfRm75zyaocAPWhEb


Generated by Claude Code

@hydrogen1222

Copy link
Copy Markdown
Owner Author

DPA-SSE §2.1 dpa-sse-provenance · 调查报告(2026-11-15)

按 DPA-SSE 规格 §2.1 执行,尚未写任何产品代码。参考值已存入 #75:
DPA-SSE reference values。

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。

@hydrogen1222

Copy link
Copy Markdown
Owner Author

DPA-SSE §5 执行完成 · 2026-11-15

按 Rev 2 §5 实现完毕,PR:#100 feat(dpa): add the DPA-2 legacy runtime for DPA-SSE(Draft)。

§5.1 安全加载

  • 旧运行时只加载 SSE-VASP-dpa2-inference.pt(fix(dpa): convert trusted NumPy-scalar training checkpoints to safe inference .pt #91 可信转换产物,sha256 8194e51f…50f4)。
    在 _require_safe_checkpoint() 里先用 torch.load(weights_only=True) 试一遍:原始训练检查点
    (带 NumPy 标量)会被拒绝,报错直接指向 scripts/convert_dpa_checkpoint.py。原因:3.0.0b3 跑在
    torch 2.3.1 上,torch.load 默认 weights_only=False,不拦就会反序列化任意对象。
  • 已证明转换文件与原文件的参考值逐位相同:三个参考结构在 b3 里分别用原文件/转换文件计算,
    dE、dF、dV 全为 0.000e+00。

§5.2 版本固定

.venv-dpa-legacy:deepmd-kit==3.0.0b3(上游预发布版,repformer 布局与检查点匹配的最新发布版)、
torch==2.3.1(GPU 主机 +cu121,含 Volta sm_70)、Python 3.10–3.12。计划里通过
LEGACY_BACKENDS + 每个架构的显式 cuda_channel="cu121" 表达,走现有 BackendSpec 表,没有绕过。
./scripts/install_mliport.sh --engines dpa-legacy --device auto 在本机 7 步全过,收尾 doctor 绿。

§5.3 选择

  • DPA_RUNTIME=legacy|current,默认 current;--dpa-runtime、INCAR DPA_RUNTIME、settings、
    Python API、queue 全部打通(有测试断言四个入口都能表达)。
  • 不发散:legacy 在 current 环境里被拒(并给出安装命令),current 在 legacy 环境里被拒(并提示
    设 DPA_RUNTIME=legacy)。
  • legacy 环境拒绝 DPA-3/DPA4/DPA4C 描述符(_require_legacy_compatible_definition),
    报错点名要改用 current 运行时。

§5.4 带真实力的参考结构

新增 Li₂S 常规胞 + 高斯扰动(σ = 0.05 Å,numpy.random.default_rng(20261115),位移形状 (12,3)),
SHA-256 e0e179f9d4e1267cb370e58fd1ed0fa4b986b8fcbbbfeb24090e4e0c96ff89b6,max|F| = 0.3018 eV/Å。
参考值(E/F/virial,b3 + 转换文件)已并入 #75 参考评论;§2.3 的探针就用这个晶胞跑 --full。

§2.3 可调用性检查(证据:#75)

检查 cpu cuda:0
doctor --engine dpa-legacy --structure li10gep2s12_primitive.vasp 通过,E = -226.0886 eV 通过,同值
validate_runtime.py --dpa-runtime legacy --structure li2s_rattled… --full 通过(单点/共享计算器/中心差分/10 步 NVE/5 image NEB) 通过
mliport vs 参考值(4 个结构) |ΔE|/atom = 0、max|ΔF| ≤ 8e-16 eV/Å、max|Δvirial| ≤ 1.1e-14 eV 同
CPU vs GPU(扰动晶胞) |ΔE|/atom = 0、max|ΔF| = 1.8e-15 eV/Å、max|Δstress| = 2.3e-17 —

身份记录:dpa_runtime: legacy、deepmd_version: 3.0.0b3、model_precision: ['float64'];
GPU 上还有 actual_device_uuid_source: CUDA_VISIBLE_DEVICES —— torch 2.3.1 不提供
device_properties().uuid,所以 UUID 取自隔离契约要求的单值 CUDA_VISIBLE_DEVICES,并如实标注
来源,而不是假装做了运行时校验。

§2.4 文档

  • docs/backends/dpa.md(+zh):DPA-SSE 是什么(DPA-2、硫化物电解质、PBEsol、LGPL-3.0 权重 /
    CC BY 4.0 数据)、旧运行时怎么装怎么用、为什么固定预发布版、安全加载要求,以及
    “118 元素 type_map ≠ 训练覆盖” 的警告(C/H 等有机体系属于外推)。
  • docs/models.md(+zh) 增加 dpa_sse 行(CPU/GPU 均 verified,链接到具体 [DEV P0 AUDIT · DO NOT MERGE/CLOSE] Living correctness and real-hardware test ledger · master #61 #75 评论)。
  • CHANGELOG Unreleased。

§5.5 测试

tests/mliport/mliport/test_dpa_runtime.py:18 个纯 stub 测试(运行时词表、两个方向的
环境不匹配、weights_only 拒绝、非 DPA-2 描述符拒绝、身份字段、四个入口的接线)。全量测试
2067 passed / 47 skipped,lint 与生成文档检查干净。

残余与风险

  • .venv-dpa-legacy 是预发布 deepmd-kit;它的上游生命周期与 DPA4 不兼容,只在 legacy 模式使用。
  • deepmd-kit 在 workspace 里测过 ABI/版本匹配;未来若上游重发 b3 wheel 或 torch 2.3.1 下架,
    需要重新审计(FRAMEWORK_PYTHON 和计划断言会 fail closed)。
  • CI 上 PR feat(dpa): add the DPA-2 legacy runtime for DPA-SSE #100 唯一红的是 test_china_source_really_uses_the_tuna_mirror:TUNA 镜像
    operation timed out(外部网络),本地同样 14 个真实安装测试全过;已重跑一次仍是网络超时。
  • 未做:fine-tune、蒸馏、change-bias、其他 DPA-2 检查点、LAMMPS、精度 benchmark;未把 DPA-SSE
    加进科研验证 manifest(非目标)。

DATA IMPACT: 不使任何既有科学记录失效。既有 DPA 运行的记录不变;新增的 dpa_runtime 字段
只是把环境显式化,默认行为未改。

hydrogen1222 added a commit that referenced this pull request Nov 15, 2026
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.

Copy link
Copy Markdown
Owner Author

[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 main. Do not change #61's code/branch, do not touch #75's historical audit evidence.

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

  1. ASE ase.md.nose_hoover_chain.IsotropicMTKNPT (ASE >=3.26); no hand-coded barostat. pressure_gpa is externally imposed hydrostatic pressure (+ compressive) and converts to pressure_au=pressure_gpa*units.GPa (eV/ų); npt_tdamp, npt_pdamp are positive fs and map to units.fs. Validate nonzero target T, PBC=(1,1,1), finite nonsingular positive-volume cell, calculator stress support, six finite stress components, physical constraints, and unsupported runtime BEFORE integration.
  2. ASE MTK does not accept any ASE positional/COM constraints. Reject constraints explicitly. com_policy=auto must not inject FixCom; choose one-time momentum removal (document its thermostat DOF handling) or an explicitly validated no-COM policy. Never silently ignore a constraint.
  3. Reject NPT for unsupported backends including NEP, and native GPUMD even when --ensemble NPT is syntactically valid. Respect fail-closed validation across CLI/INCAR/queue/API and direct MDRunner.
  4. Variable cell: canonical raw/trajectory.traj must preserve each frame's cell and momenta. Standard fixed-cell XDATCAR must not be emitted from NPT; reject explicit request or suppress with recorded reason only if default flag. Do not fake fixed-cell outputs. The main existing md.csv already records volume and total pressure; add target-pressure & barostat provenance and appropriate safety checks.
  5. NPT output must be marked NOT ELIGIBLE for fixed-cell MSD/EH/transport unless explicitly and correctly redefined. A stable equilibrium cell may be extracted offline from an equilibrated window (average cell / volume clearly labeled); only then may a separate fixed-cell NVT run be used for conductivity.
  6. Backward compatibility: NVE/NVT default outputs, artifacts, config, thermo and tests must not drift. NPT direct Python API must validate values even without schema; no output corruption after failed preflight. Don't advertise unsupported --thermostat Langevin etc. for NPT; NPT controls own MTK temperature chain.
  7. Allow actual running T,P to fluctuate; do not claim NPT or a 10-step smoke proves correct equilibrium. Validation tiers: pure-Python deterministic potential with analytic stress, short periodic full-stack ASE smoke, continuity/stress/pressure/unit/sign checks, ensemble/constraint/backends error matrix, variable-cell I/O roundtrip, no-XDATCAR, invalid and nonfinite cell/stress abort, MD progression, legacy NVE/NVT regression, docs (EN/ZH) and config all interfaces. A real MLIP/hardware long-run and physics accuracy is owner local-agent acceptance, not falsely reported as passed.

Suggested interface and delivery

--ensemble NPT --temp 800 --pressure-gpa 0 --npt-tdamp 100 --npt-pdamp 1000 --steps ... --no-pre-relax.
Defaults are starting guesses; select stable damping per material/timestep. Begin with isotropic 3D bulk; do not stretch this PR to phase-transition or transport features. Implement and test in one coherent branch and link the PR here.

Copy link
Copy Markdown
Owner Author

NPT implementation handoff · 2026-11-15 (spec comment above)

Implementation: #101, branch feat/ase-isotropic-mtk-npt, targeting main. #61 remains OPEN+DRAFT+DO-NOT-MERGE; no code changes to its permanent 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 pytest -q tests/mliport/mliport/test_md_npt.py tests/mliport/mliport/test_md_scientific_contracts.py tests/mliport/mliport/test_md_runner.py; ruff check + ruff format --check; run isolated small known-good periodic structures for UMA, MACE, GRACE, DPA; check pressure sign/units, 3D cell fluctuation, stress finite, temperature and volume stability, output roundtrip; confirm unsupported/partial-PBC/fixed-atom/GPUMD rejection; compare an NPT-equilibrated mean cell with fixed-cell NVT, avoiding direct NPT MSD. Do not interpret 5–20 step smoke as NPT equilibrium or model accuracy.

Copy link
Copy Markdown
Owner Author

NPT follow-up implementation status:

Final head: 0017c9321a0b45053b4a4f724d6b06d5c3c0750a.

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 pr-101 worktree to this head and confirms focused interface tests, TUI command construction, and JSON provenance. The prior real-weight 20-run campaign validates the unchanged MTK core; this patch changes interface forwarding, alias/scope gates, provenance persistence, and documentation.

No merge performed. #61 and #75 remain permanent Open + Draft records.

Copy link
Copy Markdown
Owner Author

[SPEC · 2026-11-15] 任务文件夹 + INCAR 使用方式改进(owner-approved)

Tracking / branch policy: 本条记录在永久 #61(OPEN + DRAFT,DO NOT MERGE/CLOSE)。实际实现与测试必须在单独、可合并、目标为 main 的 PR 中完成并回链本评论(Tracking: #61)。不得改动 #61 的代码/分支,不得改动 #75 的历史审计证据。代码 PR 先由 Claude 审阅,未经 owner 确认不得合并。

目标

让 mliport 的日常用法收敛为一件事:一个任务文件夹(INCAR.mliport + 结构文件),在文件夹里不带参数运行 mliport run,模型统一放在仓库根目录的 models/。用户不需要记命令行参数,也不需要 agent 帮忙拼命令。

不在范围内(不得顺手实现;AGENTS.md 第 10 条)

  • 不做网页界面,不做多阶段/多任务的“study”文件或配方(recipe),不做命令行重构。
  • 不做模型后端自动识别、不下载或打包权重;MODEL_TYPE 仍是必填(AGENTS.md 第 3 条:不得静默改变 model task/head)。
  • 不自动读取名为 INCAR 的文件(它可能是真正的 VASP 输入);默认文件名仍是 INCAR.mliport。
  • 不改变任何物理默认值、单位、PBC 语义;sp / opt / md / neb / batch 子命令的行为不变。
  • 不删除现有 TUI 屏幕,不修改 CLI 参数表(让 CLI 与 TUI 也由选项表生成是后续工作,不在本轮)。

需求

R1 任务文件夹与结果目录

  1. 在含 INCAR.mliport 的文件夹中,mliport run(不带参数)即可运行;结构文件沿用现有自动查找顺序(POSCAR、CONTCAR、structure.cif、structure.xyz)。
  2. mliport run 的默认输出目录从“当前目录”改为 <INCAR 所在目录>/results/。--output 与 OUTPUT_DIR 优先于默认值,且相对路径按现有路径解析规则相对 INCAR 解析;OUTPUT_DIR = . 可恢复旧行为。NEB 分支同样适用。
  3. 已有结果的目录仍拒绝写入,必须显式 --overwrite(AGENTS.md 第 11 条:保留原始轨迹与 provenance)。这是对默认输出位置的有意行为变更,必须写入 CHANGELOG 与 docs(中英)。
  4. INCAR 的语法、未知键、值校验与模型路径解析必须发生在读取结构文件和加载模型之前;配置有错时先报配置错误。

R2 models/ 约定

  1. MODEL_PATH(现有别名 MODEL 保持可用)取值为不含路径分隔符的文件名时,在 <MLIPORT_ROOT>/models/<name> 查找,其次 <MLIPORT_ROOT>/models/*/<name>(只找一层子目录);同名多个命中必须报错(fail closed),不得任选其一。
  2. 含路径分隔符的取值(绝对或相对路径)行为完全不变,且优先于 models/ 查找。文件名取值若在 INCAR 所在目录已存在同名文件,沿用现有行为;找不到才查 models/。
  3. MLIPORT_ROOT 的确定顺序:环境变量 MLIPORT_ROOT;否则若 sys.prefix 的目录名符合安装器创建的 .venv-<engine>,取其父目录;否则无根目录。无根目录时使用文件名取值必须明确报错并说明如何设置,不得静默回退。安装器生成的 bin/mliport-<engine> 启动脚本顺带导出 MLIPORT_ROOT(脚本本身位于仓库根的 bin/)。
  4. 找不到模型时,错误信息列出实际搜索过的位置和 models/ 中现有的文件名。
  5. 解析后的绝对模型路径写入 resolved_config.json 与现有 provenance(沿用现有模型身份记录,不新增格式)。
  6. mliport doctor 输出解析出的仓库根目录、models/ 路径及其中文件清单。
  7. models/ 已被 .gitignore 忽略,须保持;scripts/check_repository_hygiene.py 对已跟踪权重的拒绝不得放宽。

R3 INCAR 模板与支持范围

  1. mliport template <type> 的输出:按固定顺序分组(各分组只出现一次)、每个键一行简短英文注释、只包含当前计算类型相关的键;恒温器专属参数只写所选恒温器的;MD 模板包含注释掉的 NPT 示例键(MD_ENSEMBLE = NPT、PRESSURE_GPA、NPT_TDAMP、NPT_PDAMP)。
  2. 模板与运行必须一致:所有 template 类型 × 所有后端生成的文件,在仅填入占位符(MODEL_PATH = REQUIRED 等)后,必须被 mliport run 的校验与解析接受。以参数化往返测试固化,覆盖 sp / opt / md / neb / confsearch。
  3. mliport run 支持 CALC_TYPE = CONFSEARCH,分发到与 mliport confsearch run 相同的代码路径(CS_* 键在选项表里已有);batch 仍拒绝并提示用 mliport batch。不得复制一份 confsearch 逻辑。
  4. 模板生成、mliport config schema 与下面的键参考文档共用同一份选项表:OptionSpec(mliport/config/schema.py)增加分组、顺序、一行说明、“适用条件”(如仅 ENSEMBLE=NPT 时出现的键)元数据;不得另起一份并行的键清单。

R4 INCAR 键参考文档(中英)

  • 新增 docs/incar.md + docs/incar.zh.md:按计算类型列出键、类型、默认值、取值范围/可选项、含义、适用条件、别名。表格由 scripts/generate_docs.py 从选项表生成(--check 在 CI 中保证同步)。
  • 加入 mkdocs.yml 导航;docs/configuration.md 的 INCAR 一节补一个到该页的链接并说明任务文件夹与 models/ 约定;README 保持“前门”,只加一行链接。中文版结构必须与英文版一致(现有 docs 契约测试)。
  • docs/quickstart.md 补一个“任务文件夹”写法,原命令行写法保留。

R5 TUI:新建任务文件夹向导

  1. TUI 主屏的第一个入口改为向导,只问三件事:计算类型、结构文件、模型(先选后端 MODEL_TYPE,再从 models/ 文件清单里选)。
  2. 向导生成新文件夹:INCAR.mliport(来自 R3 的同一模板生成器,已填入 MODEL_PATH / MODEL_TYPE)+ 结构文件逐字节复制(按后缀归一为 POSCAR / structure.cif / structure.xyz,不改内容),并显示 cd <文件夹> && mliport run。“立即运行”按钮必须走与 mliport run 相同的代码路径,不得另有一套运行逻辑。
  3. 现有配置/运行/任务/分析屏幕保留,放到“高级”入口下;旧的 TemplateScreen 改为复用同一模板生成器。

兼容性与科学约束

  • 现有 INCAR 文件继续可运行;唯一有意的行为变更是 R1.2 的默认输出位置。
  • fail closed:任何无法确定的情况(根目录未知、同名模型多个、模板占位符未填)都报明确错误,不猜。
  • 不得静默改变单位、PBC、model task/head、dtype(AGENTS.md 第 3 条)。
  • 所有新增用户可见文字与文档中英文齐备,英文为维护基准。

验收(必须有自动化测试)

  • R1:默认输出为 <INCAR 目录>/results/;--output、OUTPUT_DIR(含 .)优先;已有结果时拒绝;配置错误先于结构读取与模型加载报出。
  • R2:文件名解析(命中一层子目录、同名多命中报错、路径取值不受影响、根目录未知报错、MLIPORT_ROOT 与 .venv-<engine> 推导);错误信息含搜索位置与现有文件清单。
  • R3:模板往返测试(5 种类型 × 6 个后端值);CALC_TYPE = CONFSEARCH 经 run 与经 confsearch run 得到同一路径/同一解析配置;模板内每个分组只出现一次。
  • R4:generate_docs.py --check、mkdocs build --strict、中英结构契约测试通过。
  • R5:Textual 异步测试覆盖向导生成的文件夹内容(INCAR + 结构逐字节一致)与“立即运行”调用同一入口。
  • 既有全套测试、ruff、check_repository_hygiene.py 与打包内容检查保持通过。

建议交付拆分(各自独立 PR,均回链本评论)

  1. INCAR 核心:R1 + R3.2/R3.3(含往返测试)。
  2. 模型目录:R2(含启动脚本与 doctor)。
  3. 选项表元数据 + 模板重做 + 键参考文档:R3.1/R3.4 + R4。
  4. TUI 向导:R5(依赖 2 与 3)。

仍属 owner 本地验收、不得声称已通过:真实模型 / GPU 上用任务文件夹跑通 sp、opt、md、confsearch。


Generated by Claude Code

@hydrogen1222

Copy link
Copy Markdown
Owner Author

[进展 · 2026-11-16] 「任务文件夹 + INCAR + models/」四份实现 PR 已提出(等待审阅,未合并)

按 规格评论 的拆分,四份独立 PR 全部就位,均目标 main、均回链 #61,CI(tests 3.10–3.13 / lint / build / docs / installer)全绿。均未合并,等待 owner 确认。

# 交付 覆盖需求 依赖
#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)。

hydrogen1222 added a commit that referenced this pull request Nov 15, 2026
…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
hydrogen1222 added a commit that referenced this pull request Nov 15, 2026
…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
hydrogen1222 added a commit that referenced this pull request Nov 15, 2026
…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
@hydrogen1222

Copy link
Copy Markdown
Owner Author

[进展 · 2026-11-16] 第一轮独立评审已闭环,四份 PR CI 全绿(等待 owner 确认,未合并)

对 #104–#107 做了一轮独立评审(逐条比对规格 + 实际跑代码验证,不只读 diff),发现 13 项问题,其中 1 个 blocker、8 个 major,全部已修复并补充/修正了对应测试。要点:

#105(models/)—— 修掉一个真实回归

  • GRACE 的 MODEL_PATH 是 SavedModel 目录,而查找只认文件,导致文档里的 --model saved_model --model-type grace 会报“找不到模型”。现在文件与目录都接受,models/ 里的目录也能按名命中。
  • MLIPORT_ROOT 不再从任意 .venv 推导(.venv 既是 UMA 的环境名,也是任意项目的虚拟环境名);现在要求父目录有 checkout 标记(models/、bin/mliport-* 或 mliport/pyproject.toml),否则按规格 fail closed。
  • 启动脚本改为不覆盖调用方显式设置的 MLIPORT_ROOT(原来会把共享模型库指向冲掉)。

#104(INCAR 核心)—— 修掉两个输出目录缺陷

  • OUTPUT_DIR = . 原来并不等于“当前目录”,而是被解析成 INCAR 目录:文档承诺的退路不存在。现在 ././ 保留为相对值,由 CLI 按当前目录解析。
  • 相对 OUTPUT_DIR 原来在所有层都改成了“相对声明文件”,导致 settings.ini 里的 out_root 会把其他子命令的输出挪到别处(而 CHANGELOG 声称未变)。现在只有 INCAR 声明的 OUTPUT_DIR 相对 INCAR 解析,其余层保持原来行为。

#106(选项表/模板/文档)

  • NEB 模板原来写 NEB_INITIAL = initial.vasp(看似完整、实际永远跑不了),改为 fail-closed 的 REQUIRED;模型段的注释改为取自选项表(原来还写着“相对 settings.ini”,已不成立)。
  • 生成的键参考不再把内部哨兵渲染成 CS_MODE = MODE_B(校验器会拒绝的值),示例值不再标成 required;补上之前漏掉的 batch 键;中文页翻译了分节标题并说明“含义”列来自英文选项表。

#107(TUI 向导)

  • 向导原来会一键执行模板里硬编码的 TASK = omat(UMA 任务族)/ DPA HEAD = Omat24——等于替用户决定了模型身份(AGENTS.md 第 3 条)。现在 TASK(以及后端的 HEAD)写成 REQUIRED,界面列出“仍需填写”,未填前 run 会拒绝。
  • 从 models/ 子目录选到的模型(如 uma/s1.pt)原来会被写成工作目录相对路径,现在按 models/ 解析并写绝对路径,找不到直接报错。

当前状态:四份 PR 的 tests 3.10–3.13 / lint / build / docs / installer-real-nep / wheel-install-smoke 全绿;本地 2310 passed, 48 skipped;ruff、check_repository_hygiene.py、generate_docs.py --check、mkdocs build --strict、docs 契约测试均通过。每份 PR 下都有评审回复评论(含具体提交号)。

仍然只有 owner 能做的验收(不得声称已通过):真实模型 / GPU 上用任务文件夹跑通 sp、opt、md、confsearch;GRACE 目录模型与 CUDA、MODEL_PATH 指向真实 checkpoint 的端到端验证;以及是否合并、以何顺序合并(建议 #104 → #105 → #106 → #107,后两者是栈式分支,我会在合并后重定基到 main)。

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

do-not-merge Tracking/spec PR; must never be merged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants