📋 命令参考

本页列出 GPUMDkit 稳定的命令行快捷入口。对于参数较多、需要选择的任务，也可以使用交互模式。

源表维护在 docs/command_reference.tsv。

如果你刚开始使用 GPUMDkit，请先阅读快速入门；需要让 Agent 协助处理任务时，请先看 GPUMDkit Agent Skill；远程网页访问请参阅远程 Web 控制台。只有提供了对应帮助接口的命令才支持 -h；其他命令请使用 gpumdkit.sh -h、相应模块的帮助或交互模式。

`gpumdkit.sh -h` 输出

 +-------------------------------------------------------------------------------------------------------+
 |                          GPUMDkit 1.5.8 (2026-09-29)       Command Help                               |
 +-------------------------------------------------------------------------------------------------------+
 |                                          MAIN FUNCTIONS                                               |
 +-------------------------------------------------------------------------------------------------------+
 | -h            Show this help table            | -plt <type>        Plot and visualization tools       |
 | -calc <type>  Calculator tools                | -time <gpumd|wpe|nep|gnep>  Time-consuming analyzer   |
 | -update       Update GPUMDkit                 | -clean             Clean extra files in current dir   |
 | -skill        Show GPUMDkit agent skill info  | -doctor            Check Python environment           |
 | -prediction   Write NEP prediction .out files | -prediction_dpa    Write DPA prediction .out files    |
 | -server       Start the GPUMDkit web server   |                                                       |
 +-------------------------------------------------------------------------------------------------------+
 |                                         FORMAT CONVERSION                                             |
 +-------------------------------------------------------------------------------------------------------+
 | -out2xyz      OUTCAR -> extxyz (shell)        | -out2xyz_bec       OUTCAR -> extxyz with BEC          |
 | -out2exyz     OUTCAR -> extxyz (python)       | -xyz2dp            extxyz -> DeepMD npy               |
 | -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               |
 +-------------------------------------------------------------------------------------------------------+
 |                                            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     |
 | -shift_energy Interactive energy shift        |                                                       |
 +-------------------------------------------------------------------------------------------------------+
 | 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`	清理当前目录中的冗余文件
`-server`	`gpumdkit.sh -server [port] [-b <address>] [-pw <password>]`	以当前目录为根目录启动 Web 控制台；远程访问建议使用 SSH 隧道。
`-prediction`	`gpumdkit.sh -prediction <input.xyz> <nep.txt> [workers]`	写入 NEP 格式的能量、力、应力和 virial 预测文件
`-prediction_dpa`	`gpumdkit.sh -prediction_dpa <input.xyz> <dpa_model>`	在当前目录写入 DPA 训练集预测文件

格式转换

命令	语法	说明
`-out2xyz`	`gpumdkit.sh -out2xyz <dir>`	OUTCAR 转 extxyz，shell 版本
`-out2xyz_bec`	`gpumdkit.sh -out2xyz_bec <dir>`	OUTCAR 转带 BEC 标签的 extxyz
`-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>`	提取单帧（索引从 1 开始）
`-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 性质预测
`-prediction`	`gpumdkit.sh -prediction <input.xyz> <nep.txt> [workers]`	NEP 格式预测输出文件
`-prediction_dpa`	`gpumdkit.sh -prediction_dpa <input.xyz> <dpa_model>`	DPA 训练集预测输出文件
`-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 局域极化

-calc nep 会生成包含 NEP 预测性质的 extxyz 输出文件；-prediction 则会写出训练和验证流程使用的独立 NEP 预测文件。

分析工具

命令	语法	说明
`-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>`	概率密度分析

可视化

使用：

gpumdkit.sh -plt <type> [options]
gpumdkit.sh -plt -h

常用类型包括 train、prediction（别名：test）、thermo、msd、sdc、rdf、emd、emd2、nemd、hnemd、pdos 和 plane-grid。

工具

命令	语法	说明
`-time`	`gpumdkit.sh -time <gpumd\\|wpe\\|nep\\|gnep>`	监控 GPUMD、WPE、NEP 或 GNEP 进度
`-nep_modifier`	`gpumdkit.sh -nep_modifier [nep.txt] [nep.restart\\|-] [nep.in\\|-]`	安全修改并导出 NEP4 模型文件包
`-pynep`	`gpumdkit.sh -pynep`	已弃用的 PyNEP FPS 采样

NEP 模型修改器

-nep_modifier 提供 NEP4 模型的容量调整、元素增删和文件包导出功能，需要 calorine >= 3.4。扩展、缩减和添加元素还需要与模型匹配的 nep.restart；建议同时提供源 nep.in。

gpumdkit.sh -nep_modifier
gpumdkit.sh -nep_modifier models/nep.txt models/nep.restart models/nep.in
gpumdkit.sh -nep_modifier -h

不载入 restart 时，可用 - 占位，仍可移除或保留指定元素。继续训练时应使用同一导出文件包中的 .in、.txt 和 .restart，并在实际使用前重新训练和验证。

必须引用 calorine

该 GPUMDkit 功能直接调用 calorine 的模型修改实现。科研工作中使用此功能时，应按照 calorine 开发者的要求引用：

E. Lindgren, J. M. Rahm, E. Fransson, F. Eriksson, N. Österbacka, Z. Fan, and 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 官方模型修改教程。