Skip to content

Write DFT+U occupation eigenvalues to occ_mat.txt - #8289

Merged
mohanchen merged 8 commits into
deepmodeling:developfrom
lanshuyue:codex/occ-mat-eigenvalues
Nov 13, 2026
Merged

mohanchen merged 8 commits into
deepmodeling:developfrom
lanshuyue:codex/occ-mat-eigenvalues

Conversation

@lanshuyue

@lanshuyue lanshuyue commented Nov 4, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Append sorted DFT+U occupation-matrix eigenvalues to the latest occ_mat.txt when out_occ_mat is enabled. Eigenvalue lines are comments, so restart input remains readable; numbered occ_matg*.txt files do not gain eigenvalue lines.
  • Use the same Jacobi stopping threshold as the rotation guard, including the exact 1e-10 boundary.
  • Decode LCAO dft_plus_u=1 SOC occupation data as four Pauli blocks in both output and restart input. Keep dft_plus_u=2 in its real spin-basis layout.
  • Preserve the full up-down orbital block for the real spin-basis layout. The reader reconstructs the lower block by transposition, so cross-orbital coupling survives an output/restart roundtrip.
  • Emit only the maintained channel's eigenvalues for nspin=1, labeled nonmagnetic; a stale second channel can no longer appear as a false spin 2 spectrum.
  • Document the eigenvalue comments in the out_occ_mat INPUT help text.

SOC occupation-matrix layout correction (nspin=4)

This PR also corrects how the shared output/restart code interprets LCAO occupation data. The underlying DFT+U occupation calculation and Hamiltonian are unchanged.

Path Existing in-memory representation Interpretation used by output/restart
PW Four (2l+1) × (2l+1) Pauli blocks [N0, Nx, Ny, Nz] Pauli
LCAO dft_plus_u=1 Four (2l+1) × (2l+1) Pauli blocks Changed from the previous blanket LCAO spin-basis interpretation to Pauli
LCAO dft_plus_u=2 One real 2(2l+1) × 2(2l+1) spin-basis matrix Spin basis; preserve the full upper-right orbital block

LCAO method 1 already computes four Pauli components (spin_fold=4); the old output/restart caller passed the spin-basis layout for both LCAO methods. The layout is now selected by dft_plus_u. For a Pauli input, the writer reconstructs N↑↑=(N0+Nz)/2, N↓↓=(N0−Nz)/2, and N↑↓=(Nx+iNy)/2 before writing the four compact spin blocks and diagonalizing the full Hermitian spinor matrix. For method 2, retaining the complete upper-right orbital block prevents loss of cross-orbital coupling. Both layouts continue to produce the same compact occ_mat.txt format.

Nonmagnetic normalization (nspin=1)

The eigenvalues are those of the stored occupation matrix, without an output-only rescaling. PW nspin=1 k-point weights include spin degeneracy (a unit projector with weight 2 yields an eigenvalue of 2), whereas LCAO dft_plus_u=1 halves its DMR contribution before storing the matrix. The output prints one nonmagnetic spectrum from channel 0 for both paths. This PR leaves the underlying occupation and DFT+U energy conventions unchanged.

Example:

# eigenvalues atom 1 L 2 spin 1: 0.70000000 0.80000000 0.80000000 0.80000000 0.90000000
# eigenvalues atom 1 L 2 spin 2: 0.20000000 0.20000000 0.20000000 0.20000000 0.20000000

Verification

  • cmake --build build --target MODULE_PW_dftu_base_test esolver hamilt_lcao -j4 — passed for the earlier SOC correction; cmake --build build --target MODULE_PW_dftu_base_test abacus_input_yaml -j4 — passed for the latest change.
  • OMP_NUM_THREADS=1 ./build/source/source_pw/module_pwdft/unittests/MODULE_PW_dftu_base_test --gtest_brief=1 — 33/33 passed in the normal MPI runtime environment, including the new single-channel and PW spin-summed-weight regressions.
  • ./build/source/source_io/abacus_input_yaml > /tmp/abacus-pr-8289-parameters.yaml — passed; the generated out_occ_mat help includes the new behavior.
  • git diff --cached --check — passed before the latest commit.
  • python3 tools/03_code_analysis/agent_governance_check.py --staged — passed with a documentation-sync advisory; parameter help is the source for generated docs, so no generated YAML/Markdown is committed.

Documentation

Updated the out_occ_mat INPUT help metadata. No new INPUT parameter or parsing behavior.

@mohanchen mohanchen added DFT+U Issues related to DFT plus U function Refactor Refactor ABACUS codes labels Nov 5, 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 new eigenvalue output has three correctness issues: a nonterminating collinear boundary case and incorrect spectra in both LCAO SOC representations. One non-blocking test-style item is also noted. Static source and analytic review of d1fba2e0; no builds or tests were run.

@lanshuyue
lanshuyue marked this pull request as ready for review November 11, 2026 10:58

@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 added eigenvalue output reports an unused spin spectrum for nonmagnetic LCAO calculations. The Jacobi cutoff and both SOC corrections are fixed in the inspected source.

Static review of 9035800ca; no builds, tests or CI verification. PW nspin=1 eigenvalue normalization remains unverified.

Non-blocking: Please mention the sorted eigenvalue comments in the out_occ_mat help text, including that they appear only in the latest occ_mat.txt.

Copy link
Copy Markdown
Collaborator Author

Follow-up to the latest review (e4df384): the out_occ_mat help now documents sorted eigenvalue comment lines in the latest occ_mat.txt only. I also checked the PW nspin=1 normalization: k-point weights are scaled by two for spin degeneracy, and accumulate_occ_scalar stores the weighted projection directly. The new NonmagneticPwEigenvaluesKeepSpinSummedWeight regression confirms that a unit projector with weight 2 yields a stored occupation eigenvalue of 2. LCAO dft_plus_u=1 halves its DMR contribution before storage. The output reports the eigenvalues of the stored matrix without rescaling either path; the PR description now states this convention. Builds and all 34 DFT+U tests pass.

@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. Congratulations for another PR!

@mohanchen
mohanchen merged commit 173620a into deepmodeling:develop Nov 13, 2026
19 of 20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

DFT+U Issues related to DFT plus U function Refactor Refactor ABACUS codes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants