Feature: Add direct gradient label in DeePKS.

[ErjieWu]

What's changed?

• Add gradient method in DeePKS. Now DeePKS can directly generate gradient label from real-space hamiltonian for training.

[Copilot]

🟡 Not ready to approve

Input validation/docs for deepks_grad are incomplete and the new DeePKS gradient-label functionality lacks focused unit tests despite existing module_deepks test coverage.

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

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

This PR extends the DeePKS (NAO/LCAO) label-output pipeline to support generating descriptor-gradient training intermediates directly from real-space Hamiltonians, and standardizes real-space Hamiltonian label units to Hartree to match existing DeePKS conventions.

Changes:

• Add deepks_grad option and a new DeePKS gradient-label helper module (deepks_grad.{h,cpp}) to output additional normal-equation intermediates (e.g., squared operator terms).
• Add output-only scaling support to hamilt::Output_HContainer and use it to write real-space DeePKS Hamiltonian CSR labels in Hartree (Ry→Hartree scaling).
• Update DeePKS test reference CSR outputs and adjust docs/parameter metadata accordingly.

File summaries

File	Description
tests/09_DeePKS/24_NO_KP_deepks_vdelta_r_2/deepks_hrtot.csr.ref	Update real-space H(R) CSR reference values (unit conversion/output change).
tests/09_DeePKS/24_NO_KP_deepks_vdelta_r_2/deepks_hrdelta.csr.ref	Update real-space H_delta(R) CSR reference values (unit conversion/output change).
tests/09_DeePKS/23_NO_KP_deepks_vdelta_r_1/deepks_hrtot.csr.ref	Update real-space H(R) CSR reference values (unit conversion/output change).
tests/09_DeePKS/22_NO_GO_deepks_vdelta_r_2/deepks_hrtot.csr.ref	Update real-space H(R) CSR reference values (unit conversion/output change).
tests/09_DeePKS/22_NO_GO_deepks_vdelta_r_2/deepks_hrdelta.csr.ref	Update real-space H_delta(R) CSR reference values (unit conversion/output change).
tests/09_DeePKS/21_NO_GO_deepks_vdelta_r_1/deepks_hrtot.csr.ref	Update real-space H(R) CSR reference values (unit conversion/output change).
tests/09_DeePKS/21_NO_GO_deepks_vdelta_r_1/deepks_hrdelta.csr.ref	Update real-space H_delta(R) CSR reference values (unit conversion/output change).
source/source_lcao/module_deepks/LCAO_deepks_interface.cpp	Integrate deepks_grad outputs; write HR CSR labels with Hartree scaling; output additional squared intermediates.
source/source_lcao/module_deepks/deepks_vdrpre.cpp	Refactor cal_vdr_precalc implementation (tensor layout/compute strategy changes).
source/source_lcao/module_deepks/deepks_grad.h	New header defining DeePKS gradient-label helper APIs.
source/source_lcao/module_deepks/deepks_grad.cpp	New implementation for projection and squared-operator builders used by deepks_grad.
source/source_lcao/module_deepks/CMakeLists.txt	Add deepks_grad.cpp to ML build.
source/source_io/module_parameter/read_input_item_deepks.cpp	Add deepks_grad input item and related validation hook.
source/source_io/module_parameter/input_parameter.h	Add deepks_grad field to input parameter struct.
source/source_hamilt/module_hcontainer/test/test_hcontainer_output.cpp	Add unit test validating output-only scaling behavior.
source/source_hamilt/module_hcontainer/output_hcontainer.h	Extend Output_HContainer API with value_scale parameter.
source/source_hamilt/module_hcontainer/output_hcontainer.cpp	Apply value_scale when inserting CSR values for output.
source/Makefile.Objects	Add deepks_grad.o to object list.
docs/parameters.yaml	Update deepks_v_delta unit description; add deepks_grad entry (currently missing description text).
docs/advanced/input_files/input-main.md	Update deepks_v_delta description to state Hartree output units.

Review details

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

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.