Skip to content

feat(xc): add libvdwxc-backed rVV10 nonlocal XC - #8140

Open
CleverPhysician wants to merge 55 commits into
deepmodeling:developfrom
CleverPhysician:rvv10-latest-clean
Open

CleverPhysician wants to merge 55 commits into
deepmodeling:developfrom
CleverPhysician:rvv10-latest-clean

Conversation

@CleverPhysician

@CleverPhysician CleverPhysician commented Oct 13, 2026 •

Copy link
Copy Markdown

Linked Issue

No separate issue; this continues the rVV10 work discussed in #8031.

Unit Tests and/or Case Tests for my changes

  • Commands run (OpenMPI 4.1, GCC 11.5, Libxc 6.2.2, FFTW 3.3.10, ScaLAPACK, OpenMP off and on):
    • ctest -R 'XCTest|surchem|parallel_device|MODULE_HAMILT_vdw|MODULE_HAMILT_test_vdw|read_input_serial|test_read_inp_model|nonlocal_xc': 28/28 with ENABLE_LIBVDWXC=ON, 24/24 with OFF and OpenMP (the hosted-CI configuration, where vdw_method rvv10 stops with a rebuild hint).
    • abacus --version (v3.11.0-beta12), abacus -h vdw_method|vdw_rvv10_b|vdw_rvv10_c show the choices, legal ranges, defaults and availability; abacus --check-input accepts the rVV10 integration cases and rejects vdw_rvv10_b -1 with the manual link.
    • Autotest.sh -n 4 -f CASES_LIBVDWXC.txt in tests/01_PW and tests/03_NAO_multik: pass.
    • -DENABLE_LIBXC=OFF -DENABLE_LIBVDWXC=ON: the selected tests pass 6/6, and 215_PW_rvv10_GaAs (native PBE) passes.
    • Comparison with Quantum ESPRESSO 7.2 (graphite, MoS2, S22 with forces, stress, finite-difference stress in PW and LCAO): see the benchmark comment.
    • libvdwxc MR !32 at da2d55f and branch fft-new at 4b18416b give the same results.
  • Result summary: energies agree with QE to 0.034 meV/atom, S22 to 0.021 kcal/mol, forces to 0.0014 eV/Å, stress to 0.14 kbar; the rVV10 stress matches finite differences to 0.04 kbar; counterpoise-corrected LCAO agrees with PW to 0.53 meV/atom (TZDP) and 1.91 meV/atom (DZP). Results do not depend on the number of ranks or threads beyond rounding.
  • Checks not run: hosted CI has no libvdwxc (a CI step that builds it is available on request); GPU, ELPA, USPP, rt-TDDFT and DeePKS with rVV10.

What's changed?

  • vdw_method rvv10 adds the rVV10 nonlocal correlation (Vydrov and Van Voorhis 2010; Sabatini et al. 2013) to the functional of dft_functional, evaluated by libvdwxc MR !32. vdw_rvv10_c defaults to 0.0093; vdw_rvv10_b follows dft_functional unless set (15.7 SCAN, 11.95 r2SCAN, else 6.3 with a warning unless rPW86-PBE). The energy is counted in E_xc; evdw stays 0.
  • vdw::add_rvv10 (source_hamilt/module_vdw/nonlocal_xc.{h,cpp}) is called at the end of every XC evaluator, so forces, NLCC terms and all consumers of v_xc see the term; v_xc_libxc and v_xc_meta pass on their density gradient (four FFTs saved per call). vdw::add_rvv10_stress in Stress_Func::stress_gga covers PW, LCAO, SDFT and OFDFT.
  • Rvv10Workspace (rvv10_workspace.{h,cpp}) keeps the libvdwxc object, FFT plans, slab bounds and buffers per grid and pool, created on first use and released in ESolver_FP::after_all_runners. The density is redistributed between ABACUS z planes and libvdwxc slabs with Parallel_Common::alltoallv_data; the slabs are taken from vdwxc_get_local_grid when libvdwxc has it (checked by CMake), otherwise the FFTW-MPI default blocks are assumed. Element-wise loops are OpenMP-parallel.
  • Build option ENABLE_LIBVDWXC (find_package(libvdwxc CONFIG); independent of ENABLE_LIBXC, which is needed only for Libxc functionals such as rPW86 or SCAN); an MPI build requires libvdwxc with MPI and FFTW3 (not the MKL/KML interface). Compile definition and build info follow DFT-D4.
  • The rVV10 unit tests are in unittests/ directories: MODULE_HAMILT_nonlocal_xcTest (module_vdw/unittests/test_nonlocal_xc.cpp for the adapter, test_rvv10_workspace.cpp for the workspace, shared fixture in the header nonlocal_xc_test_helpers.h) on 1, 2, 4 ranks and 2 ranks × 2 threads (adapter vs direct libvdwxc, distributed vs complete grid incl. an empty process, potential and stress vs finite differences, nspin 1/2/4, every v_xc path, rebuild after finalize_rvv10); test_vdw.cpp for make_vdw, source_io/unittests/test_read_inp_model.cpp for valid INPUT reads, declared domains and requirements, and b pairing, source_base/unittests/test_parallel_device.cpp for the two new collectives; the legacy test files are unchanged; the integration groups are gated by both ENABLE_LIBVDWXC and ENABLE_LIBXC because they include rPW86-PBE cases. The native-PBE GaAs case can also be run separately without Libxc.

