Integral-Direct 4-Center J and K in cuEST#

cuEST can build the Coulomb (J) and exchange (K) matrices, and the nuclear gradients of the corresponding energies, exactly from four-center electron repulsion integrals. The algorithm is integral-direct [1]: the integrals are evaluated on the fly from the primary basis and contracted with the density matrix immediately, so no integrals are stored. The only approximation is the integral screening described below, whose threshold the caller controls, which makes these routines the natural choice for reference-quality energies and gradients and for workflows that must reproduce a conventional quantum chemistry program exactly.

All direct routines share one cuestDirectIntPlan_t plan handle, built from the primary basis and its shell-pair list, and all of them accept a batch of density matrices in one call. The energy routines and the gradient routines are JIT-compiled (see JIT Compilation in cuEST); the one-time compilation cost is tabulated at the end of this page.

Coulomb and Exchange Matrices#

With \((pq|rs)\) the two-electron repulsion integral over atomic-orbital basis functions in Mulliken (chemists’) notation,

\[(pq|rs) = \iint \phi_p(\vec r_1)\,\phi_q(\vec r_1)\,\frac{1}{r_{12}}\,\phi_r(\vec r_2)\,\phi_s(\vec r_2)\,d\vec r_1\,d\vec r_2 ,\]

the Coulomb and exchange matrices of a density matrix \(D\) are

\[J_{pq} = \sum_{rs} (pq|rs)\, D_{rs}\]
\[K_{pq} = \sum_{rs} (pr|qs)\, D_{rs}\]

Both routines operate on a batch of density matrices and return one output matrix per density.

Range-Separated Exchange#

The exchange operator is a property of the plan rather than of a compute call. It is the linear combination

\[g_\omega(r_{12}) = s_{\rm FR}\,\frac{1}{r_{12}} + s_{\rm LR}\,\frac{\operatorname{erf}(\omega r_{12})}{r_{12}}\]

and the exchange matrix built by the plan is \(K_{pq} = \sum_{rs} (pr|g_\omega|qs) D_{rs}\). The three numbers \(s_{\rm FR}\), \(s_{\rm LR}\) and \(\omega\) are set through the plan parameters CUEST_DIRECTINTPLAN_PARAMETERS_EXCHANGE_FRACTION, CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_FRACTION and CUEST_DIRECTINTPLAN_PARAMETERS_LRC_EXCHANGE_OMEGA (defaults 1, 0 and 0: full-range exact exchange). A range-separated hybrid is specified by its full-range and long-range fractions. Short-range exchange follows from the identity \(\operatorname{erfc}(\omega r_{12})/r_{12} = 1/r_{12} - \operatorname{erf}(\omega r_{12})/r_{12}\): a pure short-range operator \(x\,\operatorname{erfc}(\omega r_{12})/r_{12}\) is obtained with \(s_{\rm FR} = x\) and \(s_{\rm LR} = -x\), as in HSE06-type functionals. The Coulomb matrix is always built with the full-range \(1/r_{12}\) operator. Scaling the exchange matrix by the hybrid’s exchange fraction is therefore already done by the plan; what the caller receives is the matrix that enters the Fock matrix.

Energies and Nuclear Gradients#

The energies associated with the two matrices are the quadratic forms

\[E_J[D] = \sum_{pqrs} D_{pq}\,(pq|rs)\,D_{rs} = \sum_{pq} D_{pq}\,J_{pq}\]
\[E_K[D] = \sum_{pqrs} D_{pq}\,(pr|g_\omega|qs)\,D_{rs} = \sum_{pq} D_{pq}\,K_{pq}\]

For a closed-shell Hartree–Fock or hybrid-DFT wavefunction with total density \(D\), the two-electron energy is \(\tfrac{1}{2} E_J[D] - \tfrac{1}{4} E_K[D]\) (with the exchange fraction folded into \(g_\omega\)); the factors are the caller’s, cuEST returns the bare quadratic forms and their derivatives.

The gradient routines return, for each density matrix in the batch, the derivative of these energies with respect to the nuclear coordinates \(\vec R_A\) at fixed density-matrix coefficients:

\[\nabla_A E_J[D] = \sum_{pqrs} D_{pq}\,\big(\nabla_A (pq|rs)\big)\,D_{rs}\]
\[\nabla_A E_K[D] = \sum_{pqrs} D_{pq}\,\big(\nabla_A (pr|g_\omega|qs)\big)\,D_{rs}\]

Only the explicit dependence of the integrals on the positions of the basis-function centers is differentiated. The response of the density to the displacement and the overlap (Pulay) term are not included: in the usual SCF gradient they are assembled from the energy-weighted density and the overlap derivative, so these routines supply exactly the two-electron integral derivative contribution that a gradient program needs. The output has shape (numDensityMatrices, natom, 3), one gradient per density matrix.

Bilinear Forms#

The quadratic forms above have bilinear counterparts in two density matrices,

