Fix: split LibXC GGA threshold masks for vrho and vsigma following QE convention

[Flying-dragon-boxing]

Linked Issue

Fix #7996

What's Changed

In XC_Functional_Libxc::v_xc_libxc (source/source_hamilt/module_xc/libxc_pot.cpp), xc_func_set_dens_threshold(&func, 1E-6) made LibXC zero all outputs — exc, vrho and vsigma — below rho = 1E-6. QE's LibXC interface (XClib/xc_wrapper_gga.f90) instead sets dens_threshold = small (1E-10) and applies two-tier masks: exc/vrho are kept down to 1E-10, while only vsigma is suppressed below rho = 1E-6 or sqrt(|sigma|) = 1E-10. ABACUS-LibXC was the only one of the four PBE code paths (QE built-in / QE LibXC / ABACUS built-in / ABACUS LibXC) that truncated vrho at 1E-6, shifting diffuse unoccupied states of finite systems up by ~0.1 eV (see the issue for the full analysis).

This PR mirrors QE's two-tier mask convention, exactly as proposed in the issue:

1. xc_func_set_dens_threshold(&func, 1E-10) instead of 1E-6;
2. new helper XC_Functional_Libxc::cal_sgn_vxc (libxc_tools.cpp) returns two masks: sgn_vrho zeroes exc/vrho only where rho <= 1E-10 (for nspin=2 both channels are masked jointly when either spin density fails, matching QE), and sgn_vsigma zeroes only vsigma where rho <= 1E-6 or sqrt(|sigma|) <= 1E-10;
3. convert_vtxc_v and cal_dh now take the two masks separately: sgn_vrho multiplies the vrho contribution, sgn_vsigma multiplies the gradient (vsigma) contribution.

Scope / side effects

• All LibXC GGA calculations on systems with low-density regions (molecules, slabs) will change slightly — this is the intended behavior change. Periodic solids are unaffected (interstitial density stays above 1E-6).
• The same threshold pattern exists, with lower impact, in v_xc_meta (mGGA), in gcxc_libxc/gcxc_spin_libxc (stress path), and in the other cal_sgn callers (write_libxc_r.cpp, module_lr/potentials/xc_kernel.cpp). These are left unchanged here and can be addressed separately, as noted in the issue.
• No INPUT parameter or user-facing interface changes, so no update to docs/parameters.yaml or docs/advanced/input_files/input-main.md is required.

Tests

• New unit-test file source/source_hamilt/module_xc/test/test_libxc_tools.cpp (target MODULE_HAMILT_XCTest_LIBXC_TOOLS) covers cal_sgn_vxc: the two-tier density thresholds for nspin=1 GGA, the sqrt(|sigma|) trigger, the LDA case (vsigma mask stays 1), joint spin-channel masking for nspin=2, and that the up-down cross component of sigma does not trigger the vsigma mask.

Verification

Executable: ./build/rel/abacus_std_para --version -> ABACUS version v3.11.0-beta10 (GCC, RelWithDebInfo, ENABLE_LIBXC=ON, ENABLE_MLALGO=OFF).

• Unit tests, OMP_NUM_THREADS=1 ctest --test-dir build/rel -R MODULE_HAMILT_XCTest --output-on-failure: 9/9 passed, including the new MODULE_HAMILT_XCTest_LIBXC_TOOLS and the existing MODULE_HAMILT_XCTest_VXC (which exercises v_xc_libxc end-to-end).
• Integration tests using explicit LibXC GGA functionals, OMP_NUM_THREADS=1, 2 MPI ranks, tests/integrate/Autotest.sh -r <regex>:
  • tests/01_PW: 14 matched cases, 0 failed — including 202_PW_ONCV_Libxc and 204_PW_SY.
  • tests/07_OFDFT: 10 matched cases, including 22_OF_LibxcPBE and 26_OF_MD_LibxcPBE passed; no reference updates were needed anywhere.
• Two matched cases could not be fully exercised locally because this build has ENABLE_MLALGO=OFF (CI builds with -DENABLE_MLALGO=ON, .github/workflows/test.yml):
  • 104_PW_Gene_Descriptors: the SCF part converged and reproduces the reference etot to 1.7E-9 eV (threshold 1E-7 eV); only the MLKEDF descriptor .npy outputs are not generated without MLALGO.
  • 06_OF_KE_MPN: aborts at input check with "ML KEDF requires ENABLE_MLALGO option" before any calculation. The system is periodic fcc Al (no low-density region), so this PR cannot change its result; CI coverage is needed.
• The H2-molecule and tail-density verification of the fix itself (unoccupied-state shift reduced from 0.06-0.12 eV to <= 0.018 eV; potential artifact reduced from 0.041 Ry to ~0.01 Ry) is documented with the standalone checks in issue LibXC GGA potential is zeroed below rho=1E-6 (including the vrho term), shifting unoccupied states of finite systems - follow-up of #4695 / #4863 #7996.
• Governance check python3 tools/03_code_analysis/agent_governance_check.py --base upstream/develop --head HEAD --format text: only the documentation-sync warning remains, addressed by the no-docs-needed statement above.
• Code quality python3 tools/03_code_analysis/code_quality_score.py on the changed files: libxc_pot.cpp scores 32, up from 31 for the unmodified upstream/develop version — the sub-60 score is pre-existing historical debt (file length, v_xc_meta complexity), not introduced by this PR; the other changed files score 68/71/95.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The change affects low-density LibXC behavior across multiple calculation paths and warrants final human review.

Review effort: Lite
Findings: None

What changed in this PR

This PR aligns LibXC GGA low-density masking with QE’s two-tier convention, preserving vrho while selectively suppressing unstable vsigma terms.

Changes:

• Added separate vrho and vsigma masks.
• Updated LibXC potential calculations and thresholds.
• Added focused unit tests and CMake registration.

File	Summary
source/​source_hamilt/​module_xc/​test/​test_libxc_tools.cpp	Tests density, gradient, LDA, and spin masking.
source/​source_hamilt/​module_xc/​test/​CMakeLists.txt	Registers the new test target.
source/​source_hamilt/​module_xc/​libxc_tools.cpp	Implements split threshold masks.
source/​source_hamilt/​module_xc/​libxc_pot.cpp	Applies the masks during LibXC evaluation.
source/​source_hamilt/​module_xc/​libxc_abacus.h	Declares updated interfaces.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Flying-dragon-boxing]

End-to-end verification against issue #4695 (the H2O case whose unoccupied-state mismatch motivated #7996): with this PR, all five bands agree with QE-LibXC to within 0.0002 eV (the unoccupied state moves from 0.051 eV above QE to -0.9224 eV vs QE's -0.9226 eV). Detailed comparison table: #4695 (comment)