docs(deltaspin): rewrite nspin=2 constraint evaluation for data sampling

Refocus on whether each scheme can deliver precise constraint for
magnetic configuration data sampling (energy/force labeling):

- Scheme A: precise direction+magnitude constraint (✅), with parameter
  recommendations (sc_thr tightening, mode selection)
- Scheme B (direction_only): cannot achieve precise constraint (❌ for both
  direction+magnitude and direction-only). Phase 2 relaxes constraint,
  not preserves it
- Scheme C (off): cannot achieve precise target (❌). Mz≠target unless
  lambda is pre-computed
- Direction-only precise sampling: not achievable in nspin=2. Should use
  nspin=4 where direction_only projection works correctly

Author: dyzheng

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

@@ -1,96 +1,116 @@
-# DeltaSpin nspin=2 磁约束方案评估
+# DeltaSpin nspin=2 磁约束方案：精确数据采样能力评估
 
-## 三种方案对比
+## 评估背景
 
-### 方案 A：标准约束（约束磁矩大小 + 方向）
+目标：对磁性体系大规模标注目标磁构型的能量和力。要求约束是精确的——计算结果对应目标磁构型本身，而非近似构型。
 
-BFGS 优化 lambda_z，使磁矩 Mz 收敛到目标值。
+评估分两个约束策略：
+1. **方向 + 大小约束**：Mz 精确收敛到目标值
+2. **仅约束方向**：Mz 的符号（方向）保持，大小由电子结构自洽决定
 
-**优势：**
-- 物理意义明确：约束力始终存在，磁矩在收敛过程中持续逼近目标
-- 数值稳定：BFGS 有完整的梯度和 Hessian 信息，收敛行为可预测
-- 适用于所有 nspin=2 场景
+---
+
+## 方案 A：标准约束（sc_direction_only = false）
+
+BFGS 优化 lambda_z，使 Mz 收敛到 target_Mz。约束收敛判据为 `|Mz - target_Mz| < sc_thr`。
+
+### 方向 + 大小约束：✅ 可实现
+
+BFGS 迭代调整 lambda_z 直到磁矩误差低于 sc_thr。设 sc_thr = 1e-6 时，每原子磁矩偏差 < 1e-6 μB，对应能量偏差 λ·ΔMz ≈ 1e-6 eV 量级，满足数据采样精度需求。
+
+约束对总能量的贡献为 `ΔE = Σ λ_i (Mz_i - Mz_target_i)`。当约束精确满足时，ΔE ≈ 0，计算所得总能即为目标磁构型下的 DFT 能量。力包含约束力项，对应目标磁构型下的 Hellmann-Feynman 力。
+
+**推荐参数：**
+
+```
+sc_mag_switch      1
+sc_direction_only  0
+sc_scf_thr_mode    immediate     # 尽早启动优化，避免前期浪费
+sc_thr             1e-6         # 磁矩收敛精度，按需收紧
+nsc                200          # lambda 优化步数上限，确保收敛
+```
+
+或使用 threshold 模式（给 SCF 几步热身时间）：
 
-**劣势：**
-- 约束的是 **磁矩大小**，不能单独控制方向——如果你只想约束自旋指向（方向不变但大小自由变化），此方案无法实现
-- 对于反铁磁（AFM）体系，BFGS 可能需要较多迭代步数才能找到正确的 lambda
+```
+sc_scf_thr_mode    threshold
+sc_scf_thr         1e-3         # drho 低于此值后开始优化 lambda
+sc_thr             1e-6
+```
 
-**生产建议：** nspin=2 下的默认选择。只要目标约束包含磁矩大小信息，就应该使用此方案。
+`sc_thr` 是数据采样精度的直接控制参数。1e-4 适合初步筛选，1e-6 适合产线数据，必要时可进一步收紧。
+
+### 仅约束方向：❌ 无法实现
+
+方案 A 约束的是 Mz 的绝对值，不提供"仅约束方向"的机制。无法在约束 Mz 符号的同时让 |Mz| 自由弛豫。
 
 ---
 
-### 方案 B：仅约束方向（direction_only）两阶段策略
+## 方案 B：direction_only 两阶段策略
 
-适用于目标：只约束自旋指向，磁矩大小由电子结构自洽决定。
+### 方向 + 大小约束：❌ 无法实现
 
-**算法：**
+Phase 2 中 lambda 指数衰减，约束力逐渐消失。系统弛豫到自然基态磁矩，而非目标值。最终 Mz ≠ target_Mz。
 
