VASP 辅助工具安装与环境配置指南

软件安装实战系列· 05

VASPKIT 1.5.1 + QVASP 2.25

从二进制部署、赝势映射，到多用户 modulefile 与完整验收

云算科技

高性能计算｜科研服务｜软件支持

版本：2026年7月

写在前面

VASP 编译成功，代表核心计算程序已经可用。真正开始日常科研后，用户还需要频繁生成 POTCAR、准备输入文件、整理能带和态密度数据、检查计算结果，以及完成结构与文件格式之间的转换。

VASPKIT 和 QVASP 都属于 VASP 辅助工具，但定位并不完全相同。VASPKIT 更像一套覆盖前处理、后处理和数据整理的交互式工具箱；QVASP 更强调命令行工作流与常用脚本封装。两者通常不需要和 vasp_std 重新编译链接，真正的安装重点是：目录是否稳定、赝势映射是否正确、普通用户是否有权限、modulefile 是否能复现环境，以及测试是否覆盖到 POTCAR 的真实生成。

本文的核心目标

本文以Ubuntu 22.04、VASPKIT 1.5.1 Linux x64 二进制包和 QVASP 2.25 为示例。其他版本的安装思路相同，但压缩包名称、解压目录和个别配置项需要以实际文件为准。我们也将环境识别、目录创建、权限设置、modulefile 生成、赝势映射和验收测试封装为一键安装脚本，可提供远程部署服务；文章仍完整展开关键步骤，便于读者自行完成并理解每一步。

文章目录

1.为什么安装完 VASP 后仍需要辅助工具

2.VASPKIT 与 QVASP 的定位和适用场景

3.安装前提、授权边界与目录规划

4.先整理赝势库：辅助工具能否工作的关键

5.安装 VASPKIT 1.5.1

6.配置 /etc/vaspkit 与用户级配置

7.创建 VASPKIT modulefile 并完成测试

8.安装 QVASP 2.25

9.配置 QVASP 赝势映射与 modulefile

10.让 VASP、VASPKIT 与 QVASP 在集群中协同使用

11.高频报错与排查顺序

12.一键安装脚本应具备的能力

13.最终验收清单与服务说明

1. 为什么安装完 VASP 后仍需要辅助工具

VASP 的核心可执行文件负责计算，却不会替用户自动管理所有输入、赝势和后处理流程。一次标准计算至少涉及 INCAR、POSCAR、POTCAR、KPOINTS 四类输入文件；计算结束后，又会产生 OUTCAR、OSZICAR、vasprun.xml、DOSCAR、EIGENVAL、PROCAR 等输出。随着体系和任务数量增加，纯手工处理很难长期保持一致。

环节	手工方式的常见风险	辅助工具的价值
生成 POTCAR	元素顺序拼错、赝势版本混用	根据 POSCAR 或命令参数读取统一赝势库
准备输入文件	模板分散、参数遗漏	提供标准化模板和常用任务入口
电子结构后处理	能量零点、路径和数据列处理不一致	按固定规则输出能带、DOS、投影数据
批量任务	目录命名和脚本难以复用	将高频操作封装为菜单或命令
多人共享	每个用户各自修改 PATH 与配置	通过 /etc 配置和 modulefile 统一交付

需要明确的边界

VASPKIT 和 QVASP 不替代 VASP 本身，也不会提高一个错误计算的物理可信度。它们减少的是重复操作和文件管理错误，最终的计算参数、赝势选择和结果解释仍需要研究者判断。

2. VASPKIT 与 QVASP：不是同一个工具的两种名字

工具	主要形式	更适合的任务	是否参与 VASP 编译
VASPKIT	交互式菜单 + 配置文件	输入生成、POTCAR、能带/DOS、结构与结果后处理	否，通常直接使用 Linux 二进制包
QVASP	命令行脚本工具集	快速生成 POTCAR、常用文件处理和脚本化流程	否，安装脚本和运行环境独立于 vasp_std
VASP	MPI 可执行程序	第一性原理计算本身	是，需要源码编译或使用已部署版本