Governance Notes

  • INPUT/docs: vdw_method gains rvv10 (rejects esolver_type dfpt and LR-TDDFT forces); new vdw_rvv10_b (Real > 0) and vdw_rvv10_c (Real ≥ 0). Docs: docs/advanced/install.md, docs/advanced/scf/advanced.md, docs/quick_start/easy_install.md, docs/CITATIONS.md.
  • Core module impact: ESolver_FP copies the three rVV10 fields into XCFunctionalParameters (via vdw::is_rvv10) and releases the workspace at the end; Hamilt/XC has one hook per XC evaluator and one in stress_gga; they call nonlocal_xc.h without preprocessor branches, because its functions are empty inline functions without libvdwxc, so __LIBVDWXC appears only in module_vdw and CMake, as for DFT-D4; source_base gains Parallel_Common::alltoallv_data and allgather_data. The governance check passes with 17 header-dependency warnings and no blockers: <vector> in nonlocal_xc.h, <mpi.h> and <vector> in rvv10_workspace.h, and the includes of the header-only test fixture nonlocal_xc_test_helpers.h. code_quality_score.py: adapter sources 97–100, test sources 93–95 and the shared fixture header 88.
  • Placement, for the maintainers: the adapter sits in module_vdw next to the other vdW methods but is compiled into xc_, its only caller. I can move it to module_xc if preferred.

