🚀 快速入门
本页帮助你安装 GPUMDkit 并运行第一个命令。你可以通过交互菜单或直接使用命令行选项来使用 GPUMDkit。
功能简介
GPUMDkit 为计算材料科学中的常见任务提供统一入口——格式转换、结构分析、性质计算和可视化——无需编写自定义脚本。
准备工作
1. 使用 Conda 安装（推荐）
该方式会安装 GPUMDkit 及其标准依赖，无需克隆仓库或配置环境变量。
部分功能需要额外安装可选依赖：
2. 从源码安装（可选）
如需使用源码，请克隆仓库并运行安装脚本：
安装脚本会写入 GPUMDkit_path 和 PATH 设置，并在当前 shell 中加载。默认写入 ~/.bashrc；如果当前 shell 是 zsh，则写入 ~/.zshrc。如果检测到已有 GPUMDkit 路径，安装脚本会打印旧路径并询问是否替换；修改 rc 文件前会先创建备份。
典型安装输出：
======================================================
GPUMDkit Installation
======================================================
[1/4] Detecting GPUMDkit directory...
/path/to/GPUMDkit
[2/4] Detecting shell configuration...
Target: /Users/you/.bashrc
Adding environment variables to /Users/you/.bashrc
Success: Environment variables added.
[3/4] Setting executable permissions...
Added executable permission to gpumdkit.sh
[4/4] Loading environment...
======================================================
Installation Complete! GPUMDkit is ready to use.
======================================================
如果之前已经安装过 GPUMDkit，可能会看到：
Existing GPUMDkit configuration found.
Existing path(s):
- /old/path/to/GPUMDkit
New path:
- /new/path/to/GPUMDkit
Replace the existing GPUMDkit configuration with the new path? [y/N]:
3. 验证安装
此命令会打印帮助表，列出所有可用选项。
更实用的首次检查是运行：
终端会分别显示 Environment、Common packages 和 Optional packages。
可选包显示 MISS 并不表示安装失败：只有需要对应功能时才安装。例如，DeepMD
转换需要 dpdata，NEP 辅助计算会使用 calorine。这样可以在开始流程前先定位缺少的模块。
运行前先读懂命令
CLI 示例中使用以下记号：
| 记号 | 含义 | 示例 |
|---|---|---|
<必填项> |
替换为必须提供的实际值；不要输入尖括号。 | <output.xyz> → model.xyz |
[可选项] |
可以省略；脚本将采用文档说明的行为。 | [max_corr_steps] |
... |
后面可以跟随一个或多个值。 | <element...> |
对于不熟悉的 Python 命令，先让命令本身解释参数。例如：
$ gpumdkit.sh -calc msd -h
Usage: gpumdkit.sh -calc msd <extxyz_file> <element_symbol> <dt_fs> [max_corr_steps]
Arguments:
extxyz_file Path to the input extxyz trajectory file
element_symbol Chemical symbol (e.g., Li, O, Na)
dt_fs Time step between consecutive frames (fs)
max_corr_steps Max correlation lag steps (optional)
这里的 dt_fs 是相邻已写出轨迹帧之间的时间间隔（fs），不会从 MD 输入文件中自动推断；应以自己的轨迹写出设置为准。绘图模块请用 gpumdkit.sh -plt -h 查看图类型；各图参数的位置见绘图脚本。
交互菜单中的 ------------>> 表示等待输入。许多 CLI 命令结束后还会打印 Code path:，可据此定位产生结果或报错的实现脚本。
交互模式
打开主菜单：
____ ____ _ _ __ __ ____ _ _ _
/ ___| _ \| | | | \/ | _ \| | _(_) |_
| | _| |_) | | | | |\/| | | | | |/ / | __|
| |_| | __/| |_| | | | | |_| | <| | |_
\____|_| \___/|_| |_|____/|_|\_\_|\__|
GPUMDkit Version 1.5.7 (dev) (2026-08-03)
Core Developer: Zihan YAN (yanzihan@westlake.edu.cn)
Main Contributors: Denan LI, Xin WU, Zhoulin LIU & Chen HUA
---------------------- GPUMD ------------------------
1) Format Conversion 2) Sample Structures
3) Workflow 4) Calculators
5) Analyzer 6) Visualization
7) Utilities 8) Help
0) Exit
------------>>
Input the function number:
按数字选择模块。每个模块提供包含具体功能的子菜单。
命令行模式
直接命令使用固定的位置参数：
示例：
gpumdkit.sh -pos2exyz POSCAR model.xyz
gpumdkit.sh -plt train
gpumdkit.sh -calc msd trajectory.xyz Li 10
第一个示例读取 POSCAR，写出 model.xyz。
Hello World 示例
一个最小化的端到端检查，确认安装是否正常——创建一个极小的硅 POSCAR，转换为 extxyz，并查看输出：
cat > POSCAR << 'EOF'
Si
1.0
0 2.715 2.715
2.715 0 2.715
2.715 2.715 0
Si
1
direct
0 0 0
EOF
gpumdkit.sh -pos2exyz POSCAR model.xyz
head model.xyz
如果 model.xyz 显示一个 Si 原子及晶格信息，说明安装成功。
什么是 extxyz？ extxyz 是扩展 XYZ 格式：第 1 行是原子数，第 2 行包含晶格及结构级属性（按需包含能量/力/维里），第 3 行及以后是每个原子及其原子级属性。它是 NEP 的原生训练数据格式。
常见示例
POSCAR 转 extxyz
添加 GPUMD group 标签
group 标签用于一些需要原子分组的 GPUMD 相关流程和分析，例如特定元素的 MSD 或扩散性质计算。
绘制 NEP 训练结果
绘制 NEP 测试集结果
绘制热力学量
绘制 MSD 和自扩散系数
说明
- 使用
gpumdkit.sh -h查看所有可用选项。 - Python 后端命令可使用
gpumdkit.sh -<选项> -h查看帮助；使用gpumdkit.sh -plt -h列出绘图类型，各绘图脚本的参数位置并不统一。 - 各模块的详细用法请参见首页中链接的对应教程页面。