Skip to content

Fix: correct My sign in noncollinear Mulliken magnetism - #8250

Merged
mohanchen merged 3 commits into
deepmodeling:developfrom
hujieting:fix-mulliken-my-sign
Nov 3, 2026
Merged

mohanchen merged 3 commits into
deepmodeling:developfrom
hujieting:fix-mulliken-my-sign

Conversation

@hujieting

@hujieting hujieting commented Oct 30, 2026 •

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.

Summary

Fix the incorrect sign of the y-component of Mulliken magnetization (My) for noncollinear calculations (nspin=4).

The previous implementation used a sign convention inconsistent with the conjugate-first density matrix representation and Pauli-matrix decomposition in ABACUS.

The corrected expression is:
My = Im(mud_ud - mud_du)
Previously:
My_old = -Im(mud_ud) + Im(mud_du)

Changes

  • Correct the Mulliken My sign for nspin=4.
  • Extract the accumulation logic into collect_MW_nspin4().
  • Add a unit test covering positive and negative y-direction magnetization and general noncollinear spin directions.
  • Keep Mx, Mz, and the nspin=1/2 paths unchanged.
  • No INPUT parameter changes.

Verification

Unit Tests

The Mulliken unit tests passed, including the new regression test OutputMullikenSpinTest.Nspin4MyFollowsPauliConvention.

Verification command:

ctest --test-dir build-test -R MODULE_IO_mulliken_test --output-on-failure
Result: 1/1 CTest target passed.

Integration Tests

Two independent ABACUS versions were compiled and compared:

  • Before fix: 0223bfeb0
  • After fix: e2a8728f0
  • Runtime: 4 MPI ranks, OMP_NUM_THREADS=1

The converged noncollinear Fe example (examples/04_noncollinear/01_Fe_noncollinear) was tested with initial magnetization along +y and out_mul 1.
SCF converged in 11 iterations with final DRHO = 8.2125e-06.

Quantity Before Fix After Fix
Fe1 My (uB) -3.620321 +3.620321
Fe2 My (uB) -3.620321 +3.620321
Total energy (eV) -6818.010393 -6818.010393
The corrected My agrees with the prescribed magnetization direction. Mx, Mz, atomic charges, and total energy remain unchanged.

Result: PASS
The existing tests/17_DS_DFTU/02_LCAO_SPIN_S4_XYZ case was also tested. It confirmed the exact My sign reversal with unchanged other quantities, but did not reach SCF convergence due to its existing numerical stability issue.

Conclusion

The Mulliken My sign correction is verified by unit tests and a converged noncollinear Fe integration calculation. The fix affects only the reported My component and does not alter the SCF calculation.
No automated integration regression case was added.

Correct the nspin=4 Mulliken My sign for the conj-first density matrix convention.

Add a regression test covering nonzero My for several noncollinear spin directions.

Keep the nspin=1/2 paths unchanged.
@hujieting hujieting added the Bugs Bugs that only solvable with sufficient knowledge of DFT label Oct 30, 2026
@mohanchen mohanchen added the Refactor Refactor ABACUS codes label Oct 30, 2026

@ABACUS-PR-BOT ABACUS-PR-BOT left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The My sign now matches the conj-first density matrix and the production overlap contraction. No new implementation defect found. Static review only; no build or runtime tests were run.

Non-blocking: Please record the exact configure/build and test commands, including the command or sign-revert procedure used to check the old-sign failure.

@mohanchen mohanchen left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@mohanchen mohanchen added the Collinear/non-collinear/SOC/delta-spin Issues related to SOC label Nov 3, 2026
@mohanchen
mohanchen merged commit f531565 into deepmodeling:develop Nov 3, 2026
19 checks passed
mohanchen pushed a commit that referenced this pull request Nov 4, 2026
* C1: add para_2d() accessor and get_blacs_ctxt() to Parallel_Orbitals

Purely additive: no call site changes, inheritance still in place.
para_2d() (const + non-const) returns *this while Parallel_Orbitals derives
from Parallel_2D, giving the two escape hatches a const getter cannot serve
(LR_Util::setup_2d_division mutation, test-side descriptor writes).
get_blacs_ctxt() completes the inherited getter family, which covers the
other seven public data members.

* D2(module_rt): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_rt call sites

* D2(module_dftu): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_dftu call sites

* D2(module_dm): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_dm call sites

* D2(pyabacus): drop Parallel_2D inheritance in Parallel_Orbitals, migrate pyabacus call sites

* D2(module_lr): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_lr call sites

* D2(misc_prod): drop Parallel_2D inheritance in Parallel_Orbitals, migrate misc_prod call sites

* D2(module_operator_lcao): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_operator_lcao call sites

* D2(test_side): drop Parallel_2D inheritance in Parallel_Orbitals, migrate test_side call sites

* D2(module_current): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_current call sites

* D2(module_ao): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_ao call sites

* style: remove trailing whitespace in LCAO layout migration

* test: use explicit serial block-cyclic layout

* refactor: use explicit layout in serial paths

* refactor: migrate optional backends to explicit layout

* fix(io): drive the Mulliken test through the explicit distribution accessor

The noncollinear Mulliken test added by #8250 sets up a serial layout on a
Parallel_Orbitals and sizes its ComplexMatrix from the distribution's row and
column counts. `set_serial`, `nrow` and `ncol` belong to Parallel_2D, which
Parallel_Orbitals no longer inherits, so route both uses through para_2d().
Without this the test target does not compile on top of current develop.

