Coulomb-metric density fitting¶
This extension proves selected factorization identities. Numerical checks passed for the cases below. Auxiliary-basis approximation errors, conditioning, screening and floating-point error bounds are separate outstanding obligations.
Metric projection¶
For an AO pair \(p=(\mu,\nu)\) and auxiliary functions \(P,Q\), define \(T_{Pp}=(P|\mu\nu)\) and \(V_{PQ}=(P|Q)\). Minimizing the Coulomb norm of the residual pair density gives the normal equation \(Vd_p=T_p\). This continuum variational argument is written here, not yet formalized. Assume a positive-definite auxiliary metric and factor \(V=LL^T\). Set \(B=L^{-1}T\) by a triangular solve. The fitted integrals are
For \(R=L^{-1}\), \(V^{-1}=R^TR\). The theorem df_inverse_metric_gram
uses explicit hypotheses \(RL=I\) and \(LB=T\) to prove
\(T^T(R^TR)T=B^TB\), without relying on a totalized inverse at a singular matrix.
df_gram_symmetric proves symmetry of \(B^TB\).
df_factor_reconstruction separately proves \(T^TT=B^TL^TLB\) from \(LB=T\);
this diagnostic identity does not identify \(T^TT\) with fitted integrals.
For a flattened density \(d\), the Coulomb contribution is
df_coulomb_nonnegative proves nonnegativity of the final sum of squares.
The equality with the matrix quadratic form is currently a written derivation.
The fitted J and K use the same indexed contractions as RHF, with
\(g\) replaced by \(\widetilde g\). Finite auxiliary spaces generally do not
reproduce the exact AO integrals. No sign of the total HF or MP2 fitting error
is inferred from this Coulomb positivity theorem.
Implementation correspondence¶
cpp/src/df.cpp::DensityFitting computes V and T, rejects a failed Cholesky
factorization and solves \(LB=T\). python/vibeqc/density_fitting.py supplies
the corresponding public J/K interface.
check_extensions.py independently
builds a NumPy Cholesky factor, checks \(B^TB=T^TV^{-1}T\), and compares
fitted J/K contractions against the implementation for water/STO-3G with
def2-universal-jkfit. A missing inverse metric must be detected.
This tests an algebraic implementation contract, not auxiliary-basis accuracy.
Current residual tolerance is \(2\times10^{-8}\) atomic units.
Reference: Weigend, A fully direct RI-HF algorithm, PCCP 4, 4285-4291 (2002), especially equations (1)-(4), DOI. The paper’s symmetric inverse-square-root factorization and the implementation’s Cholesky whitening have the same metric Gram matrix in exact arithmetic.
Measured acceptance¶
On 1 November 2026, the public Python fitting route passed on the 0.18.5
runtime documented with UHF. The separate resident C++ route was tested
through the scheduler on the qualified 0.18.6 runtime, source
7c98b77bf5a5f145129cb97a8820120d01e3ed74.
The maximum absolute residuals were \(7.106\times10^{-15}\) for resident J,
\(5.330\times10^{-15}\) for resident K and \(2.665\times10^{-15}\) for the
independent metric reconstruction. All four negative controls in the combined
harness were detected. These measurements are case-specific.
Use python check_extensions.py --cpp to require the resident C++ checks.
This mode needs bindings for build_J and build_K_density; the earlier
0.18.5 runtime lacks those bindings and its retired streaming entry points
refuse execution. No fallback or acceptance is inferred from those refusals.
The default mode tests native UHF/MP2 and the public Python fitting route.
General auxiliary-basis accuracy and the latest storage optimizations are
outside the acceptance of these recorded runtime revisions.