md-analysis-planner

MD 分析规划器

目标

在编写后处理代码前，选择合适的 MD 轨迹分析方法及其前置条件。

要求

• Python 3.10+
• 无外部依赖
• 适用于 Linux、macOS 和 Windows

需要收集的输入

输入	说明	示例
系统	材料或分子系统	oxide glass, liquid water
目标	分析目标	rdf,diffusion,coordination
轨迹格式	Dump、DCD、XYZ、H5MD 等	LAMMPS dump
速度	是否存储了速度	true
应力	是否存储了应力/维里	true
是否需要解包	原子是否会跨越 PBC	true
时间步长	每个已保存帧对应的 fs 数	10

决策指南

• 使用 RDF 和配位数 分析局部结构。
• 使用 MSD 分析扩散，但需解包轨迹并确认处于扩散区间。
• 仅在存在速度或可靠的有限差分速度时使用 VACF/VDOS。
• 仅在有应力/维里数据和形变历史时使用 应力-应变 分析。
• 拟合输运或热力学性质前，务必先检查是否已达到平衡。

脚本输出

scripts/md_analysis_planner.py 会输出以下字段（位于 results 下的 JSON）：

字段	说明
analysis_plan	每个目标对应一项：goal、method 和 status
required_data	汇总所有目标所需的数据，并按排序去重
equilibration_checks	标准的拟合前平衡检查清单
pbc_handling	unwrap_needed、minimum_action、format_note
warnings	安全关键注意事项和阻碍因素

状态值

status 的取值从严重到轻依次为：blocked > needs time axis > needs review > ready。较轻的状态不会降低较严重状态的等级。 例如，如果未存储速度，VACF/VDOS 目标会报告 blocked，即使缺少时间步长 （仍会发出这两项警告）。

默认（非 JSON）输出

不使用 --json 时，脚本会输出规划行、Required data: 列表、单行 PBC: 说明以及 Warnings: 部分（也会同步输出到 stderr），确保即使 stdout 被管道重定向，也能看到安全关键注意事项。

工作流

python3 skills/simulation-workflow/md-analysis-planner/scripts/md_analysis_planner.py \
  --system "oxide glass" \
  --goals rdf,coordination,bond-angle \
  --trajectory-format dump \
  --unwrap-needed \
  --timestep-fs 10 \
  --json

错误处理

如果缺少速度、应力或时间步长信息，则降低依赖这些信息的分析等级并报告警告。 对于无效输入（系统为空、没有目标、时间步长为非正数或非有限值，或输入超出下方的大小上限），脚本会以代码 2 退出，并向 stderr 输出一条消息。

限制

此技能用于规划分析及其前置条件；它不会直接解析大型轨迹。

验证清单

在针对规划器自身的输出记录以下所有适用项目之前，不要相信基于轨迹得出的结果：

• 运行 scripts/md_analysis_planner.py，并确认没有任何 analysis_plan 条目为 blocked 或 needs time axis；记录任何 needs review 目标，以及如何解决其自定义分析。
• 在运行相应分析之前，确认规划器 required_data 列表中的每一项都确实存在于轨迹中（例如，VACF/VDOS 需要 velocities，应力-应变分析需要 stress or virial + strain history）。
• 对于扩散/MSD：记录 MSD 与时间的对数-对数斜率，并在拟合窗口内确认斜率约为 1（扩散区间）；排除弹道/亚扩散瞬态后，再报告 D = lim MSD/(2dt)。
• 对于扩散/MSD：应用 Yeh-Hummer 1/L 有限尺寸修正，并记录所用的盒长 L 和剪切黏度 eta（D_0 = D_PBC + k_BTxi/(6pieta*L)，xi~=2.837，立方盒）。
• 对于任何基于位移的分析，若 pbc_handling.unwrap_needed 为 true：确认在计算位移前，已使用 cell + image flags 解缠位置（而不是直接使用包裹坐标）。
• 完成规划器的 equilibration_checks：舍弃启动瞬态，确认温度/压力进入平台期，并在进行任何输运/热力学拟合前比较前半段与后半段的属性估算值。
• 每项报告的输运/热力学属性都应报告通过分块平均法（或独立轨迹）得到的不确定性，而不是单个时间窗口的点估计。

常见误区与错误理由

看似省事的做法	错误之处 / 正确做法
“MSD 与时间的关系看起来是直线，所以属于扩散——直接拟合一条直线就行。”	看起来呈直线的 MSD 仍可能包含弹道/亚扩散瞬态。先确认拟合窗口内的对数-对数斜率约为 1，再拟合 D = lim MSD/(2dt)。
“模拟得到的 D 就是扩散系数。”	PBC 自扩散系数取决于系统尺寸。使用实际盒长 L 和黏度 eta 应用 Yeh-Hummer 1/L 修正；报告 D_0，而非 D_PBC。
“转储文件里有位置，所以 MSD 没问题。”	包裹坐标会使原子在穿过盒子边界时发生跳变，从而使位移失真。当 unwrap_needed 为 true 时，进行任何位移分析之前，都要使用 cell + image flags 解缠位置。
“没有存储速度，但我可以根据位置计算 VACF/VDOS。”	规划器在没有速度时将 VACF/VDOS 标记为 blocked 是有原因的。必须明确说明有限差分速度估算的合理性（帧间隔、混叠）；否则结果不可靠。
“运行结束了，所以我可以用整条轨迹拟合输运属性。”	运行完成不等于达到平衡。拟合前应舍弃启动瞬态，并确认温度/压力进入平台期（即完成 equilibration_checks）。
“一个时间窗口给出了可靠数值，不需要误差条。”	单个时间窗口会掩盖由相关性导致的方差。使用分块平均法或独立轨迹，确保每个输运/热力学数值都附带不确定性。

安全性

输入验证

输入仅包含标量 CLI 值和布尔值。plan_md_analysis 会在使用前验证并限定每个字段的范围；任何违规都会引发 ValueError，main 会捕获该错误，在 stderr 上打印消息并以代码 2 退出：

• system 去除首尾空白后必须非空，且长度不超过 256 个字符。
• 最多允许 64 个目标；每个目标最多 256 个字符。
• trajectory_format 最多 256 个字符。
• 如果提供 timestep_fs，必须为正的有限数值（math.isfinite 且 > 0）。

目标不设允许列表：无法识别的目标不会被拒绝，而会标记为 needs review，并附带“unknown goal”警告。--has-velocities、--has-stress 和 --unwrap-needed 标志都是普通布尔值，无需验证。

文件访问

该脚本不会读取或写入任何文件；所有 I/O 均为 stdin/args -> stdout（纯文本或 JSON），警告还会同步输出到 stderr。它不接受路径参数，也不会打开轨迹文件或输出文件，因此无需担心文件系统沙箱问题。由于不会读取文件，因此没有单文件大小限制；输入大小则受上述字段/目标限制约束。

工具限制

Frontmatter 中的 allowed-tools 为 Read, Bash, Write, Grep, Glob：

• Bash 仅用于运行随附的 scripts/md_analysis_planner.py。
• Read、Write、Grep 和 Glob 仅用于编写分析计划时检查、编辑和搜索此技能自身的文件（脚本、参考资料和 SKILL.md）；不会用于接触轨迹数据。

安全措施

• 不使用 eval、exec、os.system 或动态导入。
• 该脚本不会生成子进程，也不会执行外部分析程序；它只使用 argparse 解析参数，并在进程内计算计划。
• 输出为通过 json.dumps 生成的结构化 JSON（或确定性纯文本），绝不会插入 shell 命令。
• 拒绝服务防护上限（MAX_GOALS = 64、MAX_SYSTEM_LEN = 256、MAX_FIELD_LEN = 256）限制了工作量，确保规划辅助程序不会将异常输入全部加载到内存中。

参考资料

• 关于分析前提条件和失败模式，请参阅 references/md_analysis_checks.md。

版本历史

• 1.2.0：为全部三个评估用例添加确定性的 script_checks，用于固定规划器的精确输出（状态、排序后的 required_data、PBC 注释，以及具体的扩散区间 / Yeh-Hummer / blocked-not-demoted 警告），使评估能够区分此技能与基于记忆作答的基线。
• 1.1.0：修复状态降级问题（blocked 永远不会降级为 needs time axis）；在非 JSON 模式下显示警告、必需数据和 PBC；添加扩散区间和 Yeh-Hummer 有限尺寸指导；并强制执行文档规定的输入上限。
• 1.0.0：初始 MD 分析规划技能。