* docs(ao): state concrete removal triggers for the transitional accessors

Replace the PR#TBD placeholders with the actual condition for deleting para_2d()
and the implicit `operator const Parallel_2D&`, and record that the eventual
accessor name carries no get_ prefix, which is the convention this repository
follows. Comment text only.

* fix(ao): migrate remaining distribution consumers

Route optional LCAO backends through the explicit Parallel_Orbitals distribution. This covers CUDA, DeePKS, LibRI/EXX, BSE, RDMFT, RPA, cuBLASMp, and the PEXSI test fixture without changing the composition seam.

* fix(deepks): initialize serial distribution explicitly

* fix(bse): preserve 64-bit local size
mohanchen pushed a commit that referenced this pull request Nov 5, 2026
* C1: add para_2d() accessor and get_blacs_ctxt() to Parallel_Orbitals

Purely additive: no call site changes, inheritance still in place.
para_2d() (const + non-const) returns *this while Parallel_Orbitals derives
from Parallel_2D, giving the two escape hatches a const getter cannot serve
(LR_Util::setup_2d_division mutation, test-side descriptor writes).
get_blacs_ctxt() completes the inherited getter family, which covers the
other seven public data members.

* D2(module_rt): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_rt call sites

* D2(module_dftu): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_dftu call sites

* D2(module_dm): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_dm call sites

* D2(pyabacus): drop Parallel_2D inheritance in Parallel_Orbitals, migrate pyabacus call sites

* D2(module_lr): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_lr call sites

* D2(misc_prod): drop Parallel_2D inheritance in Parallel_Orbitals, migrate misc_prod call sites

* D2(module_operator_lcao): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_operator_lcao call sites

* D2(test_side): drop Parallel_2D inheritance in Parallel_Orbitals, migrate test_side call sites

* D2(module_current): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_current call sites

* D2(module_ao): drop Parallel_2D inheritance in Parallel_Orbitals, migrate module_ao call sites

* D4(module_lr): pass Parallel_Orbitals as explicit para_2d() at upcast call sites

* D4(module_hs): pass Parallel_Orbitals as explicit para_2d() at upcast call sites

* D4(module_io): pass Parallel_Orbitals as explicit para_2d() at upcast call sites

* D4(module_dftu): pass Parallel_Orbitals as explicit para_2d() at upcast call sites

* D4(module_ao): remove Parallel_Orbitals implicit upcast operator

* D5(test_side): stop writing descriptor/distribution fields directly in tests

* D5(test_side): rewrite link-mock TUs to link the real implementation

* D5(test_side): migrate parallel_orbitals_test serial branch to explicit para_2d() access

* D5(test_side): keep original is_serial member name, expose read-only is_serial() accessor

* D5(test_side): drop is_serial() accessor, restore direct member access (zero production delta vs D4)

* D6(module_ao): add composition regression guard for Parallel_Orbitals (getter-equiv, derived-layer sync, value-semantics static_assert, MPI+serial dual coverage)

* style: remove trailing whitespace in LCAO layout migration

* test: use explicit serial block-cyclic layout

* refactor: use explicit layout in serial paths

* refactor: migrate optional backends to explicit layout

* test(module_ao): tighten composition regression guard

* fix(io): drive the Mulliken test through the explicit distribution accessor

The noncollinear Mulliken test added by #8250 sets up a serial layout on a
Parallel_Orbitals and sizes its ComplexMatrix from the distribution's row and
column counts. `set_serial`, `nrow` and `ncol` belong to Parallel_2D, which
Parallel_Orbitals no longer inherits, so route both uses through para_2d().
Without this the test target does not compile on top of current develop.

* docs(ao): state concrete removal triggers for the transitional accessors

Replace the PR#TBD placeholders with the actual condition for deleting para_2d()
and the implicit `operator const Parallel_2D&`, and record that the eventual
accessor name carries no get_ prefix, which is the convention this repository
follows. Comment text only.

* test(module_ao): fold the composition guard into the parallel_orbitals test

Repository rule 11 requires one test TU per exercised source file: the new
test_parallel_orbitals_composition.cpp did not match any source file, while
parallel_orbitals_test.cpp already exercises ../parallel_orbitals.cpp. Move
its four guard cases, the two fixture helpers, and the compile-time
static_asserts into the existing file, and delete the extra source, its
MODULE_AO_parallel_orbitals_composition_test target plus _para MPI
registration, and its runner script.

No assertion was changed, weakened, or dropped: every static_assert and every
EXPECT_/ASSERT_ line from the deleted file appears verbatim in the merged
file (verified with a line-by-line set difference). The merged binary still
runs 5 gtest cases (TestParaO.Divide2D + the 4 composition cases) and passes
both the serial and the mpirun 2/3/4-rank ctest registrations.

* fix(ao): migrate remaining distribution consumers

Route optional LCAO backends through the explicit Parallel_Orbitals distribution. This covers CUDA, DeePKS, LibRI/EXX, BSE, RDMFT, RPA, cuBLASMp, and the PEXSI test fixture without changing the composition seam.

* fix(deepks): initialize serial distribution explicitly

* fix(exx): pass block-cyclic distributions explicitly

---------

Co-authored-by: D5 <d5@example.com>
Co-authored-by: marvis <marvis@local>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Bugs Bugs that only solvable with sufficient knowledge of DFT Collinear/non-collinear/SOC/delta-spin Issues related to SOC Refactor Refactor ABACUS codes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants