Feature: term-separated LCAO Hamiltonian atomic derivatives (dH)

[maki49]

Main feature

Output $\partial H/\partial \tau_I (k)$, where $\tau_I$ is the I-th atom position.

• partial means excluding density matrix derivative dD
• total dH: out_mat_dh
  • if not gamma_only, also output $\langle\phi|H|d\phi\rangle(R)$ (the existing feature)
• terms: t, vl, vnl, vh(Hartree), vxc, exx
• parameters: out_mat_dh_t/vnl/vl/vh/vxc/exx
• nspin=4 is not supported yet

Each term is output separately so downstream codes can distinguish physical contributions with clear definition.

Implementation

• source/source_io/module_dhs/ (new): unified WriteDHParams struct + per-term writers for T, Vl, Vnl, Vh, Vxc
• cal_dH method for each OperatorLCAO subclasses
  • 3 different types of Hellmann-Feynman terms for vl/vh/vxc
• Supports both gamma-only and multi-k, nspin=1/2
• Per-atom dH filter: param[2+] selects specific atoms; empty = all atoms
• Output format: dH(k) dense; dH(R) in CSR only for multi-k
• EXX dH is gated behind __EXX_DEV pending an upstream LibRI PR

A detailed document:
ABACUS-dH-API.pdf

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR expands LCAO matrix output capabilities by adding term-resolved real-/k-space outputs for H and dH/dR (including multi-k and gamma-only paths), and extends EXX/RI plumbing to support these derivatives.

Changes:

• Add new output flags and writers for H terms (T/VL/VNL/VH/VXC/EXX) and dH components, plus new integration kernel for ∇ρ on the grid.
• Extend EXX (LibRI) workflow/interfaces to support building/writing dH(EXX) and NSCF init-from-DM path.
• Add/extend integration tests and reference data for new dH(k) term outputs.

Reviewed changes