实际部署时可以同时安装两者。VASPKIT 适合交互式选择任务和标准后处理；QVASP 适合已经熟悉命令参数、希望在 Shell 脚本中快速调用的用户。两套工具共享同一份合法赝势库即可，没有必要复制多份 POTCAR 数据。

VASP 计算程序├── 读取 INCAR / POSCAR / POTCAR / KPOINTS└── 输出 OUTCAR / DOSCAR / EIGENVAL / vasprun.xml ...VASPKIT├── 读取或生成 VASP 输入文件└── 读取 VASP 输出并生成后处理数据QVASP├── 通过命令行调用常用脚本└── 根据元素参数从赝势库生成 POTCAR

3. 安装前提、授权边界与目录规划

3.1 需要准备的文件

vaspkit.1.5.1.linux.x64.tar.gzqvasp-v2.25.tar.gz# 已经合法取得并解压的 VASP 赝势库，例如：/opt/vasp/potentials/paw_pbe

授权说明

VASP 赝势库属于授权内容，由用户或所属机构从合法渠道取得。

3.2 推荐目录结构

/opt/autoinstall/packages/software/ # 安装包归档目录，也可使用 /opt/software/opt/vaspkit/ # VASPKIT 多版本目录/opt/vaspkit/latest # 指向当前启用版本的软链接/opt/qvasp/ # QVASP 多版本目录/opt/qvasp/latest # 指向当前启用版本的软链接/opt/vasp/potentials/ # VASP 赝势库根目录/opt/vasp/potentials/paw_pbe # 统一 PBE 赝势入口/opt/modulefiles/vaspkit/ # VASPKIT modulefile/opt/modulefiles/qvasp/ # QVASP modulefile

使用 latest 软链接的好处是，升级版本时只需要切换链接，modulefile 和用户脚本不必随版本目录反复修改。真正的版本目录仍然保留，方便回滚和对比。

3.3 基础工具与 module 命令

sudo apt updatesudo apt install -y tar gzip xz-utils python3 python3-pip environment-modulessource /etc/profile.d/modules.shmodule --versionsudo mkdir -p /opt/vaspkit /opt/qvasp /opt/modulefiles/vaspkit /opt/modulefiles/qvasp

4. 先整理赝势库：辅助工具能否工作的关键

VASPKIT 或 QVASP 启动成功，并不代表它们一定能够生成 POTCAR。辅助工具最终仍要找到解压后的元素赝势目录。因此，在安装工具之前应先确认统一赝势入口。

find /opt/vasp/potentials -maxdepth 3 $ -name POTCAR -o -name POTCAR.Z $ | head# 预期结构示例：/opt/vasp/potentials/paw_pbe/Si/POTCAR/opt/vasp/potentials/paw_pbe/C/POTCAR/opt/vasp/potentials/paw_pbe/H/POTCAR

如果实际解压目录名称是 potpaw_PBE，而希望所有工具统一使用 paw_pbe，可以建立软链接：

sudo ln -sfn /opt/vasp/potentials/potpaw_PBE /opt/vasp/potentials/paw_pbereadlink -f /opt/vasp/potentials/paw_pbefind /opt/vasp/potentials/paw_pbe -maxdepth 2 $ -name POTCAR -o -name POTCAR.Z $ | head

最常见的配置错误

把 PBE_PATH 写成 /opt/software/potpaw_PBE.64.tgz。辅助工具需要的是解压后的元素目录，而不是压缩包文件。

5. 安装 VASPKIT 1.5.1

5.1 解压并创建稳定入口

sudo mkdir -p /opt/vaspkitcd /opt/autoinstall/packages/softwaresudo tar -xzf vaspkit.1.5.1.linux.x64.tar.gz -C /opt/vaspkitls -lh /opt/vaspkitsudo ln -sfn /opt/vaspkit/vaspkit.1.5.1 /opt/vaspkit/latestreadlink -f /opt/vaspkit/latest

