WannierTools 直接带隙与间接带隙
运行平面与体网格带隙计算，比较局部直接带隙、全局间接带隙，并解释阈值导致的空文件。
阅读本篇目录
BulkGap_plane_calc 和 BulkGap_cube_calc 可以检查给定 k 网格上的价带、导带与局部带隙。本例给出一个最小直接带隙 2.0 eV、全局间接带隙 1.6 eV 的模型，帮助你选择正确的读数。
1. 下载与看图#
下载输入、真实结果和分析脚本，保存为 example.zip：
python3 -m zipfile -e example.zip .
cd wanniertools-gaps-fermi-level
bash show-reference.sh
bash plot-results.sh
ls -lh plots/wanniertools-direct-indirect-gap-grids.png
这是自建八带教学 HR，不是材料 DFT 拟合。中央两带来自 QWZ m=-1 模型，旁边放置三条较低、三条较高的辅助能带；所有能量加上 0.4+0.2 cos(qx) eV。晶格 3×3×10 Å，两个相关带之间有带隙，价带顶和导带底位于不同 k 点。
使用 WannierTools 2.7.0，oneAPI 2023.2 / ifort 2021.10、Intel MPI 2021.10、MKL LP64 顺序库、ARPACK-NG 3.9.1。env.sh 加载模块和已有的分析 Python，以下计算在分配的兼容 CPU 资源内执行。
2. 先运行二维平面#
source ./env.sh
mkdir manual
cp reference-results/native/plane-25x29x3/wt.in manual/
cp reference-results/native/plane-25x29x3/model_hr.dat manual/
(cd manual && wt.x)
head -n 6 manual/GapPlane.dat
关键输入：
&CONTROL
BulkGap_plane_calc=T
/
&SYSTEM
NumOccupied=4
SOC=0
E_FERMI=0
Ntotch=8
/
&PARAMETERS
Nk1=25
Nk2=29
Nk3=3
Gap_threshold=10
/
KPLANE_BULK
0 0 0
1 0 0
0 1 0
本例平面为以零点为中心的一个周期，包含边界，25×29 共 725 点。此平面分支分别使用 Nk1、Nk2。NumOccupied=4 指第 4 条带为最高占据带、第 5 条带为最低未占据带；这只是本模型的能带编号，换材料时应按实际电子结构设置。
当前 2.7.0 的平面分支会额外保存四条价带和四条导带。 因此应满足 NumOccupied>=4 且 NumWann-NumOccupied>=4。本例特意提供八条带。轨道数较少的模型应先选择适合其带数的输出方式，不能直接照搬平面分支的带窗口。
3. 读 GapPlane.dat#
本例共 18 列：
| 列 | 含义 |
|---|---|
| 1–3 | 笛卡尔 k 坐标，Å⁻¹ |
| 4–6 | 旋转到平面后的坐标，Å⁻¹ |
| 7 | 同一 k 点的第 5 带减第 4 带，eV |
| 8–15 | 八条带能量，eV；第 11、12 列是本例价带边和导带边 |
| 16–18 | 当前版本内部缩放后的坐标列，请勿直接作为分数坐标 |
当前版本对最后三列还有内部长度转换，不能按普通的倒格矢分数坐标直接读取。画图优先使用已核对的前两列笛卡尔坐标和第 7 列带隙。
在配套图中，第 7 列的最小值为 2.0 eV，表示最小直接带隙。全局间接带隙应取：
min_k Ec(k) - max_k Ev(k)
本模型 Ec 最低值是 1.2 eV，Ev 最高值是 -0.4 eV，差为 1.6 eV。这两个极值出现在不同 k 点，所以不能用“局部带隙列的最小值”代替它。
资料包的 gaps-fermi-summary.csv 会按完整原生输出整理这两个值，13×17 和 25×29 两个平面均保留。对真实材料，仍需检查极值附近的采样是否足够细，不能只看少数高对称点。
4. 三维网格与输出阈值#
完整输入的另一组只打开：
&CONTROL
BulkGap_cube_calc=T
/
&PARAMETERS
Nk1=13
Nk2=13
Nk3=5
Gap_threshold=10
/
KCUBE_BULK
-0.5 -0.5 -0.5
1 0 0
0 1 0
0 0 1
这里的起点是体网格角点，三个向量给出范围；与平面中心的写法含义不同。当前分支包含两端点，13×13×5 共 845 点。本例第三方向没有色散，仍实际输出各层网格；真实三维体系应独立收敛第三方向。
GapCube.dat 的前 3 列是 k 坐标，第 4 列直接带隙，第 5、6 列是对应价、导带边，单位分别为 Å⁻¹ 和 eV。最后三列有前面所述的坐标缩放限制。
Gap_threshold 只控制哪些点写入文件。 当前输出条件是直接带隙严格小于阈值。设为 10 eV，本例写入全部点；设为 1.5 eV 后，文件只有表头，因为没有任何 k 点的直接带隙小于 1.5 eV。这是预期筛选结果，不等于计算失败，也不能据此得出体系没有能带。
head -n 3 reference-results/native/cube-13x13x5/GapCube.dat
cat reference-results/native/cube-filter-9x9x3/GapCube.dat
5. 重算完整流程#
sbatch job.slurm
或在已分配的兼容 CPU 资源内：
bash run.sh
bash plot-results.sh
cat gaps-fermi-summary.csv
整套包含两个平面、两个完整体网格、一个阈值筛选以及下一篇的两组费米能级计算。已有 work/ 时停止；重算请重新解压到另一个目录。模型带隙由自己的参数决定，不代表某种材料的带隙预测。
接口可对照 WannierTools 官方对应源码；本篇数值和字段说明按集群当前 2.7.0，在线分支后续可能变化。