📊 绘图脚本
绘图模块包含一系列 Python 脚本，用于可视化 GPUMD、NEP 和 GPUMDkit 计算器产生的数据。所有图表均可交互显示或保存为高分辨率 PNG 文件。
脚本位置： Scripts/plt_scripts/
快速入口
gpumdkit.sh -plt # 显示所有绘图选项
gpumdkit.sh -plt <type> # 生成指定图表
gpumdkit.sh -plt <type> save # 保存为 PNG
gpumdkit.sh -plt <type> -h # 显示特定图表的帮助
运行 gpumdkit.sh -plt 会显示绘图命令菜单：
+-----------------------------------------------------------------------------------------------+
| GPUMDkit <version> PLOT & VISUALIZATION TOOLS |
+-----------------------------------------------------------------------------------------------+
| Usage: gpumdkit.sh -plt <type> Help: gpumdkit.sh -plt <type> -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 lr - Learning rate for gnep |
+-----------------------------------------------------------------------------------------------+
| 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 |
| 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 |
| net_force - Net force distribution plane-grid - Displacement plane grid |
+-----------------------------------------------------------------------------------------------+
| Heat Transport |
+-----------------------------------------------------------------------------------------------+
| emd - EMD results nemd - NEMD results |
| hnemd - HNEMD results viscosity - Viscosity |
+-----------------------------------------------------------------------------------------------+
| Phonons |
+-----------------------------------------------------------------------------------------------+
| pdos - VAC and PDOS |
+-----------------------------------------------------------------------------------------------+
NEP 训练与预测
plt_train.py
可视化 NEP 训练过程，包括 loss 曲线、RMSE 演化，以及能量/力/virial 的 DFT vs NEP parity plot。
输入文件： loss.out、energy_train.out、force_train.out、virial_train.out
plt_prediction.py
可视化测试集上的 NEP 预测结果。
输入文件： energy_test.out、force_test.out、virial_test.out
plt_train_test.py
将训练集和测试集的 parity plot 合并显示。
输入文件： energy_train.out、force_train.out、virial_train.out、energy_test.out、force_test.out、virial_test.out
plt_parity_density.py
生成基于密度的 parity plot，适用于大数据集（散点图过于密集时更易阅读）。
输入文件： energy_train.out、force_train.out、virial_train.out
plt_force_errors.py
参考 Liu et al. 的方法绘制力误差评估指标。
输入文件： force_train.out
显示指标： - 力大小误差 (delta_F) - 力角度误差 (delta_theta) - 误差分布
plt_learning_rate.py
可视化 gnep 训练过程中的学习率变化。
输入文件： loss.out
注意： 仅适用于 gnep 训练过程。
plt_nep_restart.py
可视化 nep.restart 文件中存储的参数。
输入文件： nep.restart
plt_charge.py
绘制 qNEP 模型的电荷分布。
输入文件： 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.out
plt_msd_all.py
当 GPUMD 中使用 all_groups 时，分别绘制每种原子的 MSD。
输入文件： msd.out（需要使用 all_groups 选项计算）
要求： run.in 中的 compute_msd 命令必须使用 all_groups。
plt_msd_convergence_check.py
检查不同时间窗口下 MSD 计算的收敛性。
输入文件： msd_step*.out（需要在 compute_msd 中使用 save_every 选项）
要求： 在 compute_msd 命令中使用 save_every。
用途： 验证 MSD 是否已充分收敛以准确计算扩散系数。
plt_sdc.py
绘制自扩散系数 (SDC) 随时间的变化。
输入文件： msd.out
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_sigma.py
创建 Arrhenius 离子电导率图（ln(σ·T) vs 1000/T）。
输入文件： *K/{model.xyz, run.in, thermo.out, msd.out}（每个温度子目录）
热输运
plt_emd.py
分析并绘制平衡分子动力学 (EMD) 热导率。
输入文件： GPUMD 的 EMD 输出文件
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_rdf_pmf.py
绘制 RDF 与平均力势 (PMF) 的组合图。
输入文件： rdf.out
plt_vac.py
绘制速度自相关函数 (VAC)。可用于分析声子性质和原子动力学。
输入文件： sdc.out（绘图脚本会从该文件中读取 VAC 相关列）
输出： 交互式图表或 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_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
gpumdkit.sh -plt des umap
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 |
*_test.out |
NEP 预测结果 |
train_test |
*_train.out, *_test.out |
合并 parity plot |
parity_density |
*_train.out |
密度 parity plot |
force_errors |
force_train.out |
力误差指标 |
lr |
loss.out (gnep) |
学习率 |
restart |
nep.restart |
重启文件参数 |
charge |
charge_train.out |
电荷分布 |
born_charge / bec |
bec_train.out, bec_test.out |
Born 有效电荷 |
thermo |
thermo.out |
热力学量 |
msd |
msd.out |
均方位移 |
msd_all |
msd.out (all_groups) |
全组分 MSD |
msd_conv |
msd_step*.out |
MSD 收敛性检查 |
sdc |
msd.out |
自扩散系数 |
arrhenius_d / D |
*K/msd.out |
Arrhenius 扩散系数 |
arrhenius_sigma / sigma |
*K/{model.xyz, run.in, thermo.out, msd.out} |
Arrhenius 离子电导率 |
rdf |
rdf.out |
径向分布函数 |
rdf_pmf |
rdf.out |
RDF + 平均力势 |
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 热导率 |
nemd |
NEMD 输出 | NEMD 热输运 |
hnemd |
HNEMD 输出 | HNEMD 热输运 |
viscosity |
粘度输出 | 粘度 |