================
参数选择指南
================

本指南面向首次使用 AtomPPGen 生成 TM 范数守恒赝势的同学，提供 rc 选择、局域道设置
与伪化能量调试的经验。

rc 选型的物理取舍
-----------------

赝势的"软度"与"可转移性"存在天然张力。较大的截断半径 :math:`r_c` 能降低平面波基组的
能量截断，从而加速 Quantum ESPRESSO (QE) 等固体程序；但过大的 :math:`r_c` 会把真实核区
的陡峭势场"抹平"，在化学价态发生改变时出现偏差。调参的核心任务就是围绕以下约束找到
平衡：

.. math::

   Q_l(r_c) = \int_0^{r_c} |u_l(r)|^2 dr, \quad \Delta_{\text{norm}} = \frac{Q_l^{\text{PS}} - Q_l^{\text{AE}}}{Q_l^{\text{AE}}}

- **软度目标**：平面波截断满足 :math:`E_{\text{cut}} \leq 35` Ry，金属 Al 的经验上限为 30-35 Ry。
- **可转移性目标**：:math:`|\Delta_{\text{norm}}| < 10^{-6}` 且对数导数 RMS 满足金属阈值
  :math:`L_{\text{RMS}}^{\text{valence}} < 16`。

频道推荐范围
------------

.. list-table:: Al (LDA) 通道经验范围
   :header-rows: 1

   * - 通道
     - rc 建议 (Bohr)
     - 设计思路
   * - s
     - 2.0 - 2.2
     - s 轨道无节点，适合略小的 :math:`r_c` 以抑制幽灵态；若 plane-wave 需求过高，再平滑放大 0.1-0.2。
   * - p
     - 2.1 - 2.3
     - 3p 轨道在 :math:`r \approx 2.1` Bohr 存在节点，需避开符号翻转点；配合符号保持补丁后，可安全做到 2.3。
   * - d
     - 2.3 - 2.5
     - d 通道主要用于散射投影，略大的 :math:`r_c` 有助于匹配高能量散射相移，且不直接影响价电子束缚态。

QE 推荐起点
-----------

默认参数可直接用于 QE 测试：

- :math:`r_c^s = 2.1`，:math:`r_c^p = 2.2`，:math:`r_c^d = 2.4` a_0。
- 局域道选 d：:math:`V_{\text{loc}} = V_d(r)`，能减少 s/p 通道的幽灵态风险。
- 伪化能量：s、p 取全电子束缚本征能 :math:`\varepsilon_{3s}`、:math:`\varepsilon_{3p}`；d 通道取
  :math:`\varepsilon = +0.1 \sim +0.2` Ry 的散射能量以增强相移匹配。

局域道与范数守恒联动
--------------------

局域道的选择会改变 ``V_loc`` 在 :math:`r > r_c` 的衰减形状：

- 若把 s 通道设置为局域道，d 通道的非局域投影将对短程势谷极为敏感，常出现幽灵态。
- 选择 d 为局域道时，s/p 通道继承了更平滑的短程势，范数守恒约束更容易满足。

在生成 KB 投影子时，推荐固定 :math:`l_{\text{loc}} = 2`，除非面对高 :math:`Z` 元素导致 d 通道太硬，
再考虑调换为 p 并重新扫描。

伪化能量设置
------------

- **束缚态参考**：对占据的束缚态通道（例如 Al 的 3s），可直接使用全电子本征能，
  既保留节点/相位信息，又确保 TM 方程组与 AE 轨道对齐。
- **散射参考（近零能量）**：对用于散射相移匹配的通道（例如 Al 的 p/d 投影通道），
  常选取接近 0 的参考态/参考能量（AE 求解结果中通常表现为该通道能量最高的一项），
  以强调对数导数匹配与可转移性。
- **伪化能量扫描**：当 :math:`\Delta_{\text{norm}}` 满足阈值，但对数导数 RMS 超标时，可以在
  :math:`\varepsilon_l` 附近进行 :math:`\pm 0.05` Ry 的微调；若连续调节仍无改善，优先回退到更小的 :math:`r_c`。

调试策略与排障
--------------

1. **幽灵态爆发**：若 :math:`r_c^s = 2.1` 仍出现多个深幽灵态，可尝试：

   - 增大 :math:`r_c^s` 至 2.3 a_0，或
   - 维持 :math:`r_c^s` 不变改用 RRKJ 多投影，弱化内区势阱。

2. **对数导数偏移**：若金属阈值 16 仍不满足，先检查测试半径
   :math:`r_{\text{test}}` 是否覆盖所有 :math:`r_c^l`，再通过减小 :math:`r_c^p` 提升短程相位匹配。

3. **范数守恒失真**：确认 TM 多项式求解器的符号约束已启用，
   并用 ``ValidationReport.summary()`` 检查 ``norm_error``。

4. **局域道调换**：若 s 通道幽灵态无法通过 rc 调整消除，可把局域道从 d 换成 p，再重新评估
   :math:`r_c^p` 的范围（通常需减小 0.1-0.2 a_0 以补偿硬化）。

验证前检查清单
----------------

- rc 组合满足上表范围且避开已知节点。
- 局域道固定为 d，或完成局域道切换后的重新扫描。
- 伪化能量按通道选择：束缚态参考使用 AE 本征能；散射参考通道保持轻微正值或近零能量。
- 运行参数扫描脚本，确认 ``norm_error.max_error < 1e-6``。
- 生成范数守恒、对数导数图表以可视化趋势。