docs: translate DMR pairing derivation to English

docs/nao_lcao_force_stress_derivation.md was added by the DMK->DMR
sign fix in Chinese; translate it to English and drop the references
to the internal Chinese planning/investigation documents (kept out of
the repo). Point the code comments in density_matrix.h and the
T1/T2/T3/T8 unit tests at the English derivation sections (Sec. 3 for
the Fourier sign, Sec. 5 for the closed-trace protection).

Comment-only changes; no behavior change.

Author: dyzheng

docs/nao_lcao_force_stress_derivation.md

@@ -1,137 +1,157 @@
-# LCAO 力/应力中 DMR 配对约定推导（DM/DMK/DMR 链路）
-
-- 日期：2026-08-09
-- 相关代码：`source/source_estate/module_dm/`（DMK/DMR）、
-  `source/source_hamilt/module_hcontainer/func_folding.cpp`（folding_HR）、
-  `source/source_lcao/module_operator_lcao/`（overlap/ekinetic/nonlocal 力与应力）
-- 配套文档：`docs/dm_dmk_dmr_investigation.md`（排查）、
-  `docs/dm_dmk_dmr_action_plan.md`（整改与测试方案）
-
-本文档锁定 DMK→DMR 的傅里叶符号约定，以及力/应力计算中实空间密度矩阵
-与两中心积分（含 nonlocal 的 R2−R1 配对）的收缩对应关系，作为代码注释
-（`density_matrix.cpp` 中 "See Sec. 3 ..."）所指的推导依据。
-
-## 1. 指标与 R 格矢约定
-
-- 波函数系数 `C_{μn}(k)`：μ = 轨道（行），n = 能带（列），存储为
-  `psi::Psi` 的 `wfc(ib, iw)`。
-- 密度矩阵元素 `D_{μν}`：μ = 行（bra）轨道，ν = 列（ket）轨道。
-- 格矢 R：`HContainer::AtomPair(iat1, iat2, R)` 的矩阵块为
-  `O_{μν}(R)`，μ∈iat1（0 胞）、ν∈iat2（R 胞）；格矢满足
-  `dtau = τ(iat2) + R·L − τ(iat1)`（`UnitCell::cal_dtau`）。
-- k、R 均为**直接坐标**，相位 `k·R` 前乘 `2π`。
-
-## 2. k 空间与实空间傅里叶对
-
-- 正变换（算符，`folding_HR`，`func_folding.cpp`）：
+# DMR pairing conventions in LCAO force/stress (DM/DMK/DMR chain)
+
+- Date: 2026-08-09
+- Related code: `source/source_estate/module_dm/` (DMK/DMR),
+  `source/source_hamilt/module_hcontainer/func_folding.cpp` (folding_HR),
+  `source/source_lcao/module_operator_lcao/` (overlap/ekinetic/nonlocal
+  force and stress)
+- This document fixes the DMK->DMR Fourier sign convention and the
+  contraction mapping between the real-space density matrix and the two-center
+  integrals (including the nonlocal R2-R1 pairing) used by the force/stress
+  code. It is the derivation referenced by the code comments (the
+  "See Sec. 3 ..." comments in `density_matrix.cpp`).
+
+## 1. Index and R-lattice conventions
+
+- Wave-function coefficients `C_{μn}(k)`: μ = orbital (row), n = band
+  (column), stored as `psi::Psi`'s `wfc(ib, iw)`.
+- Density-matrix elements `D_{μν}`: μ = row (bra) orbital, ν = column (ket)
+  orbital.
+- Lattice vector R: the matrix block of `HContainer::AtomPair(iat1, iat2, R)`
+  is `O_{μν}(R)` with μ ∈ iat1 (home cell) and ν ∈ iat2 (cell R); the vector
+  satisfies `dtau = τ(iat2) + R·L − τ(iat1)` (`UnitCell::cal_dtau`).
+- k and R are both in **direct coordinates**; the phase `k·R` carries a
+  factor of `2π`.
+
+## 2. k-space and real-space Fourier pair
+
+- Forward transform (operators, `folding_HR`, `func_folding.cpp`):
 
   ```
   O(k) = Σ_R e^{+ikR} O(R)
   ```
 
-- 逆变换（密度矩阵，`DensityMatrix_Tools::cal_DMR*`，`density_matrix.cpp`）：
+- Inverse transform (density matrix, `DensityMatrix_Tools::cal_DMR*`,
+  `density_matrix.cpp`):
 
   ```
   D(R) = Σ_k e^{-ikR} DMK(k)
   ```
 
