GPUMDkit预测误差：真实DFT标签与能量偏移检查
9个真实Si第一性原理构型的预测、训练测试对照、逐帧误差与能量基准诊断。
阅读本篇目录
下载结构标签、模型、完整脚本与参考结果。本篇使用GPUMDkit 1.5.8、calorine 4.0、独立Python 3.11环境；calorine的CPU扩展由G++ 13.3.0构建。这是一次真实数据的预测与诊断例子，未重新训练模型。
1 准备什么数据#
附件提供9个2原子Si扰动构型，能量、力和virial来自鸢算科技集群VASP实算。分成7帧train.xyz与2帧test.xyz，配套一个已有Si NEP模型。两个集合来自同一小范围扰动系列，名称仅用于演示工具输出，不代表模型原始训练集，也不是独立的泛化测试。
extxyz应包含能量、各原子力、晶胞和元素；要画应力/virial误差还需相应标签。没有DFT标签的普通POSCAR只能用来预测，不能凭空计算“预测误差”。
2 两个集合分别预测#
解压后先执行cd gpumd-parity，在这个子目录运行：
module load gpumdkit/1.5.8
gpumdkit.sh -prediction train.xyz si-nep.txt 1
gpumdkit.sh -prediction test.xyz si-nep.txt 1
gpumdkit.sh -plt train_test save
最后的1是CPU工作进程数，不是GPU卡数。这一入口通过calorine做CPU预测；少量构型可以在登录节点做轻量处理，大批数据使用yskit提供的CPU提交脚本。不要把该命令改成多份MPI并行，也不要因为名字含GPUMD就给它申请多张GPU。
输出文件名跟随输入文件名：train.xyz生成energy_train.out、force_train.out、stress_train.out和virial_train.out；test.xyz对应_test.out。train_test图需要两套文件都存在。
| 文件 | 列含义 | 单位 |
|---|---|---|
| energy | 预测、参考各1列 | eV/atom |
| force | 预测xyz、参考xyz各3列 | eV/Å |
| stress | 预测、参考各6列 | GPa |
| virial | 预测、参考各6列 | eV/atom |
6分量输出顺序为xx、yy、zz、xy、yz、xz。工具采用NEP应力/virial约定，与ASE原生应力符号不同；不要把ASE应力直接当成同符号的NEP virial。此例参考标签来自已核对的extxyz virial。
当前工具的能量图坐标范围按参考DFT能量设置，本例预测能量整体偏高，散点落到图框外，因此左图看似没有点。这不是没有预测结果；下方配套诊断图使用覆盖参考与预测的完整范围显示。
3 先看原始误差，不要直接平移曲线#
配套脚本按所有标量分量统一计算RMSE，避免将各方向RMSE的平均值与全分量RMSE混用：
python analyze_parity.py
cat ANALYSIS.json
head frame-errors.csv
| 集合 | 能量RMSE / eV·atom⁻¹ | 力RMSE / eV·Å⁻¹ | 应力RMSE / GPa | virial RMSE / eV·atom⁻¹ |
|---|---|---|---|---|
| 7帧集合 | 0.790667 | 0.047861 | 0.339909 | 0.043378 |
| 2帧集合 | 0.788184 | 0.062017 | 0.274594 | 0.035043 |
能量误差明显大于力误差提示的局部变化水平，但仅凭这一现象不能断言模型正确或只差一个常数。首先核对元素、赝势、泛函、每原子/整胞单位、模型训练数据基准和结构分布。
4 用训练侧偏移做诊断#
脚本仅从7帧集合计算平均预测−参考，得到 0.7906508658 eV/atom。固定这个数，再分别查看两侧残差；2帧集合不参与确定偏移。
| 集合 | 减去同一个偏移后的能量RMSE / meV·atom⁻¹ |
|---|---|
| 7帧集合 | 5.127509 |
| 2帧集合 | 3.204228 |
这一步只用于看清常数偏移和结构相关残差，没有修改模型，也没有把修正后的数值替代原始验证误差。因为两组数据相关、样本极少，不能据此给出普适精度。多元素体系还要区分每种元素的能量基准；一个常数不能替代多组分校准。
5 逐帧定位问题，再决定补哪些数据#
frame-errors.csv保留集合、帧号、参考能量、预测能量、原始误差、诊断残差和最大参考力。先查看残差最大的构型，再检查是否存在大位移、异常短键、超出训练温压范围或标签错误。不要仅删除误差大的帧来改善图形。
整个下载包可以一条命令复跑：
bash run.sh
它会重新预测两个小集合、调用GPUMDkit绘图并计算诊断数据，输出覆盖当前工作目录中的同名结果；请在自己的副本中运行。