Abinit K 点（布里渊区采样）：参数、公式与代码实现详解

2026-05-19T00:00:00+00:00
</span>
Abinit K点（布里渊区采样）：参数 + 公式 + 代码实现详解</a></h1>
基于 Abinit 10.4.7 源码分析（核心：src/56_recipspace/m_kpts.F90</code>、shared/common/src/29_kpoints/m_symkpt.F90</code>、src/57_iovars/m_inkpts.F90</code>）</p> </blockquote>
引言：K点的物理含义</a></h2>
固体物理中，由 Bloch 定理，单粒子态 $\psi_{n\mathbf{k}}(\mathbf{r}) = e^{i\mathbf{k}\cdot\mathbf{r}} u_{n\mathbf{k}}(\mathbf{r})$ 用波矢 $\mathbf{k}\in\text{BZ}$ 标记。任何物理量（密度、能量、力）都要在第一布里渊区上做积分：</p>
$$n(\mathbf{r}) = \sum_n \frac{V}{(2\pi)^3} \int_{\text{BZ}} f_{n\mathbf{k}} |\psi_{n\mathbf{k}}(\mathbf{r})|^2 d^3\mathbf{k}$$</p>
DFT 求解只能在离散</strong>的 k 点上做。Abinit 把这个积分变成加权和：</p>
$$\int_{\text{BZ}} F(\mathbf{k}),d^3\mathbf{k} ;\approx; \frac{(2\pi)^3}{V}\sum_{i=1}^{N_k} w_i,F(\mathbf{k}_i),\qquad \sum_i w_i = 1$$</p>
K点采样涉及三件事：</p>

生成均匀网格</strong>（Monkhorst–Pack 方案）</li>
用对称操作折叠到不可约布里渊区 IBZ</strong>（symkpt）</li>
分配权重 $w_i$</strong>（每个 IBZ 点代表多少个 BZ 等效点）</li>
</ol>
特殊情形：能带结构计算需要沿高对称线采样（kptopt<0</code> 路径模式）。</p>

输入参数总览</a></h2>
下表按使用频率列出所有 k 点相关变量（定义位置：abimkdocs/variables_abinit.py</code>）。</p>
输入变量</th> 类型</th> 默认值</th> 作用</th></tr></thead>

kptopt</code></td> int</td> 1（nspden=4</code> 时为 4）</td> 生成模式：0 手动，1–4 自动，<0 能带路径</td></tr>
ngkpt</code></td> int(3)</td> 0,0,0</td> Monkhorst–Pack 网格三方向点数（最常用）</td></tr>
kptrlatt</code></td> int(3,3)</td> 0</td> k 点超晶格矩阵（与 ngkpt</code> 二选一，更灵活）</td></tr>
nshiftk</code></td> int</td> 1</td> 平移子网格数（FCC/BCC 可减少 IBZ 点数）</td></tr>
shiftk</code></td> real(3,nshiftk)</td> 0.5,0.5,0.5</td> 每个子网格的平移量（约化坐标）</td></tr>
kptrlen</code></td> real</td> 30.0</td> 不指定 ngkpt</code> 时，自动搜索的最小实空间向量长度</td></tr>
kptbounds</code></td> real(3,N+1)</td> —</td> kptopt<0</code> 时的能带路径端点</td></tr>
ndivsm</code></td> int</td> —</td> 路径最短段的分点数（推荐方式）</td></tr>
ndivk</code></td> int(N)</td> —</td> 路径每段的分点数（与 ndivsm</code> 二选一）</td></tr>
kpt</code></td> real(3,nkpt)</td> 0,0,0</td> kptopt=0</code> 时手动输入的 k 点</td></tr>
kptnrm</code></td> real</td> 1.0</td> kpt</code> 的总归一化分母（避免输入分数）</td></tr>
wtk</code></td> real(nkpt)</td> 1.0</td> kptopt=0</code> 时手动权重</td></tr>
nkpt</code></td> int</td> 0（自动）</td> k 点总数（kptopt≠0</code> 时通常自动算出）</td></tr>
istwfk</code></td> int(nkpt)</td> 0（自动）</td> 波函数存储模式（利用时间反演压缩 50% 存储）</td></tr>
chksymbreak</code></td> int</td> 1</td> 是否检查网格对称性，破缺则报错</td></tr>
prtkpt</code></td> int</td> 0</td> =1 输出候选 k 网格分析并退出</td></tr>
qptn</code></td> real(3)</td> 0,0,0</td> 整体平移所有 k 点的 q 向量（响应函数）</td></tr>
</tbody></table>
主要场景对照</strong>：</p>

半导体/绝缘体 SCF：kptopt 1</code>, ngkpt 4 4 4</code>, nshiftk 1</code>, shiftk 0.5 0.5 0.5</code></li>
金属 SCF：用更密的 ngkpt</code>（如 12 12 12</code>），加 tsmear</code>（见 smearing 报告）</li>
能带结构：先 SCF（prtden 1</code>），再 iscf -2</code>, kptopt -N</code>, kptbounds ...</code>, ndivsm 20</code></li>
DFPT 响应函数：kptopt 2</code>（仅时间反演）或 kptopt 3</code>（无对称）</li>
</ul>

Monkhorst–Pack 公式与代码实现</a></h2>
数学定义</a></h3>
对每个方向 $\alpha\in{1,2,3}$，取 $N_\alpha = \tt{ngkpt}(\alpha)$ 个点：</p>
$$\mathbf{k}{ijk} = \sum</em>{\alpha=1}^3 \frac{i_\alpha - 1 + s_\alpha}{N_\alpha},\mathbf{b}\alpha,\qquad i</em>\alpha \in {1,\ldots,N_\alpha}$$</p>
其中 $\mathbf{b}\alpha$ 是倒格矢，$s</em>\alpha = \tt{shiftk}(\alpha)$ 是平移。</p>
更一般的形式用 kptrlatt</code>：k 点是晶格倒格矢</strong></p>
$$\mathbf{B}{\text{kpt}} = (B</em>{\text{rec}})\cdot(\tt{kptrlatt})^{-T}$$</p>
的子格。一个简单的对应关系：当 nshiftk=1</code> 时，kptrlatt</code> 是对角矩阵 diag(ngkpt)</code>。</p>
代码：smpbz</code>（Sampling of Brillouin Zone）</a></h3>
位置：src/56_recipspace/m_kpts.F90:2088-2615</code>。</p>
主要分支按 brav</code> 区分：</p>

brav=1</code>：通用（任意 kptrlatt</code>，包含简单晶格）</li>
brav=2</code>：面心立方专用</li>
brav=3</code>：体心立方专用</li>
brav=4</code>：六方专用</li>
</ul>
通用分支的核心循环（m_kpts.F90:2274-2354</code>）：</p>
nn = 1</span></span>
do kk = boundmin(3), boundmax(3)</span></span>
   coord(3) = kk</span></span>
   do jj = boundmin(2), boundmax(2)</span></span>
      coord(2) = jj</span></span>
      do ii = boundmin(1), boundmax(1)</span></span>
         coord(1) = ii</span></span>
         do ikshft = 1, nshiftk</span></span>
            ! 试探 k 点在 k 晶格上的整数坐标</span></span>
            k1(1) = ii + shiftk(1, ikshft)</span></span>
            k1(2) = jj + shiftk(2, ikshft)</span></span>
            k1(3) = kk + shiftk(3, ikshft)</span></span>
            ! 变换到倒格矢约化坐标</span></span>
            k2(:) = k1(1)*klatt(:,1) + k1(2)*klatt(:,2) + k1(3)*klatt(:,3)</span></span>
            ! 只保留 [0,1) 内的点</span></span>
            if (k2(1) < -tol10 .or. k2(1) > one-tol10) cycle</span></span>
            if (k2(2) < -tol10 .or. k2(2) > one-tol10) cycle</span></span>
            if (k2(3) < -tol10 .or. k2(3) > one-tol10) cycle</span></span>
            ! 折叠到 ]-1/2, 1/2]</span></span>
            call wrap2_pmhalf(k2(1), k1(1), shift)</span></span>
            call wrap2_pmhalf(k2(2), k1(2), shift)</span></span>
            call wrap2_pmhalf(k2(3), k1(3), shift)</span></span>
            spkpt(:, nn) = k1(:)</span></span>
            nn = nn + 1</span></span>
         end do</span></span>
      end do</span></span>
   end do</span></span>
end do</span></span>
nkpt = nn - 1</span></span></code></pre>
整个 BZ 上的 k 点总数应满足：</p>
$$N_{\text{BZ}} = \det(\tt{kptrlatt}) \times \tt{nshiftk}$$</p>
这是通过 nkptlatt = det(kptrlatt)</code>（m_kpts.F90:2179-2184</code>，按矩阵展开公式）然后乘 nshiftk</code> 来核对的。</p>
自动选优：testkgrid</code></a></h3>
如果输入既没给 ngkpt</code> 也没给 kptrlatt</code>，Abinit 会枚举大量候选 kptrlatt + shiftk</code> 组合，按以下准则选优：</p>

首要标准</strong>：所谓 k 点格的实空间长度</em> kptrlen</code>（k 格的倒格 = 一个超晶格，其最短实空间向量长度即 kptrlen</code>）。比 kptrlen</code>（默认 30 Bohr）大的网格才被接受。</li>
次要标准</strong>：使用 kptopt=1</code> 全对称约化后 IBZ 点数最少的组合获胜。</li>
</ul>
代码位置：m_kpts.F90:2654</code>（testkgrid</code> 子程序）。这一步耗时较多（枚举可达上万组合），所以建议 prtkpt=1</code> 单独跑一次得到推荐网格，记下来再用。</p>

对称约化：BZ → IBZ</a></h2>
数学原理</a></h3>
固体的点群 ${S_i}$（含可能的时间反演 $T$）对 k 空间有作用：</p>
$$\mathbf{k}' = S_i,\mathbf{k} \pmod{\mathbf{G}}$$</p>
如果 $\mathbf{k}_a$ 与 $\mathbf{k}_b$ 由某个对称操作连接（可能差一个倒格矢 $\mathbf{G}$），则它们是等价</strong>的，只需计算其中一个，权重相加。</p>
经过 BZ→IBZ 约化后：</p>
$$\sum_{\mathbf{k}\in\text{BZ}} F(\mathbf{k}) = \sum_{\mathbf{k}\in\text{IBZ}} w_\mathbf{k},F(\mathbf{k}),\qquad w_\mathbf{k} = \frac{|\text{star}(\mathbf{k})|}{|G_0|}$$</p>
其中 $|\text{star}(\mathbf{k})|$ 是 k 点的 star 大小，$|G_0|$ 是阶（用于归一化使权重总和=1）。</p>
代码：symkpt</code></a></h3>
位置：shared/common/src/29_kpoints/m_symkpt.F90:93-404</code>。</p>
kptopt</code> 的语义控制对称使用范围</strong>（见 m_kpts.F90:1401-1424</code>）：</p>
kptopt</code></th> 空间对称</th> 时间反演</th> 反铁磁对称</th> 典型用途</th></tr></thead>