\[E_J[D, D'] = \sum_{pqrs} D_{pq}\,(pq|rs)\,D'_{rs} = \sum_{pq} D_{pq}\,J[D']_{pq}\]
\[E_K[D, D'] = \sum_{pqrs} D_{pq}\,(pr|g_\omega|qs)\,D'_{rs} = \sum_{pq} D_{pq}\,K[D']_{pq}\]

and cuEST provides their nuclear gradients, again at fixed coefficients, for a batch of density pairs. The forms are symmetric in their two arguments, reduce to the quadratic forms at \(D' = D\), and are related to them by the polarization identity

\[\nabla_A E[D, D'] = \tfrac{1}{2}\left(\nabla_A E[D + D'] - \nabla_A E[D] - \nabla_A E[D']\right).\]

The bilinear routines replace the three gradient evaluations of the right-hand side by one call, and they accept pairs whose members differ in character: a guess or difference density against a converged one, or a response density against the SCF density, as needed in coupled-perturbed SCF and in the gradient of correlated and excited-state methods. The densities need not be positive semidefinite: a difference density \(D' = D_2 - D_1\) is an ordinary input.

Integral Screening#

The cost of a direct build is governed by how many shell quartets have to be evaluated. cuEST applies two levels of screening.

The first level is a property of the shell-pair list: pairs \(pq\) whose basis functions do not overlap appreciably, as judged by the magnitude of their Gaussian product, are dropped when the cuestAOPairList_t is created, under the thresholdPQ argument of cuestAOPairListCreate, and are never seen by the plan. The second level is derived from the Cauchy–Schwarz inequality for the repulsion integrals [2],

\[|(pq|rs)| \le Q_{pq}\,Q_{rs}, \qquad Q_{pq} = (pq|pq)^{1/2} .\]

It is applied at compute time to every surviving quartet and is weighted by the density. The contribution of a quartet to the Coulomb and to the exchange matrix is bounded by

\[|(pq|rs)\, D_{rs}| \le Q_{pq}\, Q_{rs}\, \max|D_{rs}|\]
\[|(pr|qs)\, D_{rs}| \le Q_{pr}\, Q_{qs}\, \max|D_{rs}|\]

where the maxima run over the functions of the shells involved, and quartets whose bound falls below the density Schwarz threshold are skipped. The gradient routines use the same screening strategy as the energy routines: the same pair-list sparsity, the same density-weighted Schwarz bounds applied to the derivative contributions, and the same threshold with the same meaning, so a gradient evaluated at a given threshold is consistent with the energy evaluated at that threshold. For the bilinear forms both densities enter the bound, so a pair with a sparse member costs much less than the gradient of their sum.

The threshold is an attribute of each routine’s own compute-parameters object (for example CUEST_DIRECTCOULOMBCOMPUTE_PARAMETERS_DENSITY_SCHWARZ_THRESHOLD for the Coulomb matrix; each routine’s entry in the C API reference names its attribute). Its default is \(10^{-13}\); it bounds the magnitude of each neglected contribution, so the error in a matrix element or a gradient component is of that order times the number of skipped quartets, and a value of 0 disables the screening entirely, which is useful for validating a result against a reference program. Because the bound is weighted by the density, an SCF driver that builds the Fock matrix from difference densities gets progressively more screening as the iterations converge, at no loss of accuracy. The density Schwarz threshold is the quantity to adjust, not thresholdPQ, when a tighter two-electron contribution is required.

JIT Compilation Times#

The direct routines specialize their kernels to the basis set at run time. The first call into a routine on a given machine compiles the kernels it needs and is therefore slower than every later call; the compiled kernels are cached on disk and reused by all subsequent runs (see Disk Caching). Each routine’s *_JIT_USAGE_MODE attribute selects the JIT-specialized path (CUEST_JIT_USAGE_MODE_ON, the default in the cuEST CUDA 13 package) or the precompiled path (CUEST_JIT_USAGE_MODE_OFF, the only path in the CUDA 12 package).

The table gives the cold compilation time of each routine, that is, the one-time cost of compiling its kernels when no cache holds them yet. Larger basis sets contain higher angular momenta and therefore more and larger kernels, which is why the time grows from def2-SVP to def2-QZVP. Each figure was measured for one routine in isolation; the sum of the figures is an upper bound on the cost of running several routines in one program, since any kernels they share are compiled once.

Note

These measurements were taken on an NVIDIA GB10 GPU (driver 580.126.09) with CUDA Toolkit 13.0 and the default of 16 JIT compile threads, for a spherical-harmonic basis on a small organic molecule (C, N, O, H). The figures depend on the basis set and on the elements present, which decide the set of kernels, and only weakly on the molecule’s size. Absolute times are hardware- and toolchain-dependent; treat them as relative indicators.

Table 12 Cold-cache JIT compilation time of the direct routines (seconds)#

Basis

Coulomb matrix

Exchange matrix

Coulomb gradient

Exchange gradient

def2-SVP

1.2

2.2

1.9

1.9

def2-TZVP

3.6

7.2

6.0

5.0

def2-QZVP

9.4

14.5

17.2

10.1

References#