docs(deltaspin): rewrite nspin=2 constraint evaluation with physics

Add physical mechanism analysis and improvement directions:

- Phase 2 direction stability relies on exchange splitting potential wells,
  not constraint forces. Current uniform decay strategy is the fundamental
  limitation for weak-moment atoms.
- Three improvement directions: selective constraint (don't relax weak atoms),
  switch back to standard BFGS in Phase 2, and atom-wise adaptive decay rates.
- nspin=4 direction_only as viable alternative for precise direction-only
  constraint, with transverse constraint force correctly preserved.
- Data sampling parameter recommendations with sc_thr precision mapping.

Author: dyzheng

docs/superpowers/specs/deltaspin-nspin2-magnetic-constraint-schemes.md

@@ -1,116 +1,180 @@
 # DeltaSpin nspin=2 磁约束方案：精确数据采样能力评估
 
-## 评估背景
+## 物理框架
 
-目标：对磁性体系大规模标注目标磁构型的能量和力。要求约束是精确的——计算结果对应目标磁构型本身，而非近似构型。
+DeltaSpin 通过 Lagrange 乘子 λ 在 Kohn-Sham 哈密顿量中引入约束项：
 
-评估分两个约束策略：
-1. **方向 + 大小约束**：Mz 精确收敛到目标值
-2. **仅约束方向**：Mz 的符号（方向）保持，大小由电子结构自洽决定
+```
+H = H_KS + Σ_i λ_i · (σ · M̂_i)
+E_constrained = E_KS + Σ_i λ_i · (M_i - M_target_i)
+```
+
+当约束精确满足时 M_i = M_target_i，约束对能量的贡献为零：
+
+```
+ΔE = Σ_i λ_i · (M_i - M_target_i) = 0
+```
+
+此时计算总能 E_KS 即为目标磁构型下的 DFT 能量，原子受力中的约束力项也对应对目标构型的力。这是数据采样要求的基础：**约束必须精确满足，否则 E 和 F 中的约束项不为零，标注的是偏移构型而非目标构型。**
+
+收敛判据 `|M_i - M_target_i| < sc_thr` 直接控制标注精度：sc_thr = 1e-4 时每原子磁矩偏差 ~1e-4 μB，对应能量偏移 ~1e-4 eV 量级。
 
 ---
 
 ## 方案 A：标准约束（sc_direction_only = false）
 
-BFGS 优化 lambda_z，使 Mz 收敛到 target_Mz。约束收敛判据为 `|Mz - target_Mz| < sc_thr`。
+### 算法
 
-### 方向 + 大小约束：✅ 可实现
+BFGS 共轭梯度优化器迭代调整 λ_z，使 M_z 收敛到 target_M_z。每步：
 
-BFGS 迭代调整 lambda_z 直到磁矩误差低于 sc_thr。设 sc_thr = 1e-6 时，每原子磁矩偏差 < 1e-6 μB，对应能量偏差 λ·ΔMz ≈ 1e-6 eV 量级，满足数据采样精度需求。
+```
+δM_z = M_z - target_M_z          (残差)
+search = δM + β · search_prev     (Polak-Ribiere 共轭方向)
+λ_z += α_opt · search_z            (步长自适应)
+```
+
+直到 `RMS(δM) < sc_thr` 或梯度 `∂M/∂λ` 衰减到阈值以下。
+
+### 方向 + 大小约束：✅ 可实现
 
-约束对总能量的贡献为 `ΔE = Σ λ_i (Mz_i - Mz_target_i)`。当约束精确满足时，ΔE ≈ 0，计算所得总能即为目标磁构型下的 DFT 能量。力包含约束力项，对应目标磁构型下的 Hellmann-Feynman 力。
+BFGS 有完整的梯度和 Hessian 信息，λ_z 单调趋近使 M_z = target_M_z 的值。收敛后约束精确满足。
 
 **推荐参数：**
 
 ```
-sc_mag_switch      1
-sc_direction_only  0
-sc_scf_thr_mode    immediate     # 尽早启动优化，避免前期浪费
-sc_thr             1e-6         # 磁矩收敛精度，按需收紧
-nsc                200          # lambda 优化步数上限，确保收敛
+sc_scf_thr_mode    immediate    # 或 threshold + sc_scf_thr = 1e-3
+sc_thr             1e-6         # 控制标注精度，1e-4 筛选、1e-6 生产
+nsc                200          # 足够的优化步数
 ```
 
-或使用 threshold 模式（给 SCF 几步热身时间）：
+### 仅约束方向：❌ 无法实现
+
+方案 A 约束 `sign(M_z) × |M_z| = target_M_z`，同时锁定了方向和大小，不存在只约束方向的机制。
+
+---
+
+## 方案 B：direction_only 两阶段策略
+
+### 核心问题：nspin=2 下 direction_only 投影使 λ 归零
+
+共线磁（nspin=2）的约束目标 M̂ = (0, 0, 1)，方向_only 投影移除 λ 沿 M̂ 方向的分量：
 
 ```
-sc_scf_thr_mode    threshold
-sc_scf_thr         1e-3         # drho 低于此值后开始优化 lambda
-sc_thr             1e-6
+λ_parallel = λ · M̂ = λ_z          (因为 M̂ = (0,0,1))
+λ_perp = λ - λ_parallel · M̂ = (0, 0, λ_z) - λ_z · (0, 0, 1) = (0, 0, 0)
 ```
 
-`sc_thr` 是数据采样精度的直接控制参数。1e-4 适合初步筛选，1e-6 适合产线数据，必要时可进一步收紧。
+投影后 λ = 0，约束力完全消失。BFGS 无法工作（搜索方向和残差也归零，RMS = 0）。
 
-### 仅约束方向：❌ 无法实现
+### 两阶段策略的物理机制
 
-方案 A 约束的是 Mz 的绝对值，不提供"仅约束方向"的机制。无法在约束 Mz 符号的同时让 |Mz| 自由弛豫。
+| 阶段 | 步骤 | 物理作用 |
+|---|---|---|
+| **Phase 1** (iter ≤ sc_dir_phase1_steps) | 临时禁用 direction_only，BFGS 约束 `M_z = target_M_z` | λ_z 建立到合理值范围（~0.3 eV/μB），交换场 J_ij 通过 λ_z 耦合到哈密顿量中，在自旋道上形成沿目标方向的局域势阱 |
+| **Phase 1→2 过渡** | 重置 Broyden 混合历史 | Phase 1 BFGS 直接更新密度矩阵，与 SCF 电荷混合不兼容 |
+| **Phase 2** (iter > sc_dir_phase1_steps) | λ_z 每步衰减 `λ_z *= 0.5^(1/3) ≈ 0.794`（约每 3 步减半） | 约束力逐渐释放，磁矩方向的保持依赖 **交换劈裂形成的局域势阱** |
 
----
+### Phase 2 磁矩方向保持的物理机制
 
-## 方案 B：direction_only 两阶段策略
+Phase 1 结束后，铁磁/反铁磁交换耦合已经在自旋道上建立了沿目标方向的能量极小：
+
+```
+E_exchange = - Σ_{<ij>} J_ij S_i · S_j
+```
+
+Phase 2 中 λ 衰减，约束势 `λ_z σ_z` 逐渐退出，磁矩方向的稳定性由交换劈裂的深度维持：
+
+```
+势阱深度 ∝ |M_z| × J_spin_exch
+```
+
+- |M_z| >> 1 μB：交换劈裂深（~1-5 eV），势阱足够锁定方向 ✅
+- |M_z| ~ 0.5 μB：交换劈裂浅（~0.1-0.5 eV），热涨落或数值误差可能翻越 ✅/❌ 取决于体系
+- |M_z| < 0.5 μB：交换劈裂极浅，方向锁定不可靠 ❌
+
+**这不是算法 bug，而是物理事实：** 没有约束力的情况下，弱磁矩原子的自旋方向由体系自身的交换场决定，而非由目标方向约束决定。当前的指数衰减策略无法改变这一物理约束——衰减越慢，约束保持越久，但计算步数越多；衰减越快，释放越早，弱磁矩越容易翻转。
 
 ### 方向 + 大小约束：❌ 无法实现
 
-Phase 2 中 lambda 指数衰减，约束力逐渐消失。系统弛豫到自然基态磁矩，而非目标值。最终 Mz ≠ target_Mz。
+Phase 2 λ 衰减 → 约束力消失 → |M_z| 由 DFT 自洽决定，不等于 target_M_z。
 
-### 仅约束方向：❌ 无法实现
+### 仅约束方向：⚠️ 部分失效
+
+- **强磁矩原子（|M_z| > 1 μB）**：交换劈裂势阱深，Phase 2 中方向稳定 ✅
+- **弱磁矩原子（|M_z| < 1 μB）**：势阱浅，Phase 2 中方向可能翻转 ❌
+
+**当前的均匀衰减策略（所有原子乘以同一衰减因子）是核心限制：** 对强磁矩原子衰减太慢（浪费步数），对弱磁矩原子衰减太快（方向失控）。
+
+### 改进方向
 
-Phase 2 的 lambda 衰减机制保证"约束力平滑消失"而非"方向保持不变"。算法原理：
+1. **选择性约束（弱磁矩不放松约束）**：对 |M_z| < 阈值的原子，Phase 2 不衰减 λ_z（保持标准约束），只对 |M_z| > 阈值的原子做方向_only 衰减。需要新增参数（如 `sc_dir_relax_threshold`）和代码逻辑。
 
-1. Phase 1 结束时 Mz ≈ target_Mz（AFM 序已建立，λ ≈ 0.3 eV/μB）
-2. Phase 2 起步：λ 开始衰减，每步乘以 0.5^(1/3) ≈ 0.794
-3. 约 10 步后 λ 衰减为初始值的 10%，约 20 步后为 1%
-4. λ 衰减到一定程度后约束力不足以稳定磁矩方向
+2. **Phase 2 切回标准约束**：Phase 1 结束后不衰减 λ，而是将 `sc_direction_only` 切换为 false，继续用 BFGS 优化 λ_z 使得 |M_z| 在方向一致的条件下自洽收敛。需要修改 esolver 控制流。
 
-**结果取决于交换劈裂强度：**
-- 磁矩 > 1 μB 的 3d 原子：交换劈裂强，方向可能稳定——但这是体系的内在稳定性，不是约束的功劳
-- 磁矩 < 1 μB 的原子：λ 衰减几分之一后方向就可能翻转
+3. **原子级衰减因子**：根据每个原子的 |M_z| 自适应衰减速率，强磁矩快衰减、弱磁矩慢衰减或不衰减。需要从标量衰减改为向量衰减。
 
-**结论：方案 B 的输出是一个"约束释放后弛豫"的构型，而非"约束方向不变"的构型。** 它提供的是一个近似磁基态搜索的方法，而非能在目标方向上标注精确能量的方法。Phase 2 末态的磁矩方向是否与目标一致，需要逐例事后检查，不存在可调参数使其保证。
+> 以上改进方案目前均未实现，需要进一步开发。
 
 ---
 
 ## 方案 C：常量 lambda（sc_scf_thr_mode = "off"）
 
-lambda 从 STRU 读入，作为常量约束加入哈密顿量，不做 BFGS 优化。
+### 算法
 
-哈密顿量中多了一项 `H_const = λ_z σ_z`，Mz 收敛到 λ_z 与 DFT 势的平衡值，**不等于 target_Mz**（除非 λ_z 恰好取到使 Mz = target_Mz 的值）。
+λ_z 从 STRU 读入后不做任何优化，作为固定势 `λ_z σ_z` 加入哈密顿量。SCF 收敛后 M_z 是 λ_z 下的 DFT 自洽解：
+
+```
+M_z = M_z(λ_z) ≈ M_z^0 + χ · λ_z
+```
+
+其中 χ 是磁化率，M_z^0 是无约束时的磁矩。
 
 ### 方向 + 大小约束：❌ 无法实现
 
-Mz 由 SCF 自洽决定，偏移量依赖于 λ_z 的取值。除非 λ_z 经过精确预计算（本身就需要方案 A 求解），否则 Mz ≠ target_Mz。
+除非 λ_z 恰好取到使 M_z(λ_z) = target_M_z 的值（这本身需要方案 A 求解），否则 M_z ≠ target_M_z。能量偏移：
+
+```
+ΔE = λ_z · (M_z(λ_z) - target_M_z) ≠ 0
+```
 
 ### 仅约束方向：⚠️ 弱偏置，非精确约束
 
-小的 λ_z 可以为 Mz 方向提供一个弱偏置，但：
-- λ_z 太小：方向可能不稳定
-- λ_z 太大：|Mz| 被偏置，偏离自洽值
-- 效果依赖 λ_z 的取值，不是参数化的"仅约束方向"方案
+小的 λ_z 提供 `sign(λ_z)` 的方向偏置，但 |M_z| 受 λ_z 大小影响。不存在 λ_z 的取值使得"方向精确锁定但大小任意"。
 
 ---
 
 ## 总结
 
-| 约束策略 | 方案 A（标准） | 方案 B（direction_only） | 方案 C（off） |
-|---|---|---|---|
-| 方向 + 大小 | ✅ 可实现 | ❌ | ❌ |
-| 仅约束方向 | ❌ | ❌ | ⚠️ 弱偏置 |
+| | 方向+大小 | 仅方向 |
+|---|---|---|
+| **方案 A（标准 BFGS）** | ✅ sc_thr 收紧即可精确 | ❌ 无此机制 |
+| **方案 B（direction_only 两阶段）** | ❌ λ 衰减后大小失控 | ⚠️ 强磁矩稳定，弱磁矩可能翻转 |
+| **方案 C（常量 λ）** | ❌ M_z ≠ target | ⚠️ 弱偏置，非精确 |
 
-**nspin=2 下能用于精确数据采样的只有方案 A 的方向 + 大小约束。** 仅约束方向的精确采样在 nspin=2 体系下目前没有可行方案。
+### 精确数据采样的可行路径
 
----
+**方向 + 大小约束：** 方案 A 直接可用，sc_thr 控制精度。
+
+**仅约束方向：** nspin=2 下目前没有能保证方向精确的方案。两个替代路径：
 
-## 仅约束方向的精确采样：nspin=4 替代方案
+1. **使用 nspin=4：** 非共线模式下 `direction_only` 投影正确保留横向约束力分量 λ_⊥，方向被精确锁定到目标。|M| 由 SCF 自洽决定，能量 F = E_KS + λ_⊥ · M_⊥ 中的约束项在方向精确满足时为零。代价是计算量约为 nspin=2 的 2-4 倍。
 
-如果研究问题需要"仅约束方向、大小自由弛豫"的精确数据标注，应使用 nspin=4（非共线）模式。在 nspin=4 下，lambda 有 x、y、z 三个分量，`direction_only` 投影仅移除平行于目标方向的分量，保留横向分量，约束力在横向方向精确存在。
+2. **在 nspin=2 下改进两阶段策略：** 对弱磁矩原子不释放约束（保持 Phase 1 的标准约束），仅对强磁矩原子做方向_only。需要新参数和代码修改（见上方改进方向）。
+
+### 数据采样参数推荐（方案 A）
 
 ```
-nspin              4
-noncolin           1
 sc_mag_switch      1
-sc_direction_only  1
-sc_scf_thr_mode    immediate
+sc_direction_only  0
+sc_scf_thr_mode    immediate     # 尽早启动，避免前期浪费迭代
+sc_thr             1e-6           # 生产级精度，1e-4 用于初步筛选
+nsc                200            # lambda 优化步数上限
 ```
 
-此时 M 的方向被精确约束到目标方向，|M| 由 SCF 自洽决定。能量和力对应的是"方向固定、大小自洽"的构型——这正是数据采样所需。
+约束收敛判据 sc_thr 与标注精度的对应关系：
 
-**代价：** nspin=4 计算量约为 nspin=2 的 2-4 倍（复数波函数 + 更多的自旋通道），但这是获得精确方向约束的唯一途径。
+| sc_thr | 每原子磁矩偏差 | 能量偏差量级 | 适用场景 |
+|---|---|---|---|
+| 1e-4 | ~1e-4 μB | ~1e-4 eV | 初步筛选 |
+| 1e-6 | ~1e-6 μB | ~1e-6 eV | 生产数据 |
+| 1e-8 | ~1e-8 μB | ~1e-8 eV | 高精度基准 |