若压缩包解压后的目录名与示例不同，必须按实际目录创建 latest 链接。不要仅根据压缩包文件名猜测安装路径。

5.2 设置多用户读取和执行权限

sudo chown -R root:root /opt/vaspkitsudo chmod -R a+rX /opt/vaspkitsudo chmod 755 /opt/vaspkit/latest/bin/vaspkitls -lh /opt/vaspkit/latest/bin/vaspkit/opt/vaspkit/latest/bin/vaspkit

能进入 VASPKIT 菜单，说明二进制本体可以启动；这一步仍未验证赝势路径和普通用户配置。

6. 配置 /etc/vaspkit：决定 VASPKIT 如何工作

在服务器或集群上，建议使用 /etc/vaspkit 作为全局默认配置。普通用户可以直接继承，也可以复制为 ~/.vaspkit 后进行个人修改。

sudo tee /etc/vaspkit >/dev/null <<'EOF'# Global VASPKIT configurationVASP5 .TRUE.POTCAR_TYPE PBEPBE_PATH /opt/vasp/potentials/paw_pbePYTHON_BIN /usr/bin/python3PLOT_MATPLOTLIB .FALSE.VASPKIT_UTILITIES_PATH /opt/vaspkit/latest/utilitiesADVANCED_USER .TRUE.SET_FERMI_ENERGY_ZERO .TRUE.MINI_INCAR .FALSE.USER_DEFINED_INCAR .FALSE.WRITE_SELECTIVE_DYNAMICS .FALSE.SET_INCAR_WRITE_MODE OVERRIDEPHS_CORRECTION .FALSE.SYMPREC 1E-5EMIN -20.0EMAX 20.0NEDOS 2001GAMMA_CENTERED .TRUE.VACUUM_THICKNESS 15.0CENTER_SLAB .TRUE.EOFsudo chmod 644 /etc/vaspkit

配置项	作用	需要注意的地方
PBE_PATH	指定 PBE 赝势元素目录	必须是解压目录，且普通用户可读取
SET_FERMI_ENERGY_ZERO	后处理能带、DOS 时把能量参考移到费米能级	只改变处理后数据的参考零点，不修改 VASP 原始输出
NEDOS	默认能量或 DOS 网格点数	应根据绘图和精度需求调整
GAMMA_CENTERED	默认生成Γ-centered KPOINTS	并非所有体系和任务都应固定使用
VACUUM_THICKNESS	构建低维模型时的默认真空层	只是工具默认值，正式计算仍应做收敛检查
SET_INCAR_WRITE_MODE	控制生成 INCAR 时如何处理已有文件	OVERRIDE 会覆盖旧文件，使用前应确认

关于能量零点

SET_FERMI_ENERGY_ZERO = .TRUE. 表示 VASPKIT 在部分能带、DOS 后处理中把费米能级作为 0 eV。它不等于“自动把带隙中点设为 0”，也不会改写 OUTCAR、DOSCAR 等原始文件。

6.1 用户级配置的优先级

# 普通用户需要个性化设置时：cp /etc/vaspkit ~/.vaspkitvim ~/.vaspkit# 检查是否存在个人配置：ls -la ~/.vaspkit 2>/dev/null

出现“管理员已经修改 /etc/vaspkit，但某个用户仍使用旧路径”时，首先检查该用户是否存在 ~/.vaspkit。用户级文件通常会覆盖全局配置。

7. 创建 VASPKIT modulefile 并完成测试

7.1 创建 modulefile

sudo tee /opt/modulefiles/vaspkit/1.5.1 >/dev/null <<'EOF'#%Module1.0proc ModulesHelp { } {puts stderr "VASPKIT 1.5.1 pre/post-processing tool"}module-whatis "VASPKIT 1.5.1 for VASP pre/post-processing"set root /opt/vaspkit/latestsetenv VASPKIT_HOME $rootprepend-path PATH $root/binprepend-path PATH $root/utilitiesEOFsudo chmod 644 /opt/modulefiles/vaspkit/1.5.1