1</td> 全部</td> 用</td> 不用</td> GS 标准选项</td></tr>
2</td> 不用</td> 用</td> —</td> DFPT q=0</td></tr>
3</td> 不用</td> 不用</td> —</td> DFPT q≠0 / 非共线磁</td></tr>
4</td> 全部</td> 不用</td> 用</td> 非共线磁（nspden=4）</td></tr>
</tbody></table>
代码片段：</p>
if (kptopt == 1 .or. kptopt == 4) then</span></span>
   nsym_used = 0</span></span>
   do isym = 1, nsym</span></span>
      if (symafm(isym) == 1 .or. kptopt == 4) nsym_used = nsym_used + 1</span></span>
   end do</span></span>
   ABI_MALLOC(symrec, (3,3,nsym_used))</span></span>
   ! 把实空间对称矩阵 symrel 取逆转置得到倒空间矩阵 symrec</span></span>
   do isym = 1, nsym</span></span>
      if (symafm(isym) == 1 .or. kptopt == 4) then</span></span>
         call mati3inv(symrel(:,:,isym), symrec(:,:,nsym_used))</span></span>
      end if</span></span>
   end do</span></span>
else if (kptopt == 2) then</span></span>
   nsym_used = 1</span></span>
   ! 只放一个单位矩阵；时间反演由 timrev=1 单独开启</span></span>
   symrec(1:3, 1:3, 1) = identity</span></span>
end if</span></span></code></pre>
核心约化算法</strong>（m_symkpt.F90:269-340</code>）：</p>
! 按 k 向量长度排序，方便快速跳出</span></span>
do ikpt = 1, nkbz - 1</span></span>
   ind_ikpt = list(ikpt)               ! 排序后的索引</span></span>
   if (wtk_folded(ind_ikpt) < tol16) cycle ! 已被合并</span></span>
   do ikpt2 = ikpt + 1, nkbz</span></span>
      if (length2(ikpt2) - length2(ikpt) > tol8) exit  ! 长度不同，必不等价</span></span>
      ind_ikpt2 = list(ikpt2)</span></span>
      if (wtk_folded(ind_ikpt2) < tol16) cycle</span></span>
      ! 尝试用每个对称操作把 ikpt 映到 ikpt2</span></span>
      do isym = 1, nsym</span></span>
         do itim = 1, (1 - 2*timrev), -2     ! itim = +1 然后 -1（若 timrev=1）</span></span>
            if (isym /= identi .or. itim /= 1) then</span></span>
               ksym(:) = itim * matmul(symrec(:,:,isym), kbz(:,ind_ikpt))</span></span>
               ! 检查 ksym - kbz(:,ind_ikpt2) 是否为整向量（差一个倒格矢）</span></span>
               if (sum(|reduce|) < tol8) then</span></span>
                  ! 找到对称等价，把 ikpt2 的权重并到 ikpt</span></span>
                  wtk_folded(ind_ikpt)  = wtk_folded(ind_ikpt) + wtk_folded(ind_ikpt2)</span></span>
                  wtk_folded(ind_ikpt2) = zero</span></span>
                  ! 记录映射：S*k1 + G = k2</span></span>
                  bz2ibz_smap(1, ind_ikpt2) = ind_ikpt</span></span>
                  bz2ibz_smap(2, ind_ikpt2) = isym</span></span>
                  bz2ibz_smap(3:5, ind_ikpt2) = nint(-ksym(:) + kbz(:,ind_ikpt2) + tol12)</span></span>
                  bz2ibz_smap(6, ind_ikpt2) = (itim == -1) ? 1 : 0</span></span>
                  exit</span></span>
               end if</span></span>
            end if</span></span>
         end do</span></span>
      end do</span></span>
   end do</span></span>
end do</span></span>
</span>
! 取出权重非零的点作为 IBZ</span></span>
nkibz = 0</span></span>
do ikpt = 1, nkbz</span></span>
   if (wtk_folded(ikpt) > tol8) then</span></span>
      nkibz = nkibz + 1</span></span>
      ibz2bz(nkibz) = ikpt</span></span>
   end if</span></span>
end do</span></span></code></pre>
输出</strong>：</p>

nkibz</code>：IBZ 内 k 点数（最终的 nkpt</code>）</li>
ibz2bz(1:nkibz)</code>：IBZ 索引 → BZ 索引</li>
wtk_folded(1:nkbz)</code>：聚合后的权重（IBZ 点上非零，其余为零）</li>
bz2ibz_smap(6, 1:nkbz)</code>：BZ 上每点对应的 IBZ 点 + 用了哪个对称操作 + 偏移倒格矢 + 时间反演标志</li>
</ul>
权重的最终归一化</a></h3>
getkgrid</code> 完成后，所有权重之和应为 1：</p>
$$\sum_{i\in\text{IBZ}} w_i = 1$$</p>
代码会自动除以 $N_{\text{BZ}} = \det(\tt{kptrlatt}) \cdot \tt{nshiftk}$ 来归一化。</p>

能带路径（kptopt < 0</code>）</a></h2>
输入解析</a></h3>
kptopt = -N</code> 表示路径有 N 段、N+1 个端点。代码位置：src/57_iovars/m_inkpts.F90:285-373</code>。</p>
ABI_MALLOC(kptbounds, (3, nsegment+1))    ! 端点</span></span>
ABI_MALLOC(ndivk, (nsegment))             ! 每段分点数</span></span>
</span>
! 路径生成：</span></span>
jkpt = 1</span></span>
kpt(:, 1) = kptbounds(:, 1)</span></span>
do ii = 1, nsegment</span></span>
   dkpt = ndivk(ii)</span></span>
   do ikpt = 1, dkpt</span></span>
      fraction = dble(ikpt) / dble(dkpt)</span></span>
      kpt(:, ikpt+jkpt) = fraction * kptbounds(:, ii+1) &</span></span>
                       + (one-fraction) * kptbounds(:, ii)</span></span>
   end do</span></span>
   jkpt = jkpt + dkpt</span></span>
end do</span></span></code></pre>ndivsm</code> 自动均匀分段</a></h3>
如果用户给的是 ndivsm</code>（推荐），由 mknormpath</code>（m_kpts.F90:3318-3398</code>）根据每段在倒空间中的物理长度自动决定每段的 ndivk</code>：</p>
do ii = 1, nbounds-1</span></span>
   dd(:) = bounds(:,ii+1) - bounds(:,ii)</span></span>
   ! 倒空间度规：lng = sqrt(d^T * gmet * d)</span></span>
   lng(ii) = sqrt( dd(1)*gmet(1,1)*dd(1) + dd(2)*gmet(2,2)*dd(2) + dd(3)*gmet(3,3)*dd(3) &</span></span>
                 + 2*(dd(1)*gmet(1,2)*dd(2) + dd(1)*gmet(1,3)*dd(3) + dd(2)*gmet(2,3)*dd(3)) )</span></span>
end do</span></span>
fct = minval(lng) / ndiv_small</span></span>
ndiv(:) = nint(lng(:) / fct)</span></span>
npt_tot = sum(ndiv) + 1</span></span></code></pre>
这样最短段恰好有 ndivsm</code> 个分点，其他段按比例放大，可视化时每两个 k 点在图上等距。</p>
kptopt<0</code> 路径模式下权重不需要</strong>（NSCF 计算，不积分）；getkgrid</code> 跳过 symkpt</code>。</p>

getkgrid</code>：高层封装</a></h2>
位置：m_kpts.F90:1257-1842</code>。这是 SCF 设置阶段调用的真正入口（由 src/57_iovars/m_inkpts.F90:468</code> 调起）。</p>
它的工作流：</p>

预处理 nshiftk</code></strong>：尝试用素因子分解减少 shiftk</code> 数量（m_kpts.F90:1432-1690</code>，约 250 行的优化算法）。如果两个 shift 之间差一个 k 格矢量，可以合并成更大的 kptrlatt</code> + 更少的 shift。</li>
调 smpbz</code></strong> 生成完整 BZ 上的所有 k 点（spkpt(3, nkptlatt*nshiftk)</code>）和均匀权重 $1/N$。</li>
kptopt=1,2,4</code></strong>：调 symkpt</code> 做对称约化，得到 IBZ k 点和权重。</li>
kptopt=3</code></strong>：直接保留 BZ 全部点。</li>
检查对称性破缺</strong>（chksymbreak=1</code> 时）：所有对称操作下网格应自映射，否则报错。</li>
输出</strong>：kpt(3, nkpt)</code> 是 IBZ 点，wtk(nkpt)</code> 是归一化权重。</li>
</ol>

istwfk</code>：时间反演压缩存储</a></h2>
当 k 点的所有分量都是 0 或 1/2 时（"半整数点"），波函数满足额外的对称性：</p>
$$u_{\mathbf{G}0/2}(\mathbf{G}) = u</em>{\mathbf{G}_0/2}(-\mathbf{G} - \mathbf{G}_0)^*$$</p>
只需存一半的 G 向量，内存和 FFT 时间减半。</p>
代码：src/44_abitools/m_cgtools.F90:919-950</code>：</p>
integer pure function set_istwfk(kpoint) result(istwfk)</span></span>
   real(dp), intent(in) :: kpoint(3)</span></span>
   integer :: bit0, ii, bit(3)</span></span>
   bit0 = 1</span></span>
   do ii = 1, 3</span></span>
      if (DABS(kpoint(ii)) < tol10) then</span></span>
         bit(ii) = 0</span></span>
      else if (DABS(kpoint(ii) - half) < tol10) then</span></span>
         bit(ii) = 1</span></span>
      else</span></span>
         bit0 = 0</span></span>
      end if</span></span>
   end do</span></span>
   if (bit0 == 0) then</span></span>
      istwfk = 1   ! 普通 k 点，不能压缩</span></span>
   else</span></span>
      istwfk = 2 + bit(1) + 4*bit(2) + 2*bit(3)</span></span>
   end if</span></span>
end function</span></span></code></pre>
返回值含义：</p>

istwfk = 1</code>：通用 k 点，不压缩</li>
istwfk = 2</code>：$\Gamma$ 点 (0, 0, 0)</li>
istwfk = 3..9</code>：八个 BZ 边角点（如 (1/2, 0, 0)、(1/2, 1/2, 1/2) 等）</li>
</ul>
用户通常不设 istwfk</code></strong>，让 Abinit 在 m_inkpts.F90:508-520</code> 自动判断。响应函数（RF）、自旋极化（nspinor=2</code>）、SOC 等情形强制为 1。</p>

K点在 SCF 中的并行化</a></h2>
进程分布：distrb2</code></a></h3>
位置：src/51_manage_mpi/m_mpinfo.F90:2299-2574</code>。</p>
把每个 (k 点, 自旋, 能带) 三元组分配到一个 MPI 进程：</p>
mpi_enreg%proc_distrb(ikpt, iband, isppol) = 该任务所属进程号</span></span></code></pre>
策略：</p>

paralbd=0</code>：按 k 点平均分配，要求 nkpt*nsppol</code> 能被 nproc_spkpt</code> 整除（否则警告"不高效"）。</li>
paralbd=1</code>：再把每个 k 点的能带切到多个进程上。</li>
</ul>
之后 mpi_enreg%my_kpttab(ikpt)</code> 给出本地 k 点索引（仅属于本进程的那些）。</p>
SCF k 点循环（vtorho</code>）</a></h3>
位置：src/79_seqpar_mpi/m_vtorho.F90:826-1300</code>（标注为"BIG FAT k POINT LOOP"）。骨架：</p>
do isppol = 1, nsppol</span></span>
   ! 装载该自旋通道的有效势 vlocal</span></span>
   call gs_hamk%load_spin(isppol, vlocal=vlocal, ...)</span></span>