-| 阶段 | 步骤 | 机制 | skip_solve |
-|---|---|---|---|
-| Phase 1 | iter 1 ~ `sc_dir_phase1_steps` | 临时禁用 direction_only，BFGS 约束磁矩大小到目标值 | true（BFGS 内循环处理对角化） |
-| 过渡 | iter = phase1 + 1 | 重置 Broyden 混合历史（Phase 1 的 DM 更新方式与 SCF 不兼容） | — |
-| Phase 2 | iter > phase1 | lambda 每步乘以 0.5^(1/3) ≈ 0.794 衰减（约每 3 步减半） | false（正常 SCF） |
+### 仅约束方向：❌ 无法实现
 
-**为什么需要两阶段？** nspin=2 共线磁的约束方向只能沿 z 轴。`direction_only` 投影移除 lambda 的平行分量，在 nspin=2 下这会把 lambda_z 归零（因为 z 就是全部的约束方向），导致约束力完全消失。两阶段策略通过 Phase 1 先用标准约束建立 AFM 序和合理的 lambda 分布，Phase 2 再逐渐释放约束让系统弛豫。
+Phase 2 的 lambda 衰减机制保证"约束力平滑消失"而非"方向保持不变"。算法原理：
 
-**优势：**
-- 计算速度快：Phase 2 每步只做一次标量乘法 `λ *= 0.794`，无需 BFGS 内循环
-- 可以研究磁各向异性和磁矩大小由自洽决定的体系
+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. λ 衰减到一定程度后约束力不足以稳定磁矩方向
 
-**劣势：**
-- **Phase 2 中磁矩方向不保证保持不变。** lambda 衰减使得约束力逐渐减弱，自旋可能翻转到其他方向。这在磁矩较小（< 1.0 μB）的原子上尤其容易发生。这不是 bug 而是算法本质：方向不受约束力保护，完全依赖系统的稳定性
-- Phase 1 结果依赖 `sc_dir_phase1_steps` 的选择：步数太少则 AFM 序不充分，步数太多则 lambda 过大导致 Phase 2 起始偏差大
-- Phase 1→2 过渡需要重置混合历史，可能引入瞬态振荡
-- PW 基组不支持此方案（PW 路径未实现两阶段逻辑，direction_only 投影会直接归零 lambda）
+**结果取决于交换劈裂强度：**
+- 磁矩 > 1 μB 的 3d 原子：交换劈裂强，方向可能稳定——但这是体系的内在稳定性，不是约束的功劳
+- 磁矩 < 1 μB 的原子：λ 衰减几分之一后方向就可能翻转
 
-**生产建议：**
-- **适合：** 简单 AFM 体系（每个原子磁矩 > 1 μB）、需要快速获得大致磁结构的场景、对磁矩精确值不敏感的筛选计算
-- **不适合：** 复杂磁结构（磁性原子多、磁矩小、 orientations 多样）、需要精确磁矩方向的定量计算、PW 基组
-- **使用前应先验证：** 用方案 A 得到参考磁矩分布，比较 Phase 2 弛豫后方向是否稳定。如果不稳定，说明该体系不适合此方案
+**结论：方案 B 的输出是一个"约束释放后弛豫"的构型，而非"约束方向不变"的构型。** 它提供的是一个近似磁基态搜索的方法，而非能在目标方向上标注精确能量的方法。Phase 2 末态的磁矩方向是否与目标一致，需要逐例事后检查，不存在可调参数使其保证。
 
 ---
 
-### 方案 C：常量 lambda（off 模式）
+## 方案 C：常量 lambda（sc_scf_thr_mode = "off"）
+
+lambda 从 STRU 读入，作为常量约束加入哈密顿量，不做 BFGS 优化。
 
-lambda 从 STRU 文件读入，作为常量约束加到哈密顿量中，从不优化。
+哈密顿量中多了一项 `H_const = λ_z σ_z`，Mz 收敛到 λ_z 与 DFT 势的平衡值，**不等于 target_Mz**（除非 λ_z 恰好取到使 Mz = target_Mz 的值）。
 
-**优势：**
-- 完全确定性：lambda 不变，结果可复现
-- 无额外计算开销：不运行 BFGS，迭代步数与普通 SCF 相同
-- 适合已知 lambda 的情景（如从 nspin=4 计算提取 lambda 值后做 nspin=2 重算）
+### 方向 + 大小约束：❌ 无法实现
 