7.2 验证菜单和命令来源

module purgemodule use /opt/modulefilesmodule load vaspkit/1.5.1which vaspkitreadlink -f $(which vaspkit)echo $VASPKIT_HOMEvaspkit

集群环境优先使用 modulefile，而不是把所有工具永久写进 /etc/profile.d。modulefile 能清楚展示当前加载版本，也便于未来同时保留多个版本。

7.3 用 Si 结构验证 POTCAR 读取

mkdir -p ~/vaspkit_test/Sicd ~/vaspkit_test/Sicat > POSCAR <<'EOF'Si5.430.0 0.5 0.50.5 0.0 0.50.5 0.5 0.0Si2Direct0.00 0.00 0.000.25 0.25 0.25EOFmodule load vaspkit/1.5.1vaspkit

在菜单中执行生成 POTCAR 的功能后，至少应检查文件是否存在以及赝势标题：

ls -lh POTCARgrep TITEL POTCAR# 预期能看到类似：# TITEL = PAW_PBE Si ...

8. 安装 QVASP 2.25

QVASP 的安装重点不是编译数学库，而是识别压缩包解压后的真实根目录，并让 qvasp、辅助脚本和赝势入口保持一致。原始技术文档中“先移动目录、后又使用旧的嵌套路径”容易造成混淆，因此这里采用多版本目录加 latest 软链接的方式。

8.1 解压并确认实际目录

sudo mkdir -p /opt/qvaspcd /opt/autoinstall/packages/softwaresudo tar -xzf qvasp-v2.25.tar.gz -C /opt/qvaspfind /opt/qvasp -maxdepth 3 -type f -name qvasp -o -name install.sh# 假设真实根目录为 /opt/qvasp/qvasp-v2.25：sudo ln -sfn /opt/qvasp/qvasp-v2.25 /opt/qvasp/latestreadlink -f /opt/qvasp/latest

8.2 执行工具自带安装脚本

cd /opt/qvasp/latestchmod +x install.sh qvasp 2>/dev/null || true./install.sh# 再确认命令或主脚本位置：find /opt/qvasp/latest -maxdepth 2 -type f -name qvasp -ls

不要照抄不存在的嵌套目录

如果已经把 qvasp-v2.25 重命名或移动为 /opt/qvasp，就不能继续使用 /opt/qvasp/qvasp-v2.25/...。先用 find 找到真实根目录，再统一创建 latest 链接。

9. 配置 QVASP 赝势映射与 modulefile

9.1 将 QVASP 的 POTCAR 入口指向统一赝势库

QVASP 常在自身 exefile 目录下寻找名为 POTCAR 的赝势入口。这里不复制整套赝势，而是建立软链接，使 VASPKIT、QVASP 和手工任务共享同一份 PBE 数据。

# 先检查 exefile 目录是否存在ls -ld /opt/qvasp/latest/exefile# 删除旧的空目录或错误链接，再建立统一入口sudo rm -rf /opt/qvasp/latest/exefile/POTCARsudo ln -s /opt/vasp/potentials/paw_pbe /opt/qvasp/latest/exefile/POTCARreadlink -f /opt/qvasp/latest/exefile/POTCARfind /opt/qvasp/latest/exefile/POTCAR -maxdepth 2 $ -name POTCAR -o -name POTCAR.Z $ | head

不同 QVASP 发行包的目录结构可能略有不同。如果工具实际读取的变量或目录不是 exefile/POTCAR，应以该版本安装脚本和运行提示为准，但原则仍然是：只维护一个合法赝势源，通过稳定路径进行映射。

9.2 创建 QVASP modulefile

sudo tee /opt/modulefiles/qvasp/2.25 >/dev/null <<'EOF'#%Module1.0proc ModulesHelp { } {puts stderr "QVASP 2.25 - VASP pre/post-processing toolkit"}module-whatis "QVASP 2.25 command-line toolkit"set root /opt/qvasp/latestsetenv qvasppath $rootsetenv QVASP_HOME $rootprepend-path PATH $rootprepend-path PATH $root/exefile/vtstscriptsEOFsudo chmod 644 /opt/modulefiles/qvasp/2.25