</span>
   ikpt_loc = 0</span></span>
   do while (ikpt_loc < nkpt1)</span></span>
      ikpt_loc = ikpt_loc + 1</span></span>
      ikpt = ikpt_loc</span></span>
      my_ikpt = mpi_enreg%my_kpttab(ikpt)</span></span>
</span>
      ! 跳过非本进程的 k 点</span></span>
      if (proc_distrb_cycle(mpi_enreg%proc_distrb, ikpt, 1, nband_k, isppol, me_distrb)) cycle</span></span>
</span>
      nband_k = dtset%nband(ikpt + (isppol-1)*dtset%nkpt)</span></span>
      istwf_k = dtset%istwfk(ikpt)</span></span>
      npw_k   = npwarr(ikpt)</span></span>
</span>
      ! 调对角化器（CG / RMM-DIIS / LOBPCG / ChebFi），算出 nband_k 个本征值</span></span>
      call vtowfk(...)</span></span>
</span>
      ! 累加每个量到全局：能量、密度</span></span>
      do iband = 1, nband_k</span></span>
         energies%e_kinetic     = energies%e_kinetic     + wtk(ikpt)*occ_k(iband)*ek_k(iband)</span></span>
         energies%e_eigenvalues = energies%e_eigenvalues + wtk(ikpt)*occ_k(iband)*eig_k(iband)</span></span>
         energies%e_nlpsp_vfock = energies%e_nlpsp_vfock + wtk(ikpt)*occ_k(iband)*enlx_k(iband)</span></span>
      end do</span></span>
      ! rho(r) += wtk(ikpt) * occ_k * |psi_k(r)|^2  (在 fft 网格上累加)</span></span>
   end do</span></span>
</span>
   ! MPI 规约：把各进程的 rho、E 加在一起</span></span>
   call xmpi_sum(rhoaug, spaceComm_distrb, ierr)</span></span>
end do</span></span></code></pre>
wtk(ikpt)</code> 在这里就是 BZ 积分的离散权重。所有物理量都通过这个权重做 BZ 平均</strong>。</p>
占据数计算（衔接 smearing）</a></h3>
每次 SCF 迭代后：</p>

收集所有 $\epsilon_{n\mathbf{k}}$；</li>
调 newocc</code>（见 smearing 报告）二分法求 Fermi 能级和占据数 $f_{n\mathbf{k}}$；</li>
用 $w_\mathbf{k} \cdot f_{n\mathbf{k}}$ 加权累积下一轮 $\rho(\mathbf{r})$。</li>
</ol>

Abinit 中 k 点的完整生命周期</a></h2>
下面按时间顺序，描述一次 SCF 计算从输入到输出，k 点的每个阶段。</p>
阶段 1：输入解析（m_inkpts.F90</code>）</a></h3>

读 kptopt</code>、ngkpt</code>、shiftk</code>、kptrlatt</code> 等</li>
若 kptopt < 0</code>：直接构造路径 kpt(:,:)</code>（m_inkpts.F90:285-380</code>）</li>
若 kptopt > 0</code> 且未给 ngkpt/kptrlatt</code>：调 testkgrid</code> 自动搜索最优网格（m_inkpts.F90:456</code>）</li>
调 getkgrid</code> 生成 IBZ k 点 + 权重（m_inkpts.F90:468</code>）</li>
对每个 k 点调 set_istwfk</code> 决定存储模式（m_inkpts.F90:511</code>）</li>
</ol>
阶段 2：MPI 初始化（m_mpinfo.F90</code>）</a></h3>

调 distrb2</code> 把 k 点分配到 MPI 进程：mpi_enreg%proc_distrb</code></li>
建立本地映射 mpi_enreg%my_kpttab(ikpt)</code></li>
</ol>
阶段 3：每个 k 点的内存预分配</a></h3>

在 G 空间球内填入 G 向量：m_kg.F90:kpgio</code>，每个 k 点的 npw_k</code> 和 kg_k(3, npw_k)</code></li>
计算非局域投影：nonlocal/</code>、fock/</code> 等</li>
</ul>
阶段 4：SCF 主循环（m_dft_energy</code>/m_vtorho</code>）</a></h3>
对每次迭代 istep = 1..nstep</code>：</p>
do isppol = 1, nsppol               # 自旋外循环</span></span>
   load V_xc, V_H, V_ext            # 当前势函数</span></span>
   do ikpt = 1, nkpt                # k 点循环</span></span>
      if (该进程不负责 ikpt) cycle</span></span>
      H_k = T_k + V_loc + V_nl(k)   # 构造 k 处 Hamiltonian</span></span>
      solve H_k |psi_nk> = e_nk |psi_nk>      # 对角化（npw_k * nband_k 维）</span></span>
      do iband = 1, nband_k</span></span>
         rho(r) += wtk(ikpt) * occ_k(iband) * |psi_nk(r)|^2</span></span>
         E_band += wtk(ikpt) * occ_k(iband) * e_nk</span></span>
      end do</span></span>
   end do</span></span>
end do</span></span>
xmpi_sum(rho, E_band, ...)           # 跨进程规约</span></span>
</span>
# 算 V_xc[rho]、E_total = E_band - E_dc + ... - TS</span></span>
# 调 newocc 更新 occ 和 fermie</span></span>
if (rho 已收敛) exit</span></span></code></pre>阶段 5：输出（m_iowf</code>、m_clnup1</code>）</a></h3>

写 WFK 文件：每个 k 点的 (kpt, wtk, npw_k, kg_k, eigen_k, occ_k, cg_k)</li>
写 EIG 文件：本征值数据</li>
写 DOS（若 prtdos=1</code>）：在所有 IBZ 点上用 smearing 函数做加权求和</li>
</ul>

典型例子</a></h2>
FCC Si（半导体），8×8×8</code> 网格</a></h3>
输入：</p>
kptopt 1</span></span>
ngkpt 8 8 8</span></span>
nshiftk 4</span></span>
shiftk 0.5 0.5 0.5</span></span>
       0.5 0.0 0.0</span></span>
       0.0 0.5 0.0</span></span>
       0.0 0.0 0.5</span></span></code></pre>
执行：</p>

BZ 全部点数：det(kptrlatt) * nshiftk = 8³ * 4 = 2048</code></li>
Si 的 Fd-3m 对称群有 48 个操作 + 时间反演 = 96 个</li>
symkpt</code> 把 2048 → 通常约 60</strong> 个 IBZ 点（具体数依赖网格规整性）</li>
每个 IBZ 点权重 $w_i \in {1/2048, 2/2048, ...}$，总和=1</li>
</ul>
BCC Fe（金属磁性），16×16×16</code></a></h3>
kptopt 1</span></span>
ngkpt 16 16 16</span></span>
nshiftk 1</span></span>
shiftk 0.5 0.5 0.5</span></span>
nsppol 2</span></span>
occopt 7</span></span>
tsmear 0.001</span></span></code></pre>
执行：</p>

BZ 点数：4096</li>
O_h 群 + 时间反演 = 96</li>
IBZ ≈ 126</strong> 点（具体由 Abinit 计算）</li>
每个 IBZ 点要算 2 套自旋（共 252 个独立对角化任务）</li>
用 MPI 16 进程：每进程平均 16 个 k 点，建议设置 paral_kgb 1</code> 让 nproc=nproc_kpt × nproc_band × nproc_fft</li>
</ul>
GaAs 能带结构</a></h3>
ndtset 2</span></span>
# dataset 1: SCF</span></span>
kptopt1 1</span></span>
ngkpt1 4 4 4</span></span>
shiftk1 0.5 0.5 0.5</span></span>
prtden1 1</span></span>
# dataset 2: NSCF along L-Γ-X-W-K-Γ</span></span>
iscf2 -2</span></span>
getden2 -1</span></span>
kptopt2 -5</span></span>
kptbounds2 0.5  0.5  0.5  # L</span></span>
           0.0  0.0  0.0  # Gamma</span></span>
           0.0  0.5  0.5  # X</span></span>
           0.25 0.5  0.75 # W</span></span>
           0.375 0.375 0.75 # K</span></span>
           0.0  0.0  0.0  # Gamma</span></span>
ndivsm2 20</span></span>
tolwfr2 1d-10</span></span></code></pre>
mknormpath</code> 算出路径总长，按最短段 20 分点比例分配，生成约 100 个 k 点的等距路径。</p>

关键代码地图</a></h2>
模块 / 子程序</th> 文件</th> 行号</th> 作用</th></tr></thead>

inkpts</code></td> src/57_iovars/m_inkpts.F90</code></td> 全文件</td> 输入参数解析 + 路径生成</td></tr>
getkgrid</code></td> src/56_recipspace/m_kpts.F90</code></td> 1257</td> 高层 IBZ k 网格生成</td></tr>
smpbz</code></td> 同上</td> 2088</td> Monkhorst-Pack BZ 采样</td></tr>
testkgrid</code></td> 同上</td> 2654</td> 自动枚举最优 k 网格</td></tr>
mknormpath</code></td> 同上</td> 3318</td> 能带路径均匀分点</td></tr>
listkk</code></td> 同上</td> 866</td> 两套 k 网格之间的对称映射</td></tr>
get_full_kgrid</code></td> 同上</td> 1843</td> 由 IBZ 反展开到完整 BZ</td></tr>
symkpt</code></td> shared/common/src/29_kpoints/m_symkpt.F90</code></td> 93</td> BZ → IBZ 对称约化</td></tr>
symkpt_new</code></td> 同上</td> 424</td> 新版（用 hash 表，O(N) 复杂度）</td></tr>
mapkptsets</code></td> 同上</td> 670</td> 把一组 k 点映到另一组</td></tr>
set_istwfk</code></td> src/44_abitools/m_cgtools.F90</code></td> 919</td> 时间反演压缩选择</td></tr>
distrb2</code></td> src/51_manage_mpi/m_mpinfo.F90</code></td> 2299</td> k 点 MPI 分配</td></tr>
vtorho</code> 的 k 循环</td> src/79_seqpar_mpi/m_vtorho.F90</code></td> 826</td> SCF k 点积分主循环</td></tr>
mknormpath</code> 调用</td> src/57_iovars/m_inkpts.F90</code></td> 326</td> 路径模式入口</td></tr>
</tbody></table>

参数选择建议</a></h2>

绝缘体/半导体</strong>：ngkpt 4 4 4</code>～8 8 8</code>，nshiftk 1</code>，shiftk 0.5 0.5 0.5</code>。</li>
金属</strong>：从 12 12 12</code> 起步，根据收敛性增加到 24 24 24</code> 甚至更密。</li>
小元胞超导/磁性体</strong>：16 16 16</code>～32 32 32</code> 不罕见，配 smearing 收敛。</li>
大元胞（>50 原子）</strong>：从 2 2 2</code> 或 Gamma-only</code> 开始，必要时加密。</li>
二维材料</strong>：ngkpt N N 1</code>（真空方向 1 点），用 slabwsrad</code> 切断。</li>
能带结构</strong> ndivsm</code>：粗略图 10、出版图 20–40。</li>
shiftk</strong> 的选择：

