Skip to content

Fix: Correct LCAO real-space wavefunctions and partial-charge handling - #7868

Merged
mohanchen merged 11 commits into
deepmodeling:developfrom
AsTonyshment:fix/pchg_wfc_lcao
Aug 28, 2026
Merged

Fix: Correct LCAO real-space wavefunctions and partial-charge handling#7868
mohanchen merged 11 commits into
deepmodeling:developfrom
AsTonyshment:fix/pchg_wfc_lcao

Conversation

@AsTonyshment

Copy link
Copy Markdown
Collaborator

Summary

This PR corrects the physical meaning and data flow of real-space wavefunction output and fixes the LCAO partial-charge path.

Real-space wavefunction .cube files now represent the complete, normalized single-particle Bloch state

$$\psi_{n\boldsymbol{k}}(\boldsymbol{r})=\mathrm{e}^{+\mathrm{i}\boldsymbol{k}\cdot\boldsymbol{r}}u_{n\boldsymbol{k}}(\boldsymbol{r}),\qquad \int_{\Omega}|\psi_{n\boldsymbol{k}}(\boldsymbol{r})|^2 \mathrm{d}\boldsymbol{r}=1.$$

For nspin=1, the factor of two belongs only to the partial charge, $\rho_{n\boldsymbol{k}}=2|\psi_{n\boldsymbol{k}}|^2$, and no longer rescales the wavefunction itself.

  • PW real/imaginary output previously wrote only the periodic part and applied a spin-degeneracy factor. It now includes the full Bloch position phase and uses single-particle normalization.
  • LCAO wavefunction output previously discarded the multi-k imaginary part, mixed collinear spin channels, misread the spinor layout, depended on another output selector, and truncated NAO components through an unnecessary PW FFT round trip. It now evaluates one complete complex Gint field directly, uses the correct AO-image Bloch phase, and derives the modulus and spinor components from that field. For nspin=4, the norm is $\sqrt{|\psi_{\uparrow}|^2+|\psi_{\downarrow}|^2}$ and s1/s2 contain the upper/lower spinor components.
  • LCAO partial charge previously reused SCF occupations or a HOMO occupation as state weights, which broke unoccupied, partially occupied, spin-asymmetric, and separate-k output. It now builds explicit state weights and delegates DMK construction to cal_dm_psi: Gamma and separate-k states use the appropriate spin degeneracy, while k-summed states use kv.wk. This also removes the MPI-only implementation.
  • Partial-charge and wavefunction output now use private buffers instead of overwriting Charge::rho, rho_save, or rhog. For nspin=4, the scalar charge is symmetrized separately and the three magnetization components are rotated together through the SOC symmetry path.
  • The change also fixes the local-AO band-stride out-of-bounds write, initializes unused Gamma wavefunction workspace after file input, removes unrelated Fermi metadata from state .cube files, and makes .cube file naming and precision consistent.
  • LCAO no longer accepts out_wfc_pw: the old path was a lossy LCAO-to-PW projection whose content depended on unrelated .cube output selectors. Nonzero values are rejected for non-PW bases; native PW coefficient output is unchanged. The INPUT metadata and wavefunction initialization documentation were updated and regenerated accordingly.

Scope

The shared LCAO DMK/DMR/Fourier/Pauli convention is unchanged. Partial-charge output now reuses the existing common density-matrix path and deliberately adds no output-layer phase or $m_y$ sign compensation.

Related work in #7832 changes the noncollinear Pauli-component convention, particularly the sign of $m_y$, while #7833 changes the DMK-to-DMR Fourier convention. These definitions can affect the eventual nspin=4 LCAO partial-charge semantics. This PR neither duplicates nor compensates for those proposed changes; by routing state DMK construction and real-space density evaluation through the common path, it keeps partial-charge output aligned with whichever shared convention is merged.

@AsTonyshment
AsTonyshment requested a review from mohanchen August 27, 2026 14:05
@mohanchen mohanchen added Input&Output Suitable for coders without knowing too many DFT details Refactor Refactor ABACUS codes labels Aug 28, 2026
@mohanchen
mohanchen merged commit 74dcbdf into deepmodeling:develop Aug 28, 2026
17 checks passed
@AsTonyshment
AsTonyshment deleted the fix/pchg_wfc_lcao branch August 28, 2026 00:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Input&Output Suitable for coders without knowing too many DFT details Refactor Refactor ABACUS codes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants