📋 命令参考
本页列出 GPUMDkit 稳定的命令行快捷入口。对于参数较多、需要选择的任务，也可以使用交互模式。
源表维护在 docs/command_reference.tsv。
gpumdkit.sh -h 输出
+-------------------------------------------------------------------------------------------------------+
| GPUMDkit 1.5.7 (dev) (2026-08-03) Command Help |
+-------------------------------------------------------------------------------------------------------+
| MAIN FUNCTIONS |
+-------------------------------------------------------------------------------------------------------+
| -h Show this help table | -plt <type> Plot and visualization tools |
| -calc <type> Calculator tools | -time <gpumd|nep> Time-consuming analyzer |
| -update Update GPUMDkit | -clean Clean extra files in current dir |
| -skill Show GPUMDkit agent skill info | -doctor Check Python environment |
+-------------------------------------------------------------------------------------------------------+
| FORMAT CONVERSION |
+-------------------------------------------------------------------------------------------------------+
| -out2xyz OUTCAR -> extxyz (shell) | -out2exyz OUTCAR -> extxyz (python) |
| -cp2k2xyz CP2K log -> xyz | -xdat2exyz XDATCAR -> extxyz |
| -cif2pos cif -> POSCAR | -cif2exyz cif -> extxyz |
| -pos2exyz POSCAR -> extxyz | -exyz2pos extxyz -> POSCAR |
| -pos2lmp POSCAR -> LAMMPS data | -lmp2exyz LAMMPS dump -> extxyz |
| -traj2exyz ASE traj -> extxyz | -replicate Replicate structure |
| -addgroup Add group labels | -addweight Add structure weight in extxyz |
| -clean_xyz Clean extra info in extxyz | -get_frame Extract specific frame |
| -frame_range Extract frames by range | -dp2xyz DeepMD npy -> extxyz |
| -xyz2dp extxyz -> DeepMD npy | |
+-------------------------------------------------------------------------------------------------------+
| ANALYSIS |
+-------------------------------------------------------------------------------------------------------+
| -range Energy/force/virial statistics | -analyze_comp Analyze composition |
| -chem_species Analyze chemical species | -cbc Charge balance check |
| -min_dist Min distance (no PBC) | -min_dist_pbc Min distance with PBC |
| -filter_dist Filter by min_dist (no PBC) | -filter_dist_pbc Filter by min_dist (PBC) |
| -pda Probability density analysis | -filter_box Filter by box-edge length |
| -pynep Deprecated PyNEP sampling | -nep_modifier Modify NEP model interactively |
+-------------------------------------------------------------------------------------------------------+
| Python option help: gpumdkit.sh -<option> -h Plot list: gpumdkit.sh -plt -h |
+-------------------------------------------------------------------------------------------------------+
主命令
| 命令 | 语法 | 说明 |
|---|---|---|
-h |
gpumdkit.sh -h |
显示通用帮助 |
-doctor |
gpumdkit.sh -doctor |
检查 Python 环境和 GPUMDkit 相关软件包是否可用 |
-update |
gpumdkit.sh -update |
更新 GPUMDkit |
-clean |
gpumdkit.sh -clean |
清理当前目录中的冗余文件 |
格式转换
| 命令 | 语法 | 说明 |
|---|---|---|
-out2xyz |
gpumdkit.sh -out2xyz <dir> |
OUTCAR 转 extxyz，shell 版本 |
-out2exyz |
gpumdkit.sh -out2exyz <dir> |
OUTCAR 转 extxyz，Python 版本 |
-cp2k2xyz |
gpumdkit.sh -cp2k2xyz |
CP2K 输出转 xyz/extxyz |
-xdat2exyz |
gpumdkit.sh -xdat2exyz <XDATCAR> <output.xyz> |
XDATCAR 转 extxyz |
-cif2pos |
gpumdkit.sh -cif2pos <input.cif> <output.vasp> |
CIF 转 POSCAR/VASP |
-cif2exyz |
gpumdkit.sh -cif2exyz <input.cif> <output.xyz> |
CIF 转 extxyz |
-pos2exyz |
gpumdkit.sh -pos2exyz <POSCAR> <output.xyz> |
POSCAR 转 extxyz |
-exyz2pos |
gpumdkit.sh -exyz2pos <input.xyz> |
extxyz 多帧转 POSCAR 文件 |
-pos2lmp |
gpumdkit.sh -pos2lmp <POSCAR> <output.data> |
POSCAR 转 LAMMPS data |
-lmp2exyz |
gpumdkit.sh -lmp2exyz <dump> <element...> |
LAMMPS dump 转 extxyz |
-traj2exyz |
gpumdkit.sh -traj2exyz <input.traj> <output.xyz> |
ASE trajectory 转 extxyz |
-replicate |
gpumdkit.sh -replicate <input> <output> a b c |
按晶胞倍数扩胞 |
-replicate |
gpumdkit.sh -replicate <input> <output> <target_num> |
按目标原子数扩胞 |
-addgroup |
gpumdkit.sh -addgroup <POSCAR> <element...> |
添加 GPUMD group 标签 |
-addweight |
gpumdkit.sh -addweight <input.xyz> <output.xyz> <weight> |
添加结构权重 |
-get_frame |
gpumdkit.sh -get_frame <input.xyz> <frame_index> |
提取单帧 |
-clean_xyz |
gpumdkit.sh -clean_xyz <input.xyz> <output.xyz> |
清理 extxyz 冗余属性 |
-frame_range |
gpumdkit.sh -frame_range <input.xyz> <start_frac> <end_frac> |
按比例范围提取帧 |
-dp2xyz |
gpumdkit.sh -dp2xyz <input_dir/> [output.xyz] |
将 DeepMD npy 数据集转换为 extxyz |
-xyz2dp |
gpumdkit.sh -xyz2dp |
通过交互提示将带标签的 extxyz 转换为 DeepMD npy 数据 |
计算器
| 命令 | 语法 | 说明 |
|---|---|---|
-calc ionic-cond |
gpumdkit.sh -calc ionic-cond <element> <charge> |
离子电导率 |
-calc nep |
gpumdkit.sh -calc nep <input.xyz> <output.xyz> <nep.txt> |
NEP 性质预测 |
-calc des |
gpumdkit.sh -calc des <input.xyz> <output.npy> <nep.txt> <element> |
NEP 描述符 |
-calc doas |
gpumdkit.sh -calc doas <input.xyz> <nep.txt> <output.txt> |
原子态密度 |
-calc neb |
gpumdkit.sh -calc neb <initial.xyz> <final.xyz> <n_images> <nep.txt> |
基于 NEP 的 NEB |
-calc minimize |
gpumdkit.sh -calc minimize <structure> <nep.txt> [fmax] [max_steps] |
结构优化 |
-calc msd |
gpumdkit.sh -calc msd <trajectory.xyz> <element> <dt_fs> [max_corr_steps] |
从轨迹计算 MSD |
-calc nlist |
gpumdkit.sh -calc nlist [args...] |
邻居列表 |
-calc disp |
gpumdkit.sh -calc disp [args...] |
位移 |
-calc avg-struct |
gpumdkit.sh -calc avg-struct [args...] |
平均结构 |
-calc oct-tilt |
gpumdkit.sh -calc oct-tilt [args...] |
八面体倾斜 |
-calc pol-abo3 |
gpumdkit.sh -calc pol-abo3 [args...] |
ABO3 局域极化 |
分析工具
| 命令 | 语法 | 说明 |
|---|---|---|
-range |
gpumdkit.sh -range <input.xyz> <energy\|force\|virial> [hist] |
性质范围分析 |
-shift_energy |
gpumdkit.sh -shift_energy |
交互式能量参考平移 |
-analyze_comp |
gpumdkit.sh -analyze_comp <input.xyz> |
成分分析 |
-chem_species |
gpumdkit.sh -chem_species <input.xyz> |
元素列表 |
-cbc |
gpumdkit.sh -cbc <input.xyz> |
电荷平衡检查 |
-min_dist |
gpumdkit.sh -min_dist <input.xyz> |
无 PBC 最小距离 |
-min_dist_pbc |
gpumdkit.sh -min_dist_pbc <input.xyz> |
带 PBC 最小距离 |
-filter_dist |
gpumdkit.sh -filter_dist <input.xyz> <min_dist> |
距离过滤 |
-filter_dist_pbc |
gpumdkit.sh -filter_dist_pbc <input.xyz> <min_dist> |
带 PBC 距离过滤 |
-filter_box |
gpumdkit.sh -filter_box <input.xyz> <edge_limit> |
盒子边长过滤 |
-filter_value |
gpumdkit.sh -filter_value <input.xyz> <property> <threshold> |
性质阈值过滤 |
-filter_range |
gpumdkit.sh -filter_range <input.xyz> <element1> <element2> <min_dist> <max_dist> |
元素对距离范围过滤 |
-pda |
gpumdkit.sh -pda <ref_struct> <trajectory.xyz> <species> <interval> |
概率密度分析 |
可视化
使用：
常用类型包括 train、prediction（别名：test）、thermo、msd、sdc、rdf、emd、emd2、nemd、hnemd、pdos 和 plane-grid。
工具
| 命令 | 语法 | 说明 |
|---|---|---|
-time |
gpumdkit.sh -time <gpumd\|nep> |
监控 GPUMD 或 NEP 进度 |
-nep_modifier |
gpumdkit.sh -nep_modifier [nep.txt] [nep.restart\|-] [nep.in\|-] |
安全修改并导出 NEP4 模型文件包 |
-pynep |
gpumdkit.sh -pynep |
已弃用的 PyNEP FPS 采样 |
NEP 模型修改器
-nep_modifier 启动基于 calorine NEP 模型修改 API 的双栏引导式编辑器。它用于在已有 NEP4 模型基础上继续开发，例如增加模型容量、从基础模型中提取元素子集，或在不丢弃原有元素已学习参数的前提下加入新元素。
依赖与启动方式
该命令需要 calorine >= 3.4。扩展、缩减和添加元素还需要与模型匹配的 nep.restart，因为其中保存了 SNES 参数均值和搜索宽度。建议同时提供源 nep.in，以保留其中非架构类训练设置。
# 交互式询问文件；默认文件从所选 nep.txt 的同目录解析
gpumdkit.sh -nep_modifier
# 直接载入完整模型文件包
gpumdkit.sh -nep_modifier models/nep.txt models/nep.restart models/nep.in
# 不载入 restart；仍可移除元素或仅保留指定元素
gpumdkit.sh -nep_modifier models/nep.txt - models/nep.in
# 不导入 calorine，直接查看命令帮助
gpumdkit.sh -nep_modifier -h
各项功能的含义
| 菜单操作 | 用途及其对模型的影响 |
|---|---|
| Expand model capacity | 增加神经元，启用 4/5 体或 q_* 描述符项，或者添加电荷输出头。保留已有参数的训练均值，并初始化新增参数，以便继续优化。 |
| Reduce model capacity | 保留排名较高的神经元并舍弃其余神经元，禁用描述符项，或移除电荷输出头。它可以生成更小的起始模型，但必须在再训练后实际评估精度和速度。 |
| Add chemical species | 为新元素添加 ANN 子网络，以及所有涉及该元素的描述符权重对。新增参数尚未训练；显式 seed 用于保证初始化可复现。 |
| Remove chemical species | 删除指定元素及其 ANN 子网络和描述符权重对，适合待删除元素较少的情况。 |
| Keep selected species | 保留列出的元素并删除其余元素。从大型模型中提取少量元素时，该反向选择方式更方便。 |
| Inspect current model | 显示元素顺序、cutoff、描述符开关与维数、神经元和参数数量、restart 状态、ZBL 及 charge mode。 |
| Review pending changes | 写文件前查看全部已确认操作、参数、架构变化以及导出状态。 |
| Export model package | 为模型、可选 restart、更新后的输入及来源摘要选择统一且不冲突的文件后缀。 |
示例：可复现地扩展模型
载入文件包后输入 1，选择需要扩展的字段，再输入目标值。可以同时选择多个字段，calorine 会在一次 augment() 调用中完成。例如：
Input the function number:
------------>>
1
Input one or more choices, separated by spaces:
------------>>
1 4
Input target neuron count (current: 50):
------------>>
60
Use these SNES initialization defaults? (Y/n)
------------>>
y
Apply these changes? (y/N)
------------>>
y
该示例把神经元数从 50 调整为 60，并启用 q_112。选择 7 可以检查记录的参数和架构变化，再选择 8 导出。继续训练时，必须配套使用同一导出包中的 .in、.txt 和 .restart；沿用旧 nep.in 可能导致 restart 布局与修改后的参数数量不一致。
示例：提取或扩展元素模型
如需提取 Li-O 子模型，选择 5，输入 Li O，检查返回的元素顺序后导出。如需添加碳，选择 3，输入 C，然后提供明确的随机 seed。对于 typewise-cutoff 模型，程序还会询问碳元素的径向和角向 cutoff。这些 cutoff 是具有科学含义的模型选择，必须根据目标训练方案确定，工具不会替用户决定。
导出文件包括 *_modified.txt、载入 restart 时的 *_modified.restart、*_modified.in 和 *_modified.changes.txt。后续训练前，应使用准备执行训练的同一 NEP 版本检查生成的输入，并使用有代表性的参考数据重新训练和验证修改后的模型，再将其用于生产模拟。
必须引用 calorine
该 GPUMDkit 功能直接调用 calorine 的模型修改实现。科研工作中使用此功能时，应按照 calorine 开发者的要求引用：
E. Lindgren, J. M. Rahm, E. Fransson, F. Eriksson, N. Österbacka, Z. Fan 和 P. Erhart，“calorine: A Python package for constructing and sampling neuroevolution potential models”，Journal of Open Source Software 9(95)， 6264 (2024)，https://doi.org/10.21105/joss.06264。
更完整的说明见 NEP modifier README 和 calorine 官方模型修改教程。