[Feature Request] Export density-independent LCAO H0 for HamGNN without SCF iterations

[goodchong]

Background

HamGNN needs an inexpensive reference Hamiltonian H0 in the LCAO basis, so that the model can learn a correction and reconstruct the full Hamiltonian as

$$H_{\mathrm{pred}} = H_0 + \Delta H_{\mathrm{NN}}.$$

This request consolidates feedback from HamGNN on the physical definition and calculation workflow for H0. It is a focused follow-up to #6519: the scope here is explicit reference-Hamiltonian definitions and export without SCF iterations. The angular-momentum-matrix request in #6519 remains separate.

For ordinary pseudopotential LDA/GGA calculations, before adding other corrections, the converged Kohn–Sham Hamiltonian can be written as

$$H_{\mathrm{SCF}} = T + V_{\mathrm{nl}} + V_{\mathrm{loc}} + V_H[\rho_{\mathrm{SCF}}] + V_{xc}[\rho_{\mathrm{SCF}}].$$

Here V_loc is the local ionic pseudopotential, whereas the local effective potential is the sum V_eff = V_loc + V_H + V_xc. These two meanings of “local potential” should be distinguished.

Describe the solution you'd like

Provide a supported way to construct and export H0(R) without converging an electronic density. The primary requested definition is

$$\boxed{H_0^{\mathrm{ion}} = T + V_{\mathrm{nl}} + V_{\mathrm{loc}}}.$$

For fixed structure, pseudopotentials and basis, all three terms are independent of the electronic density. “Density-independent” does not mean that their matrix elements must be evaluated analytically; numerical integrals are still needed.

Please distinguish the following reference choices explicitly:

Reference	Included terms	Density dependence	Role
Ionic reference	T + V_nl + V_loc	None	Preferred definition in this request
Legacy HamGNN reference	T + V_nl	None	Compatibility with the existing ABACUS-3.5.3-based exporter and corresponding datasets/models
Initial-density reference	Conventionally T + V_nl + V_loc + V_H[rho0] + V_xc[rho0]	Depends on a prescribed initial density rho0	A separate alternative for discussion, not a prerequisite for the primary feature

The feedback also mentioned constructing exchange-correlation contributions from an initial density. If that alternative is supported, the inclusion of both Hartree and exchange-correlation potentials, and the construction of rho0, must be specified. It should not be conflated with either density-independent reference above. The quantity entering the Hamiltonian is V_xc, not the exchange-correlation energy E_xc itself.

The desired workflow is:

1. Prepare the structure, pseudopotentials, numerical atomic orbitals, neighbors and required integrals.
2. Assemble the explicitly selected reference terms and export H0(R), with matching S(R) available for downstream use.
3. Finish without an electronic self-consistency loop. For the density-independent references, diagonalization, density reconstruction and density mixing are not required to obtain the matrices.

Reusing the existing SCF initialization path can be an intermediate implementation, but the operation should be described as matrix construction/export, rather than as a converged SCF calculation. Merely setting the maximum SCF iteration count to one does not select the desired Hamiltonian terms. A dedicated export path that avoids unnecessary electronic-state calculations would be preferable; the exact INPUT/API design is open for discussion.

Legacy implementation and engineering context

The ABACUS-3.5.3-based postprocessor bundled with HamGNN implements the two-term reference:

• In the archived source/module_esolver/esolver_ks.cpp, line 357 sets GlobalV::VL_IN_H = 0 before beforescf(), and the SCF iteration loop is commented out.
• In source/module_hamilt_lcao/hamilt_lcaodft/hamilt_lcao.cpp, lines 81–91 gate the local ionic, Hartree and exchange-correlation potential registration together. Turning off that gate therefore removes V_loc as well as the density-dependent terms; kinetic and nonlocal pseudopotential operators remain enabled under their normal defaults.
• In source/module_esolver/esolver_ks_lcao.cpp, the modified hamilt2density() calls updateHk(0) at line 601, while the subsequent electronic-state/density calculation is commented out. Thus “one SCF step” is not an accurate description of the numerical work performed by this patched path.

The upstream LCAO potential registration, inspected on 2026-09-07, likewise places these contributions under vl_in_h, with separate ionic/Hartree switches and an xc registration inside that gate. The requested three-term reference therefore needs a deliberate way to retain V_loc while excluding Hartree and XC, instead of disabling the whole effective-potential contribution. This is an implementation choice, not a physical requirement to bundle the terms.

Behavior and compatibility considerations

The selected reference definition must be documented and identifiable in the output. Changing from the legacy reference to the ionic reference changes the learned residual:

$$H_0^{\mathrm{ion}}-H_0^{\mathrm{legacy}}=V_{\mathrm{loc}},\qquad \Delta H^{\mathrm{ion}}=\Delta H^{\mathrm{legacy}}-V_{\mathrm{loc}}.$$

An existing model trained against the legacy reference cannot simply have the new reference added to its unchanged prediction. Training and inference must use consistent definitions. HamGNN's add_H0 implementation explicitly adds the supplied reference blocks.

The export should use a documented matrix format, units, orbital/spin ordering and lattice-vector convention compatible with the full H(R)/S(R) outputs. Reusing the legacy filenames is not itself a requirement. Ordinary SCF behavior should remain unchanged when the export feature is not selected. The formulas above establish the basic LDA/GGA case; supported spin modes and the treatment of SOC, hybrid exchange, DFT+U and other additional terms should be stated explicitly rather than silently changing the meaning of H0.

Suggested validation

• Verify the exported ionic reference against T + V_nl + V_loc, and verify that its difference from the legacy reference is V_loc within numerical tolerance.
• Verify that changing an initial density does not change either density-independent reference when structure, pseudopotentials and basis are fixed.
• Verify that export does not require SCF convergence, diagonalization, density updates or density mixing.
• Read back the exported matrices and check their numerical values and indexing against the corresponding full-matrix conventions.

This is a feature request based on HamGNN feedback and static inspection of the bundled legacy source and current upstream source. No new implementation or runtime validation is claimed here.