Skip to content

Fix: LCAO nspin=2/4 density-matrix chain (DMK -> DMR), the SOC nonlocal force/stress path, and the force/stress contraction tests - #7833

Open
dyzheng wants to merge 7 commits into
deepmodeling:developfrom
dyzheng:fix/dmk-dmr-fourier-sign
Open

Fix: LCAO nspin=2/4 density-matrix chain (DMK -> DMR), the SOC nonlocal force/stress path, and the force/stress contraction tests#7833
dyzheng wants to merge 7 commits into
deepmodeling:developfrom
dyzheng:fix/dmk-dmr-fourier-sign

Conversation

@dyzheng

@dyzheng dyzheng commented Aug 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Reminder

  • I have read AGENTS.md and docs/developers_guide/agent_governance.md.
  • I have linked an issue or explained why this PR does not need one.
  • I have added adequate unit tests and/or case tests, or explained why not.
  • I have listed the exact verification commands run and their results.
  • I have described user-visible behavior changes, including INPUT parameter changes.
  • I have explained core-module impact for ESolver, HSolver, ElecState, Hamilt, Operator, Psi, or other source/ changes.
  • I have requested any needed governance exception below.

Linked Issue

Fix #7834

Unit Tests and/or Case Tests for my changes

  • Commands run:
  • Result summary:
  • Checks not run, with reason:

What's changed?

  • Example: brief summary of the user-visible or developer-facing change.

Governance Notes

  • INPUT/docs changes:
  • Core module impact:
  • Exceptions requested:

dyzheng added 7 commits August 14, 2026 19:03
dyzheng
Fix DMK->DMR inverse Fourier sign to e^{-ikR} and freeze DM conventions
6cefa36 
- cal_DMR/cal_DMR_td/cal_DMR_full and LR dmr_complex: use e^{-ikR} as the
  inverse transform of folding_HR's e^{+ikR}, fixing the R pairing in the
  nspin=4 SOC nonlocal force
- density_matrix.h: document DMK transposed convention (DMK = (C f C+)^T),
  embedded k weights (no 1/Nk), and closed-trace protection conditions
- operator_fs_utils: replace stale 'factor of 2' comments; full R-set
  iteration uses factor 1.0
- output_mulliken: correct the M_y inline-comment algebra (code unchanged)
- add docs/nao_lcao_force_stress_derivation.md (Sec. 3 derivation referenced
  by density_matrix.cpp comments)
- unit tests: T1 Fourier round-trip (sign sentinel), T2 DMR Hermiticity,
  T3 closed-trace equivalence incl. non-symmetric-in-R operator,
  T8 full-direction pairing storage guard

Verification: ctest -R 'ESTATE_dm|LCAO_operator' passes (13/14; the
parallel_operator_tests.sh failure is a pre-existing build-dir artifact).
Sensitivity check: flipping -sinp back to +sinp turns T1 red.
Note: integrate-case reference results affected by the sign fix (e.g. SOC
nonlocal force) are NOT regenerated in this commit and will follow.
dyzheng
test: make Autotest.sh compare case-local extra checks
7c71ef2 
check_out broke out of the key loop at totaltimeref, so keys appended
after it (e.g. by a case-local check_extra.py) were never compared.
Change the break to a continue (totaltimeref is only skipped, never
compared) and run check_extra.py (when present) right after
catch_properties.sh, appending its stdout to result.out / result.ref.

No existing cases ship a check_extra.py, so this only enables the
hook for the new T4-T7 cases that follow.
dyzheng
test: add T4-T7 integration tests locking DMK->DMR conventions
1351d83 
- T4 240_NO_KP_15_SO_FD: SOC nonlocal force finite-difference (GaAs,
  nspin=4, multi-k). check_extra.py compares the analytic force with a
  central finite difference (delta=1e-3 Bohr, threshold 1e-4 eV/Bohr)
  and the acoustic sum rule. Measured max_dev ~5.8e-5 eV/Bohr.
- T4 260_NO_DJ_PK_PU_SO_4K: sign-sensitive Fe DFT+U case (4x1x1 grid
  with non-TRIM k points) with the reference regenerated for the
  e^{-ikR} fix (etot -6791.4650419973 eV). Flipping the sign back to
  +sinp shifts etot by 0.44 eV and the Fe1 force by ~4 eV/Ang, so the
  case turns red under the wrong sign.
- T5 18_NO_hyb_TDDFT: current physics checks via check_extra.py
  (zero-field current ~5e-17, full-k vs per-k DMR path deviation
  ~3e-18, +/-k cancellation 0).
- T6 260_NO_DJ_PK_PU_SO_4K_MUL: nspin=4 multi-k Mulliken calibration.
  Cross-checks Mulliken charge/magnetization against the rho cell
  magnetization (max |dev| 0.044 uB < 0.1 uB). No anomalous m_y
  deviation is present, so the B-class gemm (S^T -> S^dagger) is not
  applied.
- T7 260_NO_DJ_PK_PU_AFM_URAMPING_MUL: nspin=2 AFM spin-channel
  checks (opposite-sign Fe moments +1.92/-3.73 uB, spin1+spin2 equals
  total charge 44, small O moments, Mulliken sum vs rho cell
  magnetization).

All cases converge (SCF CONVERGED; guarded by *_converged_pass keys).
Verified with OMP_NUM_THREADS=1, mpirun -np 1: full CASES_CPU.txt run
passes 27/27 keys and T5 passes 6/6.
dyzheng
docs: translate DMR pairing derivation to English
6891da7 
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.
dyzheng
Merge remote-tracking branch 'origin/develop' into fix/dmk-dmr-fourie…
4a0cf9c 
…r-sign

Conflict resolutions (build fixes required by the merged tree):
- module_operator_lcao/test/CMakeLists.txt: ORB_atomic_lm.cpp ->
  orb_atomic_lm.cpp, matching develop's filename normalization (deepmodeling#7797)
  in the dm_trace test target sources.
- module_lr/utils/exciton_plotter.cpp: add missing 'template' keyword
  for the dependent-template call eval_wfc_bloch<T> (upstream BSE
  module, deepmodeling#7718) that fails to compile with the standard C++11 rule.
dyzheng
docs: drop redundant LCAO force/stress derivation document
51e36d3 
Remove docs/nao_lcao_force_stress_derivation.md and the code-comment
references that pointed at it. The conventions it documented (DMK =
(C f C†)^T storage, e^{-ikR} inverse Fourier sign, closed-trace
protection for force/stress) are already stated inline in
density_matrix.h/.cpp and the T1/T2/T3/T8 unit tests.
dyzheng
test: drop dangling references to the out-of-repo DM/DMK/DMR planning…
4c7a89d 
… doc

The check_extra.py scripts of the T4-T7 integration cases referenced
docs/dm_dmk_dmr_action_plan.md, which is intentionally kept out of the
repository. Replace those pointers with self-contained text; no behavior
change (verified with python3 -m py_compile).
@dyzheng dyzheng changed the title Fix: dmk and dmr fourier sign Fix: LCAO nspin=2/4 density-matrix chain (DMK -> DMR), the SOC nonlocal force/stress path, and the force/stress contraction tests Aug 18, 2026
@mohanchen mohanchen added the Refactor Refactor ABACUS codes label Aug 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

Refactor Refactor ABACUS codes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

DMK->DMR inverse Fourier sign (e^{-ikR}) and frozen density-matrix conventions for LCAO force/stress

2 participants

@dyzheng @mohanchen