Skip to content

Commit 1ae1bfc

Browse files
dyzhengdyzheng
committed
docs(constraint): user manual + progress summary + glossary + mixed-charge-spin test + FD tools
- docs/constraint_user_manual.md: INPUT params, target JSON, audit line, sign convention (mu=-lambda), current boundaries (forces pre-FD, no stress, no mixed charge+spin) - specs: progress summary (test inventory), mixed charge/spin H2O tests, terminology glossary; dev log synced - tests/constraint_fd_force/tools: Task 2.6 stationary4 FD scripts
1 parent c984b70 commit 1ae1bfc

7 files changed

Lines changed: 795 additions & 0 deletions

‎docs/constraint_user_manual.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# 实空间权重约束（constraint）用户使用说明
2+
3+
> 版本基线：feat/deltap 分支 `c984b708e`（2026-08-31）。功能状态：**SCF 级电荷/自旋约束已验证可用；约束力已接线但尚未通过 FD 判决（Task 2.6 前不可用于 relax/MD）；应力不支持**。
4+
5+
## 1. 功能概述
6+
7+
在实空间网格上定义原子/片段权重 w_I(r)（逐点 Σ_I w_I ≡ 1），对约束观测量
8+
Q_α = ∫ w_α(r) d_α(r) dr 施加 Lagrange 约束，约束势 V_con = Σ_α μ_α w_α(r)
9+
注入有效势。乘子 μ 由外环逐分量 secant 自动收敛（带 κ 限幅、翻号检测、
10+
μ_max 熔断）。
11+
12+
- **观测量 = 注入算符**：读数与注入共用同一权重场，记账恒等式自洽；
13+
- **基组无关口径**：PW 与 LCAO 在同一密度网格上读数，同密度下逐位一致；
14+
- **每 SCF 打印审计行**：sum rule（total_charge vs nelec）与单位分解偏差
15+
maxdev（应恒为 ~1e-16）永久自检。
16+
17+
## 2. INPUT 参数
18+
19+
| 参数 | 缺省 | 说明 |
20+
|---|---|---|
21+
| `constraint` | false | 总开关 |
22+
| `constraint_type` | charge | `charge`（通道 ρ）或 `spin`（通道 m=ρ↑−ρ↓，**要求 nspin=2**）。同一次计算只能选一种（混合约束未实现） |
23+
| `constraint_weight_type` | becke | 权重类型，当前仅 `becke`（Becke 模糊 Voronoi 分区，3 阶迭代多项式 + 共价半径异核修正） |
24+
| `constraint_target_file` | （必填） | 靶点 JSON 文件路径；**缺失或为空 → WARNING_QUIT**（不允许无靶点隐式约束） |
25+
| `constraint_target_mode` | delta | `delta`：靶点 = 参考态读数 + 偏移（推荐）；`absolute`：绝对靶点（会打印口径 WARNING——Becke 电荷与 SZV/ Mulliken 量级不同） |
26+
| `constraint_mu_max` | 5.0 | 乘子熔断上限（Ry）；顶限且残差平台 → 判 UNREACHABLE 并报告 Q(μ) 端点 |
27+
| `constraint_thr` | 1e-4 | 约束收敛容差（每分量 \|Q−t\|，单位 e 或 μB） |
28+
29+
## 3. 靶点文件（JSON）
30+
31+
```json
32+
{"targets": [0.1, -0.1], "atoms": [[0], [1, 2]]}
33+
```
34+
35+
- `targets[i]`：第 i 个约束的目标值（delta 模式为偏移量，charge 单位 e、spin 单位 μB）；
36+
- `atoms[i]`：第 i 个约束的原子下标组（0 起；片段 = 多原子求和）；
37+
- 约束个数 = len(targets) = len(atoms)，可多约束（逐分量独立 secant）。
38+
39+
## 4. 输出解读
40+
41+
```
42+
CONSTRAINT_AUDIT nconstraint=1 e_con=... max_residual=... total_charge=... nelec=8 maxdev=2.2e-16
43+
CONSTRAINT_AUDIT c[0] q=6.3554 t=6.3554 mu=-0.1765 res=3.06e-05
44+
[constraint] outer step 6 after SCF iteration 62 (phase=constrained)
45+
[constraint] final status: CONVERGED (targets reached within 0.0001 e)
46+
```
47+
48+
- `q/t/mu/res`：逐约束读数/靶点/乘子（Ry）/残差；
49+
- `total_charge vs nelec`：sum rule 审计（恒等即口径正确）；
50+
- 终态：`CONVERGED`（全部达标）或 `UNREACHABLE`（熔断，附 Q(μ) 端点——目标物理不可达，非数值故障）。
51+
52+
**符号约定**：两通道均为负响应——正 μ 排斥该区域电荷/自旋上。delta>0（增电荷/增磁矩）对应 μ*<0。与 DeltaSpin 的 λ 换算：**μ = −λ**。
53+
54+
## 5. 当前边界（务必阅读）
55+
56+
1. **力**：已接线（PW/LCAO 同一网格核，含驻点守卫），**但未过 stationary4 FD 判决——禁止用于 relax/MD/几何优化**。SCF 单点力打印（test_force=1 的 CONSTRAINT FORCE 块）仅供调试；
57+
2. **应力**：不支持；
58+
3. **混合约束**：同 run 仅单一 constraint_type（charge+spin 混合会 WARNING_QUIT）；
59+
4. **平台**：仅 double/CPU/double_grid（其余 WARNING_QUIT 拒绝）；KPAR=1；
60+
5. **多自旋约束**：近共线靶点（如同时对 O 和 H 约束磁矩）收敛显著变慢（实测 47 外步），属预期行为；
61+
6. 金属/近简并体系未验证。
62+
63+
## 6. 示例用例（已注册测试套件）
64+
65+
- `tests/01_PW/211_PW_constraint_h2o/`：PW 电荷约束（delta=+0.1 e on O）
66+
- `tests/01_PW/212_PW_constraint_h2o_spin/`：PW 自旋约束（delta=+0.1 μB on O）
67+
- `tests/02_NAO_Gamma/212_NAO_constraint_h2o/`：LCAO 电荷约束
68+
69+
各目录 README 含期望值；FD 验证脚本（开发用）：`tests/constraint_fd_force/tools/`。
70+
71+
## 7. 设计/验证文档
72+
73+
架构：`plan-architecture.md`；进展与测试总览：
74+
`docs/superpowers/specs/2026-08-31-constraint-framework-progress-summary.md`；
75+
术语表：`docs/superpowers/specs/deltap-constraint-glossary.md`。

