Skip to content

GitLab

Last edited by Ben Link
Page history

SCF

Table of contents

Details

The SCF section handles the SCF parameters for the optimization of the reference wave functions specified in QM.REFERENCE. The SCF section is optional, and the default parameters are often sufficient. However, as SCF optimizations can often be non-trivial, it may be the case that these parameters must be adjusted for the optimization.

Keywords

Keyword Type Description Default
NEO Boolean Whether or not Nuclear-electronic Orbital method is included FALSE
GUESS String Initial guess for reference wave function SAD
PROT_GUESS String Initial guess for nuclear wave function (only valid for NEO methods) CORE
FIELD Multiline string Static external field specification in which to perform optimization None
ALG String Algorithm for SCF procedure (e.g. NR, Conventional, Skip) CONVENTIONAL
ENETOL Double precision float Convergence tolerance for the change in total energy 10^{-10}
DENTOL Double precision float Convergence tolerance for the root-mean-squared change in the one particle density matrix 10^{-8}
FDCTOL Double precision float Convergence tolerance for Max(Gradient) 10^{-8}
MAXITER Integer Maximum number of SCF iterations 128
INCFOCK Boolean Whether or not to perform an incremental Fock build throughout the SCF for improved screening TRUE if ERI formation is DIRECT; FALSE otherwise
NINCFOCK Integer Number of SCF iterations after which to start the incremental Fock build 20
EXTRAP Boolean Whether to do extrapolation of Fock matrix with DIIS and damping TRUE
DIIS Boolean Whether to use direct inversion of the iterative subspace extrapolation TRUE
DIISALG String Algorithm for DIIS (e.g. CDIIS, EDIIS or CEDIIS) CEDIIS
SWITCH Double precision float Tolerance of Max(Gradient) to switch from EDIIS to CDIIS in CEDIIS 0.05
NKEEP Integer Number of previous iterations to track for DIIS/SOSCF 10
DAMP Boolean Whether to damp Fock matrix changes TRUE
DAMPPARAM Double precision float Damping parameter 0.7
DAMPERROR Double precision float Energy difference after which to turn off Fock damping 10^{-3}
PRINTMOS Integer Control printing of MO information after SCF procedure 0
SWAPMO Multiline string Swap ordering of MOs for SCF.GUESS=READMO None
NRAPPROX String Which algorithm to approximate the Hessian (e.g. FULL, BFGS, SR1, GradDescent) BFGS
NRTRUST Double precision float Maximum displacement along search direction 0.1
NRLEVELSHIFT Double precision float Amount to add to the diagonal Hessian 0.0

The NEO Keyword

The NEO keyword assigns whether or not the nuclear-electronic orbital approach is used to describe quantum nuclei. By default this is set to false. Note that for a NEO SCF call to be valid, the molecule must have specified quantum nuclei and the QM/PROTQM sections are populated with the nuclear reference. A nuclear basis must also be defined in the PBasis section.

The GUESS and PROTGUESS Keywords

The GUESS and PROTGUESS keywords define the method for producing the initial one-particle reduced density matrix (1PDM) in the SCF procedure for an electronic and protonic reference (if NEO = True). Currently there are 5 options, with support for reading in Gaussian fchk files:

  1. CORE: Use the 1PDM from the core Hamiltonian
  2. SAD: Use the Superposition of Atomic Densities method
  3. READMO: Read MO coefficients from ChronusQ restart file (specified with -b) or old restart file (specified with -z).
  4. READDEN: Read 1PDM from ChronusQ restart file (specified with -b), old restart file (specified with -z), or scratch file (specified with -s). If restarting from 1PDM of different size or type, use -s to avoid errors with overwriting datasets of different size or type.
  5. FCHKMO: Read MO coefficients from ChronusQ scratch file (specified with -s), where the scratch file should be an fchk file from the Gaussian software package. ChronusQ does not match the default underlying basis representation in Gaussian (e.g., orthogonalization, primitive deletion, etc.) and we recommend using the following Gaussian IOp: IOp(3/60=-1).

The SWAPMO Keyword

The SWAPMO keyword is an optional keyword to be used in conjunction with SCF.GUESS=READMO. It swaps the ordering of MOs, which can be useful when trying to converge to a specific state. Below is a basic example that swaps the ordering of MOs 2 and 3.

[SCF]
guess=readmo
swapmo:
 2 3

Note that the swaps are applied sequentially. That means that the following example will result in the original orbital ordering.

[SCF]
guess=readmo
swapmo:
 2 3
 2 3

For the unrestricted case, the beta MOs can also be swapped. Below is an example that swaps two sets of alpha MOs (denoted A) and one set of beta MOs (denoted B). If no indication of spin is used, alpha (denoted A) will be assumed.

[SCF]
guess=readmo
swapmo:
 2 3 A
 4 5 A
 2 3 B