-- 归一化：k 点权重 `w_k` 已内嵌在 `DMK`（`wg = w_k·occ`，
-  `occupy.cpp`），因此 `cal_DMR` **不**再乘 `1/Nk`。
+- Normalization: the k-point weights `w_k` are embedded in `DMK`
+  (`wg = w_k·occ`, `occupy.cpp`), so `cal_DMR` must **not** multiply by
+  `1/Nk` again.
 - `DMK(μ,ν;k) = Σ_n f_nk C*_{μn}(k) C_{νn}(k) = (C f C†)^T = D_std^T`
-  （`cal_dm_psi.cpp`，`zgemm('N','T')` + 先取共轭）。
+  (`cal_dm_psi.cpp`, `zgemm('N','T')` on pre-conjugated coefficients).
 
-## 3. 正逆变换互为逆（Sec. 3 约定）
+## 3. Forward and inverse transforms are mutual inverses (Sec. 3 convention)
 
-对同一套 R 定义，`e^{+ikR}`（folding_HR）与 `e^{-ikR}`（cal_DMR）构成
-自洽的正逆傅里叶对。若把 `density_matrix.cpp` 中的 `-sinp` 改回 `+sinp`，
-则 `D(R)` 实际存的是正变换 `Σ_k e^{+ikR} DMK(k)`，与 `folding_HR` 不再
-互为逆变换，非对角/非对称消费方（如 nspin=4 nonlocal 力）即出错。
-该符号由单元测试 `T1_fourier_round_trip` 锁定（见
-`docs/dm_dmk_dmr_action_plan.md` §T1）。
+For the same set of R vectors, `e^{+ikR}` (folding_HR) and `e^{-ikR}`
+(cal_DMR) form a self-consistent forward/inverse Fourier pair. If the
+`-sinp` in `density_matrix.cpp` were changed back to `+sinp`, then `D(R)`
+would actually store the forward transform `Σ_k e^{+ikR} DMK(k)`, which is no
+longer the inverse of `folding_HR`; non-diagonal / non-symmetric consumers
+(such as the nspin=4 nonlocal force) then become wrong. This sign is locked
+by the unit test `T1_fourier_round_trip` (see below).
 
-## 4. 力/应力的一般形式
+## 4. General form of the force/stress
 
-Feynman–Hellmann 型受力（overlap/ekinetic/nonlocal 等）：
+The Feynman–Hellmann-type forces (overlap/ekinetic/nonlocal etc.) read:
 
 ```
 F = Σ_k Tr[ D(k) · ∂O(k)/∂τ ]
   = Σ_k Σ_{μν} D_{μν}(k) ∂O_{νμ}(k)/∂τ
 ```
 
-代入 `∂O(k) = Σ_R e^{+ikR} ∂O(R)`：
+Substituting `∂O(k) = Σ_R e^{+ikR} ∂O(R)`:
 
 ```
 F = Σ_R Σ_{μν} ∂O_{νμ}(R) D_{μν}(−R)          (*)
-   其中 D(−R) := Σ_k e^{+ikR} DMK(k)
+   with D(−R) := Σ_k e^{+ikR} DMK(k)
 ```
 
-代码存储的是 `D(R) = Σ_k e^{-ikR} DMK(k)`，两者通过 §5 的闭合迹论证等价。
+The code stores `D(R) = Σ_k e^{-ikR} DMK(k)`; the two are equivalent through
+the closed-trace argument of Sec. 5.
 
-## 5. 闭合迹共轭保护（Sec. 5 配对）
+## 5. Closed-trace conjugate protection (Sec. 5 pairing)
 
-代码在两中心积分路径中，对每个 `(iat1,iat2,R)` 同指标收缩：
+In the two-center integral path the code contracts same-index pairs for every
+`(iat1,iat2,R)`:
 
 ```
 W_code = Σ_{μνR} D(μ,ν;R) ∂O(μ,ν;R)
 ```
 
-把 `D(R) = Σ_k e^{-ikR} DMK(k)` 代入：
+Substituting `D(R) = Σ_k e^{-ikR} DMK(k)`:
 
 ```
 W_code = Σ_k Σ_{μν} DMK(μ,ν;k) [Σ_R e^{-ikR} ∂O(μ,ν;R)]
        = Σ_k Tr( DMK(k) · ∂O'(−k) )
 ```
 