Copilot reviewed 70 out of 70 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/integrate/tools/catch_properties.sh	Add comparisons for dhk* reference outputs and conditionally skip sparse dHR under gamma-only.
tests/03_NAO_multik/scf_out_dh_t/result.ref	Add expected dhk* comparison keys to test reference summary.
tests/03_NAO_multik/scf_out_dh_t/dhk_ref/dhkz_iat1_ik1_nao.txt	Add reference dhk(z) output for iat1/ik1.
tests/03_NAO_multik/scf_out_dh_t/dhk_ref/dhkz_iat1_ik0_nao.txt	Add reference dhk(z) output for iat1/ik0.
tests/03_NAO_multik/scf_out_dh_t/dhk_ref/dhky_iat1_ik1_nao.txt	Add reference dhk(y) output for iat1/ik1.
tests/03_NAO_multik/scf_out_dh_t/dhk_ref/dhky_iat1_ik0_nao.txt	Add reference dhk(y) output for iat1/ik0.
tests/03_NAO_multik/scf_out_dh_t/dhk_ref/dhkx_iat1_ik1_nao.txt	Add reference dhk(x) output for iat1/ik1.
tests/03_NAO_multik/scf_out_dh_t/dhk_ref/dhkx_iat1_ik0_nao.txt	Add reference dhk(x) output for iat1/ik0.
tests/02_NAO_Gamma/scf_out_dh/result.ref	Add new gamma-only test expected keys for dH term outputs.
tests/02_NAO_Gamma/scf_out_dh/dhk_ref/dvxckz_iat2_nao.txt	Add reference for dVxc/dR (k-space) gamma-only test.
tests/02_NAO_Gamma/scf_out_dh/dhk_ref/dvnlkz_iat2_nao.txt	Add reference for dVnl/dR (k-space) gamma-only test.
tests/02_NAO_Gamma/scf_out_dh/dhk_ref/dvlkz_iat2_nao.txt	Add reference for dVl/dR (k-space) gamma-only test.
tests/02_NAO_Gamma/scf_out_dh/dhk_ref/dvhkz_iat2_nao.txt	Add reference for dVh/dR (k-space) gamma-only test.
tests/02_NAO_Gamma/scf_out_dh/dhk_ref/dtkz_iat2_nao.txt	Add reference for dT/dR (k-space) gamma-only test.
tests/02_NAO_Gamma/scf_out_dh/dhk_ref/dhkz_iat2_nao.txt	Add reference for total dH/dR (k-space) gamma-only test.
tests/02_NAO_Gamma/scf_out_dh/STRU	Add structure file for new gamma-only dH test case.
tests/02_NAO_Gamma/scf_out_dh/INPUT	Add input enabling out_mat_dh and per-term dH outputs (gamma-only).
tests/02_NAO_Gamma/CASES_CPU.txt	Register the new scf_out_dh test case.
source/source_pw/module_pwdft/forces.h	Add friend decl for hamilt::Veff reuse of local-force logic.
source/source_lcao/spar_dh.cpp	Use pv.nloc under gamma-only local mode for nnr sizing.
source/source_lcao/setup_exx.cpp	Initialize EXX integration tables for NSCF with init_chg=dm.
source/source_lcao/module_ri/RI_2D_Comm.hpp	Add DM(R) -> Ds conversion helper for EXX/RI workflow.
source/source_lcao/module_ri/RI_2D_Comm.h	Declare dm_container_to_Ds template API.
source/source_lcao/module_ri/Exx_LRI_interface.hpp	Add EXX dH builder from mixed DM and consolidate includes.
source/source_lcao/module_ri/Exx_LRI_interface.h	Expose dHexxs and two_level_step, add dHs completion flag.
source/source_lcao/module_ri/Exx_LRI.hpp	Compute dHexxs via LibRI dev API; enable dC/dV when dH(EXX) output requested.
source/source_lcao/module_ri/Exx_LRI.h	Add dHexxs storage and cal_exx_dHs API declaration.
source/source_lcao/module_operator_lcao/veff_lcao.h	Add veff cal_dH API for term-wise dH output generation.
source/source_lcao/module_operator_lcao/veff_lcao.cpp	Include veff_dh implementation hook.
source/source_lcao/module_operator_lcao/op_exx_lcao.hpp	Refactor OperatorEXX constructors, add NSCF init-from-DM, implement EXX dH mapping.
source/source_lcao/module_operator_lcao/op_exx_lcao.h	Add interface-based constructor and EXX dH API; remove raw two_level_step pointer.
source/source_lcao/module_operator_lcao/nonlocal_dh.hpp.bak	Add backup copy of nonlocal dH implementation (new file).
source/source_lcao/module_operator_lcao/nonlocal_dh.hpp	Add nonlocal pseudopotential dH/dR kernel (Pulay/HF) for per-atom containers.
source/source_lcao/module_operator_lcao/nonlocal.h	Declare Nonlocal::cal_dH and include .
source/source_lcao/module_operator_lcao/nonlocal.cpp	Include nonlocal_dh implementation unit.
source/source_lcao/module_operator_lcao/ekinetic_dh.hpp	Add kinetic dH/dR kernel for per-atom containers.
source/source_lcao/module_operator_lcao/ekinetic.h	Declare EKinetic::cal_dH and include .
source/source_lcao/module_operator_lcao/ekinetic.cpp	Include ekinetic_dh implementation unit.
source/source_lcao/module_hcontainer/test/test_add_value.cpp	Add gtest coverage for HContainer add_value_union/intersection behavior.
source/source_lcao/module_hcontainer/test/CMakeLists.txt	Register new hcontainer add-value unit test target.
source/source_lcao/module_hcontainer/hcontainer.h	Add add_value_intersection/union APIs.
source/source_lcao/module_hcontainer/hcontainer.cpp	Implement add_value_intersection/union (union via rebuild + swap).
source/source_lcao/module_gint/gint_interface.h	Add cal_gint_drho API.
source/source_lcao/module_gint/gint_interface.cpp	Wire cal_gint_drho to new Gint_drho implementation.
source/source_lcao/module_gint/gint_dvlocal.h	Allow nspin=1/2, add full_triangle mode and pvdpR getters.
source/source_lcao/module_gint/gint_dvlocal.cpp	Use configurable triangle fill mode for pvdpR accumulation.
source/source_lcao/module_gint/gint_drho.h	Add new grid-kernel class for gradient density integration.
source/source_lcao/module_gint/gint_drho.cpp	Implement ∇ρ grid integration using orbital gradients and dm contraction.
source/source_lcao/module_gint/CMakeLists.txt	Compile gint_drho.cpp into module_gint library.
source/source_lcao/hamilt_lcao.cpp	Switch OperatorEXX creation to interface-based constructor wiring.
source/source_io/module_parameter/input_parameter.h	Add out_mat_h_* and out_mat_dh_* input flags for term-wise outputs.
source/source_io/module_output/filename.cpp	Extend allowed output properties for new H(k) term matrix outputs.
source/source_io/module_hs/write_H_terms.h	Add WriteHParams and writers for H term outputs (and EXX).
source/source_io/module_hs/write_H_terms.cpp	Implement H term writers and H(k) folding/output for each term.
source/source_io/module_hs/output_mat_sparse.cpp	Update comment to reflect <phi
source/source_io/module_dhs/write_dH.h	Add WriteDHParams and API for dH component outputs and per-atom writer helper.
source/source_io/module_dhs/write_dH.cpp	Implement per-atom dH(k)/dH(R) writer and driver to emit selected components.
source/source_io/module_ctrl/ctrl_scf_lcao.h	Extend ctrl_scf_lcao signature to pass dense grid, vloc, solvent for dH veff pots.
source/source_io/module_ctrl/ctrl_scf_lcao.cpp	Integrate new dH component writers and new H term writers into SCF output flow.
source/source_io/CMakeLists.txt	Build and link new dH/H-term writer compilation units.
source/source_estate/module_pot/potential_new.h	Add getter for vloc table for dH(VL) reuse.
source/source_estate/module_charge/charge.h	Make kin_density() const.
source/source_estate/module_charge/charge.cpp	Implement kin_density() as const.
source/source_estate/init_scf.cpp	Skip charge renormalization when init_chg == "dm".
source/source_esolver/esolver_ks_lcao.cpp	Pass pw_rhod/vloc/solvent through to ctrl_scf_lcao.
docs/advanced/input_files/input-main.md	Document new out_mat_h_* and out_mat_dh_* parameters and formats.
CMakeLists.txt	Add EXX_DEV option and compile definition gating for LibRI dev features.