-**劣势：**
-- 需要事先知道合理的 lambda 值——如果 lambda 偏差较大，磁矩会偏离目标
-- 无法收敛到自洽的 lambda——得到的是约束下的电子基态，不是约束优化的基态
+Mz 由 SCF 自洽决定，偏移量依赖于 λ_z 的取值。除非 λ_z 经过精确预计算（本身就需要方案 A 求解），否则 Mz ≠ target_Mz。
 
-**生产建议：** 适用于已知 lambda 的重算场景，或只需要固定约束下做带隙/能量比较的计算。不适合探索性计算。
+### 仅约束方向：⚠️ 弱偏置，非精确约束
+
+小的 λ_z 可以为 Mz 方向提供一个弱偏置，但：
+- λ_z 太小：方向可能不稳定
+- λ_z 太大：|Mz| 被偏置，偏离自洽值
+- 效果依赖 λ_z 的取值，不是参数化的"仅约束方向"方案
 
 ---
 
-## 方案选择要点
+## 总结
 
-| 决策因素 | 方案 A（标准） | 方案 B（direction_only） | 方案 C（off） |
+| 约束策略 | 方案 A（标准） | 方案 B（direction_only） | 方案 C（off） |
 |---|---|---|---|
-| 约束目标 | 大小 + 方向 | 仅方向（大小自由弛豫） | 大小 + 方向（固定 lambda） |
-| 计算速度 | 中（每步运行 BFGS） | 快（Phase 2 无 BFGS） | 快（无 BFGS） |
-| 方向保真度 | ✓ 严格约束 | ⚠ 不保证，依赖体系 | ✓ 严格约束 |
-| 数值稳定性 | ✓ 高 | ⚠ Phase 1→2 过渡可能振荡 | ✓ 高 |
-| PW 基组支持 | ✓ | ✗ | ✓ |
-| 对 lambda 初值的依赖 | 低（BFGS 自优化） | 低（Phase 1 自建立） | 高（需要已知值） |
+| 方向 + 大小 | ✅ 可实现 | ❌ | ❌ |
+| 仅约束方向 | ❌ | ❌ | ⚠️ 弱偏置 |
+
+**nspin=2 下能用于精确数据采样的只有方案 A 的方向 + 大小约束。** 仅约束方向的精确采样在 nspin=2 体系下目前没有可行方案。
+
+---
 
-### 何时用方案 B 而非方案 A？
+## 仅约束方向的精确采样：nspin=4 替代方案
 
-唯一合理的场景：**你需要的是磁矩方向而非大小。** 也就是说，物理问题本身决定了磁矩大小应由自洽计算得出，而非被约束到预设值。
+如果研究问题需要"仅约束方向、大小自由弛豫"的精确数据标注，应使用 nspin=4（非共线）模式。在 nspin=4 下，lambda 有 x、y、z 三个分量，`direction_only` 投影仅移除平行于目标方向的分量，保留横向分量，约束力在横向方向精确存在。
 
-如果最终需要磁矩大小也准确，方案 B 只能作为初步探索——先用 B 快速判断磁结构取向，再用 A 精确约束大小。
+```
+nspin              4
+noncolin           1
+sc_mag_switch      1
+sc_direction_only  1
+sc_scf_thr_mode    immediate
+```
 
-### 方案 B 的磁矩方向风险
+此时 M 的方向被精确约束到目标方向，|M| 由 SCF 自洽决定。能量和力对应的是"方向固定、大小自洽"的构型——这正是数据采样所需。
 
-> **关键风险：Phase 2 弛豫过程中，磁矩方向没有约束力保护。**
->
-> Phase 2 的 lambda 衰减机制保证的是"约束力平滑消失"而非"方向保持不变"。系统在约束力减弱后能否维持方向，完全取决于交换劈裂的强度：
-> - 磁矩 > 1 μB 的 3d 过渡金属原子：交换劈裂强，方向一般稳定 ✅
-> - 磁矩 < 1 μB 的原子（如界面原子、近简并态）：交换劈裂弱，方向容易翻转 ❌
-> - 非共线磁矩的初始猜测偏离较大时：可能弛豫到不同磁构型 ❌
->
-> 方案 B 的输出结果中磁矩方向是否稳定，**必须事后检查**。如果 Phase 2 末期磁矩方向偏离目标方向超过可接受范围，应改用方案 A。
+**代价：** nspin=4 计算量约为 nspin=2 的 2-4 倍（复数波函数 + 更多的自旋通道），但这是获得精确方向约束的唯一途径。