py4vasp 电子收敛与带隙检查

HDF5能读出能量，不代表已经看清电子收敛。先保留电子步的能量变化，再与OSZICAR对照；带隙也应确认来自哪一组k点。本篇使用已发表的Si光学SCF与NaCl电荷SCF两个实际结果，演示原生CSV、表格、Plotly对象和带边核对，不新增电子结构计算。

1. 获取数据与选择操作#

下载py4vasp数据、输入与绘图实例包：

unzip py4vasp-quantities-wave151-*.zip -d py4vasp-examples
cd py4vasp-examples
bash run.sh list

后处理模块为 py4vasp/0.11.3，使用独立Python3.11环境；结构和静态图使用 ase/3.29.0 的Python3.11.16、NumPy2.3.5、Matplotlib3.11.2。只需已分配资源内1个CPU，不需要GPU。

bash run.sh 1    # 39个数据入口、版本和文件前提
bash run.sh 2    # 介电、Born、压电和内部应变
bash run.sh 3    # 电子收敛、带隙及CSV

也可以在新解压目录运行 bash run-all.sh，得到 analysis/ 与 figures/。另一份新目录运行 bash analyze.sh，结果写入 analysis-reference/、figures-reference/。这两条命令只处理已经提供的数据，不重新运行VASP。输出目录保护会拒绝覆盖已有结果。

8份输入包含两类实际计算：5份已有VASP6.6.1/P100 HDF5结果（NVHPC25.3、CUDA12.8），以及3份Si/NaCl/ZnS的CPU DFPT结果（vasp/6.6.1-8173m-hdf5，InteloneAPI2024.2、MPI/OpenMP、HDF51.14.6）。新CPU计算采用1个MPI进程×4个OpenMP线程；读取HDF5与计算平台分开，py4vasp本身不替代VASP求解。

2. 先看这份结果当时如何计算#

本篇Si数据来自P100 HDF5构建，不是前两篇新的4×4×4 CPU响应例。完整Si光学SCF的INCAR为：

SYSTEM = si-optics-hdf5
ENCUT = 550
PREC = Accurate
EDIFF = 1E-6
EDIFFG = -0.02
IBRION = -1
NSW = 0
ISIF = 2
ISMEAR = 0
SIGMA = 0.05
LREAL = .FALSE.
LASPH = .TRUE.
LWAVE = .FALSE.
LCHARG = .FALSE.
NELM = 150
ALGO = Normal
ISYM = 2
LORBIT = 11
NBANDS = 32
NEDOS = 1001
LH5 = .TRUE.
LELF = .FALSE.
NPAR = 1
LOPTICS = .TRUE.
CSHIFT = .1

Gamma mesh
0
Gamma
11 11 11
0 0 0

结构位于 inputs/si-optics-hdf5/POSCAR。这里用实际均匀网格结果查看SCF和采样带隙；本篇不是通过一条高对称路径寻找全布里渊区带边，也不报告GW或实验带隙。

3. 读取电子步及最终能量#

module load py4vasp/0.11.3
python - <<'PYCODE'
import py4vasp
c = py4vasp.Calculation.from_path("inputs/si-optics-hdf5")
a = c.electronic_minimization.read()
print(a.keys())
for n, e, de in zip(a["N"], a["E"], a["dE"]):
    print(f"{int(n):3d}  {e: .10f}  {de: .6e}")
print("converged:", c.electronic_minimization.is_converged())
print("final energies:", c.energy.read())
PYCODE

E和 dE分别是该电子步的能量和变化，单位eV；deps、ncg、rms、rms(c)有各自含义，不应统称“总能误差”。这里选择静态SCF例子，避免把DFPT多个扰动方程的迭代序列误画成一次普通SCF收敛。

4. 原生导出CSV与表格#

python - <<'PYCODE'
import py4vasp
c = py4vasp.Calculation.from_path("inputs/si-optics-hdf5")
print(c.electronic_minimization.to_frame("E"))
print(c.electronic_minimization.to_frame("dE"))
c.electronic_minimization.to_csv("E", filename="scf-energy.csv")
c.electronic_minimization.to_csv("dE", filename="scf-dE.csv")
fig = c.electronic_minimization.to_plotly("E")
print("Plotly traces:", len(fig.data))
PYCODE

这个入口的图形转换一次选择一个字段，分别写 E、dE，不使用 E,dE。Plotly对象可用于支持交互图形的环境；本包在终端用Matplotlib生成可直接打开的PNG，不依赖服务器安装无界面浏览器导图组件。

bash run-all.sh
ls figures
head -5 analysis/electronic/si-optics-hdf5-E-api.csv

能量不必每一步单调下降；看对应算法、电子阈值和最终收敛标记，再判断这一次计算是否完成。材料目标性质的k点、截断能等收敛需要另外检查。

5. rms(c)的记录时点不要直接混用#

这两份实际VASP6.6.1结果中，HDF5的 rms(c) 保存的是前一电子步的混合残差：HDF5第i+1步对应OSZICAR第i行打印的 rms(c)。能量、dE等列仍按同一步对应；不能把整个表盲目统一平移。

head -12 inputs/si-optics-hdf5/OSZICAR
cat analysis/electronic/si-optics-hdf5-charge-residual-recording.csv

例如Si的OSZICAR第5步打印约0.47479，而HDF5在第6步保存这个值。配套CSV保留“原HDF5步号和值”与“原OSZICAR行号和值”，没有改写或静默挪动原始数据。需要画本例当前步的电荷残差时，直接使用OSZICAR对应列更清楚。这里说明的是这两份文件的实际记录，不推广成所有VASP版本和构建都具有相同时点。

6. 带隙：先读取摘要，再检查实际采样#

python - <<'PYCODE'
import py4vasp
c = py4vasp.Calculation.from_path("inputs/nacl-charge-hdf5")
gap = c.bandgap.read()
print("fundamental:", gap["fundamental"], "eV")
print("direct:", gap["direct"], "eV")
print("VBM kpoint:", gap["kpoint_VBM"])
print("CBM kpoint:", gap["kpoint_CBM"])
print(c.kpoint.read())
PYCODE

本例实际摘要为：

基本带隙用实际采样的占据最高态与空带最低态相减；直接带隙要求在同一个k点比较。本例为有明确带隙的非自旋SCF，可用占据数检查带边；金属、显著部分占据、自旋/SOC以及不同数据源需要按实际定义处理，不能硬套这两个数。

本包还从原生 band.read() 的能量/占据重新核对上述两种采样带隙，保留文件中的费米能和k点信息。想画能带路径继续看能带与DOS实操。

7. 操作结束后的文件#

ls analysis/electronic
cat analysis/electronic/CHECKS.json
ls figures/py4vasp-scf-convergence.png

保留原始INCAR、KPOINTS、OUTCAR和OSZICAR，连同导出的E/dE及电荷残差CSV，才能回看图中每个点来自哪一次计算。其他可读物理量及文件前提见39个数据入口索引，API定义见py4vasp官方目录。