Note that for four-component calculations, the MO is ordered such that the first half of MOs are negative-energy, and the second half are normal electronic MOs. Thus, if one wants to swap between electronic MOs, an offset of total number of negative-energy MOs should be added.

The FIELD Keyword

The FIELD keyword specifies the static external field to be applied to the molecule. Currently, only electric or magnetic fields in the dipole approximation are supported. The format of the FIELD keyword is:

FIELD = FieldType Ix Iy Iz

where FieldType is one of ELECTRIC or MAGNETIC, and Ix/Iy/Iz are the intensities of the applied field in each cartesian direction in a.u.

The ALG Keyword

The ALG keyword specifies the algorithm used for the SCF procedure. Currently CONVENTIONAL first-order optimization is the default. Second-order methods like Newton-Raphson will be implemented in the near future. Additionally, SKIP skips the SCF cycles completely. This can be useful for analyzing the quality of an SCF guess or for saving time when a post-SCF treatment is desired.

The INCFOCK and NINCFOCK Keywords

The INCFOCK keyword is a boolean that turns on the incremental Fock build algorithm. In short, and incremental Fock build uses the difference density between the current and last SCF step to screen which electron-repulsion integrals aren't necessary to compute for certain Fock matrix elements from the coulomb and exchange matrices, speeding up the Fock build timing.

NINCFOCK then controls which SCF step the incremental Fock build procedure starts. The default is set to 20 since smaller density differences offer the greatest speed-up.

The PRINTMOS Keyword

The PRINTMOS Keyword controls the printing of MO information, which may include MO coefficients and the analysis of the angular momentum components of each MOs. This value could be

PRINTMOS print MO coefficient Analysis of Angular Moment Group Same Element of Atoms Sum over Alpha and Beta
0 ❌ ❌ ❌ ❌
1 ✅ ❌ ❌ ❌
2 ❌ ✅ ❌ ❌
3 ✅ ✅ ❌ ❌
4 ❌ ✅ ✅ ❌
5 ✅ ✅ ✅ ❌
6 ❌ ✅ ❌ ✅
7 ✅ ✅ ❌ ✅
8 ❌ ✅ ✅ ✅
9 ✅ ✅ ✅ ✅

Extrapolation Keywords

Currently, ChronusQ uses the direct inversion of the iterative subspace, also known as CDIIS,1 along with energy DIIS (EDIIS)2 and the combination of both (CEDIIS),2 to perform extrapolations of future Fock matrices in the SCF procedure. The commutator used is [\mathbf{F}, \mathbf{P}] where \mathbf{F} is the Fock matrix and \mathbf{P} is the 1PDM.

The DIIS and NKEEP Keywords

The DIIS keyword is just a boolean that tells ChronusQ wether or not to perform DIIS. The NKEEP keyword is an integer that decides how many previous Fock matrices are used for the extrapolation. The NKEEP keyword is also used in the approximate Newton-Raphson SCF algorithms using quasi-Newton updates (e.g. BFGS and SR1).3[]4

The DAMP, DAMPPARAM, and DAMPERROR Keywords

Fock damping is when the Fock matrix of the previous iteration is mixed in to the current step to damp large oscillations in energy.

  1. DAMP is the boolean for choosing to do damping, by default it is TRUE.
  2. DAMPARAM is a floating point value between 0 and 1 that represents the fraction of the previous Fock matrix to average into the current step for damping. By default the value is 0.7 meaning that 70% of the previous Fock matrix is mixed in.
  3. DAMPERROR is the energy tolerance at which damping is turned off. Since damping is most useful for early steps in the SCF when there can be large changes in the energy and density. By default the damping error threshold is set to 0.001 Hartree.

Example

For example, let's say we want to specify that during the SCF procedure in a ChronusQ job, we will use 12 Fock matrices for extrapolation, keep damping on until the energy change is less than 10^{-5}, and only mix in 50% of the previous Fock matrix for damping. Then, the [SCF] section will look like the following:

[SCF]
nkeep = 12
damperror = 1e-5
dampparam = 0.5

References

  1. Pulay, P. (1982). Improved SCF convergence acceleration. Journal of Computational Chemistry, 3(4), 556-560. ↩

  2. Kudin, K. N.; Scuseria, G. E.; Cancès, E. (2002). A Black-Box Self-Consistent Field Convergence Algorithm: One Step Closer. J. Chem. Phys. 116 (19), 8255–8261. ↩2 ↩

  3. Chaban, G.; Schmidt, M. W.; Gordon, M. S. (1997). Approximate Second Order Method for Orbital Optimization of SCF and MCSCF Wavefunctions. Theor. Chem. Acc. 97 (1-4), 88–95. ↩

  4. Neese, F. (2000). Approximate Second-Order SCF Convergence for Spin Unrestricted Wavefunctions. Chem. Phys. Lett. 2000, 325 (1-3), 93–98. ↩