Governance Exception

  • Rule: new compile definitions (AGENTS rule 20).
  • Reason: __LIBVDWXC, ABACUS_LIBVDWXC_VERSION and __LIBVDWXC_LOCAL_GRID (private to xc_) switch an optional library and one of its functions, as DFT-D4 does (CMake: Move __DFTD4 to global feature definitions #7793).
  • Scope: the feature definition list, build_info.h.in, module_xc/CMakeLists.txt.
  • User or maintenance risk: none with ENABLE_LIBVDWXC=OFF.
  • Why the normal rule cannot be followed now: optional external libraries are switched by feature definitions in this code base.
  • Follow-up cleanup plan: none needed.
  • Requested approver: a maintainer

Open points for the maintainers

  • The libvdwxc version for hosted CI and the installation script remains to be agreed; the tested revisions are MR !32 at da2d55f and fft-new at 4b18416b.
  • 215_PW_rvv10_GaAs uses native PBE on purpose: in PW, the stress of a libxc functional with NLCC pseudopotentials double counts the core term, independent of this PR; I will report it separately.

@CleverPhysician

Copy link
Copy Markdown
Author

Update after the hosted checks completed:

  • The standard upstream workflow is green: 18/18 checks passed on head f3d41ad55ed53abb18ec8953d64df805d926dedd.
  • The serial intern004 validation remains green: the libvdwxc adapter test passed 1/1 and the minimal CPU/PW/nspin=1 Si SCF converged with the recorded energy and density checks.
  • This revision addresses the main concerns from feat: add restricted rVV10 plane-wave support #8031: semilocal and nonlocal XC are separate inputs, the host side uses a generic additive component, and rVV10-specific numerical work is kept behind the thin libvdwxc adapter rather than duplicated in the generic XC evaluator.
  • Following the pattern of merged Add optional DFT-D4 support #7380, the PR now includes explicit dependency/build commands, user-facing INPUT documentation, citations, unit coverage, and an honest statement of checks not run.

The PR remains Draft while the maintainer confirms the staged CPU/serial/nspin=1 scope and while the QE same-density reference comparison (including gradient/divergence sign and normalization) is completed. libvdwxc MR !32 is still a Draft dependency, so I am not presenting it as a stable release.

@Growl1234

Copy link
Copy Markdown
Collaborator

The pinned libvdwxc Draft branch's own rvv10.serial test is not fully green: 7/8 CTest groups passed and 69 finite-difference/strain checks fail at roughly 1e-6--1e-5. This is reported as a dependency-side Draft issue, not hidden.

Could you provide the detailed information?

Another side note: libvdwxc currently requires FFTW-MPI wrapper when MPI is enabled, so be careful with MKL; for now you can consider adding a USE_FFTW3_WITH_MKL that use MKL Blas/lapack/scalapack but standalone FFTW library, but I'm in progress of refactoring its FFT backend and dropping the direct FFTW-MPI dependency, so hopefully in the future everything will be better.

@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.

Static review of 32e12de74c07d2307a90c695dac6f8e452f592e5, independently cross-checked against the pinned libvdwxc implementation. Two geometry issues and one nonblocking timer-label cleanup are noted inline. No builds or runtime tests were run.

@CleverPhysician

Copy link
Copy Markdown
Author

Follow-up on head 32e12de:

  • The parser now rejects para.sys.double_grid explicitly, so unsupported double-density-grid inputs fail during input validation with a clear single-density-grid diagnostic.
  • The host component now enforces the declared first-PR nspin=1 scope instead of retaining an untested nspin=2 path.
  • The updated Python contract test is 7/7. On intern004, the real libvdwxc adapter CTest is 1/1, the abacus_pw_ser target relinks successfully, the two-atom Si CPU/PW/nspin=1 SCF converges with E_xc=-4.2517234318 Ry, E_total=-208.0135469216 eV, and the double-grid and nspin=2 negative-input checks both fail at the intended parser diagnostic.

The PR remains Draft while the new head's hosted checks are queued and the QE same-density reference is discussed.

@CleverPhysician

Copy link
Copy Markdown
Author

Addressed the ABACUS-PR-BOT static review on head e65e07c:

  • The libvdwxc cell adapter now passes ABACUS lattice rows as the C API's C00,C10,C20 vector groups. The oblique-cell test constructs the direct reference with the same documented row convention, so a transpose mismatch is now detected.
  • The adapter rejects non-positive latvec.Det() before constructing the backend. A left-handed-cell regression test covers this case.
  • The PotNonlocalXC timer labels now use cal_v_eff consistently.

The intern004 adapter CTest is 1/1 after these changes, and the Si CPU/PW/nspin=1 SCF remains numerically unchanged. The PR stays Draft pending the hosted checks for the new head and maintainer review.

Comment thread CMakeLists.txt Outdated
Comment on lines +633 to +637
if(NOT TARGET libvdwxc::vdwxc)
message(FATAL_ERROR
"ENABLE_LIBVDWXC requires the libvdwxc::vdwxc CMake target. "
"Use the libvdwxc development build that includes the rVV10 API.")
endif()

@Growl1234 Growl1234 Oct 14, 2026 •

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.

That shouldn't be needed as libvdwxc's CMake config will definitely have libvdwxc::vdwxc target. Previously I did this in abacus for RapidJSON due to its embarrassing release status, but with it replaced by nlohmann-json there's no longer the case. If abacus can deal with items like dftd4 and pexsi well then the same for libvdwxc (its cmake is cleaner). If you really encountered issues please report them.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Agreed. c23f000 removes the if(NOT TARGET libvdwxc::vdwxc) check; ABACUS now relies on find_package(libvdwxc CONFIG REQUIRED) and links the exported libvdwxc::vdwxc target through _abacus_feature_libs, alongside Libxc::xc.

Comment thread CMakeLists.txt Resolved
Comment thread docs/developers_guide/nonlocal_xc.md Resolved
@CleverPhysician

Copy link
Copy Markdown
Author

Thanks for asking. I reran the unchanged libvdwxc revision 91ef4820f3270e22b35fddc2ab4cab8efa4b6d79 in two fresh build directories. My earlier wording was too broad: these were 69 failed comparisons within one CTest, rather than 69 failed tests or evidence that all libvdwxc algorithms fail.

Both builds used GCC 11.2.1, Release (-O3 -DNDEBUG; the tests also use -UNDEBUG), shared libraries, and MPI disabled. The MKL imported target additionally supplies -m64:

-DCMAKE_BUILD_TYPE=Release
-DCMAKE_C_COMPILER=/opt/rh/devtoolset-11/root/usr/bin/cc
-DBUILD_SHARED_LIBS=ON -DBUILD_TESTING=ON -DVDWXC_ENABLE_MPI=OFF

With -DVDWXC_FFT_PROVIDER=MKL -DMKL_INTERFACE=lp64 -DMKL_THREADING=sequential -DMKL_LINK=dynamic and MKL 2022.2.1, 7/8 CTests pass. rvv10.serial reports:

  • 50 density-derivative finite-difference mismatches: maximum absolute discrepancy 2.34733549e-6; tolerance 3e-8 × (1 + |expected|).
  • 16 sigma-derivative mismatches: maximum absolute discrepancy 5.68711029e-6; tolerance 3e-7 × (1 + |expected|).
  • 3 full-strain derivative mismatches: maximum absolute discrepancy 9.01266900e-6; tolerance 3e-7 × (1 + |expected|).

The original MKL executable reproduces exactly the same values under a clean environment with no LD_LIBRARY_PATH:

env -i PATH=/usr/bin:/bin LANG=C LC_ALL=C OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 \
  /tmp/libvdwxc-mr32-audit/build-audit/libvdwxc_rvv10_test

Selecting -DVDWXC_FFT_PROVIDER=FFTW3 with standalone FFTW 3.3.11 and the same common settings gives 8/8 CTests passing, and the same rvv10.serial test reports 0 failures, also under env -i.

Both configurations pass the separate CP2K-table reference comparisons in that test: energy, density/sigma derivatives, and explicit stress on a 3 × 3 × 5 oblique grid, for both default and custom parameters. Those fixtures were generated independently using CP2K's kernel table, NumPy FFT, and SciPy splines; this is a table-level reference, not a CP2K SCF or QE comparison.

The current evidence therefore isolates the discrepancy to this MKL backend configuration. The underlying cause has not been established.

Updated head c23f000 now builds ABACUS with OpenBLAS and the same standalone FFTW as libvdwxc, avoiding mixed fftw_* implementations. The full serial PW executable builds, the adapter/Makefile CTests pass 2/2 (six C++ numerical/error cases), and the Si SCF converges with E_total=-208.0135469216242 eV. I corrected the PR description accordingly. MPI is not yet implemented, so I have not tested the FFTW-MPI wrapper or added a new MKL/FFTW mixing option.

This update also removes the manual CMake target/header/API checks and uses libvdwxc::vdwxc directly as suggested. The redundant developer page has been removed, and the adapter does not encode a PFFT dependency. It uses ABACUS's standard error diagnostics and adds an independent oblique/orthogonal-cell geometry test: deliberately restoring the wrong transpose makes that test fail. The PR stays Draft pending the scope decision and independent QE comparison.

@Growl1234

Copy link
Copy Markdown
Collaborator

Ah OK, I can now reproduce the failure with oneMKL 2026.1.0. I will have a look into it.

@Growl1234

Copy link
Copy Markdown
Collaborator

Ah OK, I can now reproduce the failure with oneMKL 2026.1.0. I will have a look into it.

@CleverPhysician This should be fixed on libvdwxc side, please check

@CleverPhysician

Copy link
Copy Markdown
Author

Follow-up on c3dedfb:

  • The adapter now forbids copying its owned libvdwxc handle. A type-contract
    regression failed on the original implicit copy constructor/assignment and
    passes with the two deleted operations.
  • Added one focused host test using real Charge, UnitCell, and the backend.
    It checks valence-plus-core density construction, additive energy/vtxc/potential,
    preservation of existing XC values and unchanged density arrays. The separately
    tested adapter supplies the correction reference; this is host bookkeeping
    coverage, not an independent physical reference.
  • Mutation checks confirm it catches missing core density (3.33e-5 Ry energy
    discrepancy) and replacing += by =. Production source was restored and
    checksum-matched before final verification.
  • The full serial PW executable builds and all three libvdwxc-related CTests
    pass (seven adapter cases, one host case, one build-report test). The Si SCF
    and unsupported-input checks were rerun. Scope is unchanged.

The earlier 18 successful hosted checks apply to c23f000, not this new head;
new CI still needs to finish. The PR remains Draft pending scope approval and
independent QE validation. I found preserved raw QE density/output fixtures for
that next comparison, but have not counted the old native-backend results as
validation of this adapter.

@CleverPhysician

Copy link
Copy Markdown
Author

Thanks, checked the fix at 94410ebdf3dc9615a40f40c3a5b59dbe20a433d2.
With GCC 11.2.1, both standalone FFTW 3.3.11 and MKL 2022.2.1
(lp64/sequential/dynamic) now pass all 8 library CTests, including
fft.weights and rvv10.serial. The seven ABACUS adapter tests and the real
host bookkeeping test also pass with the new standalone-FFTW library.
These runs were on a scheduled compute node (Slurm 555743), with the two
FFT providers kept separate. I updated the documented pin; no ABACUS
implementation change was needed for this fix.

The new adapter has now also been compared against the immutable original-QE
directional fixtures: seven cases, 960 points each, nine steps each.
Maximum energy difference is 3.50e-13 Ry, and its own-energy directional
residual is at most 1.25e-10 Ry at h=1e-4 (L1-direction normalized).
I have not called the pointwise potential comparison a pass: low-q and
small-sigma conventions differ, and the kernel convolution G sets are not
identical even when the host PW gradient cutoff is the same. Those differences
are recorded separately in the PR description; material/vacuum reference
validation and staged-scope agreement are still pending. Keeping this Draft.

1 and others added 13 commits November 4, 2026 09:10
The Rvv10Workspace::evaluate timer separates libvdwxc and the plane
exchange from the density and potential work of vdw::add_rvv10, so the
timer table shows where rVV10 spends its time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Rvv10Workspace: function-local static instead of a leaked heap object,
  non-copyable; prepare split into same_grid/set_cell/rebuild; the FFTW-MPI
  slab bounds come from one helper; evaluate takes XCFunctionalParameters and
  skips the dE/dn exchange in the stress path, which never reads it
- add_rvv10 and add_rvv10_stress share the density and libvdwxc preamble
- the workspace buffers are reported to ModuleBase::Memory
- ScopedType::restore swaps the whole XCFunctionalParameters struct, so a new
  parameter cannot be forgotten there
- easy_install.md lists libvdwxc among the CMAKE_PREFIX_PATH packages

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…air vdw_rvv10_b with the functional

- MatchesDirectLibvdwxc checks the four-component layout: energy and vtxc of
  the total density, potential in v(0) only
- BigGridDistributionMatchesCompleteGrid runs the adapter on a PW_Basis_Big
  with bz = 4 (the LCAO density grid), where a process may own no plane
- VxcAddsRvv10ToEveryFunctionalPath also covers the gga_grad 0 noncollinear
  branches of v_xc and v_xc_libxc and the libxc local collinear map
- vdw_rvv10_b, when not given, follows dft_functional: 15.7 for SCAN, 11.95
  for r2SCAN, 6.3 otherwise with a warning unless rPW86-PBE; read_input_test
  checks the four cases

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
With one spin channel, v_xc_libxc and v_xc_meta already hold the plane-wave
gradient of the total density. They now hand it to add_rvv10, which saves the
adapter's own transform and gradient (four dense-grid FFTs per SCF call).
The gradient is built the same way on both sides, so results are identical to
the last bit; the unit test requires exact equality on these two paths.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The transposes, the density sum, sigma and the scaling of the gradient get
the OpenMP pragmas that the neighbouring module_xc loops use. The two
reductions (vtxc and the gradient term of the stress) stay serial, so the
result does not depend on the thread count.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…esses take the same path

In LCAO the density grid is shared by all processes in blocks of bz planes, and
a process may hold no point at all. Its empty gradient has a null data pointer,
which add_rvv10 took as "compute the gradient here": that process entered the
collective transforms while the others went on to libvdwxc, and the run hung
before the first SCF step. The overload now takes the vector itself; the unit
test runs v_xc_libxc with rVV10 on the big-cell grid, where rank 3 of 4 is empty.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- tests/01_PW/815_PW_rvv10_GaAs: zincblende GaAs with NLCC pseudopotentials,
  two spin channels, forces and stress, PBE through the native XC path
- tests/03_NAO_multik/relax_cell_rvv10: one cell-relaxation step of SnTe in
  LCAO (the relax_cell_vdw4_d4 case with rVV10 instead of D4)
Both are listed in CASES_LIBVDWXC.txt and registered under
if(ENABLE_LIBVDWXC), so they run only when the library is built in. The
references were generated with 4 MPI ranks.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- assert the length of a handed-over gradient; schedule clauses on the
  transposes; comments on the workspace lifetime and the exchange plan
- the warning for an unset vdw_rvv10_b says that the functional comes from the
  pseudopotential when dft_functional is default; docs follow the automatic pairing
- unit tests: exact equality only for the point-wise potential (etxc and vtxc
  are OpenMP reductions of the caller), a 2-process/2-thread registration,
  300 s timeouts because a collective mismatch shows as a hang, two more
  vdw_rvv10_b pairings in the input test

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- tests/01_PW/216_PW_rvv10_graphite: AB graphite with ONCV carbon, rPW86-PBE
  through libxc (the path that hands its gradient to the rVV10 term), forces
  (one atom displaced) and stress
- tests/01_PW/215_PW_rvv10_GaAs replaces 815_PW_rvv10_GaAs: Γ point and
  60 Ry (8.5 s instead of 13 s), numbered with the other XC cases
References generated with 4 MPI ranks and reproduced.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- workspace lifetime comment says why data_ is left alone; the header speaks
  of all three functions; the test comment names the halved axis correctly
- docs spell the dft_functional values that select b and say that rPW86-PBE
  gets no warning; the three test READMEs say how their references were made

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…end of life

- Rvv10Workspace moves to rvv10_workspace.{h,cpp} (declaration with Doxygen,
  definitions apart); nonlocal_xc.cpp keeps the adapter functions
- the instance is created on first use and released by vdw::finalize_rvv10,
  which ESolver_FP::after_all_runners calls before MPI_Finalize, instead of a
  function-local static that was never finalized
- vdw::is_rvv10 holds the method name; ESolver_FP and make_vdw use it
- unit tests split into a fixture header with its helpers source and two test
  sources, constants in lower case, a check that a released workspace is
  rebuilt; 215_PW_rvv10_GaAs at 30 Ry; two-line test READMEs

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@CleverPhysician

CleverPhysician commented Nov 4, 2026 •

Copy link
Copy Markdown
Author

@mohanchen I compared vdw_method rvv10 with Quantum ESPRESSO 7.2 (input_dft='rVV10') for graphite, 2H-MoS2 and S22. The PW comparisons below use the same SG15 ONCV pseudopotentials, 80 Ry wavefunction cutoff, k-mesh, smearing and FFT grid, with 32 MPI ranks. Both codes use rPW86 + PBE + rVV10 (b = 6.3, C = 0.0093). I can share the inputs and analysis script.

check systems max deviation
binding energy vs QE graphite E_b(c), 12 distances; 2H-MoS2 E_b(c), 8 distances 0.018 / 0.034 meV/atom
S22 interaction energy vs QE all 22 dimers, 20 Å box 0.021 kcal/mol
forces vs QE 17 S22 dimers 0.0014 eV/Å
stress vs QE graphite (4 cells), MoS2 (8 cells), PW 0.14 kbar
rVV10 stress vs finite differences of E graphite PW, LCAO DZP, LCAO TZDP; MoS2 PW 0.04 kbar
PW vs LCAO (TZDP) graphite E_b(c) 0.24 meV/atom
PW vs LCAO, counterpoise-corrected graphite E_b(c), TZDP / DZP 0.53 / 1.91 meV/atom
system ABACUS QE experiment
graphite c_eq (Å), E_b (meV/atom) 6.686, −69.1 6.686, −69.1 6.70
2H-MoS2 c_eq (Å), E_b (meV/atom) 12.49, −82.8 12.49, −82.8 12.29
S22 MAE vs CCSD(T) (kcal/mol) 0.37 0.37 —

An rVV10 call took 0.63 s on a 216³ grid with 32 ranks; about 0.55 s was spent inside libvdwxc. Across the timing cases, rVV10 accounted for 6–16 % of the wall time for S22 dimers in a 20 Å box, 9 % for four-atom graphite and below 1 % for 64-atom graphite. The 64-atom case used an additional 27–66 MB per rank across the measured rank counts. libvdwxc's buffers are distributed over the pool.

I checked the DZP–PW binding-energy gap with counterpoise correction using the existing ghost-atom support. Each monomer calculation contains one graphene layer in a finite 20 Å periodic cell, with the other layer's orbitals at c/2 as ghost atoms. The binding-energy reference remains the bulk c = 20 Å cell. At c = 6.70 Å, the DZP correction is 5.15 meV/atom with rVV10 and 5.30 meV/atom without it. Across the 12 distances, correction reduces the maximum DZP–PW deviation from 9.02 to 1.91 meV/atom; the fitted c_eq values are 6.715 and 6.717 Å. For TZDP, the correction is 0.28 meV/atom at c = 6.70 Å and the corrected curve differs from PW by at most 0.53 meV/atom. These results support using larger orbitals or counterpoise correction for weak LCAO binding energies.

The counterpoise comparisons use the default ABACUS FFT grid. For five graphite cells that grid is 27×27×75, versus 27×27×80 in QE. Matching QE's grid reduces the PW binding-energy deviation from 0.14 to 0.018 meV/atom; the c_eq = 6.686 Å result in the table uses this matched grid.

Graphite E_b(c), meV/atom
c (Å) 6.00 6.30 6.50 6.55 6.60 6.65 6.70 6.75 6.80 6.85 7.00 7.40
QE PW −47.47 −63.24 −67.84 −68.45 −68.87 −69.13 −69.10 −69.07 −68.92 −68.65 −67.28 −60.84
ABACUS PW (QE FFT grid) −47.45 −63.22 −67.82 −68.43 −68.85 −69.11 −69.08 −69.05 −68.90 −68.63 −67.26 −60.82
ABACUS PW (default grid) −47.45 −63.22 −67.82 −68.43 −68.85 −69.11 −69.24 −69.20 −69.04 −68.77 −67.36 −60.82
ABACUS LCAO TZDP −47.38 −63.05 −67.60 −68.20 −68.62 −68.87 −69.00 −68.96 −68.80 −68.52 −67.12 −60.60
ABACUS LCAO DZP −56.47 −71.40 −75.48 −75.93 −76.19 −76.28 −76.27 −76.08 −75.77 −75.34 −73.49 −65.81
ABACUS LCAO DZP, counterpoise −49.09 −65.05 −69.74 −70.34 −70.75 −70.99 −71.12 −71.07 −70.90 −70.62 −69.19 −62.52
ABACUS LCAO TZDP, counterpoise −46.95 −62.70 −67.29 −67.90 −68.32 −68.58 −68.72 −68.69 −68.53 −68.26 −66.87 −60.40
2H-MoS2 E_b(c), meV/atom
c (Å) 11.60 12.00 12.20 12.30 12.40 12.60 13.00 13.60
QE PW −54.82 −76.01 −80.66 −81.92 −82.60 −82.54 −78.49 −67.71
ABACUS PW −54.84 −76.03 −80.68 −81.95 −82.63 −82.56 −78.52 −67.75
ABACUS PW, no rVV10 66.47 33.23 22.70 18.55 15.02 9.50 2.94 −0.66
S22, kcal/mol (monomers in the dimer geometry)
# dimer CCSD(T) QE ABACUS max |ΔF| vs QE (eV/Å)
1 ammonia dimer −3.17 −3.48 −3.47 0.0006
2 water dimer −5.02 −5.67 −5.67 —
3 formic acid dimer −18.80 −20.47 −20.46 0.0007
4 formamide dimer −16.12 −16.91 −16.90 0.0006
5 uracil dimer, H-bonded −20.69 −21.21 −21.20 0.0006
6 2-pyridoxine–2-aminopyridine −17.00 −18.28 −18.27 0.0005
7 adenine–thymine, Watson–Crick −16.74 −17.47 −17.45 0.0006
8 methane dimer −0.53 −0.49 −0.48 —
9 ethene dimer −1.50 −1.41 −1.40 —
10 benzene–methane −1.45 −1.43 −1.42 0.0006
11 benzene dimer, parallel displaced −2.62 −2.64 −2.62 —
12 pyrazine dimer −4.20 −3.99 −3.98 0.0005
13 uracil dimer, stacked −9.74 −9.62 −9.60 0.0004
14 indole–benzene, stacked −4.59 −4.40 −4.38 0.0004
15 adenine–thymine, stacked −11.66 −11.28 −11.26 0.0009
16 ethene–ethyne −1.51 −1.69 −1.68 0.0014
17 benzene–water −3.29 −3.34 −3.33 —
18 benzene–ammonia −2.32 −2.29 −2.27 0.0004
19 benzene–HCN −4.55 −4.33 −4.32 0.0007
20 benzene dimer, T-shaped −2.71 −2.53 −2.52 0.0006
21 indole–benzene, T-shaped −5.62 −5.28 −5.27 0.0004
22 phenol dimer −7.09 −7.20 −7.19 0.0010
Stress, kbar
case QE σxx ABACUS σxx QE σzz ABACUS σzz max |Δ|
graphite c = 6.55 16.17 16.16 11.88 11.98 0.10
graphite c = 6.65 16.69 16.68 3.69 3.77 0.08
graphite c = 6.75 17.11 17.10 −2.86 −2.88 0.02
graphite c = 6.85 17.44 17.44 −8.37 −8.51 0.14
MoS2, 8 cells ≤ 0.08

rVV10 part of the stress, analytic vs central differences of E (±0.5 % strain):

system, basis Δσzz analytic / FD Δ(σxx+σyy) analytic / FD
graphite PW −38.38 / −38.34 −4.82 / −4.79
graphite LCAO DZP −37.78 / −37.78 −4.01 / −4.01
graphite LCAO TZDP −38.22 / −38.22 −4.93 / −4.93
MoS2 PW −20.80 / −20.81 −51.72 / −51.71

This update also reuses the libxc density gradient, adds OpenMP to element-wise loops and releases the libvdwxc workspace at the end of the run. In the five-case old/new regression, energies, forces and stresses agree within rounding. The added tests cover nspin=4, an LCAO big-cell grid with an empty process and workspace rebuilding after release. vdw_rvv10_b now follows dft_functional when omitted, with explicit values left unchanged. Three integration cases are gated by ENABLE_LIBVDWXC.

The latest commits (03786dd87, 2ddf235d6) read the grid slabs from libvdwxc when its local-grid API is available, with the existing FFTW-MPI layout retained for older libraries. The XC, stress and solver call sites now use the adapter's empty inline hooks when libvdwxc is disabled, keeping the feature switch in module_vdw. Adapter and workspace tests have also been reorganized to match their source files.

1 and others added 3 commits November 4, 2026 10:34
… rVV10

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
vdwxc_init_mpi takes the slab of each process from FFTW-MPI but did not
report it, so the adapter assumed the FFTW-MPI default blocks of
ceil(nz/P) planes. With a libvdwxc that provides vdwxc_get_local_grid,
every process now asks for its slab when the workspace is built, the
slabs are gathered over the pool with the new
Parallel_Common::allgather_data and checked to cover the z axis in rank
order, and the exchange is planned from them. CMake detects the function
(LIBVDWXC_HAS_LOCAL_GRID); without it the previous rule is kept.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… tests after their sources

Following AGENTS.md:
- nonlocal_xc.h provides empty inline hooks without libvdwxc, so v_xc,
  v_xc_libxc, v_xc_meta, stress_gga and ESolver_FP call them without
  #ifdef __LIBVDWXC; the switch stays in module_vdw, as for DFT-D4.
- Rule 11: test_nonlocal_xc.cpp tests nonlocal_xc.cpp and the new
  test_rvv10_workspace.cpp tests rvv10_workspace.cpp; the shared fixture
  moves to nonlocal_xc_test_helpers.{h,cpp}, whose header includes only
  what its declarations need.
- Rule 14: computed arguments are assigned to named locals first.

No change of results.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

```{important}
For some dependencies built with CMake, such as Libxc, dftd4, cereal, and nlohmann-json, you'll have to add their prefix paths to the environment variable `CMAKE_PREFIX_PATH` so that CMake can correctly find and use their CMake configuration files. A non-general variable such as `PKG_DIR` is discouraged for these packages.
For some dependencies built with CMake, such as Libxc, dftd4, libvdwxc, cereal, and nlohmann-json, you'll have to add their prefix paths to the environment variable `CMAKE_PREFIX_PATH` so that CMake can correctly find and use their CMake configuration files. A non-general variable such as `PKG_DIR` is discouraged for these packages.

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.

What is this package used for?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

libvdwxc evaluates the rVV10 nonlocal correlation for vdw_method rvv10 (kernel, FFT convolution, energy, potential and stress). It is optional; that line now says so.

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.

... that line now says so.

Please leave the package description to where it should be. Here is simply a hint regarding CMake dependencies.

#ifdef __MPI
#include <vdwxc_mpi.h>
#endif
#undef I

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.

this line is strange, remove it if possible

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.

this line is strange, remove it if possible

Unfortunately, libvdwxc's public header pulls in <complex.h>, exposing the C99 macro I to subsequently included ABACUS headers. Therefore, #undef I is needed as a workaround. This is actually an upstream bug as the public libvdwxc API doesn't use any complex type...

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Thanks @Growl1234 for the explanation. I will drop the line once the libvdwxc header no longer includes <complex.h>.

@CleverPhysician
CleverPhysician marked this pull request as ready for review November 13, 2026 01:25
Comment thread CMakeLists.txt Outdated
option(ENABLE_ABACUS_LIBM "Build libmath from source to speed up" OFF)
option(ENABLE_LIBXC "Enable using the LibXC package" OFF)
cmake_dependent_option(ENABLE_LIBVDWXC "Enable using the libvdwxc package" OFF
"ENABLE_LIBXC" OFF)

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.

Why it requires libxc?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

You are right, it was a leftover from when rVV10 was tied to rPW86-PBE. ENABLE_LIBVDWXC no longer depends on ENABLE_LIBXC; the Libxc-specific tests are built only with ENABLE_LIBXC, and the adapter tests and the native-PBE GaAs case pass with ENABLE_LIBXC=OFF.

Comment thread CMakeLists.txt Outdated
Comment on lines +668 to +678
# vdwxc_get_local_grid reports the grid slab of each process; without it the adapter assumes the FFTW-MPI
# default blocks (see source_hamilt/module_vdw/rvv10_workspace.h).
include(CheckCXXSourceCompiles)
set(CMAKE_REQUIRED_LIBRARIES libvdwxc::vdwxc)
check_cxx_source_compiles(
"#include <complex.h>
#include <complex>
#include <vdwxc.h>
int main() { int shape[3]; int offset[3]; vdwxc_get_local_grid(nullptr, shape, offset); return 0; }"
LIBVDWXC_HAS_LOCAL_GRID)
unset(CMAKE_REQUIRED_LIBRARIES)

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.

It's not a good idea to include a code test against dependencies in CMake.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Agreed. Will vdwxc_get_local_grid be in the release that brings rVV10? If so, I will require that release and remove the probe and the ceil(nz/P) fallback.

1 and others added 2 commits November 13, 2026 11:30
rVV10 is independent of the semilocal functional and works with the
built-in ones, so ENABLE_LIBVDWXC no longer depends on ENABLE_LIBXC.
The unit tests run the Libxc paths (v_xc_libxc, v_xc_meta) only with
__LIBXC, and the integration cases, two of which use rPW86-PBE, are
registered when both libraries are enabled. easy_install.md says what
libvdwxc is used for.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Following the unit-test layout rule of AGENTS.md (deepmodeling#8245): the rVV10
adapter and workspace tests move to module_vdw/unittests, with the
shared fixture as a header; the tests added to legacy directories move
to new files next to them, test_vdw.cpp (module_vdw/unittests),
test_read_inp_model.cpp (source_io/unittests) and
test_parallel_device.cpp (source_base/unittests), and the legacy files
are restored. The INPUT test checks invalid values on the declared
domains, since a rejected INPUT ends the process in the MPI build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@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 earlier lattice mapping, left-handed-cell and timer findings are addressed in the current source. The remaining notes concern workspace cleanup, memory guidance, test coverage and call-site clarity.

Static review of 5a3eb84 against f531565; full and incremental whitespace checks passed. No builds, numerical/runtime tests or CI diagnostics ran. Author-reported numerical results, installed dependency identity and the newer optional grid-query implementation remain unverified.

Comment thread source/source_esolver/esolver_fp.cpp Outdated
GlobalV::ofs_running << " --------------------------------------------\n\n" << std::endl;

// the libvdwxc FFT plans must be destroyed before MPI_Finalize
vdw::finalize_rvv10();

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.

Non-blocking: LCAO calls this base cleanup before its XC matrix output, which can recreate the workspace after this release; the ks-lr finalizer also does not reach this hook. Please release the workspace after the last post-processing XC evaluation, while MPI is still active, so its final FFT plans and buffers are freed.

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.

Addressed in source at 04e913b: Driver::driver_run now releases the workspace after late solver output and solver destruction, while MPI is still active. This also covers the ks-lr composite path.

Comment thread docs/advanced/install.md Outdated
cmake --build build-libvdwxc && cmake --install build-libvdwxc
```

Then pass `-DENABLE_LIBVDWXC=ON` to CMake for ABACUS and add `/path/to/libvdwxc` to `CMAKE_PREFIX_PATH`. rVV10 works with the built-in functionals; functionals such as rPW86 (`GGA_X_RPW86+GGA_C_PBE`) or SCAN also need `-DENABLE_LIBXC=ON`. CMake also checks for `vdwxc_get_local_grid`; with it, ABACUS asks libvdwxc for the grid slab of each process instead of assuming the FFTW-MPI default distribution. ABACUS hands each k-point pool's density to libvdwxc's distributed interface, so the nonlocal convolution and its memory are shared by the processes of the pool; libvdwxc keeps about 25 doubles (200 bytes) per grid point of a process's slab, and the adapter 5 more, so the memory per process falls as the pool grows. libvdwxc's MPI build plans its FFTs with FFTW-MPI, so an MPI build of ABACUS with libvdwxc must use FFTW3 rather than the FFTW interface of MKL or KML; CMake stops otherwise. The legacy Makefile does not build this feature.

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.

Non-blocking: Please label the adapter's five-double estimate as cached workspace storage. During add_rvv10 evaluation, nonlocal_xc.cpp also holds rho, sigma, the three-component gradient, dedn and dedsigma, totaling another seven doubles per ABACUS-local grid point. The current estimate therefore does not describe peak adapter memory.

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 guide now separates cached workspace storage from the additional seven doubles per ABACUS-local grid point used during evaluation. This addresses the requested memory-description clarification at 04e913b.

{
for (int iz = 0; iz < pw.nplane; ++iz)
{
values[(ix * pw.ny + iy) * pw.nplane + iz] = f(pw, ix, iy, pw.startz_current + iz);

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.

Non-blocking: Please assign pw.startz_current + iz to a named global_z before calling f, following AGENTS rule 14. Likewise, name the generated valence and core grids before their constructor calls in test_rvv10_workspace.cpp:42-43; the data and formulas can stay unchanged.

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 requested call sites now use named global_z, valence and core values before passing them as arguments. The data, assertions and numeric thresholds are preserved in 04e913b.

Comment thread tests/01_PW/CMakeLists.txt Outdated
endif()

# the rVV10 cases also use the Libxc functional rPW86-PBE
if(ENABLE_LIBVDWXC AND ENABLE_LIBXC)

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.

Non-blocking: This guard leaves ENABLE_LIBVDWXC=ON, ENABLE_LIBXC=OFF without a registered rVV10 integration case. Please register the native-PBE GaAs case separately under ENABLE_LIBVDWXC alone, so the newly supported configuration keeps SCF, force and stress regression coverage; graphite still needs Libxc.

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 native-PBE GaAs case is now registered under ENABLE_LIBVDWXC alone, while graphite and the NAO case retain the additional Libxc gate. The requested native-only integration registration is present at 04e913b.

for (const std::string esolver: {"lr", "ks-lr"})
{
input.esolver_type = esolver;
input.cal_force = true;

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.

Non-blocking: Setting cal_force directly drops the former full-INPUT check that calculation relax activates forces before the rVV10 requirement is validated. Please retain an isolated-process rejection test for rvv10 + ks-lr + calculation relax to cover that reset/validation ordering. The current rejection logic remains intact.

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.

MODULE_IO_input_error_mpi_rvv10_lr_relax now reads the requested combination without explicit cal_force, checking the dependency diagnostic and all four reader shutdown markers. This restores the full-INPUT regression coverage in source at 04e913b.

1 and others added 5 commits November 13, 2026 14:39
io_input references stru_frame_io::extract_frame_by_step since deepmodeling#8159,
so MODULE_IO_test_read_inp_model compiles stru_frame_io.cpp, as the
neighbouring targets do.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
vdwxc_get_local_grid is not part of the libvdwxc interface this PR
depends on (merge request !32), so the CMake probe, the
__LIBVDWXC_LOCAL_GRID definition, the query branch of the workspace and
Parallel_Common::allgather_data are removed. The adapter applies the
documented ceil(nz/P) slab rule again; the query can come back once a
libvdwxc release provides it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
ESolver_FP::after_all_runners released the workspace before the LCAO and
PW post-processing, which evaluates XC again and rebuilt it, and the
ks-lr solver did not reach the hook. The driver now releases it once,
after the solver is deleted and before MPI_Finalize; ESolver_FP only
copies the rVV10 parameters.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…llow-ups

- tests: 215_PW_rvv10_GaAs (built-in PBE) is registered with
  ENABLE_LIBVDWXC alone, the rPW86-PBE cases with Libxc as well.
- An isolated-process INPUT test rejects rvv10 + ks-lr + relax, where
  relax turns the forces on before the requirement is checked.
- docs: the libvdwxc component is described in the component list of
  easy_install.md; install.md separates the adapter's cached storage
  from the memory of an evaluation.
- AGENTS rule 14 in the unit tests; named constants for the published
  b values and the test lower bounds.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

@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 five outstanding cleanup, memory-description, argument-style, native-PBE registration and INPUT-regression requests are addressed in source at 04e913b. I found no new implementation defect in the incremental changes.

Non-blocking: Please refresh the PR description for the driver cleanup, removed grid-query/allgather path and split test lists (CASES_LIBVDWXC_LIBXC.txt for NAO). Attribute earlier test results to their tested revision, and identify the new parser regression when reporting that check.

Verification was limited to static source/dependency-contract review and recorded governance/whitespace checks. No build or runtime test was run; CI and the installed dependency versions remain unverified.

@Growl1234

Growl1234 commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Just a heads up in case I missed it:

  • Please do not merge this PR until the new libvdwxc release is out.
  • Libvdwxc provides not only incoming rVV10 but also existing vdW-DF family, so this PR cannot be marked as a full integration; what we want in the future is a generalized non-local vdW infrastructure that links against libvdwxc. Therefore, I will have a dedicated major follow-up refactor after merging this PR, to reduce complexity and generalize the code (but dude please don't include them here).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Feature Discussed The features will be discussed first but will not be implemented soon

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants