4.3 崩溃与报错排查手册

4.3 崩溃与报错排查手册

本节摘要：MD 崩溃的表象千奇百怪，病根却高度集中：本册遇到的每一个崩溃都能归入能量爆炸、约束失败、邻居表失效、PBC 异常四大类。本节按"报错原文 → 机制 → 处置"组织成手册，附一张排查决策树与一段批量扫描 log 的巡检脚本；核心方法论只有一句——崩溃是症状不是病，往前找最近一次"健康证据"，病根几乎总在它之前。

这一节是全册的保险丝。前两章的每一个环节（盒子太小、EM 不到位、步长越线、参数抄错）都会在运行期以崩溃形式讨债，而讨债的方式高度重复——这正是手册化的底气。读法建议：先通读建立分类框架，出事时按报错原文对号入座，处置后回到对应章节补课，而不是机械重试。

四大类崩溃：报错原文与机制

第一类：能量爆炸（"Particle too fast" 或坐标签名丢失）。 报错典型原文："Particle too fast: potential energy ... restoring trajectory"。机制：某原子受力巨大，一步积分飞出合理范围，势能瞬间飙升。病根排序：EM 没做够或根本没做（3.5）→ 体系里有重叠原子（2.3 溶剂化遗留）→ 步长越线（3.2）→ 时间反演类分析操作误用。处置走 3.5 的分诊台：回 EM，查最大力原子，可视化看它周围有什么。

第二类：约束失败（LINCS WARNING）。 报错典型原文："LINCS WARNING: relative constraint deviation after constraining" 随后 "Water molecule starting at atom ... can not be settled"。机制：LINCS/SETTLE 求不出满足约束方程的解——通常是上一步已经有人飞了，约束只是"最后死掉的器官"而非死因。新手在这里的常见误动作是加大 lincs-iter 或 lincs-order：那是在给尸体化妆。正确姿势：把它当第一类的变体处理，回查能量曲线找到起飞的起点（用 gmx energy 看势能的阶跃时刻，再从对应帧附近的 xtc 抓出肇事原子）。

第三类：邻居表失效（"Water molecule ... not bonded" 之前的 step 0 莫名崩溃、或 "rgcuda 错误"之外的 "Update group ... moved too far"）。 机制：Verlet 邻居表假设两次重建之间原子跑不出缓冲带；若 EM 严重不到位或初速度分布病态，第一步就穿帮。处置：确认 nstlist 与默认缓冲未被手改（3.1 的告诫），确认第一步前有 EM，确认 gen_vel 的温度没写成物理单位的错误值。

第四类：PBC 异常（"Atom ... moved ... too far" 与越写越大的盒子）。 机制：原子一步跨越超过半盒宽，最小镜像约定（2.3）无法唯一确定它的归属。深层原因几乎总是第一类的伴生：先是飞了，然后才 PBC 报警。单独出现时查盒子是不是真的太小（微盒 + 大步长）。

图 4-1 崩溃排查决策树：从报错原文到病根章节

巡检脚本：让慢性病无所遁形

突发崩溃会喊疼，慢性漂移不喊。与其等人肉翻 log，不如定时扫描：下面的脚本读任意 mdrun 的 log，输出每个记录块的步号、势能与最大受力，并标记势能阶跃（相邻记录块势能突跳超过阈值）——阶跃点就是事故第一现场：

import re, sys

def scan_run_log(path, jump_thresh=1e5):
    pot_records = []                      # (step, potential, fmax)
    step = pot = fmax = None
    rx_step = re.compile(r"^\s*Step\s+(\d+)")
    rx_pot  = re.compile(r"Potential Energy\s*=\s*([-\d.e+]+)")
    rx_fmax = re.compile(r"Maximum force\s*=\s*([-\d.e+]+)")
    for line in open(path, encoding="utf-8", errors="ignore"):
        if (m := rx_step.match(line)): step = int(m.group(1))
        if (m := rx_pot.search(line)): pot = float(m.group(1))
        if (m := rx_fmax.search(line)):
            fmax = float(m.group(1))
            if None not in (step, pot, fmax):
                pot_records.append((step, pot, fmax))
    print(f"记录块 {len(pot_records)} 个；末块 step={pot_records[-1][0]} "
          f"U={pot_records[-1][1]:.3e} Fmax={pot_records[-1][2]:.1f}")
    events = 0
    for (s0, u0, _), (s1, u1, _) in zip(pot_records, pot_records[1:]):
        if abs(u1 - u0) > jump_thresh:
            events += 1
            print(f"  !! 阶跃：step {s0} -> {s1}，势能 {u0:.3e} -> {u1:.3e}")
            print(f"     处置：从 {s0} 步附近抓帧找肇事原子（可视化定位重叠或断链）")
    if not events:
        print("  无势能阶跃，本段运行平稳")

scan_run_log(sys.argv[1] if len(sys.argv) > 1 else "md.log")
​

配套两条纪律：log 与 edr 属于"事故黑匣子"，即使轨迹删了也要留档；每次崩溃后把报错原文、处置方案、回炉章节记进课题日志——同一类坑第二次踩到时，手册上已经有了你的批注。

报错速查表：从原文到处置

速查表的使用姿势：先按关键词归类，再执行"第一处置"，不要跳过归类直接调参数——十个崩溃里七个的真正病根不在报错指向的那个参数上，而在更早的构建环节。

崩溃后的取证顺序

决策树之外，一套固定的取证动作能少走弯路。第一取 log 尾部：崩溃前最后一个 Step 号与最后的能量值（势能是否已经飙到不物理的量级，还是"好好地在跑突然被杀"——后者先怀疑集群因素：超时、内存、磁盘满）。第二取 edr 曲线：势能阶跃发生在几万步之前还是恰好崩溃时刻？阶跃在前说明病早已存在，崩溃只是死亡确认书。第三取肇事帧：用 trjconv -dump 把阶跃前后的帧抽出来，可视化找重叠原子或断链。三步走完，80% 的崩溃原因已经写进了你的实验记录，剩下两成（真随机硬件故障、罕见软件 bug）才值得上论坛问人——而提问时你贴的取证材料，也足以让别人帮你了。

速记：崩溃四大类——爆炸、约束、邻居表、PBC，约束告警多是症状不是死因；处置套路永远是"找最近的健康证据，往前回炉"；-maxwarn 留下的债由崩溃来收；巡检脚本盯势能阶跃，慢性漂移与突发爆炸一起抓。跑得稳了，第5章开始把轨迹变成结论。