-其中 `∂O'(−k) := Σ_R e^{-ikR} ∂O(R)` 是 folding 在 −k 处的取值。
-若 `∂O` 在 HContainer 中**全方向成对**（对每个 `(iat1,iat2,R)` 存在
-`(iat2,iat1,−R)`，且 `∂O(iat2,iat1,−R) = ∂O(iat1,iat2,R)†`），则
-`∂O'(k) = Σ_R e^{+ikR} ∂O(R)` 逐 k 厄米，`∂O'(−k) = ∂O'(k)†`。于是
+where `∂O'(−k) := Σ_R e^{-ikR} ∂O(R)` is the folded operator evaluated at
+`−k`. If `∂O` is stored in the HContainer with **full-direction pairing**
+(for every `(iat1,iat2,R)` there is `(iat2,iat1,−R)` with
+`∂O(iat2,iat1,−R) = ∂O(iat1,iat2,R)†`), then `∂O'(k) = Σ_R e^{+ikR} ∂O(R)`
+is Hermitian for each k and `∂O'(−k) = ∂O'(k)†`. Hence
 
 ```
 W_code = Σ_k w_k Tr( DMK(k) · ∂O'(k)† )
        = Σ_k w_k conj( Tr( DMK(k) ∂O'(k) ) )
-       = Σ_k w_k Tr( DMK(k) ∂O'(k) )        [厄米矩阵对的迹为实数]
+       = Σ_k w_k Tr( DMK(k) ∂O'(k) )        [trace of Hermitian pair is real]
        = Σ_k w_k Re Tr( DMK(k) ∂O'(k) )
 ```
 
-即**总和受共轭保护**，而非"逐项相等"。保护成立的三条件：
+That is, the **total is protected by the conjugate** rather than by
+"term-by-term equality". The protection holds under three conditions:
 
-1. 收缩是**全轨道闭合 Frobenius 迹**（不按元素取用）；
-2. 配对算符**逐 k 厄米**（HContainer 全方向成对存储）；
-3. 只取**实部**。
+1. The contraction is a **closed Frobenius trace over all orbitals**
+   (no element-wise consumption);
+2. The paired operator is **Hermitian per k** (HContainer full-direction
+   paired storage);
+3. Only the **real part** is kept.
 
-破坏任一条件的消费方即暴露于 O(1) 配对误差。
+Any consumer that breaks one of these conditions is exposed to an O(1)
+pairing error.
 
-### 5.1 overlap / ekinetic（两中心积分路径）
+### 5.1 overlap / ekinetic (two-center integral path)
 
-`operator_fs_utils.hpp` 的 `cal_force_stress_2center` 对
-`(iat1,iat2,R)` 直接取 `D(μ,ν;R) ∂O(μ,ν;R)` 同指标收缩，且对
-`(iat2,iat1,−R)` 同样各计一次（全 R 集迭代），故
-`finalize_force_stress(force_factor = 1.0)`（无需因子 2）。
+`cal_force_stress_2center` in `operator_fs_utils.hpp` contracts
+`D(μ,ν;R) ∂O(μ,ν;R)` with same indices for every `(iat1,iat2,R)`, and
+`(iat2,iat1,−R)` is visited once as well (full R-set iteration), hence
+`finalize_force_stress(force_factor = 1.0)` (no factor 2 needed).
 
-### 5.2 nonlocal（β 投影，R2−R1 配对）
+### 5.2 nonlocal (β projection, R2−R1 pairing)
 
-`nonlocal_fs.cpp::cal_force_stress` 以中心原子 `iat0` 为基准枚举两个
-邻原子：`iat1`（胞 `R1`）、`iat2`（胞 `R2`），取用的 DMR 块是
+`nonlocal_fs.cpp::cal_force_stress` enumerates two neighbor atoms relative to
+the central atom `iat0`: `iat1` (cell `R1`) and `iat2` (cell `R2`), and
+consumes the DMR block
 
 ```
 dmR->find_matrix(iat1, iat2, R2 − R1)
 ```
 
-即配对结构为 `R_vector = R2 − R1`（`nonlocal_fs.cpp` 中
-`R_index2 − R_index1`），不是简单同 R 闭合迹。该路径的受力公式为
+i.e. the pairing structure is `R_vector = R2 − R1` (`R_index2 − R_index1` in
+`nonlocal_fs.cpp`), which is not a simple same-R closed trace. The force on
+this path reads
 
 ```
 F(iat0) = Σ_{iat1,iat2} <∂β_{iat1,R1}/∂τ_iat0 | D_{iat1,iat2}(R2−R1) | β_{iat2,R2}>
 ```
 