默认 0.5 0.5 0.5</code> 在很多体系收敛最快，但破缺四方/六方对称</strong>，会被 Abinit 拒绝。</li>
兼容性最好但收敛慢：0 0 0</code>（含 Γ）。</li>
FCC 优选：4 个 shift (½ ½ ½) (½ 0 0) (0 ½ 0) (0 0 ½)</code>。</li>
六方推荐：0 0 ½</code>。</li>
</ul>
</li>
chksymbreak</code></strong>：建议保留默认 1，否则错误的网格会静默给出错的结果。</li>
</ul>

附录：一次完整 SCF 中 k 点处理逐步追踪</a></h2>
设输入：FCC Si, ngkpt 4 4 4</code>, nshiftk 4</code>（默认 FCC 4-shift）, kptopt 1</code>。</p>
Step 1: 输入解析</a></h3>
m_inkpts.F90</code> 读到 kptopt=1</code>, ngkpt=4 4 4</code>, 自动构造 kptrlatt = diag(4,4,4)</code>。</p>
Step 2: 进入 getkgrid</code></a></h3>

nshiftk_reduction</code>：发现 4 个 shifts 可以合并成 kptrlatt = ((-4 4 4), (4 -4 4), (4 4 -4))</code> + nshiftk=1</code>（FCC k 格的紧致表示）。</li>
调 smpbz</code>，扫 BZ 上 $\det(\tt{kptrlatt}) = 128$ 个 k 点。</li>
</ul>
Step 3: symkpt</code> 约化</a></h3>

Si 有 48 个空间对称 + 时间反演 = 96</li>
排序 128 个 k 点的长度（m_symkpt.F90:178-204</code>）</li>
双重循环找等价对：每个对称操作作用后看能否落到其他 k 点上</li>
最终 nkibz = 10</code>（FCC Si 的标准结果），权重比例如 (1, 8, 6, 24, 8, 6, 12, 8, 24, 3) / 128</code></li>
</ul>
Step 4: 设置 istwfk</code></a></h3>

对每个 IBZ k 点，调 set_istwfk</code></li>
Γ 点得到 istwfk = 2</code>，X 点得到 istwfk = 3..4</code>（看具体哪个分量），其余多为 1</li>
这影响 G 球内 npw_k</code> 的实际存储数</li>
</ul>
Step 5: G 球预分配</a></h3>

对每个 k，从 0.5*|k+G|² < ecut</code> 选出 npw_k</code> 个 G 向量</li>
调 kpgio</code> 建立 kg_k(3, npw_k)</code></li>
</ul>
Step 6: MPI 分发（假设 5 个 MPI 进程）</a></h3>

distrb2</code>：10 IBZ kpt / 5 proc = 每进程 2 个 k 点</li>
例：proc 0 拿 (k=1,2)，proc 1 拿 (k=3,4)，…</li>
</ul>
Step 7: SCF 迭代</a></h3>
每步 SCF：</p>

每进程并行求解自己负责的 2 个 k 点的 Hamiltonian 矩阵：
$H_\mathbf{k} \psi_{n\mathbf{k}} = \epsilon_{n\mathbf{k}} \psi_{n\mathbf{k}}$（约 200 plane waves × 20 bands）</li>
局部累积 rho_proc(r) += wtk(k) * occ * |psi|²</code></li>
xmpi_sum</code>：把 5 个进程的 rho 加起来</li>
算 V_new(r) = V_H[rho] + V_xc[rho] + V_ext</li>
调 newocc</code> 二分找 Fermi 能级（只用 IBZ 的 10 个 k 点</strong>，因为权重已经包含了 BZ 折叠）</li>
检查 tolvrs / toldfe / ...</code> 是否达标</li>
</ol>
Step 8: 输出</a></h3>

写 WFK：保存 kpt(3, 10)</code>, wtk(10)</code>, eigen(nband, 10)</code>, occ(nband, 10)</code>, cg(2, npw_k*nband, 10)</code></li>
写 EIG：纯本征值文本</li>
若 prtdos=1</code>：在 10 个 IBZ 点上用展宽函数做加权和得到 DOS</li>
</ul>

报告生成于 2026-05-19，基于 Abinit 10.4.7。</em></p>
References</a></h2>
Gonze, Xavier, et al. "The Abinit Project: Impact, Environment and Recent Developments." Computer Physics Communications</em>, vol. 248, 2020, p. 107042. link</a></p>
Monkhorst, Hendrik J., and James D. Pack. "Special Points for Brillouin-Zone Integrations." Physical Review B</em>, vol. 13, no. 12, 1976, pp. 5188–5192. link</a></p>
The Abinit Code. Version 10.4.7, 2024. link</a></p>


Abinit occopt：占据数选项完整解析
2026-05-19T00:00:00+00:00
</span>Abinit occopt</code>：占据数选项完整解析</a></h1>

基于 Abinit 10.4.7 源码分析
核心模块：</p>

src/44_abitypes_defs/m_dtset.F90</code>（占据数初始化 dtset_initocc_chkneu</code>）</li>
src/57_iovars/m_invars1.F90</code>（fband</code> → nband</code> 自动计算）</li>
src/57_iovars/m_chkinp.F90</code>（occ</code> 一致性检查）</li>
src/61_occeig/m_occ.F90</code>（占据更新 newocc</code>, getnel</code>, occ_fd</code> 等）</li>
src/79_seqpar_mpi/m_vtorho.F90</code>（SCF 中的固定/可变占据分支）</li>
src/67_common/m_mkrho.F90</code>（占据数 × 波函数 → 密度）</li>
abimkdocs/variables_abinit.py</code>（变量定义）</li>
</ul>
</blockquote>

引言：占据数在 DFT 中的角色</a></h2>
Kohn-Sham 密度的构造是</p>
$$\rho(\mathbf{r}) = \sum_{\sigma}\sum_{n,\mathbf{k}} w_\mathbf{k},f_{n\mathbf{k}\sigma},|\psi_{n\mathbf{k}\sigma}(\mathbf{r})|^2$$</p>
其中 $f_{n\mathbf{k}\sigma} \in [0, f_{\max}]$ 是占据数。它必须满足全电子数约束</p>
$$\sum_{\sigma n \mathbf{k}} w_\mathbf{k}, f_{n\mathbf{k}\sigma} = N_{\text{elect}}$$</p>
总能（变分）</p>
$$E_{\text{tot}}[\rho, {f}] = \sum w_\mathbf{k},f_{n\mathbf{k}},\epsilon_{n\mathbf{k}} - E_{\text{dc}}[\rho] - T,S[{f}]$$</p>
最后一项熵贡献只在有限温（金属型 smearing）时出现。</p>
occopt</code> 决定了 ${f_{n\mathbf{k}\sigma}}$ 如何确定：</p>

由用户手动给定</strong>（occopt = 0, 2</code>）</li>
由代码按"半导体满填"自动给定</strong>（occopt = 1</code>）</li>
由 Fermi-Dirac / Gaussian / Cold smearing 等公式根据当前本征值动态计算</strong>（occopt = 3..8</code>）</li>
双 Fermi 能级，强制激发态</strong>（occopt = 9</code>）</li>
</ol>
下文按"输入参数 → 物理原理 → 公式 → 代码实现 → 一步步流程"展开。</p>

occopt</code> 全部 10 种取值速查</a></h2>
occopt</code></th> 类型</th> 占据决定方式</th> $N_{\text{band}}$ 行为</th> 物理含义</th></tr></thead>

0</td> 固定</td> 用户手动 occ</code> 数组 + 用户手动 wtk</code></td> 单一标量</td> 完全自定义；适合特殊计算</td></tr>
1</td> 固定</td> 代码自动生成"半导体填充"</td> 单一标量；可由 fband</code> 推算</td> 绝缘体/半导体默认</strong>；要求整数填充</td></tr>
2</td> 固定</td> 用户手动 occ</code>（k 点/带分别给）+ 手动 wtk</code></td> 数组 nband(ikpt,isppol)</code> 可不同</td> 每个 k 点不同 band 数；最大自由度</td></tr>
3</td> 可变</td> Fermi-Dirac（真有限温）</td> 自动</td> 真实有限温金属</td></tr>
4</td> 可变</td> Marzari 冷展宽，a=−0.5634</td> 自动</td> 金属 + 收敛</td></tr>
5</td> 可变</td> Marzari 冷展宽，a=−0.8165</td> 自动</td> 金属 + 单调占据</td></tr>
6</td> 可变</td> Methfessel-Paxton 2 阶</td> 自动</td> 金属 + 高精度</td></tr>
7</td> 可变</td> Gaussian smearing</td> 自动</td> 金属默认推荐</strong></td></tr>
8</td> 可变</td> 均匀展宽</td> 自动</td> 仅测试用</td></tr>
9</td> 可变</td> 双 quasi-Fermi 能级（FD）</td> 自动</td> 激发态（ΔSCF），需 ivalence</code>, nqfd</code></td></tr>
</tbody></table>
判定标准：</p>

occopt < 3</code> → 固定占据（fixed_occ = .true.</code>）：SCF 期间不调 newocc</code></li>
occopt >= 3</code> → 金属型（可变）：每次 SCF 步都调 newocc</code></li>
</ul>
关键代码（src/79_seqpar_mpi/m_vtorho.F90:527</code>）：</p>
fixed_occ = (dtset%occopt < 3 .or. electronpositron_calctype(electronpositron) == 1)</span></span></code></pre>

与占据相关的输入参数总览</a></h2>
下表收齐了所有与 occopt</code> 直接/间接相关的输入变量（定义位置 abimkdocs/variables_abinit.py</code>）：</p>
输入变量</th> 类型</th> 默认值</th> 适用 occopt</code></th> 作用</th></tr></thead>

occopt</code></td> int</td> 1</td> 全</td> 占据方案选择</td></tr>
occ</code> / occ_orig</code></td> real(nband*nkpt*nsppol)</td> 0</td> 0, 2</td> 手动输入占据数</td></tr>
nband</code></td> int</td> 自动</td> 全</td> k 点上的能带数（occopt=2</code> 可数组）</td></tr>
fband</code></td> real</td> 0.125（occopt=1）/ 0.5（其他）</td> 1, 3..9</td> 自动 nband</code> 时附加 band 系数</td></tr>
wtk</code></td> real(nkpt)</td> 1.0</td> 0, 2</td> 手动 k 点权重（其他自动归一化）</td></tr>
cellcharge</code></td> real(nimage)</td> 0</td> 全</td> 单胞电荷数（决定 nelect</code>）</td></tr>
nelect</code></td> real</td> INTERNAL</td> 全</td> 价电子总数（由 zion-cellcharge 算出）</td></tr>
tsmear</code></td> real</td> 0.01 Ha</td> 3..9</td> 展宽宽度 / 电子温度</td></tr>
tphysel</code></td> real</td> 0.0</td> 4..7</td> 物理温度（双重 smearing）</td></tr>
spinmagntarget</code></td> real</td> −99.99</td> 1, 3..7</td> 固定磁矩</td></tr>
ivalence</code></td> int</td> 0</td> 9</td> 价带最高指标</td></tr>
nqfd</code></td> real</td> 0.0</td> 9</td> 激发电子/空穴数</td></tr>
nspinor</code></td> int</td> 1</td> 全</td> 自旋自由度（影响 maxocc）</td></tr>
nsppol</code></td> int</td> 1</td> 全</td> 自旋通道数</td></tr>
nspden</code></td> int</td> 1</td> 全</td> 自旋密度组件数</td></tr>
prtstm</code></td> int</td> 0</td> 7</td> STM 模式偏置占据</td></tr>
stmbias</code></td> real</td> 0.0</td> 7 + prtstm</td> STM 偏压</td></tr>
nbdbuf</code></td> int</td> 0</td> 全</td> 顶端 band 缓冲（不参与收敛检查）</td></tr>
</tbody></table>
nelect</code> 的计算</a></h3>
代码位置：src/44_abitypes_defs/m_dtset.F90:1199-1208</code>：</p>
zval = 0</span></span>
do iatom = 1, natom</span></span>
   zval = zval + ziontypat(typat(iatom))</span></span>
