Feature: Support ultrasoft pseudopotentials (USPP) in PW BPCG

[AsTonyshment]

Summary

• Enable PW BPCG to solve the generalized Kohn-Sham eigenproblem required by ultrasoft pseudopotentials (USPP).
• Apply the overlap metric consistently to normalization, residuals, gradient projection, Cholesky orthogonalization, and line minimization.
• Select the lower Ritz root during line minimization and safely handle already-converged zero-norm search directions.

Numerical validation

The same spin-polarized Fe USPP system was evaluated with conventional CG and with BPCG before and after this change. The BPCG rows use KPAR=1 and BNDPAR=2.

Metric	CG reference	BPCG before	BPCG after
Total energy (eV)	-673.8349346994	-658.6272943523	-673.8349347375
Integrated charge (electrons)	7.999971733	7.922562413	7.999980846
Pressure (kbar)	-22206.773131	-20530.256205	-22206.710168

After the fix, the BPCG total energy differs from CG by approximately $3.8\times10^{-8}$ eV, the integrated charge returns to 8 electrons, and the pressure difference is reduced from approximately 1676.5 kbar to 0.063 kbar.

Other changes

• Refresh typed host/device beta-projector interpolation tables after cell rescaling to prevent stale projector data in variable-cell calculations.
• Correct float input handling in the USPP radial Fourier transform instead of reinterpreting float buffers as double.
• Store the canonical USPP projector occupations in double precision so single-precision force and stress calculations consume the correct data.
• Add one centralized runtime check that rejects unsupported USPP basis, solver, spin, XC, and post-processing combinations before numerical initialization.
• Fix explicit dense FFT-grid selection when only ndz is larger than nz.

[Copilot]

🟡 Changes recommended

The review found build/robustness issues in changed code (notably missing standard headers for newly used std:: APIs, plus a couple of fragile size checks) that should be corrected before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR extends the PW BPCG diagonalization path to support ultrasoft pseudopotentials (USPP) by consistently treating the Kohn–Sham problem as a generalized eigenproblem with an overlap metric, and adds a CPU regression case to cover the new capability.

Changes:

• Update BPCG (CPU + CUDA + ROCm) to apply the overlap metric in normalization, residuals, orthogonal projection, Cholesky orthogonalization, and line minimization (including safer handling of zero-norm directions and choosing the lower Ritz root).
• Fix USPP data handling/precision issues (radial FFT float handling, projector-occupation storage, GPU table refresh after rescaling) and add a centralized USPP configuration validator.
• Add/refresh tests and reference outputs, including a new PW USPP+BPCG CPU test case.

File summaries

File	Description
tests/16_SDFT_GPU/005_PW_SDFT_MALL_BPCG_GPU/result.ref	Refresh GPU SDFT BPCG reference values.
tests/01_PW/CASES_CPU.txt	Register new USPP+BPCG CPU test case.
tests/01_PW/212_PW_USPP_BPCG/STRU	New USPP BPCG test structure input.
tests/01_PW/212_PW_USPP_BPCG/result.ref	New USPP BPCG reference outputs.
tests/01_PW/212_PW_USPP_BPCG/README	Document new USPP BPCG test purpose.
tests/01_PW/212_PW_USPP_BPCG/KPT	New test k-point mesh.
tests/01_PW/212_PW_USPP_BPCG/INPUT	New USPP+BPCG test input parameters.
source/source_pw/module_pwdft/vnl_pw.h	Document radial FFT template constraints.
source/source_pw/module_pwdft/vnl_pw.cpp	Refresh host/device beta-projector tables after rescaling.
source/source_pw/module_pwdft/vnl_pw_qrad.cpp	Fix float radial FFT handling (avoid reinterpret-cast to double); adjust instantiations.
source/source_pw/module_pwdft/uspp_support.h	Declare centralized USPP support validation API.
source/source_pw/module_pwdft/uspp_support.cpp	Implement centralized USPP support validation and early rejection.
source/source_pw/module_pwdft/stress_us.cpp	Use canonical double-precision USPP projector occupations via ElecState bridge.
source/source_pw/module_pwdft/hamilt_pw.cpp	Refactor USPP overlap application path used by BPCG generalized solve.
source/source_pw/module_pwdft/force_pw_us.cpp	Use canonical double-precision USPP projector occupations via ElecState bridge.
source/source_pw/module_pwdft/CMakeLists.txt	Wire new uspp_support.cpp into the module build.
source/source_io/test_serial/read_input_item_test.cpp	Stabilize dense-grid selection unit tests (double_grid reset).
source/source_io/module_parameter/read_inp_sys.cpp	Fix explicit dense FFT-grid selection logic for ndz.
source/source_hsolver/test/diago_bpcg_test.cpp	Update BPCG unit test to provide an S
source/source_hsolver/kernels/rocm/bpcg_kernel_op.hip.cu	Apply overlap metric and improved line minimization in ROCm kernels.
source/source_hsolver/kernels/cuda/bpcg_kernel_op.cu	Apply overlap metric and improved line minimization in CUDA kernels.
source/source_hsolver/kernels/bpcg_kernel_op.h	Extend kernel interfaces to pass S
source/source_hsolver/kernels/bpcg_kernel_op.cpp	CPU kernel updates for overlap metric + line minimization behavior.
source/source_hsolver/hsolver_pw.cpp	Pass S
source/source_hsolver/diago_bpcg.h	Extend BPCG API/data structures to handle generalized eigenproblem (S
source/source_hsolver/diago_bpcg.cpp	Implement generalized BPCG flow using overlap operator throughout.
source/source_estate/test/elecstate_pw_test.cpp	Assert becsum starts empty for both precisions.
source/source_estate/elecstate_pw.h	Store becsum as double vector + expose bridge accessor for force/stress.
source/source_estate/elecstate_pw.cpp	Populate canonical double becsum and add Device-template bridge accessor.
source/source_esolver/esolver_fp.cpp	Add early USPP configuration validation before numerical initialization.
source/Makefile.Objects	Add uspp_support.o to non-CMake object list.

Review details

• Files reviewed: 31/31 changed files
• Comments generated: 3
• Review effort level: Lite

---

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

[mohanchen]

Great!