Comments suppressed due to low confidence (4)

source/source_lcao/module_operator_lcao/nonlocal_dh.hpp.bak:1

• A .bak backup file is committed under source/ and duplicates a large implementation. This can confuse builds/maintenance and may get accidentally included later. Please remove nonlocal_dh.hpp.bak from the repository (or move it to documentation/notes if it must be kept).
  source/source_lcao/module_ri/Exx_LRI_interface.h:1
• This const accessor returns a non-const reference, which breaks const-correctness (callers can mutate dHexxs through a const Exx_LRI_Interface). Consider returning const auto& here, and add a separate non-const accessor only where mutation is intended.
  tests/integrate/tools/catch_properties.sh:1
• shopt is a bash-specific builtin. If this script is executed with /bin/sh on some CI environments, it will fail. Ensure the script uses a bash shebang (#!/usr/bin/env bash) or avoid shopt by using a portable glob-existence check.
  tests/02_NAO_Gamma/scf_out_dh/INPUT:1
• The new reference outputs under tests/02_NAO_Gamma/scf_out_dh/dhk_ref/*.txt have a header line # gamma only 0, which appears inconsistent with gamma_only 1 in this INPUT. If that header is intended to reflect runtime settings, the refs likely won't match actual output (or vice versa). Please regenerate/verify the refs so the metadata matches the test input.

---

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