9.3 用 C、H 两种元素测试 POTCAR

module purgemodule use /opt/modulefilesmodule load qvasp/2.25which qvaspecho $qvasppathmkdir -p ~/qvasp_testcd ~/qvasp_testqvasp -pbe C Hls -lh POTCARgrep TITEL POTCAR

正确结果应依次出现 C 和 H 的 PBE 赝势标题。顺序非常重要：多元素 POTCAR 的拼接顺序必须与 POSCAR 的元素顺序完全一致。

10. 让 VASP、VASPKIT 与 QVASP 在集群中协同使用

辅助工具可以独立加载，也可以通过一个上层环境模块统一加载。对于多人集群，推荐保留独立模块，再根据实际 VASP 版本创建组合模块，避免把工具和某个编译器版本永久绑死。

方案	加载方式	优点	适用场景
独立加载	module load vaspkit/1.5.1 或 qvasp/2.25	边界清楚，可自由搭配 VASP 版本	多版本集群，推荐
组合加载	module load vasp/5.4.4-gnu 后自动加载辅助工具	用户操作最少	固定教学环境或单一生产环境
全局 PATH	写入 /etc/profile.d	登录后直接可用	单机、版本少；集群不优先

10.1 建议的日常加载方式

module purgemodule use /opt/modulefiles# 加载已有 VASP 环境，名称按服务器实际情况修改module load vasp/5.4.4-gnumodule load vaspkit/1.5.1module load qvasp/2.25module listwhich vasp_stdwhich vaspkitwhich qvasp

如果一键安装脚本已经把 VASPKIT 集成到 VASP modulefile，用户只需加载 VASP 模块即可。但管理员仍应能够通过 module show 确认工具路径、赝势变量和版本来源。

10.2 可选的 VASP 端到端测试

# 前提：当前目录已有完整 INCAR/POSCAR/POTCAR/KPOINTSexport OMP_NUM_THREADS=1mpirun -np 4 vasp_std > vasp.outtail -n 40 vasp.outgrep "Voluntary context switches" OUTCAR

这一步验证的是“辅助工具生成文件后，VASP 是否能真实读取并完成计算”。正式验收建议使用普通用户，而不是只在 root 环境中测试。

11. 高频报错与排查顺序

现象	优先检查	处理思路
vaspkit: command not found	module use、module load、PATH	检查 modulefile 与 latest/bin/vaspkit
VASPKIT 能启动但生成 POTCAR 失败	PBE_PATH、赝势目录权限	确认指向解压后的元素目录
管理员改了配置但某用户仍报旧路径	~/.vaspkit	删除或同步用户级配置
QVASP 找不到 POTCAR	exefile/POTCAR 软链接	用 readlink -f 和 find 验证目标
qvasp: command not found	真实 QVASP 根目录	find 主脚本并修正 latest/modulefile
root 可用、普通用户不可用	目录 x/r 权限、/etc 配置权限	chmod -R a+rX，普通用户重新测试
生成的 POTCAR 元素不对	命令参数或 POSCAR 元素顺序	grep TITEL 并按元素顺序重建
后处理能量零点不符合预期	SET_FERMI_ENERGY_ZERO	明确费米能级、VBM、带隙中点是不同参考

11.1 VASPKIT 找不到 PBE 赝势

grep -E 'POTCAR_TYPE|PBE_PATH' /etc/vaspkitls -ld /opt/vasp/potentials/paw_pbereadlink -f /opt/vasp/potentials/paw_pbefind /opt/vasp/potentials/paw_pbe -maxdepth 2 $ -name POTCAR -o -name POTCAR.Z $ | head# 同时检查用户级覆盖：grep -E 'POTCAR_TYPE|PBE_PATH' ~/.vaspkit 2>/dev/null

11.2 module 已加载，但命令仍指向旧版本