end do</span></span>
nelect = zval - (cellcharge - nelectjell)</span></span></code></pre>
其中 ziontypat</code> 来自每种伪势文件头部的 Zion（价电子数）。</p>
maxocc</code> 与每条带容量</a></h3>
maxocc = 2 / (nsppol * nspinor)</span></span></code></pre>

nsppol=1, nspinor=1</code> → maxocc=2</code>（每条带可装 2 个电子，自旋简并）</li>
nsppol=2, nspinor=1</code> → maxocc=1</code>（自旋极化，每条带 1 个）</li>
nsppol=1, nspinor=2</code> → maxocc=1</code>（非共线，自旋升降同等地位）</li>
nsppol=2, nspinor=2</code> → maxocc=0.5</code>（理论上禁止，代码会报错）</li>
</ul>

占据数初始化：dtset_initocc_chkneu</code></a></h2>
代码位置：src/44_abitypes_defs/m_dtset.F90:1181-1444</code>，是整个 SCF 启动前的占据数主入口。它做三件事：</p>

计算 nelect</code></strong>：核电荷数减去 cellcharge</code></li>
初始化 occ_orig</code></strong>（仅当 occopt = 1</code> 或 3..9</code> 时；occopt = 0, 2</code> 时占据数由用户手动给）</li>
检查电荷平衡</strong>：Σ wtk × occ ≈ nelect</code>，偏差超 tol8</code> 报错</li>
</ol>
半导体填充算法（occopt = 1</code> 或 3..9</code> 的初始猜测）</a></h3>
代码 m_dtset.F90:1216-1289</code>：</p>
if (occopt == 1 .or. (occopt >= 3 .and. occopt <= 9)) then</span></span>
</span>
   maxocc = 2.0 / (nsppol * nspinor)</span></span>
</span>
   ! 全占满的能带数</span></span>
   nocc = int((nelect - nh_qFD - 1e-8) / maxocc) + 1</span></span>
</span>
   ! 最高占据带的"残量"（可能 < maxocc）</span></span>
   occlast = nelect - nh_qFD - maxocc * (nocc - 1)</span></span>
</span>
   ! 检查 nband 足够</span></span>
   if (nocc <= nband(1) * nsppol .or. iscf == -2) then</span></span>
</span>
      ! 情况 A: 无磁矩约束</span></span>
      if (spinmagntarget < -99.98) then</span></span>
         tmpocc(1 : nocc-1) = maxocc        ! 全满</span></span>
         tmpocc(nocc)      = occlast        ! 最后一带部分填</span></span>
         tmpocc(nocc+1 :)  = zero           ! 空带</span></span>
</span>
      ! 情况 B: 固定磁矩 (nsppol=2)</span></span>
      else</span></span>
         do isppol = 1, nsppol</span></span>
            sign_spin = 3 - 2*isppol         ! +1 spin-up, -1 spin-down</span></span>
            nelect_spin = 0.5 * (nelect * maxocc + sign_spin * spinmagntarget)</span></span>
            nocc = ceiling(nelect_spin / maxocc)</span></span>
            occlast = nelect_spin - (nocc-1)*maxocc</span></span>
            occ(1:nocc-1, isppol) = maxocc</span></span>
            occ(nocc,    isppol) = occlast</span></span>
            occ(nocc+1:, isppol) = 0</span></span>
         end do</span></span>
      end if</span></span>
   end if</span></span>
end if</span></span></code></pre>
示例</strong>：nelect=8</code> (Si), nsppol=1</code>, nspinor=1</code>：</p>

maxocc = 2</code></li>
nocc = int((8-0-1e-8)/2) + 1 = 4</code> → 4 条全满带</li>
occlast = 8 - 2*3 = 2</code> → 第 4 带也是满的</li>
occ_orig = [2, 2, 2, 2, 0, 0, 0, 0]</code>（如果 nband=8）</li>
</ul>
有半填的例子</strong>：nelect=7</code> (Al, nsppol=1)：</p>

nocc = int(7/2-eps) + 1 = 4</code></li>
occlast = 7 - 2*3 = 1</code> → 第 4 带半填</li>
occ_orig = [2, 2, 2, 1, 0, 0, 0]</code></li>
</ul>
这种"非 0 非满"的半填会触发 occopt=1</code> 报错（除非是 H 原子），告诉用户改用 occopt=7</code>。检查代码 m_chkinp.F90:2780-2792</code>。</p>
occopt=9 的双 Fermi 分支</a></h3>
m_dtset.F90:1245-1268</code>，先填价带（留 nh_qFD</code> 个空穴）：</p>
if (occopt == 9) then</span></span>
   ! 填到 ivalence-1 满，第 ivalence 部分填到 nelect-nh_qFD</span></span>
   tmpocc(nocc+1 : ivalence*nsppol) = zero    ! 价带顶部留空穴</span></span>
   nocc2 = (ne_qFD - 1e-8) / maxocc + 1</span></span>
   occlast2 = ne_qFD - maxocc * (nocc2 - 1)</span></span>
   ! 然后在导带（ivalence+1..）填 ne_qFD 个电子</span></span>
   tmpocc(ivalence*nsppol + 1 : ivalence*nsppol + nocc2 - 1) = maxocc</span></span>
   tmpocc(ivalence*nsppol + nocc2)                          = occlast2</span></span>
end if</span></span></code></pre>
得到例如：occ = [2, 2, 2, 1.5, 0, ..., 0, 0.5, 0, ...]</code>（价带顶部 0.5 个空穴，导带底部 0.5 个电子）。</p>
电荷平衡检查</a></h3>
代码 m_dtset.F90:1380-1442</code>：</p>
nelect_occ = 0</span></span>
do isppol, ikpt, iband</span></span>
   nelect_occ = nelect_occ + wtk(ikpt) * occ_orig(...)</span></span>
end do</span></span>
</span>
if (|nelect_occ - nelect| > tol11) → 警告</span></span>
if (|nelect_occ - nelect| > tol8)  → 错误并停止</span></span></code></pre>
注意：</p>

occopt = 0, 2</code>：用户给定占据。代码核对总数</li>
occopt = 1, 3..9</code>：代码刚生成占据，这步检查只是个 sanity check</li>
occopt = 2</code> 特殊：wtk</code> 不自动归一化</strong>，必须用户保证 $\sum w_k = 1$（其他都自动归一化）</li>
</ul>

nband</code> 的自动决定（与 fband</code> 联动）</a></h2>
代码位置：src/57_iovars/m_invars1.F90:1933-2021</code>。当用户没指定 nband</code>（且 occopt</code> 不是 0 或 2），由 fband</code> 自动算出：</p>
! fband 默认值</span></span>
if (occopt == 1) fband = 0.125    ! 绝缘体只需少量空带</span></span>
else            fband = 0.5       ! 金属需要更多空带做 smearing</span></span>
</span>
! 自动 nband 公式</span></span>
zelect = zval - cellcharge_min</span></span>
mband_upper = nspinor * ( (ceiling(zelect-tol10) + 1) / 2          &</span></span>
                          + ceiling(fband*natom - tol10) )         &</span></span>
            + (nsppol - 1) * ceiling(half * sum_spinat)</span></span>
</span>
nband(:) = mband_upper</span></span></code></pre>
含义：</p>

基础</strong>：填满 zelect</code> 个电子所需的最小 band 数 ≈ ceiling(zelect/2)</code></li>
缓冲</strong>：再加 fband × natom</code> 条空带（默认绝缘体 12.5%，金属 50%）</li>
自旋极化补丁</strong>：nsppol=2</code> 时额外加 spinat</code> 总和的一半</li>
</ol>
示例</strong>：Si (8 电子, natom=1)：</p>

occopt=1</code>：mband_upper = 1 * (4 + ceiling(0.125*1)) = 5</code></li>
occopt=7</code>：mband_upper = 1 * (4 + ceiling(0.5*1)) = 5</code></li>
</ul>
示例</strong>：Al (3 电子, natom=1)：</p>

occopt=7</code>：mband_upper = 1 * (2 + 1) = 3</code></li>
</ul>
用户可以显式给 nband，覆盖 fband 默认</strong>，对金属强烈建议显式设大（例如 1.5 倍占据 band 数）。</p>

occopt = 0</code>：手动占据</a></h2>
输入要求</a></h3>
occopt 0</span></span>
nband 8                          # 单标量</span></span>
nkpt 10</span></span>
nsppol 1</span></span>
occ                              # nband*nsppol = 8 个数</span></span>
  2.0 2.0 2.0 2.0  0.0 0.0 0.0 0.0</span></span>
wtk                              # nkpt = 10 个数</span></span>
  0.5  1.0 ... ...</span></span></code></pre>
所有 k 点共享同一组 occ</code>，wtk</code> 由用户保证 $\sum w_k = 1$。</p>
代码处理</a></h3>
m_chkinp.F90:2743-2769</code> 做：</p>
if ((iscf > 0 .or. iscf == -1 .or. iscf == -3) .and. (occopt == 0 .or. occopt == 2)) then</span></span>
   sumocc = 0</span></span>
   do iband over all bands:</span></span>
      if (occ < -tol8) → 报错"负占据"</span></span>
      sumocc += occ</span></span>
   end do</span></span>
   if (sumocc < 1e-8) → 报错"未定义"</span></span>
end if</span></span></code></pre>
进一步通过 dtset_initocc_chkneu</code> 检查 $\sum w_k \cdot \text{occ} = N_{\text{elect}}$。</p>
应用场景</a></h3>

强制磁矩高自旋态（如 Cr+5+ d¹ 配置）</li>
验证波函数耦合（特殊几何）</li>
与外部代码做对比测试</li>
</ul>

occopt = 1</code>：半导体自动填充（默认值</strong>）</a></h2>
触发条件</a></h3>
需满足"整数填充"：(nelect - nh_qFD)</code> 必须正好等于 maxocc * n</code> 形式（n 整数），否则代码报错。</p>
算法</a></h3>
dtset_initocc_chkneu</code> 第 4.1 节算法的退化情形（spinmagntarget = -99.99</code>）。</p>
自旋极化时的强制 spinmagntarget</code></a></h3>
m_chkinp.F90:2780-2792</code>：当 nsppol=2</code> 且 occopt=1</code> 时，必须</strong>显式给 spinmagntarget</code>（除非是 H 原子）：</p>
if (nsppol == 2 .and. occopt == 1 .and. abs(spinmagntarget+99.99) < tol8) then</span></span>
   if (natom /= 1 .or. |znucl-1| > tol8) then</span></span>
      ABI_ERROR("In nsppol=2 + occopt=1 case, must specify spinmagntarget. ...")</span></span>
   end if</span></span>
