Skip to content

🚀 快速入门

本页带你完成 GPUMDkit 的安装、首次检查和一个独立的小练习，然后根据已有数据进入下一步。

功能简介

GPUMDkit 将格式转换、结构分析、性质计算和可视化等计算材料学常见任务统一到一个命令行工具中，无需另写脚本。

准备工作

先安装 GPUMDkit，再进行命令检查。推荐使用 Conda：

conda create -n gpumdkit -c gpumdkit -c conda-forge gpumdkit
conda activate gpumdkit

这种方式会安装 GPUMDkit 及其标准依赖，不需要先克隆仓库或配置环境变量。

2. 检查安装

gpumdkit.sh -h
gpumdkit.sh -doctor

-h 会列出可用选项；-doctor 会检查 Python 环境，并分别报告环境、常用包和可选包的状态。可选包显示 MISS 不代表安装失败，只有使用对应功能时才需要安装它们。

第一个练习：转换一个 POSCAR

请在新的练习目录中运行，避免覆盖已有文件。

(
set -e
mkdir gpumdkit-first-check && cd gpumdkit-first-check || exit 1
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 原子及晶格信息，说明这次 POSCAR 到 extxyz 的转换和输出检查已经成功。

extxyz 是扩展 XYZ 格式：第一行是原子数，第二行包含晶格和结构级属性，后续行记录每个原子的元素、坐标及其他原子级属性；它是 NEP 使用的原生训练数据格式。

已有数据：选择下一步

如果你已经有结构或轨迹，不必重复上面的练习。回到教程首页，在“常见任务”表中按目标进入格式转换、结构采样、分析、计算器、绘图或工作流教程；具体页面会说明所需输入、输出和适用条件。

可选依赖与 Agent Skill

部分功能需要额外安装可选依赖：

pip install neptrain calorine

安装包同时包含中英文 Agent Skill。运行下面的命令可查看其安装路径，以及在 Agent 客户端中配置 Skill 的方法：

gpumdkit.sh -skill

从源码安装（可选）

如果需要使用或修改源码，请克隆仓库并运行安装脚本：

git clone https://github.com/zhyan0603/GPUMDkit.git
cd GPUMDkit
source ./install.sh

安装脚本会根据 $SHELL 选择 shell 配置文件，将 GPUMDkit_path 和 PATH 设置写入其中，并在当前 shell 中加载。默认使用 ~/.bashrc；如果 $SHELL 指向 zsh，则使用 ~/.zshrc。如果检测到已有 GPUMDkit 路径，脚本会打印旧路径并询问是否替换；修改 rc 文件前会先创建备份。

运行前先读懂命令

CLI 示例中使用以下记号：

记号 含义 示例
<必填项> 替换为必须提供的实际值；不要输入尖括号。 <output.xyz> → model.xyz
[可选项] 可以省略；脚本将采用文档说明的行为。 [max_corr_steps]
... 后面可以跟随一个或多个值。 <element...>

对于不熟悉的 Python 命令，可以先运行它的 -h 查看参数说明。dt_fs 等时间参数应根据自己的轨迹写出设置确定，不会从 MD 输入文件中自动推断；绘图类型和参数位置请参见绘图脚本。

交互模式

运行 gpumdkit.sh 后，按数字选择模块；每个模块都有对应的子菜单。

命令行模式

直接命令使用固定的位置参数：

gpumdkit.sh -<选项> [参数...]

需要查看完整选项时，运行：

gpumdkit.sh -h

说明

  • 对于提供选项帮助的 Python 后端命令，可以使用 gpumdkit.sh -<选项> -h 查看帮助；使用 gpumdkit.sh -plt -h 列出绘图类型。各绘图脚本的参数位置并不统一。
  • 各模块的详细用法请参见教程首页中的任务导航。