Seminumerical exchange (SGX)#

Modules: pyscf.sgx

The SGX module implements seminumerical computation of the exchange matrix.

Introduction#

Direct computation of the Hartree-Fock exchange matrix in the atomic orbital basis scales poorly with system size. To achieve better scaling, one three-dimensional integral in the 6-dimensional two-electron integrals can be computed analytically, while the other can be evaluated on a real-space grid, as proposed by Friesner [80]. The PySCF implementation resembles the chain-of-spheres (COSX) algorithm of Neese et al. [81], but uses more conservative grids and a slightly different P-junction screening function. Overlap fitting is used to reduce aliasing errors [82]. SGX scales as \(O(N^2)\) with system size, as opposed to the \(O(N^4)\) scaling of analytical exchange [81].

Usage and Example#

Any scf.hf.SCF object mf can be converted to an equivalent object that computes the Coulomb and exchange matrices with SGX instead of analytical integration by calling sgx.sgx_fit(mf).

#!/usr/bin/env python

'''
This example shows how to use pseudo spectral integrals in SCF calculation.
'''

from pyscf import gto
from pyscf import scf
from pyscf import sgx
mol = gto.M(
    atom='''O    0.   0.       0.
            H    0.   -0.757   0.587
            H    0.   0.757    0.587
    ''',
    basis = 'ccpvdz',
)
# Direct K matrix for comparison
mf = scf.RHF(mol)
mf.kernel()

# Using SGX for J-matrix and K-matrix, without using P-junction screening
mf = sgx.sgx_fit(scf.RHF(mol), pjs=False)
mf.kernel()

# Using RI for Coulomb matrix while K-matrix is constructed with SGX method
mf.with_df.dfj = True
mf.kernel()

# Turn on P-junction screening to accelerate large calculations
# (uses algorithm similar to COSX)
mf.with_df.pjs = True
mf.kernel()

# direct_scf_sgx turns on direct SCF for SGX
# JK matrix is rebuilt from scratch every rebuild_nsteps steps
mf.direct_scf_sgx = True
# If grids_level_i == grids_level_j, no grid switch occurs
mf.with_df.grids_level_i = 1
mf.kernel()

# If dfj is off at runtime, it is turned on and a user warning is issued
# because SGX-J cannot be used with P-junction screening.
mf.with_df.dfj = False
mf.kernel()

# Use direct J-matrix evaluation (slow, primarily for testing purposes)
mf = sgx.sgx_fit(scf.RHF(mol), pjs=False)
mf.with_df.direct_j = True
mf.with_df.dfj = False
mf.kernel()

In this case, the error of DFJ+SGX compared to analytical exchange is about 0.03 mEh. The line

mf.with_df.dfj = True

specifies to compute the Coulomb matrix using density fitting (DF-J) while using SGX for the exchange matrix.

The pjs option turns on P-junction screening, which means that the three-center integrals are screened by the density matrix. If a three-center integral gets contracted only with negligibly small density matrix elements, it is not computed. This feature can only be used with dfj=True. If dfj=False and pjs=True, dfj is set to True, and a warning is issued. The P-junction screening threshold is determined by mf.direct_scf_tol.

Direct evaluation of the J matrix can be used by setting mf.with_df.direct_j = True, but this is much slower than SGX-J or DF-J and only intended for testing purposes.

Adjustable Parameters#

Calling the sgx_fit function on an scf.hf.SCF object returns an equivalent SGXHF object with a with_df attribute that handles SGX integration. To use a non-default auxiliary basis (for dfj=True), auxbasis can be specified in the call to sgx_fit. In addition, there are various adjustable parameters for SGX:

with_df attributes:

  • grids_level_i: The grid level to use for initial SCF iterations.

  • grids_level_f: The grid level to use for final SCF iterations.

  • grids_thrd: The grid points where no atomic orbital is significant (has a value greater than this threshold) are removed from consideration.

  • grids_switch_thrd: The threshold for the magnitude of the change in the density matrix that triggers the switch from the initial grid specified by grids_level_i to the final grid specified by grids_level_f.

  • blockdim: The maximum number of grid points to loop over at once. The number of grid points per batch is the minimum of blockdim and the maximum number of points allowed by the memory available for the calculation. The maximum memory can be adjusted by setting the max_memory attribute, which is initially set to mol.max_memory, the max memory setting for the Mole object.

  • dfj: If True, density fitting is used for the J-matrix. If False, SGX is used.

  • direct_j: If True, direct evaluation of the J-matrix is used (slow, for testing only).

  • pjs: If True, P-junction screening is used. Threshold determined by direct_scf_tol.

SGXHF attribute:

  • direct_scf_sgx: Whether to use direct SCF within the SGX module, meaning that the J and K matrices are evaluated from the difference in the density matrix from the previous iteration.

  • rebuild_nsteps: Rebuild the SGX JK matrix from scratch every rebuild_nsteps steps (default 5). Set to 0 to turn off rebuilding the JK matrix (Warning: This can cause creeping numerical error).