GPU fixes and optimization for Diago_DavSubspace, plus paged GPU memory mode (PAGED_GPU) #7727

Describe the bug

Background

Diago_DavSubspace has several GPU-path correctness bugs, and large k-point sets can exceed GPU memory because all k-point wavefunctions are resident on the device. This issue covers (a) GPU correctness fixes and a host-buffer optimization in dav_subspace, and (b) a new paged GPU memory mode that pages k-points to the device one at a time. The dav_subspace paged-mode fixes depend on the Psi paging infrastructure, so they are delivered together.

Bugs to fix

1. Stale d_eigenvalue on GPU refresh in Diago_DavSubspace. d_eigenvalue must be synchronized before the GPU refresh path reads it; otherwise eigenvalues from a previous k-point/iteration are used.
2. PAGED_GPU to_range() type-punning. Incorrect reinterpretation of Psi storage when only a subset of k-points is resident on device.
3. PAGED_GPU cal_grad reference corruption. References into paged Psi storage become dangling after a k-point is paged out.
4. PAGED_GPU buffer overflow and invalid D2H copy, and an abort in psi_norm when the norm is computed on non-resident k-points.
5. Psi PAGED_GPU issues in psi_prepare, operator(), force, and stress code paths that assume all k-points are device-resident.
6. Missing load_k_to_gpu before k-point loops that access psi in force/stress/onsite code in paged mode.
7. GPU memory MPI communication bugs affecting GPU-resident buffers.
8. GPU build compilation errors: missing unique_cuda_ptr, missing isk parameter in a CUDA kernel.

Optimization and feature work

• dav_subspace host-buffer optimization: add persistent host buffers hcc_h/scc_h for the subspace H/S matrices to avoid repeated GPU allocation/copy jitter in the subspace diagonalization path.
• Paged GPU memory mode: new device_memory_mode input parameter: full_gpu (default, current behavior) or paged.
  • New PsiStorageMode and psi_paging.cpp implementing per-k-point paging of PW wavefunctions.
  • Integrate k-point paging into the HSolverPW::solve loop.
  • Log the active GPU memory mode in setup_psi_pw.
  • Trade-off: reduced VRAM at the cost of H2D/D2H transfer overhead; intended for large k-point sets that exceed GPU memory.
• Add CUDA cusolver stubs and device check helpers (module_container/base/macros/cuda.h, third_party/cusolver.h).

Scope

• source/source_hsolver/diago_dav_subspace.{h,cpp}, hsolver_pw.cpp
• source/source_psi/ (psi.{h,cpp}, psi_paging.cpp, psi_prepare.cpp, setup_psi_pw.cpp)
• source/source_pw/module_pwdft/ (forces*.cpp, stress*.cpp: load_k_to_gpu guards)
• source/source_container/base/macros/cuda.h, third_party/cusolver.h
• Input parameter: device_memory_mode in read_input_item_* + input-main.md / parameters.yaml

Testing

• GPU build with -DUSE_CUDA=ON; run PW dav_subspace cases in both full_gpu and paged modes and compare total energies/forces.
• Regression: existing dav_subspace unit tests.
• Verify identical results between paged and full_gpu modes for multi-k-point PW cases.

Dependencies

• Depends on Issue 1 (onsite kernel interfaces touched by load_k_to_gpu guards).

Related

Split out from PR #7693.

Expected behavior

No response

To Reproduce

No response

Environment

No response

Additional Context

No response

Task list for Issue attackers (only for developers)

• Verify the issue is not a duplicate.
• Describe the bug.
• Steps to reproduce.
• Expected behavior.
• Error message.
• Environment details.
• Additional context.
• Assign a priority level (low, medium, high, urgent).
• Assign the issue to a team member.
• Label the issue with relevant tags.
• Identify possible related issues.
• Create a unit test or automated test to reproduce the bug (if applicable).
• Fix the bug.
• Test the fix.
• Update documentation (if necessary).
• Close the issue and inform the reporter (if applicable).