Add spin-summed RKS density setting

[DCM-Uni-Paderborn]

This separates the core GauXC part of the spin-summed RKS density-matrix handling from the Skala/Fortran-facing API exposure.

GauXC keeps the existing default RKS convention: an RKS density matrix is interpreted as a one-spin density and the closed-shell density is formed internally with the usual factor of two. Some external interfaces provide the already spin-summed closed-shell density matrix. This PR adds an explicit opt-in setting for that case without changing the default behavior.

Changes:

• add IntegratorSettingsKS::rks_density_matrix_is_spin_summed
• use the setting in the host and device RKS xmat_fac paths
• propagate settings through the shell-batched wrapper paths
• add a standalone-driver keyword for HDF5/reproducer workflows
• add a C++ regression check for spin-summed RKS density input on the stable LDA RKS reference path

No Skala, OneDFT, C API, or Fortran API exposure is included here; those belong in a follow-up change on the skala branch once this core convention is agreed.

Validation performed on Spark:

• configured and built host/HDF5 GauXC from this branch against master
• built standalone_driver and gauxc_test
• ran targeted gauxc_test "XC Integrator" -c "Benzene / SVWN5 / cc-pVDZ" -c Host -c Reference --success successfully
• ran the CP2K-generated H2O all-electron GAPW/QZVPP HDF5 reproducer with full spin-summed RKS density:
  • N_EL = 9.999998605222
  • EXC = -9.247398490121
  • EXC gradient rows:
    • 4.093047e-13 6.159873e-14 -4.648139e-01
    • -1.646459e-13 3.214351e-01 2.324069e-01
    • -2.447600e-13 -3.214351e-01 2.324069e-01

The full serial GauXC test target was also tried, but existing MGGA reference sections fail in this environment independently of this focused RKS convention check.

[Copilot]

Pull request overview

This PR introduces an explicit opt-in integrator setting to interpret RKS density matrices as spin-summed closed-shell densities (instead of GauXC’s default one-spin convention), and threads that setting through host/device reference paths and shell-batched wrappers. It also adds a standalone-driver keyword for reproducer workflows and a focused regression check.

Changes:

• Add IntegratorSettingsKS::rks_density_matrix_is_spin_summed (default false) to control the RKS xmat_fac scaling.
• Apply the setting to host/device replicated integrator xmat_fac computation and propagate through shell-batched wrapper call chains.
• Add a standalone-driver keyword and a regression test exercising spin-summed RKS density input on an LDA reference path.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
include/gauxc/xc_integrator_settings.hpp	Adds the new rks_density_matrix_is_spin_summed flag to KS settings.
src/xc_integrator/replicated/host/reference_replicated_xc_host_integrator_exc_vxc.hpp	Uses the new flag to choose the RKS xmat_fac (2 vs 1) in EXC/VXC host reference path.
src/xc_integrator/replicated/host/reference_replicated_xc_host_integrator_exc_grad.hpp	Propagates the flag into EXC gradient host reference xmat_fac selection.
src/xc_integrator/replicated/host/reference_replicated_xc_host_integrator_fxc_contraction.hpp	Uses the new flag for xmat_fac in host FXC contraction path.
src/xc_integrator/replicated/device/incore_replicated_xc_device_integrator.hpp	Extends device local-work APIs to accept settings for downstream scaling decisions.
src/xc_integrator/replicated/device/incore_replicated_xc_device_integrator_exc_vxc.hpp	Threads settings into device EXC/VXC local work and applies spin-summed handling in xmat_fac.
src/xc_integrator/replicated/device/incore_replicated_xc_device_integrator_exc_grad.hpp	Propagates the flag into device EXC gradient xmat_fac selection.
src/xc_integrator/replicated/device/incore_replicated_xc_device_integrator_fxc_contraction.hpp	Threads settings into device FXC contraction local work and applies spin-summed handling in xmat_fac.
src/xc_integrator/replicated/device/incore_replicated_xc_device_integrator_exc.hpp	Updates device EXC-only path to pass settings through (currently has a correctness issue noted in comments).
src/xc_integrator/shell_batched/shell_batched_replicated_xc_integrator.hpp	Propagates settings through shell-batched replicated integrator interfaces.
src/xc_integrator/shell_batched/shell_batched_replicated_xc_integrator_exc.hpp	Passes settings down into shell-batched EXC local-work path.
src/xc_integrator/shell_batched/shell_batched_replicated_xc_integrator_exc_vxc.hpp	Passes settings down into shell-batched EXC/VXC task execution path.
src/xc_integrator/shell_batched/shell_batched_replicated_xc_integrator_exc_grad.hpp	Updates NYI shell-batched EXC-grad stubs to accept/unused settings.
src/xc_integrator/shell_batched/shell_batched_replicated_xc_integrator_fxc_contraction.hpp	Updates NYI shell-batched FXC contraction stubs to accept/unused settings.
tests/standalone_driver.cxx	Adds input keyword and forwards it to selected integrator calls (gap noted in comments).
tests/xc_integrator.cxx	Adds a regression check for spin-summed RKS density input (LDA-only) (coverage gap noted in comments).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.