end if</span></span></code></pre>
原因：纯填充无法决定 spin-up / spin-down 各占多少；需要用户告诉系统期望的磁矩。</p>
反铁磁的特殊处理</a></h3>
反铁磁体（如 NiO）用 nsppol=1, nspden=2</code>：自旋密度分量在同一通道内交替分布，不需要 spinmagntarget</code>。occopt=1</code> 在这种情形下也能用。</p>

occopt = 2</code>：每 k 点自由占据</a></h2>
输入要求</a></h3>
occopt 2</span></span>
nband     12 8 10 8 ...           # nkpt*nsppol 个值</span></span>
occ       2.0 2.0 ...             # Σ_ikpt nband(ikpt) * nsppol 个数</span></span>
wtk       0.05 0.10 ...           # NOT 自动归一化</span></span></code></pre>
每 k 点的 band 数可以不一样（其他 occopt 都要求 nband</code> 是标量）。</p>
代码分支</a></h3>
src/57_iovars/m_invars1.F90:2009-2017</code>：</p>
else if (occopt == 2) then</span></span>
   ABI_MALLOC(reaalloc, (nkpt*nsppol))</span></span>
   call intagm(reaalloc, nband, ..., 'nband', tnband, 'INT')</span></span>
   if (tnband == 1) then</span></span>
      do ikpt = 1, nkpt*nsppol</span></span>
         if (nband(ikpt) > mband_upper) mband_upper = nband(ikpt)</span></span>
      end do</span></span>
   end if</span></span>
end if</span></span></code></pre>
vtorho</code> 在 k 点循环时有特殊分支（m_vtorho.F90:215, 267 等</code>）：</p>
if (occopt == 2) high_band_index = nband(ikpt + nkpt*(isppol-1))</span></span></code></pre>应用场景</a></h3>

强迫某 k 点上的占据 (响应函数测试)</li>
在特定 k 点用更多 band 提高精度</li>
历史用法：早期版本算 SOC 的 workaround</li>
</ul>
不推荐普通用户使用，复杂且易错。</p>