‎docs/superpowers/specs/2026-08-31-constraint-framework-progress-summary.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# 实空间权重约束框架：开发进展总结（一期闭合 + 二期进行中）
2+
3+
> 截至 HEAD `3351ff6d3`（2026-08-31）。范围：从方案评审到一期闭合、二期 Task 2.1–2.4 完成、Task 2.5（M6 力核，含 LCAO 接线）完成。
4+
> 本文重点：**完成了什么测试、各自判据与实测值**。全部数值均经评审者实跑复核（非仅采信开发报告）。
5+
6+
---
7+
8+
## 1. 一句话现状
9+
10+
统一实空间权重约束框架（Hirshfeld/Becke 网格权重替代 SMO 投影，电荷/自旋/偶极同一路径）已在 ABACUS 落地：一期（PW + Becke 电荷约束）判决性验证全过；二期已交付 LCAO 通道、自旋通道、力核（PW 侧）。当前能力：**PW/LCAO 双基组电荷约束 + PW 自旋约束的 SCF 与收敛乘子；PW 约束力已接线待 FD 验收**。
11+
12+
## 2. 交付清单（16 commit）
13+
14+
| 阶段 | 模块 | 内容 | 提交 |
15+
|---|---|---|---|
16+
| 一期 | M0 | Becke 异核修正 χ_ij + 解析位置导数（partition.h/.cpp） | 8a39dac75 |
17+
| 一期 | M1 | 网格权重构造 + 单位分解审计 + MPI | 16aeed899 |
18+
| 一期 | M2 | 约束读数 Q_α=∫w·d | 9b0fda37f |
19+
| 一期 | M4 | 逐分量 secant + 七护栏 | c35f398b2 |
20+
| 一期 | M7/M3a/M5/M8 | IO 守卫 / PW 注入 / 记账 / 外环编排接线 | dff13618b…e43b1d5d5 |
21+
| 评审修复 | — | P1–P4（勾选失信/inject 契约/ctest 注册等） | 293f53aa8 |
22+
| 二期 | 2.1 | V2a 网格收敛 + V2b 独立 Becke 参考 | f6fcc443d |
23+
| 二期 | 2.2 | M3b LCAO 约束矩阵 Gint 核（审计仪器） | 17781e5da |
24+
| 二期 | 2.3 | LCAO 四薄钩子接线 + PW/LCAO 共享配置下沉 | 308e509e4 |
25+
| 二期 | 2.4 | 自旋通道 ±μ + 符号修正（response_sign） | ae9bfc600 |
26+
| 二期 | 2.5.1/2.5.2/2.5.3 | 导数网格 / M6 力核 / PW 力接线 | f0c221b3c…60c67e79d |
27+
| 二期 | 2.5.4/2.5.5 | LCAO 力接线（同一网格力核，FORCE_STRESS 通道）+ Task 2.5 闭合 | 52aa1e436、3351ff6d3 |
28+
29+
## 3. 测试总览（重点）
30+
31+
### 3.1 单元测试：12 个 ctest 目标，当前全绿（12/12，实测复核）
32+
33+
| 模块 | 关键测试与判据 | 实测 |
34+
|---|---|---|
35+
| M0 partition | f_3 解析对拍；单位分解 1e-10；**FD 导数 <1e-6**；对称性 | PASS |
36+
| M1 weight_grid | 逐点 sum rule <1e-10；对称性；近邻表 | PASS |
37+
| M1 MPI ×2 | 1/2/4-rank（含非方进程网格）逐点一致 1e-12 | PASS（3/3 MPI） |
38+
| M2 observe | 原子叠加密度解析对拍 1e-8；ΣQ=N_el 1e-10；单点 δ 钉 1e-12；**V2b 独立 Becke 参考 <1e-8** | PASS |
39+
| M4 mu_solver | 已知根收敛（合成 Q(μ) mock）；κ clamp 上下限；翻号检测；μ 硬顶；**熔断=顶限∧残差平台联合判据**；反假收敛 | 7/7 PASS |
40+
| M7 io | schema/往返；absolute 模式 WARNING（口径守卫）；无 target→WARNING_QUIT；nspin≠2+spin→ERROR | PASS |
41+
| M3a inject_pw | 逐点注入机器精度；**观测量==注入算符数值恒等式（∫ρ·μw dr == μ·Q，1e-10）**；spin 拆分注入 | PASS |
42+
| M3b inject_lcao | **Σ_α W^α ≡ S（重叠矩阵，2.0e-15）**；W^α↔网格直积 3.4e-15 | PASS |
43+
| M5 accounting | E_con=Σμ(Q−t)；key=value 审计行 | 4/4 PASS |
44+
| M8 loop | 两阶段门控状态机；conv_esolver 门控（未收敛 SCF 不外步）；inject 返回值契约（P2）；**反假收敛全链路** | 6/6→含 spin PASS |
45+
| M6 deriv/force | 导数网格平移不变性 Σ_J∂w/∂R_J+∂w/∂r≡0（1e-10，独立 5 点差分作 ∂w/∂r）；**力 vs 合成密度解析 2.2e-10（判据 1e-8）；牛顿第三定律 7e-13（判据 1e-9）**；力对 μ 线性 1e-12 | PASS |
46+
47+
### 3.2 集成测试（3 用例，全部注册 CASES_CPU.txt 并对拍 result.ref）
48+
49+
| 用例 | 场景 | 实测关键值 | 对拍偏差 |
50+
|---|---|---|---|
51+
| tests/01_PW/211_PW_constraint_h2o | PW 电荷 delta=+0.1 e on O | 6 外步 CONVERGED；μ*=−0.1765 Ry；Q_ref=6.2555 | etot 差 4.1e-9 eV |
52+
| tests/01_PW/212_PW_constraint_h2o_spin | PW 自旋 delta=+0.1 μB on O | 3 外步 CONVERGED；μ*=−0.07234 Ry；m_ref=5.9e-6 | etot 差 9.5e-10 eV |
53+
| tests/02_NAO_Gamma/212_NAO_constraint_h2o | LCAO 电荷 delta=+0.1 e on O | 6 外步 CONVERGED；μ*=−0.2193 Ry；Q_ref=6.4080 | etot 差 2.4e-11 eV |
54+
55+
### 3.3 判决性验证（一期验收门）
56+
57+
- **V1 sum rule PASS**：Σ_I N_I ≡ nelec=8，maxdev=2.2e-16（逐点单位分解的机器精度直接体现）；O=6.2555/H=0.87227（PW）。
58+
- **V2 口径基准 PASS（重定义后内部闭环，无外部工具）**：V2a 网格收敛三档（81³/120³/162³）相邻档差 max 8.2e-5 < 1e-4 e；V2b 仓库内 C++ 独立参考（从 Becke 1988 原始公式重写，不调生产实现）对拍 <1e-8。严格单调失败已如实登记为口径偏差。Multiwfn 降级为可选 V2c'。
59+
- **V3 可达性 PASS（7/7）**：delta=±0.05/0.1/0.2/0.3 e 全收敛无封顶，μ*≈−1.7·delta 线性平滑，|μ*|max=0.56 Ry ≪ μ_max=5.0；**熔断**：delta=+5.0 e 不可达 → μ 顶限 + Q 平台 3 步无改进 → UNREACHABLE + Q(μ) 端点报告；**反假收敛**：μ=0 自由跑从不收敛到非自然靶点。
60+
- **T12 判决**：可达域宽（κ≈1.7 远离 0.3 下限），开二期条件满足。
61+
62+
### 3.4 反向破坏验证（sabotage，守卫非摆设的证据）
63+
64+
| 破坏 | 结果 |
65+
|---|---|
66+
| 移除 nspin 守卫 | 恰 2 个目标测试 FAIL（SpinTypeGuard + ConfigureFromInputsShared） |
67+
| 翻转 spin 注入符号（V_↑+= → −=） | 恰 SplitInjectionSpin FAIL |
68+
| response_sign 设 +1 | 恰 SpinChannelConvergesOnLinearResponse FAIL（m 被驱到 −2 而非 +0.02） |
69+
70+
### 3.5 MPI 一致性
71+
72+
权重网格 1/2/4-rank 逐点一致 1e-12；LCAO 集成用例 4-rank vs 串行能量差 3.4e-11 eV、Q/μ 逐位一致；M6 导数网格 MPI 3/3。
73+
74+
### 3.6 回归
75+
76+
每轮 `ctest -R constraint|partition|read_input|elecstate_pw` 全绿；PW 037_FM、PW 211、LCAO 212 逐位复现；已知的 MODULE_LCAO 2 FAIL+2 Not Run 与 unitcell_test_pw 经核实为**既有 CWD/构建树问题**（脚本/support 未拷入），与 constraint 改动零交集。
77+
78+
### 3.7 评审链（5 轮实证评审，问题全部闭环）
79+
80+
| 轮次 | 裁定 | 发现问题 | 状态 |
81+
|---|---|---|---|
82+
| 一期总评 | 通过 | P1 勾选失信 / P2 inject 契约 / P3 措辞 / P4 集成用例未注册 | 293f53aa8 全部闭环 |
83+
| Task 2.3 | 通过 | Task 2.1 Step 6 漏勾；M3b 头注误导 | 已闭环（ae9bfc600 随轮修正） |
84+
| Task 2.4 | 通过 | 符号修正判定为正当（实测驱动，非改判据）；037 回归与 sabotage 未复核（低风险登记） | 无需处理 |
85+
| V2 阻塞消解 | 方案修订 | Multiwfn 依赖 → V2a/V2b 内部闭环 | f6fcc443d 闭环 |
86+
| Task 2.5（M6 力核，§3.8） | 通过 | 无阻断项；驻点 WARNING 守卫与核守卫实证在线 | 无需处理 |
87+
88+
### 3.8 Task 2.5 评审实录（2026-08-31，评审者亲自复跑）
89+
90+
- **PW 集成**（211 + `test_force=1` 复跑）：CONSTRAINT FORCE 块 O z=+0.09929、H1/H2 x=∓0.0963、z=+0.0722 Ry/Bohr——与 spec 逐项吻合；**总力平移不变性** Σ_J F_J≈4e-5 eV/Å≈0（含约束块；约束块自身不必求和为零——包络定理下 KS 块在约束密度处补偿，属预期行为，实测总力闭合）。
91+
- **μ=0 短路**（delta=0 变体复跑）：约束块精确全零（零乘子短路实证）。
92+
- **LCAO 集成**（212_NAO + cal_force/test_force 复跑）：O z=+0.10902、H x=∓0.10723、z=+0.08304——与 spec 吻合；FORCE_STRESS.cpp:468 与 PW 调**同一个** `constraint_force` 核（grep 实证，无双份力代码）。
93+
- **守卫实证**：`compute_force` 懒建导数网格 + 驻点守卫（外环未收敛时 WARNING "residual O(|Q−t|)"）；力核对未建导数网格的直调 WARNING_QUIT（开发期"修复 1 处"声称的核守卫真实）。
94+
- **判定边界**：以上验证的是**管线正确性**（非零/零/对称/守恒/守卫），力的**物理精度**（FD 对拍）属 Task 2.6，此前力不可用于生产——此边界不变。
95+
96+
## 4. 当前边界与遗留债务
97+
98+
1. **力未验收**：M6 双基组力均已接线、单测过（解析 2.2e-10/牛三 7e-13/线性 1e-12；LCAO 侧冒烟 O z=+0.1090、H x=∓0.1072 Ry/Bohr，μ=0 参考相力块精确全零），但 stationary4 FD 判决（0.0129 eV/Å，网格前提 ecutwfc=100+ecutrho≥400+scf_thr=1e-8）在 Task 2.6 才执行——此前力不可用于生产。
99+
2. ~~LCAO 力未接线~~（2.5.4 已完成：同一网格力核经 FORCE_STRESS 通道，验证"双基组同码"架构声明）。
100+
3. **M3b 悬置资产**：W^α HContainer 路径仅作 ctest 审计仪器（生产走 v_eff 网格注入）；Task 2.6 升格运行时审计或收尾删除。
101+
4. **V2c'（Multiwfn 约定级对拍）**：可选，不阻塞。
102+
5. **三期内不做**：Hirshfeld 权重、Broyden、偶极/多极子、应力（R6 待证）、Hirshfeld-I——禁止清单在案。
103+
6. 未独立复核项（低风险）：037_PW_FM 回归、sabotage 重做。
104+
105+
## 5. 下一步
106+
107+
Task 2.6 三判决验证（PW≡LCAO 逐位一致 / 力 FD stationary4 / 力矩 FD 严格 μ=−λ 换算）+ M3b 命运判决 → Task 2.7 二期判决门（不过不降低判据）。
108+
109+
---
110+
111+
> 文档链：方案（实空间权重约束框架设计方案.md）→ 架构（plan-architecture.md）→ 评审 5 份（2026-08-26-*）→ 计划 2 份（plans/2026-08-30-phase1、2026-08-31-phase2）+ Task 2.5 详案 → 每模块 dated spec 14 份 + 评审记录 4 份 → 本总结。全部运行记录见 deltap-development-log.md 2026-08-26 起各节。

