用 Python 重写 VASPKIT 1.5.1 的 VASP 后处理 — 不再依赖 Linux 二进制
A pure-Python reimplementation of VASPKIT 1.5.1 post-processing for DOS, Bader, charge density, band structure, optics, work function and thermochemistry.
VASPKIT 1.5.1 官方只提供 Linux x86-64 可执行文件。在 Windows、macOS 或没有 Linux 环境的工作站上，无法直接运行它的后处理菜单；即使能用，也要通过 echo -e "314\n..." | vaspkit 这样的交互方式操作，难以脚本化、复用和二次开发。
本项目把 VASPKIT 1.5.1 中最常用的 VASP 后处理逻辑独立重写为纯 Python：
- 直接读取 VASP 原始输出：
DOSCAR、EIGENVAL、PROCAR、CHGCAR、LOCPOT、OUTCAR、vasprun.xml、ACF.dat、POTCAR； - 每个功能独立成文件夹，带 CLI、README 和回归测试；
- 输出文件名尽量沿用 VASPKIT（
TDOS.dat、PDOS_*.dat、BAND_CENTER、CHGDIFF.vasp、PLANAR_AVERAGE.dat、BAND.dat、ABSORPTION.dat、bader.pqr、WORKFUNCTION.dat、THERMO.dat等）； - 只用 NumPy 作为必需依赖，Windows / Linux / macOS 均可运行。
本项目是对 VASPKIT 行为的独立 Python 重实现，不是 VASPKIT 官方项目，也不包含 VASPKIT 的二进制或源代码。
| 文件夹 | 功能 | 对应 VASPKIT 任务 | 主要输入 |
|---|---|---|---|
dos/ |
TDOS/PDOS、原子/元素/轨道选择、m 分辨轨道、sigma 展宽、s/p/d 带中心 | 111–120、503 | DOSCAR、EIGENVAL、PROCAR |
bader_charge/ |
chgsum、Bader→PQR、ACF 电荷分析、一条命令完成 Bader 全流程 |
BD、508 | AECCAR0/2、CHGCAR、ACF.dat、POTCAR |
charge_difference/ |
电荷密度差分、平面/宏观平均、切片、自旋拆分 | 310–318 | CHGCAR、LOCPOT |
band/ |
能带结构、K 路径标签、带隙、有效质量 | 211–216、250–257 | EIGENVAL、POSCAR、KPOINTS |
optical/ |
介电函数、吸收谱、折射率、消光、反射率、能量损失、JDOS | 710、711、716 | vasprun.xml、REAL.in/IMAG.in |
workfunction/ |
平面平均静电势、真空能级、功函数、电子亲和势/电离能 | 422、426 | LOCPOT、OUTCAR |
frequency/ |
振动频率热校正：ZPE、U/H/G、熵与 T·S | 501 | OUTCAR、频率列表 |
common/ |
共享 VASP 文件读写库（无第三方依赖，仅 NumPy） | — | — |
tests/ |
基于 VASPKIT 示例数据的回归测试 | — | — |
需要 Python 3.10+。核心功能只依赖 NumPy；--plot 额外需要 matplotlib。
git clone https://github.com/moyulyy/vaspkit-python.git
cd vaspkit-python
python -m pip install -r requirements.txt只安装核心依赖：
python -m pip install numpy仓库不包含 VASPKIT 的 300+ MB 示例数据。若要运行完整回归测试，请下载 VASPKIT 1.5.1，并把 examples 目录路径告诉测试：
# Linux/macOS
export PYVASPKIT_EXAMPLES=/path/to/vaspkit.1.5.1/examples
# Windows PowerShell
$env:PYVASPKIT_EXAMPLES = "C:\path\to\vaspkit.1.5.1\examples"默认也会尝试读取仓库根目录下的：
vaspkit.1.5.1.linux.x64/vaspkit.1.5.1/examples
找不到示例时，依赖示例的测试会自动跳过，合成数据测试仍会运行。
# 1) DOS / PDOS / d 带中心（DOSCAR）
python dos/run_dos.py --doscar DOSCAR --poscar POSCAR --dband-center --relative
# 2) DOS：按元素、轨道、自旋，带 sigma 展宽
python dos/run_dos.py doscar --doscar DOSCAR --elements Ni,O \
--orbitals s,p,d --emin -10 --emax 10 --sigma 0.05 --spin both
# 3) TDOS from EIGENVAL（117）/ PDOS from PROCAR（118-120）
python dos/run_dos.py eigenval --eigenval EIGENVAL --sigma 0.05 --smearing gaussian
python dos/run_dos.py procar --eigenval EIGENVAL --procar PROCAR \
--poscar POSCAR --orbitals s,p,d --bands 1-9 --kpts 1-10
# 4) 电荷密度差分 AB - A - B，并同时输出平面平均（314 + 316）
python charge_difference/run_charge_difference.py difference \
AB/CHGCAR A/CHGCAR B/CHGCAR --planar --axis z
# 5) Bader 全流程：chgsum + bader（或 Python 回退）+ ACF 分析
python bader_charge/run_bader.py pipeline \
--aeccar0 AECCAR0 --aeccar2 AECCAR2 --chgcar CHGCAR \
--poscar POSCAR --potcar POTCAR --outdir bader_out
# 6) 能带 + 带隙（211）
python band/run_band.py bands --eigenval EIGENVAL --poscar POSCAR --kpoints KPATH.in
python band/run_band.py gap --eigenval EIGENVAL
# 7) 光学谱（710/711）
python optical/run_optical.py all vasprun.xml --outdir optical_out
# 8) 功函数（426）
python workfunction/run_workfunction.py --locpot LOCPOT --outcar OUTCAR --axis z
# 9) 频率热校正（501）
python frequency/run_frequency.py --outcar OUTCAR --temperature 298.15每个脚本都支持 -h / --help 查看完整参数。
| 原 VASPKIT 命令 | 本仓库等价命令 |
|---|---|
echo -e "314\n./AB/CHGCAR ./A/CHGCAR ./B/CHGCAR" | vaspkit |
python charge_difference/run_charge_difference.py difference AB/CHGCAR A/CHGCAR B/CHGCAR |
echo -e "316\n3\nCHGDIFF.vasp\n3" | vaspkit |
python charge_difference/run_charge_difference.py planar CHGDIFF.vasp --axis z |
| 314 + 316 两步 | python charge_difference/run_charge_difference.py difference ... --planar --axis z |
chgsum.pl AECCAR0 AECCAR2 && bader CHGCAR -ref CHGCAR_sum |
python bader_charge/run_bader.py pipeline --aeccar0 AECCAR0 --aeccar2 AECCAR2 --chgcar CHGCAR --poscar POSCAR --potcar POTCAR |
echo -e "426\n3" | vaspkit |
python workfunction/run_workfunction.py --locpot LOCPOT --outcar OUTCAR --axis z |
echo -e "503\n1\nN\n1\nall" | vaspkit |
python dos/run_dos.py bandcenter --doscar DOSCAR --poscar POSCAR（输出 BAND_CENTER） |
echo -e "501\n298.15" | vaspkit |
python frequency/run_frequency.py --outcar OUTCAR --temperature 298.15 |
echo -e "211\n" | vaspkit |
python band/run_band.py bands --eigenval EIGENVAL --poscar POSCAR --kpoints KPATH.in |
python dos/run_dos.py doscar --doscar DOSCAR --poscar POSCAR \
--elements Ni,O --atoms 1-3 --orbitals s,p,d \
--emin -10 --emax 10 --nedos 2000 --sigma 0.05 \
--spin both --band-center --dband-center--orbitals支持s p d f all，LORBIT=11 时还支持 m 分辨分量px py pz dxy dyz dz2 dxz dx2-y2；eigenval子命令用 Gaussian / Lorentzian / Fermi 展宽从 EIGENVAL 计算 TDOS；procar子命令从 EIGENVAL + PROCAR 计算轨道投影 PDOS，支持--kpts、--bands；bandcenter/--band-center输出BAND_CENTER与BAND_CENTER.dat，--dband-center输出兼容格式的D_BAND_CENTER。
# 全流程
python bader_charge/run_bader.py pipeline \
--aeccar0 AECCAR0 --aeccar2 AECCAR2 --chgcar CHGCAR \
--poscar POSCAR --potcar POTCAR --outdir bader_out
# 单独：ACF.dat -> bader.pqr（VMD 按电荷着色）
python bader_charge/run_bader.py pqr ACF.dat --poscar POSCAR --potcar POTCAR -o bader.pqrpipeline 会优先调用 PATH 上的 Henkelman bader；找不到或无法执行时，自动回退到纯 NumPy 近似划分。正式发表建议使用原版 bader。
python charge_difference/run_charge_difference.py difference AB/CHGCAR A/CHGCAR B/CHGCAR --planar
python charge_difference/run_charge_difference.py macroscopic CHGCAR --period 10 --iterations 2
python charge_difference/run_charge_difference.py spin CHGCARpython band/run_band.py bands --eigenval EIGENVAL --poscar POSCAR --kpoints KPATH.in
python band/run_band.py gap --eigenval EIGENVAL
python band/run_band.py mass --eigenval EIGENVAL --band 7 --kpoint 0python optical/run_optical.py all vasprun.xml --outdir optical_out
python optical/run_optical.py jdos --eigenval EIGENVAL --sigma 0.05python workfunction/run_workfunction.py --locpot LOCPOT --outcar OUTCAR --axis zpython frequency/run_frequency.py --outcar OUTCAR --temperature 298.15输出 THERMO.dat 与 ZPE.dat，屏幕包含：
Zero-point energy E_ZPE : ... eV
Thermal correction to U(T): ... eV
Thermal correction to H(T): ... eV
Thermal correction to G(T): ... eV
Entropy S : ... eV/K
Entropy contribution T*S : ... eV
- 使用 REA 检查
vaspkit二进制身份与导出表，确认ELF x86-64、SHA-256 和符号信息； - 由于 Windows 上 REA 的 ELF 深度反编译提供商不可用（Hopper 仅 macOS，Ghidra P0 仅 PE），使用 Python 从 13.7 MB 未去符号的 ELF 中提取 70 441 条字符串，恢复菜单任务号、交互提示、输出文件名和公式线索；
- 用 VASPKIT 1.5.1 自带的
examples/参考数据逐项校准关键行为：- d 带中心：VASPKIT 503 对全能量区间积分，而不是只积占据态；
- 光学：
α = 2Ek/(ħc)、n/k来自复介电函数，ħc = 1.973269804e-5 eV·cm； - Bader→PQR：电荷为
ACF - ZVAL，半径取 POTCAR 的RWIGS； - 能带 K 路径：使用
2π·A⁻¹倒格矢计算路径长度。
| 模块 | 参考数据 | 结果 |
|---|---|---|
| DOS / d 带中心 | examples/d_band_center |
5 原子 × 2 自旋，最大误差 1e-4 eV |
| DOS（EIGENVAL） | examples/ZnO_optimization |
全能量积分 32.000 states；占据积分 36.000 electrons = NELECT |
| DOS（PROCAR） | examples/hybrid_DFT_band |
199 k × 144 bands × 2 ions；9 轨道 m 分辨 PDOS |
| Bader→PQR | examples/bader2pqr |
与 bader.pqr 逐字节一致 |
| 光学 | examples/Si_BSE_optical |
5 个谱文件，最大相对误差 4.8e-4 |
| 能带路径 | examples/hybrid_DFT_band |
KLABELS 坐标完全一致 |
| 电荷差分 / 功函数 | 合成 CHGCAR/LOCPOT | 解析解验证通过（0.5 差分、4.0 eV 功函数） |
| 频率热校正 | 单频解析解 + examples/thermo_correction/ORR |
1000 cm⁻¹ → ZPE=0.061992 eV；8 实频 + 1 虚频 |
python -m unittest discover -s tests -v- 配有 VASPKIT 示例数据时：19 个测试全部运行；
- 没有示例数据时：依赖示例的测试自动跳过，合成数据测试仍会运行。
.
├── common/ # 共享 VASP 读写库
│ ├── vaspio.py
│ └── __init__.py
├── dos/run_dos.py + README.md # TDOS/PDOS/带中心
├── bader_charge/run_bader.py + README.md
├── charge_difference/run_charge_difference.py + README.md
├── band/run_band.py + README.md
├── optical/run_optical.py + README.md
├── workfunction/run_workfunction.py + README.md
├── frequency/run_frequency.py + README.md
├── tests/test_all.py
├── requirements.txt
└── LICENSE
- Bader 网格划分：纯 Python 版本是基于 FFT 网格的近似实现；正式发表请使用 Henkelman 的
bader。pipeline会优先调用 PATH 上的原版bader。 - 频率热校正：实现的是 VASPKIT 501（吸附物/固体）；502 气相平动/转动/电子贡献尚未实现。
- DOS 实空间分辨：VASPKIT 123–126 的实空间 DOS 尚未实现。
- SOC 专用输出：
TDOS_SOC/PDOS_SOC_(MX,MY,MZ)尚未单独实现。 - 投影能带：VASPKIT 212–216 的投影能带需要额外的 PROCAR 处理，目前未包含。
欢迎提交 issue / PR：
- 新功能建议请说明对应的 VASPKIT 任务号与输入文件；
- 修复 bug 时请附上最小复现数据和期望输出；
- 提交前请运行
python -m unittest discover -s tests -v。
- 本项目是对 VASPKIT 1.5.1 行为的独立 Python 重实现。使用 VASPKIT 或本项目产生的结果时，请按 VASPKIT 官方要求引用相关文献。
- 感谢 VASPKIT 作者提供公开的示例数据，使本项目的数值验证成为可能。
本项目使用 MIT License。