-逐项按 `(iat1,iat2,R2−R1)` 取用复数 DMR 块（nspin=4 时由
-`cal_DMR_full` 提供，不丢虚部）。该路径**不满足** §5 的同 R 闭合迹
-保护条件，其正确性依赖：
-1. `cal_DMR_full` 采用 `e^{-ikR}`（与 `folding_HR` 的 `e^{+ikR}` 互逆）；
-2. DMR 块在 `(iat1,iat2,R2−R1)` 上的取值与 β 投影的指标顺序一致；
-3. 数值上由 SOC 有限差分力测试锁定（见 `docs/dm_dmk_dmr_action_plan.md` §T4）。
-
-若未来引入半集存储优化（只存 `(iat1,iat2,R)` 不存 `(iat2,iat1,−R)`），
-§5 的保护论证与 `force_factor=1.0` 约定同时失效，须恢复 factor=2 并
-重跑 T2/T3/T8 守卫。
+Each term consumes the complex DMR block element-wise by
+`(iat1,iat2,R2−R1)` (for nspin=4 the block is provided by `cal_DMR_full`
+without dropping the imaginary part). This path **does not** satisfy the
+same-R closed-trace protection of Sec. 5; its correctness relies on:
+
+1. `cal_DMR_full` using `e^{-ikR}` (mutually inverse with `folding_HR`'s
+   `e^{+ikR}`);
+2. the DMR block taken at `(iat1,iat2,R2−R1)` matching the index order of
+   the β projection;
+3. numerically locked by the SOC finite-difference force integration test
+   (`tests/integrate/240_NO_KP_15_SO_FD`).
+
+If a half-set storage optimization is introduced in the future (storing only
+`(iat1,iat2,R)` without `(iat2,iat1,−R)`), the Sec. 5 protection argument
+and the `force_factor = 1.0` convention both break; the factor must be
+restored to 2 and the T2/T3/T8 guards re-run.

source/source_estate/module_dm/density_matrix.h

@@ -11,8 +11,7 @@ namespace elecstate
 {
 // ---------------------------------------------------------------------------
 // Density-matrix conventions (DMK/DMR), frozen by the DM/DMK/DMR chain.
-// See docs/dm_dmk_dmr_investigation.md and
-// docs/nao_lcao_force_stress_derivation.md for the full derivation.
+// See docs/nao_lcao_force_stress_derivation.md for the full derivation.
 //
 // 1. DMK(μ,ν;k) = Σ_n f_nk C*_{μn}(k) C_{νn}(k) = (C f C†)^T = D_std^T.
 //    μ = row (bra) orbital, ν = column (ket) orbital. Stored as the transpose

source/source_estate/module_dm/test/test_cal_dm_R.cpp

@@ -392,7 +392,7 @@ TEST_F(DMTest, cal_DMR_blas_complex)
 // folding_HR (e^{+ikR}). This is the test that locks the Fourier sign of the
 // inverse transform: with the k-phase flipped (density_matrix.cpp: -sinp ->
 // +sinp), D~(k) = DMK(-k) = DMK(k)† and the assertions below turn red.
-// See docs/dm_dmk_dmr_action_plan.md (T1).
+// See Sec. 3 of docs/nao_lcao_force_stress_derivation.md.
 TEST_F(DMTest, T1_fourier_round_trip)
 {
     // k-grid {0, 1/4, 1/2, 3/4} along x: contains non-Gamma k-points and k and
@@ -512,7 +512,7 @@ TEST_F(DMTest, T1_fourier_round_trip)
 // ((iat1,iat2,R) and (iat2,iat1,-R)), cal_DMR must satisfy
 //   D(iat2,iat1,-R) = D(iat1,iat2,R)^T   (real DMR, nspin<4)
 //   D(iat2,iat1,-R) = D(iat1,iat2,R)^\dagger (complex DMR, nspin=4)
-// See docs/dm_dmk_dmr_action_plan.md (T2).
+// See Sec. 5 of docs/nao_lcao_force_stress_derivation.md.
 TEST_F(DMTest, T2_dmr_hermiticity)
 {
     // two k-points, both non-Gamma, k and -k distinct
@@ -634,7 +634,8 @@ TEST_F(DMTest, T2_dmr_hermiticity)
 // T8: full-direction pairing storage guard. Every (iat1,iat2,R) block of the
 // DMR HContainer built by init_DMR must have a (iat2,iat1,-R) counterpart.
 // gint_rho and the force/stress paths rely on this pairing (closed-trace
-// protection, see docs/dm_dmk_dmr_action_plan.md T8). A future half-set
+// protection, see Sec. 5 of docs/nao_lcao_force_stress_derivation.md).
+// A future half-set
 // storage optimization will turn this test red.
 TEST_F(DMTest, T8_full_direction_pairing_guard)
 {

source/source_lcao/module_operator_lcao/test/test_dm_trace.cpp

@@ -24,8 +24,7 @@
  * This holds even when O(R) is NOT symmetric within the same R (the key case
  * for overlap/kinetic derivative operators): the protection comes from the
  * closed trace + per-k Hermiticity of O(k), not from same-R symmetry.
- * See docs/dm_dmk_dmr_action_plan.md (T3) and
- * docs/nao_lcao_force_stress_derivation.md Sec. 5.
+ * See Sec. 5 of docs/nao_lcao_force_stress_derivation.md.
  ************************************************/
 
 namespace