📊 绘图脚本
绘图模块包含一系列 Python 脚本，用于可视化 GPUMD、NEP 和 GPUMDkit 计算器产生的数据。所有图表均可交互显示或保存为高分辨率 PNG 文件。
脚本位置： Scripts/plt_scripts/
快速入口
gpumdkit.sh -plt # 显示所有绘图选项
gpumdkit.sh -plt <type> # 生成指定图表
gpumdkit.sh -plt <type> save # 保存为 PNG
gpumdkit.sh -plt -h # 列出可用绘图类型
建议的绘图流程
与其反复尝试图类型，建议按以下顺序操作：
- 用
gpumdkit.sh -plt -h列出可用类型。 - 确认当前工作目录中已经有哪些数据文件。
- 在下文找到对应条目，并按其给出的完整命令格式运行。
- 仅在该条目明确展示时加入
save；不同绘图脚本中它的位置并不完全相同。
| 已有文件 | 优先使用 | 首先检查什么 |
|---|---|---|
loss.out、energy_train.out、force_train.out |
gpumdkit.sh -plt train |
损失曲线与能量/力 parity 图 |
prediction 模式生成的 energy_train.out、force_train.out |
gpumdkit.sh -plt prediction |
train.xyz 中结构的 parity 结果 |
thermo.out |
gpumdkit.sh -plt thermo |
平衡过程和热力学量演化 |
gpumdkit.sh -calc msd 生成的四列 msd.out |
gpumdkit.sh -plt msd |
解读拟合前的扩散区间 |
GPUMD compute_msd 单分组生成的七列 msd.out |
gpumdkit.sh -plt sdc 或 gpumdkit.sh -plt msd_sdc |
SDC 列和扩散区间 |
GPUMD compute_sdc 生成的 sdc.out |
gpumdkit.sh -plt vac |
速度自相关 |
rdf.out |
gpumdkit.sh -plt rdf |
所选原子对列和峰位置 |
xrd.out |
gpumdkit.sh -plt xrd |
第 2 列角度和第 4 列强度 |
compute_msd 请求多个分组时会追加其他分组的数据。请检查分组布局，并在
适用时使用 msd_all，不要把每个 msd.out 都当作七列文件。
例如，保存训练结果图的命令是：
下方 Gallery 图片用于展示图的布局，并不是通用的质量阈值。loss 曲线、parity 散点或输运拟合是否合理，取决于模型、数据和模拟方案；不能仅凭图片作出科学结论。
为什么不使用
gpumdkit.sh -plt train -h？ 各绘图脚本没有统一的单图-h接口。请用gpumdkit.sh -plt -h查看列表，再按下文对应小节的命令格式和输入文件说明执行。
显示完整绘图命令菜单
运行 gpumdkit.sh -plt 会显示绘图命令菜单：
+-----------------------------------------------------------------------------------------------+
| GPUMDkit <version> PLOT & VISUALIZATION TOOLS |
+-----------------------------------------------------------------------------------------------+
| Usage: gpumdkit.sh -plt <type> List: gpumdkit.sh -plt -h |
+-----------------------------------------------------------------------------------------------+
| NEP Training & Evaluation |
+-----------------------------------------------------------------------------------------------+
| train - NEP training results prediction - NEP prediction results |
| train_test - NEP train and test results parity_density - Parity density plot |
| train_density - Training results density plot restart - Parameters in nep.restart |
| charge - Charge distribution born_charge - Born effective charges |
| dimer - Dimer energy/force curve force_errors - Force errors |
| des - Descriptors net_force - Net force distribution |
+-----------------------------------------------------------------------------------------------+
| Diffusion & Transport |
+-----------------------------------------------------------------------------------------------+
| msd - Mean square displacement msd_conv - MSD convergence |
| msd_all - MSD for all species sdc - Self diffusion coefficient |
| msd_sdc - MSD and SDC together sigma - Arrhenius ionic conductivity|
| D - Arrhenius diffusivity sigma_xyz - Directional Arrhenius sigma |
| D_xyz - Directional Arrhenius D |
| D_PT - PT Arrhenius D sigma_PT - PT Arrhenius sigma |
| doas - Density of atomistic states |
+-----------------------------------------------------------------------------------------------+
| MD & Structural Analysis |
+-----------------------------------------------------------------------------------------------+
| thermo - thermo info in thermo.out thermo2/3 - Thermo in different styles |
| rdf - Radial distribution function rdf_pmf - Potential of mean force |
| vac - Velocity autocorrelation cohesive - Cohesive energy curve |
| xrd - X-ray diffraction plane-grid - Displacement plane grid |
| xrd_comp - Compare XRD |
+-----------------------------------------------------------------------------------------------+
| Heat Transport |
+-----------------------------------------------------------------------------------------------+
| emd - EMD results emd2 - EMD all directions |
| nemd - NEMD results hnemd - HNEMD results |
| viscosity - Viscosity |
+-----------------------------------------------------------------------------------------------+
| Phonons |
+-----------------------------------------------------------------------------------------------+
| pdos - VAC and PDOS phonon - Phonon band structure |
| phonon_comp - Compare phonon band structures |
+-----------------------------------------------------------------------------------------------+
NEP 训练与预测
train、prediction、train_density 和 parity_density 绘图还会在终端
输出能量、力和应力的 R^2、MAE 与 RMSE 表格。若没有有效的应力数据，
应力项显示为 N/A。
plt_train.py
可视化 NEP 训练过程，包括 loss 曲线、RMSE 演化，以及能量/力/virial 的 DFT vs NEP parity plot。
输入文件： loss.out、energy_train.out、force_train.out，以及优先读取的
stress_train.out 或回退使用的 virial_train.out
plt_prediction.py
可视化 prediction 模式对 train.xyz 中结构生成的 NEP 预测结果。
prediction 模式的 parity 数据仍写入以 _train.out 结尾的文件。
输入文件： energy_train.out、force_train.out，以及优先读取的
包含有效行的 stress_train.out，或回退使用的 virial_train.out
plt_train_test.py
将训练集和测试集的 parity plot 合并显示。
输入文件： energy_train.out、force_train.out、stress_train.out、
energy_test.out、force_test.out 和 stress_test.out
plt_parity_density.py
生成基于密度的 parity plot，适用于大数据集（散点图过于密集时更易阅读）。
输入文件： energy_train.out、force_train.out，以及优先读取的
stress_train.out 或回退使用的 virial_train.out
plt_force_errors.py
参考 Liu et al. 的方法绘制力误差评估指标。
输入文件： force_train.out
显示指标： - 力大小误差 (delta_F) - 力角度误差 (delta_theta) - 误差分布
plt_nep_restart.py
可视化 nep.restart 文件中存储的参数。
输入文件： nep.restart
plt_charge.py
绘制 qNEP 模型的电荷分布。
输入文件： train.xyz 和 charge_train.out
重要提示： 确保训练集和电荷输出的原子排序一致。建议使用全 batch 训练或先运行预测步骤。
plt_born_charge.py
为训练集和测试集创建 Born 有效电荷 (BEC) 的 parity plot。全零参考 BEC 的结构会被过滤。
输入文件： bec_train.out；可选 bec_test.out
热力学量
plt_thermo.py
综合可视化热力学性质的主脚本。
输入文件： thermo.out
plt_thermo2.py & plt_thermo3.py
不同风格的热力学量可视化。
输入文件： thermo.out
扩散和离子输运
plt_msd.py
绘制各方向的均方位移 (MSD)。
输入文件： 前四列为时间和 MSD_x/y/z 的 msd.out。这包括
gpumdkit.sh -calc msd 生成的四列输出，以及 GPUMD compute_msd 输出的前四列。
图中的斜率使用 MSD 数据中间 40%–80% 的区间拟合。
plt_msd_all.py
当 GPUMD 中使用 all_groups 时，分别绘制每种原子的 MSD。
输入文件： msd.out（需要使用 all_groups 选项计算）
要求： run.in 中的 compute_msd 命令必须使用 all_groups。多个分组时，
GPUMD 会追加分组数据；请检查其布局，不要假定文件具有单分组结果的七列。
plt_msd_convergence_check.py
检查不同时间窗口下 MSD 计算的收敛性。
输入文件： msd_step*.out（需要在 compute_msd 中使用 save_every 选项）
要求： 在 compute_msd 命令中使用 save_every。
用途： 验证 MSD 是否已充分收敛以准确计算扩散系数。
plt_sdc.py
绘制自扩散系数 (SDC) 随时间的变化。
输入文件： GPUMD compute_msd 生成的单分组七列 msd.out：时间、
MSD_x/y/z 和 SDC_x/y/z。-calc msd 生成的四列文件不能用于该绘图。
plt_msd_sdc.py
并排绘制 MSD 和自扩散系数（SDC）。图中的斜率使用 MSD 数据中间 40%–80% 的区间拟合；右图插图展示 SDC 数据最后 80% 的部分，并叠加移动平均曲线。
输入文件： GPUMD compute_msd 生成的单分组七列 msd.out：时间、
MSD_x/y/z 和 SDC_x/y/z。-calc msd 生成的四列文件不能用于该绘图。
plt_arrhenius_d.py
创建 Arrhenius 扩散系数图（log10 D vs 1000/T）。
输入文件： *K/msd.out（每个温度子目录下的 msd.out）
输出示例：
T: 300K, D_total: 1.001e-07 cm2/s
T: 350K, D_total: 4.184e-07 cm2/s
T: 400K, D_total: 1.027e-06 cm2/s
Ea: 0.230 eV
plt_arrhenius_d_PT.py
在用户指定的相变温度两侧绘制分段 Arrhenius 扩散系数图。相变温度点同时纳入
LowT（T <= Tc）和 HighT（T >= Tc）两段拟合。
输入文件： *K/msd.out
图例会直接标出两段活化能，例如 HighT (xx eV) 和 LowT (xx eV)。
plt_arrhenius_sigma.py
创建 Arrhenius 离子电导率图（ln(σ·T) vs 1000/T）。
输入文件： 每个 *K/ 目录中的 thermo.out 和 msd.out；首个温度目录中的
model.xyz 以及可选的 run.in
plt_arrhenius_sigma_PT.py
在用户指定的相变温度两侧绘制分段 Arrhenius 离子电导率图。相变温度点同时纳入
LowT（T <= Tc）和 HighT（T >= Tc）两段拟合。300 K 电导率使用与
300 K 位于相变温度同一侧的分支外推。
输入文件： 每个 *K/ 目录中的 thermo.out 和 msd.out；首个温度目录中的
model.xyz 以及可选的 run.in
图例会直接标出两段活化能，例如 HighT (xx eV) 和 LowT (xx eV)。
热输运
plt_emd.py
分析并绘制平衡分子动力学 (EMD) 热导率。
输入文件： GPUMD 的 EMD 输出文件
plt_emd2.py
在同一幅图中绘制 x、y、z 三个方向的热流关联函数和 EMD 总热导率。该功能使用与
plt_emd.py 相同的 run.in、hac.out 和平均规则。
输入文件： GPUMD 的 EMD 输出文件
HAC 图使用对数相关时间轴，同时在纵轴保留 HAC 的正负号。物理上为零的 方向会显示为零曲线。输出的不确定度沿用旧版规则，即后半段窗口波动除以 HAC 重复次数的平方根；它不是独立轨迹之间的标准误差。
plt_nemd.py
可视化非平衡分子动力学 (NEMD) 热输运性质。
输入文件： GPUMD 的 NEMD 输出文件
参数说明：
| 参数 | 说明 |
|---|---|
real_length |
传热区实际长度（nm），设为 Auto 可自动计算 |
scale_eff_size |
有效截面积缩放因子（默认：1）。三维体相用 1；含真空层的低维体系用 S_box / S_eff |
cutoff_freq |
SHC 计算的截止频率（THz，默认：60） |
save |
可选，保存图片为 nemd.png |
注意： 如果没有 SHC 数据，使用 save 时请将 scale_eff_size 和 cutoff_freq 设为任意占位数字。
plt_hnemd.py
绘制均匀非平衡分子动力学 (HNEMD) 结果。
输入文件： GPUMD 的 HNEMD 输出文件
参数说明：
| 参数 | 说明 |
|---|---|
scale_eff_size |
有效截面积缩放因子（默认：1） |
cutoff_freq |
SHC 计算的截止频率（THz，默认：60） |
save |
可选，保存图片为 hnemd.png |
注意： 如果没有 SHC 数据，使用 save 时请将 scale_eff_size 和 cutoff_freq 设为任意占位数字。
结构分析
plt_rdf.py
绘制径向分布函数 (RDF)，展示原子对关联。
输入文件： rdf.out
完整 RDF 输出：
单对 RDF：
plt_xrd.py
绘制计算器 413 生成的 X 射线衍射（XRD）输出。
输入文件： 默认读取 xrd.out；也可以将其他 XRD 输出文件路径作为第一个参数传入。
绘图脚本直接读取数值数据的第 2 列（索引 1）作为角度，第 4 列（索引 3）作为强度。
以 # 开头的说明行会被忽略，不进行平滑或重新归一化。
绘图脚本会检查计算器 413 写出的文件头和四列数据格式。如果格式无法识别，
程序会停止并提示使用 gpumdkit.sh -> 4 -> 413 重新生成 XRD 文件。
使用 save 时，图片保存为当前工作目录下的 xrd.png。
示例：
Gallery 中的示例图使用独立流程以 100 DPI 生成；正式脚本显示时使用 150 DPI， 保存图片时使用不低于 300 DPI。
plt_xrd_comp.py
比较当前工作目录下多个温度目录中的 XRD 曲线。每个目录必须命名为
<temperature>K，并包含由计算器 413 写出的 xrd.out。图像按照高温在上、
低温在下的顺序堆叠显示。
gpumdkit.sh -plt xrd 读取并绘制已有的 xrd.out，不会生成该文件。请先使用
计算器 413 生成各温度目录中的 xrd.out；如果需要检查单个温度的曲线，可以
先在对应的温度目录中执行 -plt xrd，再进行温度对比。
请在包含多个 *K 子目录的目录中执行以下命令；该命令不接受目录参数：
使用 save 时，图片保存为当前工作目录下的 xrd_comp.png。脚本会按照计算器
413 的输出格式检查发现的每个 xrd.out；如果文件格式错误，程序会停止。该对比
图不添加 Gallery 示例。
plt_rdf_pmf.py
绘制 RDF 与平均力势 (PMF) 的组合图。
输入文件： rdf.out
plt_vac.py
绘制速度自相关函数 (VAC)。可用于分析声子性质和原子动力学。
输入文件： GPUMD compute_sdc 写入的 sdc.out（绘图脚本会从该文件中读取
VAC 相关列）。该文件与 -plt sdc、-plt msd_sdc 读取的 msd.out 不同。
输出： 交互式图表或 vac.png（使用 save 选项时）
plt_cohesive.py
从 cohesive.out 绘制内聚能曲线。可用于分析晶格稳定性和平衡晶格常数。
输入文件： cohesive.out（各向同性缩放因子 vs 内聚能）
输出： 交互式图表或 cohesive.png（使用 save 选项时）
plt_net_force.py
绘制结构上的净力分布，可用于识别问题构型。
输入文件： train.xyz（extxyz 格式）
参考文献： arXiv:2510.19774
声子
plt_phonon.py
绘制由计算器 414 生成的声子谱。绘图脚本会直接读取 line-mode 格式的
QPOINTS 文件中的 Q 点路径和高对称点标签，因此不需要在脚本中重复写死
路径。
输入文件： phonon_NEP.dat 和 QPOINTS
计算步骤使用交互模式：
Python 页面会依次询问原胞结构（默认 PRIMCELL.vasp）、NEP 模型（默认
nep.txt）、路径文件（默认 QPOINTS）、超胞、位移幅度和输出文件名
（默认 phonon_NEP.dat）。该功能除了 GPUMDkit/Calorine 的常规依赖外，还
需要安装 phonopy。
绘图命令：
不同的 Q 点路径段会分别绘制，避免在路径断点处产生伪连接。类似 S|S₀ 的
边界标签会合并在同一个横坐标位置；标签默认保持同一高度，只有相邻标签拥挤
时才通过横向对齐尽量分开。
plt_phonon_comp.py
比较两个或多个声子谱文件。图例会从文件名自动读取：phonon_NEP.dat 显示
为 NEP，phonon_DFT.dat 显示为 DFT，phonon_MACE.dat 显示为 MACE。
gpumdkit.sh -plt phonon_comp phonon_DFT.dat phonon_NEP.dat save
gpumdkit.sh -plt phonon_comp phonon_DFT.dat phonon_NEP.dat phonon_MACE.dat \
--qpoints QPOINTS save
默认读取 QPOINTS 作为路径文件；如果路径文件名称不同，可以使用
--qpoints FILE 指定。两个文件比较时，DFT 使用灰色实线，NEP 使用砖红色
虚线；增加其他模型时会自动使用其他配色和线型。所有对比文件的 q 点距离
必须一致；只有行数相同并不足以保证路径一致。
plt_pdos.py
计算并绘制归一化的速度自相关函数 (VAC)、声子态密度 (PDOS) 和热容 (Cv)。
输入文件： model.xyz、run.in、dos.out、mvac.out
热容输出：
描述符、Dimer 和其他分析
plt_descriptors.py
使用降维方法（PCA 或 UMAP）可视化高维 NEP 描述符。
输入文件： descriptors.npy（由 gpumdkit.sh -calc des 生成）
方法：
- pca — 主成分分析
- umap — 统一流形逼近与投影
# 先计算描述符
gpumdkit.sh -calc des train.xyz descriptors.npy nep.txt Li
# 再可视化
gpumdkit.sh -plt des pca descriptors.npy
gpumdkit.sh -plt des umap descriptors.npy
plt_dimer.py
绘制二聚体相互作用曲线。将两个原子放入立方盒子（30 Å），使用 NEP 模型计算势能和力随距离的变化。
输入文件： nep.txt
参考文献： J. Chem. Inf. Model. 2026, 66, 3, 1406-1413
plt_doas.py
绘制 Wang et al. 提出的原子态密度 (DOAS)。
输入文件： doas.out（由 gpumdkit.sh -calc doas 计算）
极性材料的 Plane-Grid 绘图
此工作流将位移或极化数据映射到网格上，并绘制选定平面的轮廓。详细用法和实际案例请参见 极性材料分析。
依赖：
典型前置步骤：
gpumdkit.sh -calc nlist -i model.xyz -c 4 -n 12 -C Pb Sr -E O
gpumdkit.sh -calc disp -i movie.xyz -n nl-Pb_Sr-O.dat -o displacements.dat
gpumdkit.sh -calc avg-struct -i movie.xyz -l 0.2 -o averaged_structure.xyz
使用方法：
gpumdkit.sh -plt plane-grid -i averaged_structure.xyz -d displacements.dat -e Pb Sr
gpumdkit.sh -plt plane-grid -i averaged_structure.xyz -d displacements.dat -e Pb Sr --select-xy 0 1
快速参考表
| 命令 | 输入文件 | 用途 |
|---|---|---|
train |
loss.out, *_train.out |
NEP 训练结果 |
prediction / test |
*_train.out |
train.xyz 的 prediction 模式 parity 结果 |
train_test |
*_train.out, *_test.out |
合并 parity plot |
parity_density |
*_train.out |
密度 parity plot |
force_errors |
force_train.out |
力误差指标 |
restart |
nep.restart |
重启文件参数 |
charge |
train.xyz, charge_train.out |
电荷分布 |
born_charge / bec |
bec_train.out, 可选 bec_test.out |
Born 有效电荷 |
thermo |
thermo.out |
热力学量 |
msd |
-calc msd 生成的四列 msd.out，或 GPUMD compute_msd 输出的前四列 |
均方位移 |
msd_all |
msd.out (all_groups) |
全组分 MSD |
msd_conv |
msd_step*.out |
MSD 收敛性检查 |
sdc |
GPUMD compute_msd 单分组七列 msd.out |
自扩散系数 |
msd_sdc |
GPUMD compute_msd 单分组七列 msd.out |
MSD 和 SDC 合并 |
arrhenius_d / D |
*K/msd.out |
Arrhenius 扩散系数 |
arrhenius_sigma / sigma |
*K/{thermo.out, msd.out}，以及首个温度目录中的 model.xyz 和可选 run.in |
Arrhenius 离子电导率 |
D_PT |
*K/msd.out 以及相变温度 |
相变温度两侧的分段 Arrhenius 扩散系数 |
sigma_PT |
*K/{thermo.out, msd.out}，首个目录中的 model.xyz、可选 run.in 以及相变温度 |
相变温度两侧的分段 Arrhenius 离子电导率 |
rdf |
rdf.out |
径向分布函数 |
rdf_pmf |
rdf.out |
RDF + 平均力势 |
xrd |
xrd.out |
XRD 强度曲线 |
xrd_comp |
*K/xrd.out |
不同温度的 XRD 对比 |
vac |
sdc.out |
速度自相关 |
cohesive |
cohesive.out |
内聚能曲线 |
net_force |
train.xyz |
净力分布 |
doas |
doas.out |
原子态密度 |
des |
descriptors.npy |
描述符 PCA/UMAP |
dimer |
nep.txt |
二聚体能量/力曲线 |
pdos |
model.xyz, run.in, dos.out, mvac.out |
VAC 和 PDOS |
emd |
EMD 输出 | 单个方向的 EMD 热导率 |
emd2 |
EMD 输出 | 全部方向的 EMD 热导率 |
nemd |
NEMD 输出 | NEMD 热输运 |
hnemd |
HNEMD 输出 | HNEMD 热输运 |
viscosity |
粘度输出 | 粘度 |