‎docs/superpowers/specs/2026-08-31-mixed-charge-spin-test.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# 电荷+自旋同时约束的可行性实测（H₂O，nspin=2）
2+
3+
> 问题：当前版本能否同时约束电荷和自旋？方式：三组 H₂O 实测（/tmp，串行，15 Å 盒，ecutwfc=20/ecutrho=80）。无代码改动。
4+
5+
## 结论速览
6+
7+
| 场景 | 当前支持？ | 实测 |
8+
|---|---|---|
9+
| 同 run 多约束（同一类型、多片段） | ✅ 支持 | A/B 两组均 CONVERGED |
10+
| **同 run 混合 charge+spin** | ❌ **不支持** | 输入无法表达；守卫实证拒绝 |
11+
12+
## 测试 A：电荷双片段（type=charge，nspin=2）
13+
14+
`{"targets":[0.1,-0.1],"atoms":[[0],[1,2]]}`（O +0.1 e，H 片段 −0.1 e）：
15+
16+
- **CONVERGED**（少外步）：c[0] res=+1.66e-5、c[1] res=−1.66e-5（均 <1e-4）；
17+
- μ_O=−0.0881、μ_HH=+0.0881 Ry（纯电荷转移对的镜像乘子，物理合理）。
18+
19+
## 测试 B：自旋双片段（type=spin，nspin=2）
20+
21+
`{"targets":[0.1,-0.05],"atoms":[[0],[1]]}`（O +0.1 μB，H1 −0.05 μB）：
22+
23+
- **CONVERGED，但用了 47 个外步**（单自旋约束仅 3 步）：c[0] res=−6.0e-5、c[1] res=+5.3e-5；
24+
- μ_O=−0.07236 Ry（与单约束 μ*=−0.07234 一致）、μ_H1≈−5.0e-5 ≈ 0；
25+
- 分析：两约束近共线——H1 权重区小，m 读数主要由 O 区贡献，H1 靶点几乎被 O 约束"顺带"满足；轨迹前 4 步残差振荡（+0.0036→−0.0090→−0.0149），是对角 secant 在近共线约束对下的预期行为（T-7p 教训同类），最终自愈未触熔断。**多自旋约束可用但收敛成本显著高。**
26+
27+
## 测试 C：混合输入守卫
28+
29+
`constraint_type charge_spin` → before_scf **WARNING_QUIT**（EXIT=1）：
30+
`constraint_type="charge_spin" is not implemented in phase 2 (only "charge" and "spin")`。
31+
32+
代码事实：`ConstraintConfig.type` 为 run 级单值，`channel_from_type(cfg_.type)` 在 observe/inject/force 四处全局调用——混合约束在当前 schema 下无法表达。
33+
34+
## 实现混合约束的改动评估（框架内，无新算法）
35+
36+
M2/M3a/M6 均已按 channel 参数化，M4 逐分量与 channel 无关。所需改动：
37+
1. 靶文件 JSON 增加逐约束 type 字段（如 `{"targets":[...],"atoms":[...],"types":["charge","spin"]}`），M7 解析+守卫（spin 型约束要求 nspin=2）；
38+
2. ConstraintLoop 持有逐约束 channel 数组，observe/inject/force 三处按分量取 channel（注入时 charge 分量同号、spin 分量 ±μ 叠加进同一 v_eff）；
39+
3. 审计行/输出标注每分量类型。
40+
估计 1–2 天含测试。建议立项为 Task 2.4.1 或三期项（非当前判决门阻塞项）。
41+
42+
---
43+
44+
## 本轮记录
45+
46+
- 实验轮，无代码改动。用例在 /tmp/mixed/{a_charge,b_spin,c_guard}（未入库；如需保留可按 P4 先例注册 tests/）。

0 commit comments

Comments
 (0)