WannierTools 六晶面 Chern 数与相位展开
用四组三维实算演示六平面Wilson相位、方向约定、加密网格和独立Berry积分。
阅读本篇目录
Chern_3D_calc 可以一次计算六个固定晶面上的 Wilson loop。本篇用真正包含第三方向跃迁的三维小模型，演示输入、完整输出、相位展开与符号核对；同时比较两种网格、平庸模型和相反手性的模型。
1. 下载并先查看已有结果#
下载模型、输入、实际输出、CSV 和绘图工具，保存为 example.zip：
python3 -m zipfile -e example.zip .
cd wanniertools-chern-six-planes
source ./env.sh
bash show-reference.sh
bash plot-results.sh
ls -lh plots/wanniertools-chern-six-planes.png
采用集群已有 WannierTools 2.7.0 CPU 构建，Intel oneAPI 2023.2 / ifort 2021.10、Intel MPI 2021.10、MKL LP64 顺序库、ARPACK-NG 3.9.1。每次单 MPI 进程、单线程，在已经分配的兼容 CPU 资源中运行。
2. 模型与占据带#
模型每原胞两个同位置轨道，SOC=0，晶格常数 3 Å。哈密顿量为 H=dₓσₓ+dᵧσᵧ+d_zσ_z：
d_x = hand × sin(2πq_x)
d_y = sin(2πq_y)
d_z = m + cos(2πq_x) + cos(2πq_y) + 0.2 cos(2πq_z)
能量参数单位为 eV，q 为倒格矢分数坐标；第三方向的 0.2cos 项使模型具有真实的 z 方向色散。它是用于理解拓扑流程的紧束缚模型，不是某种实际材料的 DFT 结果。
本例计算下方一条带的拓扑，设置 NumOccupied=1。它指参与占据子空间的带数，不能直接填写体系总电子数。四组输入均保持体能隙不闭合：
| 条件 | m | hand | Nk1×Nk2 |
|---|---|---|---|
| 非平庸模型 | −1 | +1 | 24×25 |
| 同一模型加密 | −1 | +1 | 48×49 |
| 平庸对照 | −3 | +1 | 24×25 |
| 相反手性 | −1 | −1 | 24×25 |
3. 完整输入与六列的含义#
第一组的 wt.in：
&TB_FILE
Hrfile='model_hr.dat'
/
&CONTROL
Chern_3D_calc=T
/
&SYSTEM
NumOccupied=1
SOC=0
E_FERMI=0
/
&PARAMETERS
Nk1=24
Nk2=25
Nk3=3
/
LATTICE
Angstrom
3 0 0
0 3 0
0 0 3
ATOM_POSITIONS
1
Direct
X 0 0 0
PROJECTORS
2
X s s
SURFACE
1 0 0
0 1 0
本功能内部已经固定六个晶面，不需要另外用 KPLANE_BULK 指定它们。Nk1 是每条闭合积分线上的点数，Nk2 是扫描线的数量；本例写入的 Nk3 不控制这六个平面的采样。Chern 数要扫描完整周期，不能照搬时间反演 Z₂ 教程中的半个扫描区间。
输出 wanniercenter3D_Chern.dat 第一列为从 0 到 1 的扫描比例，后六列依次为：
| 数据列 | 固定晶面 | 闭合积分方向 | 扫描方向 |
|---|---|---|---|
| 2 | q₁=0 | q₃ | q₂ |
| 3 | q₁=0.5 | q₃ | q₂ |
| 4 | q₂=0 | q₃ | q₁ |
| 5 | q₂=0.5 | q₃ | q₁ |
| 6 | q₃=0 | q₁ | q₂ |
| 7 | q₃=0.5 | q₁ | q₂ |
相位以 2π 为单位并折回 0 到 1；0 和 1 是同一相位。对多条占据带，这个文件保存的是占据子空间相位和，不是每一条单带的能带能量。
4. 手动运行、展开相位并画图#
source ./env.sh
mkdir manual
cp reference-results/native/chern-m-1-hand1-24x25/{wt.in,model_hr.dat} manual/
(cd manual && wt.x)
head -n 6 manual/wanniercenter3D_Chern.dat
"$PYTHON_FOR_ANALYSIS" - <<'PY'
import numpy as np
a = np.loadtxt('manual/wanniercenter3D_Chern.dat')
phase = np.unwrap(2*np.pi*a[:, 1:], axis=0)/(2*np.pi)
winding = phase[-1] - phase[0]
print('六个平面的连续相位绕行:', winding)
print('靠近整数时取最近整数:', np.rint(winding).astype(int))
np.savetxt('manual/wilson-unwrapped.csv', np.c_[a[:, 0], phase], delimiter=',')
PY
(cd manual && gnuplot wanniercenter3D_Chern.gnu)
ls -lh manual/wanniercenter3D_Chern.eps manual/wilson-unwrapped.csv
第一组从原生相位展开得到 0 0 0 0 −1 −1。图中跨越 0/1 边界的跳变需要按相位周期连接，不能把每次图上跳变简单计为一次绕行。这里使用的 unwrap 适用于本例单占据带且相邻采样相位差足够小的情况；多占据带应处理整个占据子空间，不要随意给交叉的单条轨迹编号。
当前安装分支在这些模型的 WT.out 中将六个整数摘要都打印成了 0，和非平庸模型的完整相位绕行不一致。不要直接采用这项摘要判断平庸与否。 当前源码的最终整数显示使用截断，本文保留实际整数摘要，同时根据原生完整相位展开取最近整数，并与独立 Berry 积分核对。不能通过只修改输出摘要来解决采样或模型问题。
5. 符号为什么需要说明方向#
对于 q₃ 固定的平面，当前输出是“沿 q₁ 闭合积分、沿 q₂ 增大扫描”的 Wilson 相位绕行；它与按正向 q₁、q₂ 定义的 Berry 曲率面积积分相差一个负号。
| 条件 | 六平面 Wilson 绕行 | 正向 xy Berry 积分：q₃=0 / 0.5 |
|---|---|---|
| m=−1，hand=+1，两种网格 | 0 0 0 0 −1 −1 | +1 / +1 |
| m=−3，hand=+1 | 0 0 0 0 0 0 | 0 / 0 |
| m=−1，hand=−1 | 0 0 0 0 +1 +1 | −1 / −1 |
本例逐点用独立本征态重叠计算核对全部 Wilson 相位，最大模 1 误差小于 5×10⁻⁹；独立解析 Berry 曲率在 81 和 161 网格积分得到上表结果。反转一个方向的手性会反转带符号的拓扑结果，所以比较不同程序或论文时，应同时记录坐标、积分面朝向和相位约定。
6. 重算四组并输出对照图#
sbatch job.slurm
或在已获得的兼容 CPU 资源内：
bash run.sh
bash plot-results.sh
cat chern-six-plane-summary.csv
ls -lh plots/wanniertools-chern-six-planes.png
整套依次生成四套输入、运行 wt.x、整理每组的六平面绕行及独立积分，再生成对照图。已有 work 目录时停止；另行解压即可从头计算。
替换为自己的材料时，先验证体能带、占据子空间以及整个积分面的能隙，再加密积分线和扫描线。只有充分采样后接近稳定整数，才能采用最近整数；不要把任意未收敛的非整数强行取整。本例涉及破坏时间反演的 Chern 模型，不能把这里的整数当成 Z₂ 指标。
相关操作：Haldane 模型与 Chern 数、Wilson loop 与 Z₂、Berry 曲率平面图。参考：WannierTools 官方功能说明、当前功能的上游源码。