module purgemodule use /opt/modulefilesmodule load vaspkit/1.5.1hash -rwhich -a vaspkitreadlink -f $(which vaspkit)module show vaspkit/1.5.1

11.3 QVASP 软链接失效

readlink -f /opt/qvasp/latestreadlink -f /opt/qvasp/latest/exefile/POTCARls -ld /opt/qvasp/latest/exefile/POTCAR# 重新建立：sudo rm -rf /opt/qvasp/latest/exefile/POTCARsudo ln -s /opt/vasp/potentials/paw_pbe /opt/qvasp/latest/exefile/POTCAR

排错原则

不要在报错后立刻复制更多文件或把多个目录写入 PATH。先确认当前命令来自哪里、配置文件读取哪一个、软链接最终指向哪里，再做最小修改。

12. 一键安装脚本应具备哪些能力

辅助工具看似“解压即可用”，但真正适合服务器交付的一键脚本，不能只执行 tar。至少应覆盖下列能力：

• 自动识别 VASPKIT 与 QVASP 压缩包解压后的真实根目录，而不是写死目录名；

• 创建版本目录和 latest 软链接，并支持重复执行时安全更新；

• 检测 VASP 赝势库是否存在，拒绝把 PBE_PATH 指向压缩包或空目录；

• 生成 /etc/vaspkit、VASPKIT/QVASP modulefile，并保留已有配置备份；

• 统一设置 root 所有权和普通用户读取、进入、执行权限；

• 使用普通用户完成菜单启动、POTCAR 生成和 TITEL 顺序检查；

• 保存安装日志、版本信息、目录清单和最终验收结果；

• 不打包、不传输用户未授权的 VASP 源码与赝势库。

安装脚本的理想流程：预检查→ 识别安装包 → 解压到版本目录 → 创建 latest→ 检查赝势库 → 生成全局配置 → 创建 modulefile→ 修正权限 → 普通用户测试 → 输出验收报告

我们的远程安装流程采用同样的工程化思路：先识别现有 VASP、module 和赝势目录，再部署工具，避免为了安装一个辅助程序破坏服务器上已经稳定运行的编译环境。

13. 最终验收清单

验收项	检查命令或结果	通过标准
VASPKIT 命令	which vaspkit	指向 /opt/vaspkit/latest/bin/vaspkit
VASPKIT 配置	grep PBE_PATH /etc/vaspkit	指向真实解压赝势目录
VASPKIT POTCAR	grep TITEL POTCAR	元素和泛函正确
QVASP 命令	which qvasp	来自 /opt/qvasp/latest
QVASP 赝势入口	readlink -f exefile/POTCAR	指向统一 paw_pbe 目录
QVASP POTCAR	qvasp -pbe C H	按 C、H 顺序生成并可检查 TITEL
普通用户权限	普通用户重新登录测试	无需 sudo 即可启动和读取赝势
版本管理	module list / module show	当前工具版本和路径清晰
VASP 协同	可选最小计算	VASP 能读取生成文件并正常结束

建议交付的文件

安装完成后应保留：目录规划、/etc/vaspkit 备份、modulefile、软链接清单、测试目录、命令来源检查结果和安装日志。这样后续升级或迁移时，不需要重新猜测当初的配置。

结语：辅助工具安装的重点不是“多装两个命令”

VASPKIT 和 QVASP 的部署难度远低于 VASP 源码编译，但它们直接连接赝势库、输入文件和后处理数据。一旦路径、权限或配置优先级处理不当，就可能出现“程序能打开，但结果不可信”或“管理员能用，普通用户不能用”的问题。

一个可靠的安装结果应当具备四个特征：路径可追溯、赝势来源明确、多人环境可复现、测试覆盖真实工作流。读者可以按照本文逐步完成部署；对于不希望自行排查目录差异、用户权限和历史环境冲突的服务器，也可以使用一键安装脚本或远程安装服务完成标准化交付。

后续的软件安装实战系列还将继续整理 VASP 生态工具、第一性原理、分子动力学和有限元计算软件的安装与环境管理方法。