Periodic Hartree AO matrices#
task = hartree builds the electrostatic Hartree operator from the currently
loaded SCF eigenvectors and their physical, k-weighted occupations. The result
is the complete complex matrix in the spatial AO basis, in Hartree. The
operator sums physical spin channels and diagonal spinor components and is
the same scalar spatial operator for both collinear spins.
This endpoint is a one-shot build and comparison. It does not update a QSGW Hamiltonian or introduce a Hartree inner self-consistency loop.
Build support#
The default build prepares the unmodified LibRI revision
ab81ac939d820b1350c1e00f0e09e8e1edfc3d96. No separate LibRI installation or auxiliary-potential
extension is needed. With LIBRPA_USE_LIBRI=ON, CMake checks for
RI/physics/Hartree.h in the resolved headers, including external headers.
This header enables standalone Hartree and QSGW feedback.
CMake reports this capability; unsupported Hartree requests fail explicitly.
See Installation for dependency selection.
Band-path matrices use the ordinary mesh Hartree result: inverse Fourier
transform to AO real-space blocks, then the same atom-pair BvK image averaging
(option_bvk_remap) and forward Fourier convention as EXX. This finite-mesh
interpolant reproduces the input mesh; away from it, convergence depends on
the mesh and the BvK convention. The dedicated RI input remains full precision,
but its unwrapped translations are not used to define a separate path operator.
Input#
Use the ordinary structure, full-BZ mean-field, wave-function/auxiliary-basis, and RI-coefficient inputs, with an explicitly supplied Hartree metric prefix:
task = hartree
input_preset = abacus-legacy
input_dir = ../dataset
version_coul_reader = 1
version_lri_reader = 1
prefix_lri_coeff = v1_Cs_data
prefix_lri_coeff_shrink = v1_Cs_shrinked_data
prefix_shrink_sinvS = v1_shrink_sinvS_
prefix_coul_hartree = v1_coulomb_hartree_
parallel_routing = libri
use_shrink_abfs = false
cs_threshold = 0
vq_threshold = 0
This example matches the reference producer’s out_librpa_reader_version 1
filenames. The abacus-legacy preset selects its structure/basis/eigenstate
names; the versioned RI filenames are overridden explicitly above.
This first-comparison example uses unshrunk auxiliary data without extra
consumer-side coefficient screening. Use use_shrink_abfs=true only with
the matching shrunk producer metric and coefficients.
For the ABACUS reference producer, use a converged LCAO SCF calculation with
symmetry -1, a Gamma-centered regular k mesh, rpa 1,
out_librpa_reader_version 1 and out_mat_h_vh 1. Stage its ordinary
structure/basis/eigenstate and selected C files, the dedicated
v1_coulomb_hartree_iq_*_rank0.dat file and the native vh1_nao.csr
from the output directory into input_dir. The metric and C files must
come from the same full/shrunk producer setup. The native CSR is in Ry;
the metric is already in Ha. This compares LibRPA’s first build from the
exported DFT state to ABACUS’s post-SCF Hartree operator for that state.
prefix_coul_hartree has no preset/default fallback. Its files must contain
the bare three-dimensional Coulomb auxiliary matrix at zero lattice
momentum transfer, with the reciprocal-space G=0 term set to zero. That
choice fixes the background/potential convention. A single q=0 v1 file is
sufficient; the task does not require Coulomb files at every nonzero q. The
metric must match the selected full/shrunk auxiliary basis and the RI
coefficients. Supplying this prefix asserts that physical kernel convention;
a generic Coulomb filename does not establish it.
The ordinary EXX prefix_coul_full and prefix_coul_cut inputs are not used
as Hartree fallbacks. A truncated, erfc-screened, optical-head-replaced or
other modified metric must not be substituted for the required bare metric.
The first implementation requires a complete Gamma-centered BZ mean-field grid, the supported
three-dimensional periodic geometry, and no atomic-position Bloch phase
(bloch_ratom=0). The producer’s remaining Bloch convention must match the
computation API and native comparison; these restrictions are not a claim of
support for arbitrary basis gauges. Only parallel_routing=libri is supported.
parallel_routing=auto selects libri before any data input. Explicit rtau
and atompair routes are rejected collectively at that point. The rtau
setter uses a different coefficient representation that this Hartree backend
does not consume; atompair additionally omits one directed LRI endpoint.
A shifted SCF mesh is not supported by this public input path: the existing
Coulomb-index setter resolves q indices through the SCF grid, so q=0 must be
an actual supplied grid point.
Output and native reference comparison#
Root writes hartree_ao.dat, retaining every complex AO entry at every loaded
SCF k point. Rows are k i j real imag, with zero-based indices and Hartree
units. These are full spatial AO matrices rather than KS diagonal values.
To compare a native ABACUS Hartree CSR export, add:
hartree_fn_reference = vh1_nao.csr
hartree_reference_scale = 0.5
hartree_check_tolerance = -1
The reference filename is relative to input_dir, unless absolute. The
explicit scale converts its energy to Hartree; 0.5 is appropriate for
Rydberg input, while Hartree input requires 1.0. The reader retains both
complex triangles and all supplied lattice translations. It constructs
V_H(k) = sum_R exp(+2 pi i k.R) V_H(R) on the actual SCF grid and compares
every complex entry without fitting a constant or an overlap-proportional
potential shift. The reference and exported auxiliary metric must therefore
share the same electrostatic background convention and density.
hartree_comparison.dat records the maximum absolute entry difference and
Frobenius norm for each k point and over the complete matrix bundle. All
differences are in Hartree. A negative hartree_check_tolerance only reports
the discrepancies. A positive value explicitly gates the global maximum
entry error and requires a reference; a failure is propagated to all MPI
ranks. The code supplies no universal material-accuracy tolerance.
Agreement can be limited by the RI approximation, radial/plane-wave grids, finite real-space support, CSR export precision, or a mismatch between the final grid density and the density reconstructed from occupations. A completed build or a report-only comparison does not by itself establish numerical acceptance or physical convergence.
QSGW density-difference feedback#
The optional feedback adds V_H[P_live - P_original_DFT] explicitly to the
QSGW Hamiltonian before cuts/mixing and removes the same component from the
entering-state QP static subtraction. It is enabled by default; set
qsgw_update_hartree = false for fixed-Hartree runs. In addition
to normal QSGW input, supply the matching bare q=0 metric and coefficients
with physical, unwrapped translations:
qsgw_update_hartree = true
prefix_coul_hartree = v1_coulomb_hartree_iq_
prefix_lri_coeff_hartree = v1_Cs_hartree_shrinked_data_
Use v1_Cs_hartree_data_ for the full, unshrunk auxiliary basis. The raw-C
prefix must match the auxiliary basis selected by use_shrink_abfs;
the coefficients are folded consistently onto the integration mesh. Band paths
use the resulting AO operator with the EXX BvK interpolation convention. The supported public
route uses LibRI, bare 3D Coulomb, a complete unshifted Gamma-containing mesh,
and bloch_ratom=0. Disabled behavior retains its previous requirements.
qsgw_hartree.csv reports the entering and post-update density differences,
AO/fixed-initial-KS matrix norms and grid matrices; path output contains KS
diagonals. A fresh DFT entering state has zero correction by definition. After
one QSGW update, the reported updated-state value is the correction for the
next Hamiltonian; its evaluation does not perform a second GW build.
The immutable original DFT density remains the reference across restart. Checkpoints reject changes in the enabled flag, reference, metric or raw C using the checkpoint’s numerical input tolerance. The BvK convention and actual atom-pair image mapping are also bound. Checkpoints from the earlier direct-R Hartree path require a fresh start. The C/C++ opaque QSGW API accepts these inputs; the standalone Fortran Hartree API does not expose a Fortran QSGW task interface.