occopt = 3..9</code>：可变占据（smearing）</a></h2>
这部分已在 abinit_smearing_report.md</code> 中详细写过。这里仅给一个与本报告焦点相关的浓缩</strong>。</p>
八种 smearing 核函数</a></h3>
设 $x = (\mu - \epsilon)/k_BT$，下表给出展宽 δ 函数 $\tilde{\delta}(x)$ 与对应占据数函数 $f(x) = \int_{-\infty}^x \tilde{\delta}(x')dx'$：</p>
occopt</code></th> $\tilde{\delta}(x)$</th> $f(x)$</th></tr></thead>

3</td> $\dfrac{1}{4\cosh^2(x/2)}$</td> $\dfrac{1}{1+e^{-x}}$</td></tr>
4</td> $\dfrac{e^{-x^2}}{\sqrt{\pi}}\bigl(1.5 - 1.5ax - x^2 + ax^3\bigr)$, $a=-0.5634$</td> （数值积分）</td></tr>
5</td> 同 4 但 $a=-0.8165$</td> （数值积分）</td></tr>
6</td> $\dfrac{1}{\sqrt{\pi}}(1.5-x^2)e^{-x^2}$</td> （数值积分）</td></tr>
7</td> $\dfrac{1}{\sqrt{\pi}}e^{-x^2}$</td> $\tfrac{1}{2}(1+\text{erf}(x))$</td></tr>
8</td> 矩形函数（$\lvert x\rvert<1/2$ 时 1，否则 0）</td> 线性</td></tr>
9</td> 同 3，但两个独立 $\mu$</td> 同 3</td></tr>
</tbody></table>
代码位置：src/61_occeig/m_occ.F90:1116-1168</code>。所有公式被预先在 12001 点的查找表里离散化，运行时通过 splfit</code> 三次样条插值得到 $f$、$s$、$df/dx$。</p>
SCF 中的占据更新</a></h3>
每次 SCF 步在 vtorho</code> 里：</p>

求解 $H\psi = \epsilon\psi$ 得新本征值 ${\epsilon_{n\mathbf{k}}}$</li>
调 newocc</code></strong> 用二分法（最多 120 次）找 Fermi 能级 $\mu$ 使 $\sum w_\mathbf{k} f_{n\mathbf{k}} = N_{\text{elect}}$</li>
更新 occ(:)</code> 和 doccde(:)</code>（占据对能量的导数）</li>
用新 occ 累加密度 $\rho(\mathbf{r})$</li>
</ol>
代码片段（m_vtorho.F90:1365-1369</code>）：</p>
call newocc(doccde, eigen, energies%entropy_ks, energies%e_fermie, energies%e_fermih, &</span></span>
            ivalence, spinmagntarget, mband, nband, nelect, ne_qFD, nh_qFD, &</span></span>
            nkpt, nspinor, nsppol, occ, occopt, prtvol, tphysel, tsmear, wtk, &</span></span>
            prtstm=prtstm, stmbias=stmbias, extfpmd=extfpmd)</span></span></code></pre>熵进入总能</a></h3>
occopt ∈ {3..8}</code> 时（不含 9），总能多一项 $-TS$：</p>
if (occopt >= 3 .and. occopt <= 8) then</span></span>
   if (|tphysel| < tol10) then</span></span>
      e_entropy = -tsmear * entropy</span></span>
   else</span></span>
      e_entropy = -tphysel * entropy</span></span>
   end if</span></span>
end if</span></span></code></pre>
这就是 Mermin 自由能 $F = E - TS$。代码 src/67_common/m_dft_energy.F90:1148-1156</code>。</p>

占据与密度的耦合（mkrho</code>）</a></h2>
代码位置：src/67_common/m_mkrho.F90</code>。每个 SCF 步收尾时由本子程序把占据数 × 波函数 → 密度：</p>
do isppol, ikpt:</span></span>
   weight = wtk(ikpt) / ucvol</span></span>
   do iband = 1, nband_k:</span></span>
      if (|occ(iband)| > tol8) then         ! 跳过零占据的 band</span></span>
         weight_t(nband_occ) = occ(iband) * wtk(ikpt) / ucvol</span></span>
         cwavef = cg(iband)</span></span>
         nband_occ = nband_occ + 1</span></span>
      end if</span></span>
   end do</span></span>
</span>
   ! 用 FFT 把 ψ(G) → ψ(r)，并累加 |ψ|² × weight 到 rhoaug</span></span>
   call fourwf(option=1, rhoaug, cwavef, ..., weight_array_r=weight_t, ...)</span></span>
end do</span></span></code></pre>
关键点：</p>

零占据带不进入密度</strong>（节省 FFT）</li>
每个 band 的权重 = occ × wtk / ucvol</strong>（这就是 BZ 积分的离散权重）</li>
PAW 还要额外加上"球内"贡献 rhoij</code></strong>，由 pawmkrhoij</code> 处理</li>
</ul>
最后跨 MPI 进程求和（k 点并行）：</p>
call xmpi_sum(rhoaug, mpi_comm_kpt, ierr)</span></span></code></pre>

占据与本征值能量</a></h2>
代码位置：src/61_occeig/m_occ.F90</code> 调用 e_eigen</code>（src/79_seqpar_mpi/m_vtorho.F90:727</code>）：</p>
e_eigenvalues = 0</span></span>
do isppol, ikpt, iband:</span></span>
   e_eigenvalues = e_eigenvalues + wtk(ikpt) * occ(iband) * eigen(iband)</span></span>
end do</span></span></code></pre>
类似地，动能、非局域能、Fock 能等都用同样权重 wtk * occ</code> 加和（m_vtorho.F90:1165-1171</code>）：</p>
energies%e_kinetic     += wtk(ikpt) * occ_k(iband) * ek_k(iband)</span></span>
energies%e_nlpsp_vfock += wtk(ikpt) * occ_k(iband) * enlx_k(iband)</span></span>
energies%e_fock        += 0.5 * wtk(ikpt) * occ_k(iband) * fock_eigen(iband)</span></span></code></pre>

occopt</code> 对 SCF 流程的影响图</a></h2>
下图把 occopt</code> 在三大阶段的分支条件用 Mermaid 流程图表达，便于直观对比"固定占据"（occopt < 3</code>）与"可变占据"（occopt ≥ 3</code>）两条主路径。</p>
flowchart TD</span></span>
    Start([输入文件 + 伪势]) --> A1</span></span>
</span>
    subgraph PhaseInit["阶段一：初始化（istep = 0）"]</span></span>
        direction TB</span></span>
        A1["<b>chkinp</b><br/>检查 occ, wtk, fband, occopt 一致性"]</span></span>
        A2["<b>invars1</b><br/>由 fband 自动决定 nband<br/>mband = ceiling(zelect/2) + ceiling(fband·natom)"]</span></span>
        A3["<b>dtset_initocc_chkneu</b><br/>nelect = zval − cellcharge<br/>maxocc = 2 / (nsppol·nspinor)"]</span></span>
        A4{"occopt 分支"}</span></span>
        A5["验证用户给的 occ<br/>(总和需 = nelect)"]</span></span>
        A6["自动生成 occ_orig<br/>nocc = int(nelect/maxocc) + 1<br/>occlast = nelect − maxocc·(nocc−1)"]</span></span>
        A7["电荷检查：<br/>|Σ wtk·occ − nelect| < tol8"]</span></span>
        A1 --> A2 --> A3 --> A4</span></span>
        A4 -- "occopt = 0 或 2<br/>(固定占据，用户输入)" --> A5 --> A7</span></span>
        A4 -- "occopt = 1 或 3..9<br/>(半导体填充作为初值)" --> A6 --> A7</span></span>
    end</span></span>
</span>
    A7 --> B1</span></span>
</span>
    subgraph PhaseSCF["阶段二：SCF 主循环（istep = 1..nstep）— vtorho"]</span></span>
        direction TB</span></span>
        B1["fixed_occ = (occopt &lt; 3)"]</span></span>
        B2["对每个 k 点：<br/>solve H ψ = ε ψ → eigen(k)<br/>(CG / LOBPCG / ChebFi)"]</span></span>
        B3{"fixed_occ?"}</span></span>
        B4["跳过占据更新<br/>occ 保持初始化时的值<br/>(occopt ≤ 2)"]</span></span>
        B5["<b>call newocc</b><br/>二分法找 μ，重算 occ<br/>(occopt ≥ 3)"]</span></span>
        B6["<b>get_entropy</b><br/>S = Σ wtk · s(x)"]</span></span>
        B7["<b>e_eigen</b>：<br/>E_band = Σ wtk · occ · ε"]</span></span>
        B8["<b>mkrho</b>：<br/>ρ(r) = Σ wtk · occ · |ψ(r)|²<br/>(零占据带跳过 FFT)"]</span></span>
        B1 --> B2 --> B3</span></span>
        B3 -- "true (固定)" --> B4</span></span>
        B3 -- "false (可变)" --> B5 --> B6</span></span>
        B4 --> B7</span></span>
        B6 --> B7</span></span>
        B7 --> B8</span></span>
    end</span></span>
</span>
    B8 --> C1</span></span>
</span>
    subgraph PhaseEtot["阶段三：能量汇总 — etotfor"]</span></span>
        direction TB</span></span>
        C1{"3 ≤ occopt ≤ 8?"}</span></span>
        C2["e_entropy = −tsmear × S<br/><i>Mermin 自由能 F = E − TS</i>"]</span></span>
        C3["e_entropy = 0"]</span></span>
        C4["etotal = e_band − e_dc + e_entropy + E_ewald + ..."]</span></span>
        C1 -- "是" --> C2</span></span>
        C1 -- "否 (occopt ≤ 2 或 = 9)" --> C3</span></span>
        C2 --> C4</span></span>
        C3 --> C4</span></span>
    end</span></span>
</span>
    C4 --> D1{"收敛？<br/>res2 &lt; tolvrs ?<br/>|Δetotal| &lt; toldfe ?"}</span></span>
    D1 -- "否" --> Mix["Pulay/Anderson 混合<br/>(m_ab7_mixing)"]</span></span>
    Mix --> B1</span></span>
    D1 -- "是" --> End([输出 WFK, EIG,<br/>etotal, fermie, forces])</span></span>
</span>
    classDef fixedOcc fill:#e3f2fd,stroke:#1976d2,stroke-width:1.5px,color:#0d47a1</span></span>
    classDef varOcc   fill:#fce4ec,stroke:#c2185b,stroke-width:1.5px,color:#880e4f</span></span>
    classDef phase    fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px</span></span>
    classDef decision fill:#fff9c4,stroke:#f9a825,stroke-width:1.5px,color:#e65100</span></span>
    class A5,B4,C3 fixedOcc</span></span>
    class A6,B5,B6,C2 varOcc</span></span>
    class A4,B3,C1,D1 decision</span></span></code></pre>
图例：</p>

蓝色节点代表"固定占据"路径（occopt = 0, 1, 2</code>）</li>
粉色节点代表"可变占据"路径（occopt = 3..9</code>，需在 SCF 中调 newocc</code>）</li>
黄色菱形是 occopt</code> 控制的关键分支判断</li>
occopt = 9</code> 落在阶段二的可变路径，但不进入</strong> Mermin 自由能（C1 判断为"否"）</li>
</ul>

典型例子</a></h2>
例 1：Silicon 半导体（推荐 occopt=1</code>）</a></h3>
nband 8           # 8 价电子，半导体只需 4 占据 + 几条空带</span></span>
occopt 1</span></span>
# 不需要 tsmear</span></span></code></pre>
dtset_initocc_chkneu</code> 自动生成 occ = [2, 2, 2, 2, 0, 0, 0, 0]</code>。SCF 不调 newocc</code>，占据数永不改变。</p>
例 2：Aluminum 金属（推荐 occopt=7</code>）</a></h3>
nband 10          # 3 价电子 + 缓冲带（fband=0.5 默认）</span></span>
occopt 7</span></span>
tsmear 0.01       # Ha = 3160 K</span></span>
ngkpt 16 16 16</span></span></code></pre>
初始 occ_orig = [2, 0.5, 0, 0, 0, 0, 0, 0, 0, 0]</code>（来自 initocc_chkneu</code> 第 4.1 节）。每次 SCF 步通过 newocc</code> 重算：</p>
istep 1 : occ = [2.0, 0.50, 0.001, 1e-8, 0, ...]</span></span>
istep 2 : occ = [2.0, 0.48, 0.020, 1e-5, 0, ...]</span></span>
...</span></span>
istep 8 : occ = [1.99, 0.41, 0.45, 0.15, 0.001, ...]  # 真实 metallic 分布</span></span></code></pre>
fermie</code> 在迭代中逐步收敛到正确值。</p>
例 3：Fe 铁磁（occopt=7, nsppol=2, spinmagntarget=2.2</code>）</a></h3>
nsppol 2</span></span>
nspinor 1</span></span>
occopt 7</span></span>
tsmear 0.01</span></span>
spinmagntarget 2.2     # μ_B per Fe atom</span></span></code></pre>
initocc_chkneu</code> 第 4.1 节"情况 B"路径：</p>
nelect_up   = (8 + 2.2)/2 = 5.1    ! 5.1 个 spin-up 电子</span></span>
nelect_down = (8 - 2.2)/2 = 2.9    ! 2.9 个 spin-down 电子</span></span></code></pre>
注意 maxocc = 2/(2*1) = 1</code> 了（每带每自旋通道最多 1 个）：</p>
occ_spin_up   = [1, 1, 1, 1, 1, 0.1, 0, ...]</span></span>
occ_spin_down = [1, 1, 0.9, 0, ...]</span></span></code></pre>
SCF 后 newocc</code> 在分自旋通道上独立做二分（m_occ.F90:836-913</code> 的固定磁矩分支），各自旋通道有不同的 Fermi 能级。</p>
例 4：ΔSCF 激发态（occopt=9</code>）</a></h3>
occopt 9</span></span>
ivalence 4         # 价带最高指标</span></span>
nqfd 1.0           # 强制 1 个电子激发</span></span>
nband 10</span></span>
tsmear 0.005</span></span></code></pre>
initocc_chkneu</code> 第 4.2 节路径，初始 occ = [2, 2, 2, 1, 0, 1, 0, 0, 0, 0]</code>（价带顶 1 空穴，导带底 1 电子）。SCF 中 newocc</code> 同时维持 2 个 Fermi 能级 $\mu_e, \mu_h$（m_occ.F90:583-606, 718-737</code>）。</p>
熵不进入 Mermin 自由能（occopt=9</code> 排除），因为它是约束态而非有限温。</p>
例 5：STM 模拟（occopt=7, prtstm=1, stmbias=0.001</code>）</a></h3>
m_occ.F90:786-829</code>：在 Fermi 能级附近 [μ - stmbias, μ]</code> 区间内的占据数被单独保留：</p>
call getnel(... fermie_biased = fermie - stmbias ...)  ! 算偏置后的占据</span></span>
occ(:) = occ_at_fermie(:) - occ_at_biased(:)            ! 只留差值</span></span></code></pre>
得到的 occ</code> 仅在 STM 偏压窗口内非零，对应 STM 像的"差分密度"。</p>

常见陷阱与诊断</a></h2>
"occopt=1 整数填充不通过"</a></h3>
症状</strong>：</p>
ERROR initialization of occupation numbers ... charge balance ...</span></span></code></pre>
原因</strong>：nelect / maxocc</code> 不是整数（半填的 band）。</p>
对策</strong>：</p>

改用 occopt 7 + tsmear 0.01</code>（金属型）</li>
或检查 cellcharge</code> 是否设错</li>
</ul>
"nsppol=2 + occopt=1 但没给 spinmagntarget"</a></h3>
症状</strong>：</p>
ERROR This is a calculation with spin-up and spin-down wavefunctions ...</span></span>
must be specified, while the default value is observed.</span></span></code></pre>
对策</strong>：</p>

加 spinmagntarget X.X</code>（先做小型测试估算磁矩）</li>
或改 occopt 7</code>（让代码自己决定磁矩）</li>
</ul>
"金属用 occopt=1 收敛极慢/振荡"</a></h3>
症状</strong>：SCF 不收敛，能量上下抖动。</p>
原因</strong>：Fermi 面附近的能带跨越导致占据数突变。</p>
对策</strong>：必须用 occopt 7</code>（或 3、4、6），加 tsmear 0.005..0.02</code>。</p>
"occopt=2 的 wtk 没归一化"</a></h3>
症状</strong>：nelect_occ ≠ nelect</code> 警告。</p>
原因</strong>：occopt=2</code> 是唯一一个不自动归一化 wtk</strong> 的选项。</p>
对策</strong>：</p>

显式让 $\sum w_k = 1$</li>
或改 occopt 1</code> 让代码自动归一化</li>
</ul>
"Cold smearing (4, 5, 6) 能量跳变"</a></h3>
症状</strong>：几何优化中相邻几何能量出现台阶。</p>
原因</strong>：cold smearing 的占据函数非单调，二分法可能落到不同 Fermi 解上。</p>
对策</strong>：</p>

改用单调的 occopt 7</code>（Gaussian）</li>
或 occopt 5（cold smearing 单调版）</li>
</ul>
"几何弛豫中 nband 不够"</a></h3>
症状</strong>：</p>
ERROR There are not enough bands to get charge balance right</span></span></code></pre>
原因</strong>：体积膨胀后能带数下降，原本占据带超出 nband</code>。</p>
对策</strong>：增大 nband</code> 留出余量；或用 fband 0.7</code> 而非 0.5。</p>

关键代码地图</a></h2>
子程序</th> 文件</th> 行号</th> 作用</th></tr></thead>

dtset_initocc_chkneu</code></td> src/44_abitypes_defs/m_dtset.F90</code></td> 1181</td> 占据初始化主入口；电荷检查</td></tr>
chkinp</code> (occ 部分)</td> src/57_iovars/m_chkinp.F90</code></td> 2741</td> 验证手动 occ</code> 合理性</td></tr>
invars1</code> (nband 部分)</td> src/57_iovars/m_invars1.F90</code></td> 1933</td> fband</code> → nband</code> 自动算</td></tr>
newocc</code></td> src/61_occeig/m_occ.F90</code></td> 453</td> 二分法找 Fermi 能级</td></tr>
getnel</code></td> 同上</td> 124</td> 给定 μ 算 N、occ、S</td></tr>
init_occ_ent</code></td> 同上</td> 1007</td> 建 12001 点 smearing 查找表</td></tr>
occ_fd</code> / occ_dfde</code></td> 同上</td> 1643 / 1695</td> 解析 Fermi-Dirac</td></tr>
occeig</code></td> 同上</td> 1552</td> DFPT 用：(occ_kq - occ_k)/(ε_kq - ε_k)</td></tr>
vtorho</code> (fixed_occ 分支)</td> src/79_seqpar_mpi/m_vtorho.F90</code></td> 527, 1301</td> SCF 中选固定 / 可变占据</td></tr>
e_eigen</code></td> 同上</td> 727</td> 算 $E_{\text{band}} = \sum w,f,\epsilon$</td></tr>
mkrho</code></td> src/67_common/m_mkrho.F90</code></td> 410</td> 算 $\rho = \sum w,f,\lvert\psi\rvert^2$</td></tr>
entropy</code> (汇总)</td> src/67_common/m_dft_energy.F90</code></td> 1130</td> $-TS$ 进入总能</td></tr>
get_fact_spin_tol_empty</code></td> src/61_occeig/m_occ.F90</code></td> 1947</td> 自旋因子辅助</td></tr>
</tbody></table>

附录：一次完整 SCF 中 occ</code> 的逐步追踪</a></h2>
设输入：FCC Al（3 价电子），occopt=7</code>，tsmear=0.01</code>，ngkpt 8 8 8</code> → 10 IBZ k 点，nband=6</code>。</p>
Step 0: 初始化</a></h3>

invars1</code>：fband=0.5</code>，mband_upper = 1 * (ceiling(3) + ceiling(0.5)) = 1 * (3 + 1) = 4</code>。用户给了 nband=6</code>，覆盖之。</li>
dtset_initocc_chkneu</code>：

zval = 3</code>, cellcharge = 0</code> → nelect = 3</code></li>
maxocc = 2 / (1*1) = 2</code></li>
nocc = int(3/2 - 1e-8) + 1 = 2</code></li>
occlast = 3 - 2*1 = 1</code> → 第 2 带半填</li>
occ_orig = [2, 1, 0, 0, 0, 0]</code>（10 个 k 点都一样）</li>
</ul>
</li>
电荷检查：Σ wtk × occ = 1 × (2 + 1 + 0 + 0 + 0 + 0) = 3 = nelect</code> ✓</li>
</ol>
Step 1: 第一次 SCF</a></h3>

vtorho</code> 设 fixed_occ = (7 < 3) = .false.</code></li>
求解 H ψ = ε ψ 得 eigen = [k=1: -0.42, -0.08, +0.15, ...; k=2: ...; ...]</code>（10 k × 6 bands = 60 eigenvalues）</li>
调 newocc</code>：

边界：fermie_lo = min(eigen) - 0.06 = -0.48</code>, fermie_hi = max(eigen) + 0.06</code></li>
二分到 fermie ≈ -0.05 Ha</code></li>
用 Gaussian smearing 表查得每个 (ε, k) 处的 occ</li>
结果约：occ_k1 = [2.0, 1.6, 0.05, 1e-7, ...]</code>（k=1 处）；其他 k 略不同</li>
</ul>
</li>
mkrho</code>：ρ(r) = Σ_{k,n} wtk(k) × occ(k,n) × |ψ_kn(r)|²</code></li>
etotfor</code>：E_tot = E_band - E_dc - tsmear × S = ... - 0.01 × 0.02 = ...</code></li>
</ol>
Step 2-7: 后续 SCF</a></h3>
每步 occ 都微调（因为 eigen 在变）。典型情况下：</p>
istep    fermie       Σ entropy×wtk     occ at fermi level</span></span>
  1     -0.0521      0.0184            ~0.5</span></span>
  2     -0.0498      0.0156            ~0.5</span></span>
  ...</span></span>
  7     -0.0501      0.0152            ~0.49</span></span></code></pre>
occ</code> 数组在每次 SCF 步都会重新计算，但因为 eigen</code> 变化越来越小，occ</code> 也越来越稳定。</p>
Step 8: 收敛退出</a></h3>
res2 < tolvrs (1e-12) 连续 2 次 → quit</span></span>
final fermie = -0.0501 Ha</span></span>
final entropy = 0.0152</span></span>
final etotal = ... - 0.0001 (= -tsmear × S)</span></span></code></pre>

报告生成于 2026-05-19，基于 Abinit 10.4.7。</em></p>
References</a></h2>
Gonze, Xavier, et al. "The Abinit Project: Impact, Environment and Recent Developments." Computer Physics Communications</em>, vol. 248, 2020, p. 107042. link</a></p>
Marzari, Nicola, and David Vanderbilt. "Maximally Localized Generalized Wannier Functions for Composite Energy Bands." Physical Review B</em>, vol. 56, no. 20, 1997, pp. 12847–12865. link</a></p>
Mermin, N. David. "Thermal Properties of the Inhomogeneous Electron Gas." Physical Review</em>, vol. 137, no. 5A, 1965, pp. A1441–A1443. link</a></p>
Methfessel, M., and A. T. Paxton. "High-Precision Sampling for Brillouin-Zone Integration in Metals." Physical Review B</em>, vol. 40, no. 6, 1989, pp. 3616–3621. link</a></p>
Paillard, Charles, et al. "Noncollinear Magnetism from First Principles." Physical Review B</em>, vol. 100, no. 2, 2019, p. 024426. link</a></p>
The Abinit Code. Version 10.4.7, 2024. link</a></p>


Abinit SCF 计算：收敛标准与代码流程详解
2026-05-19T00:00:00+00:00
本文总结了Abinit当中SCF计算的收敛标准，以及代码运行的详细流程。</p>


Abinit SCF 波函数收敛过程：原理与代码实现详解
2026-05-19T00:00:00+00:00
本文详细介绍了Abinit的SCF计算过程中波函数收敛的过程。</p>


Abinit Smearing（占据数展宽）计算：参数与代码实现详解
2026-05-19T00:00:00+00:00
本文总结了Abinit当中smearing的参数细节以及代码实现的方法。</p>


Abinit 结构优化（离子移动）：计算流程与代码实现详解
2026-05-19T00:00:00+00:00
本文总结了Abinit结构优化的计算流程，以及代码的实现方法。</p>


COHP 计算中 SCF 后阶段阻塞问题的诊断与修复
2026-05-19T00:00:00+00:00
在利用 ABINIT + LOBSTER 进行 $\mathrm{Al}(111)$ slab 吸附体系的 COHP 计算时，发现所有 24 个任务在 SCF 收敛后进入长达约 12 小时的静默阻塞状态，无任何输出写入日志文件。本文记录该问题的诊断过程与修复方案。</p>


PAW 赝势 SCF 收敛问题的诊断与修复
2026-05-19T00:00:00+00:00
将赝势从 norm-conserving（psp8，ta015）切换到 PAW（xml，PseudoDojo pbe/paw-sr-11，ta031）后，所有 COHP 计算的 SCF 迭代出现严重的收敛困难。能量在前几步快速下降后开始振荡上升，残差（vres2</code>）在 $\sim1\times10^{-2}$ 处停滞不前。本文记录该问题的诊断与修复过程。</p>


ABINIT 8.6.3 + LOBSTER 5.1.1 COHP 计算工作流
2026-05-17T00:00:00+00:00
本文档记录使用 ABINIT 8.6.3 计算波函数，配合 LOBSTER 5.1.1 进行 COHP（Crystal Orbital Hamilton Population）分析的完整流程，包括版本选择理由、关键参数设置、输入文件模板、资源估算及常见问题排查。</p>


等离子球的物理原理与公式推导
2026-05-10T00:00:00+00:00
等离子球（plasma globe）内部的发光"电弧"严格说更接近低压气体放电丝状通道</strong>，不是空气中高温金属电弧那种连续强电流电弧。它的形成涉及高频高压电场、气体击穿、电离、电子雪崩、等离子体鞘层和介质阻挡放电等过程。本文将逐一解释其中每一个关键公式的推导过程。</p>


ABINIT 单原子计算 SCF 收敛问题排查：开壳层占据与混合参数优化
2026-05-01T00:00:00+00:00
在使用 ABINIT 进行单原子参考能计算时，O 和 S 两种开壳层原子出现了 SCF 自洽迭代不收敛的问题。本文记录从问题发现到最终解决的完整排查过程，涵盖输入文件设置、根因分析和修正方案。</p>


从 CubicSpline 到 PchipInterpolator：DFT 吸附能曲线插值振荡问题的排查与修复
2026-05-01T00:00:00+00:00
在使用 Python 绘制 DFT 吸附能曲线的过程中，发现某些元素的曲线图在特定 $z$ 坐标附近出现不符合物理预期的异常振荡。排查后定位到问题根源：CubicSpline</code> 三次样条插值在面对尖峰数据时会产生严重的过冲（overshoot）。本文将记录这一问题的分析过程和修复方案。</p>


使用 Python/Matplotlib 绘制多元素吸附能曲线网格图
2026-05-01T00:00:00+00:00
在密度泛函理论（DFT）计算化学研究中，绘制 adatom（吸附原子）沿表面法线方向的吸附能曲线是分析表面催化性质的重要手段。本文介绍一个完整的 Python 脚本，利用 Matplotlib 将六种元素（N、H、C、Si、O、S）在四种吸附位点（Top、Bridge、fcc、hcp）上的 $\Delta E_{\mathrm{ads}}$ 曲线以 $3 \times 2$ 网格布局呈现，每个面板同时包含主图和局部放大图。</p>


ABINIT结构优化`ionmov=2`算法：BFGS方法实现与分析
2026-04-15T00:00:00+00:00
在ABINIT软件中，当设置计算参数 ionmov=2</code> 时，程序采用 Broyden-Fletcher-Goldfarb-Shanno (BFGS)</strong> 的拟牛顿法来进行晶体结构和原子位置的几何优化。BFGS方法通过近似目标函数（系统总能量）的逆海森矩阵来引导原子坐标朝着能量极小值收敛，在计算效率与优化收敛性之间取得了极佳的平衡。</p>


ABINIT结构优化算法分析：ionmov=22 (L-BFGS)
2026-04-15T00:00:00+00:00
在ABINIT的结构优化过程中，参数 ionmov=22</code> 对应于有限内存Broyden-Fletcher-Goldfarb-Shanno (Limited-memory BFGS, L-BFGS) 方法</strong>。该方法是一种著名的拟牛顿法（Quasi-Newton Method），不需要显式计算并存储庞大的Hessian矩阵及其逆矩阵，而是通过保存最近几步的迭代历史信息来近似逆Hessian矩阵，特别适用于拥有大量自由度（如大体系多原子结构的弛豫和晶胞优化）的问题。</p>


VASP计算中BFGS优化器突然爆力问题的诊断与解决
2026-04-14T00:00:00+00:00
在VASP计算中，经常会遇到这样的情况：前面十几步优化都在正常进行，结构逐渐改善，但突然在某一步力值暴涨，结构开始"跑飞"或"扩散"。这种现象通常不是单一原因造成的，而是多种数值因素叠加的结果。</p>


第一性原理计算中的结构优化：从入门经验到实战策略
2026-04-14T00:00:00+00:00
结构优化（structure optimization 或 structure relaxation）是第一性原理计算中最基础、也最容易"算了很久却不一定算对"的环节。它的目标是通过调整原子坐标、晶格形状或晶胞体积，使体系到达一个能量更低、受力更小的稳定构型。对于 VASP 而言，优化的自由度主要由 ISIF</code> 控制，优化算法主要由 IBRION</code> 控制，而是否收敛通常由 EDIFFG</code> 等参数判断。</p>


Hermes Agent 入门指南
2026-04-11T00:00:00+00:00
本文适合完全没有命令行经验的新手，也适合从 OpenClaw 迁移过来的用户。手把手带你从零开始，装好 Hermes Agent，接入 Telegram，并了解它的核心玩法。</p>
Abinit occopt：占据数选项完整解析

Abinit SCF 计算：收敛标准与代码流程详解

Abinit SCF 波函数收敛过程：原理与代码实现详解

Abinit Smearing（占据数展宽）计算：参数与代码实现详解

Abinit 结构优化（离子移动）：计算流程与代码实现详解

COHP 计算中 SCF 后阶段阻塞问题的诊断与修复

PAW 赝势 SCF 收敛问题的诊断与修复

ABINIT 8.6.3 + LOBSTER 5.1.1 COHP 计算工作流

等离子球的物理原理与公式推导

ABINIT 单原子计算 SCF 收敛问题排查：开壳层占据与混合参数优化

从 CubicSpline 到 PchipInterpolator：DFT 吸附能曲线插值振荡问题的排查与修复

使用 Python/Matplotlib 绘制多元素吸附能曲线网格图

ABINIT结构优化`ionmov=2`算法：BFGS方法实现与分析

ABINIT结构优化算法分析：ionmov=22 (L-BFGS)

VASP计算中BFGS优化器突然爆力问题的诊断与解决

第一性原理计算中的结构优化：从入门经验到实战策略

Hermes Agent 入门指南

Meta Vector Field

将 DeepSeek V4 Pro 接入 Claude Code：非侵入式配置指南

Mac 上跑 Claude Code 如何防止睡眠？caffeinate 完全指南

Abinit K 点（布里渊区采样）：参数、公式与代码实现详解
