CI: Configuration Interaction

Code author: Daniel G. A. Smith, C. David Sherrill, and Matthew L. Leininger

Section author: Daniel G. A. Smith and C. David Sherrill

Module: Keywords, PSI Variables, DETCI

Configuration interaction (CI) is one of the most general ways to improve upon Hartree–Fock theory by adding a description of the correlated motions of electrons. Simply put, a CI wavefunction is a linear combination of Slater determinants (or spin-adapted configuration state functions), with the linear coefficients being determined variationally via diagonalization of the Hamiltonian in the given subspace of determinants. For a “single-reference” CI based on reference function \(| \Phi_0 \rangle\), we can write the CI expansion as follows:

(1)\[| \Psi \rangle = c_0 | \Phi_0 \rangle + \sum_i^{\rm occ} \sum_a^{\rm vir} c_i^a | \Phi_i^a \rangle + \sum_{i<j}^{\rm occ} \sum_{a<b}^{\rm vir} c_{ij}^{ab} | \Phi_{ij}^{ab} \rangle + \sum_{i<j<k}^{\rm occ} \sum_{a<b<c}^{\rm vir} c_{ijk}^{abc} | \Phi_{ijk}^{abc} \rangle + \cdots\]

The simplest standard CI method that improves upon Hartree–Fock is a CI that adds all singly \(| \Phi_i^a \rangle\) and doubly \(| \Phi_{ij}^{ab} \rangle\) substituted determinants (CISD) to the reference determinant \(| \Phi_0 \rangle\). The CISD wavefunction has fallen out of favor because truncated CI wavefunctions are not size-extensive, meaning that their quality degrades for larger molecules. MP2 is a less expensive alternative giving results similar to those of CISD for small molecules, but the quality of MP2 does not degrade for larger molecules. Coupled-cluster singles and doubles (CCSD) is another size-extensive alternative; it is only slightly more costly computationally than CISD, but it typically provides significantly more accurate results.

The CI code in PSI4 is described in detail in [Sherrill:1999:CI]. For the reasons stated above, the CI code in PSI4 is not optimized for CISD computations, and it uses data structures that are particularly inefficient for CISD and may result in the program running out of memory and crashing for CISD except on very small molecules. Instead, DETCI was designed to be efficient in handling more highly correlated CI wavefunctions that can be helpful in more challenging cases such as highly strained molecules or bond breaking reactions. The CI code is based on the fast, determinant-based string formalism of Handy [Handy:1980]. It can solve for restricted active space configuration interaction (RAS CI) wavefunctions as described by Olsen, Roos, Jorgensen, and Aa. Jensen [Olsen:1988]. Excitation-class selected multi-reference CI wavefunctions, such as second-order CI, can be formulated as RAS CI’s. A RAS CI selects determinants for the model space as those which have no more than \(n\) holes in the lowest set of orbitals (called RAS I) and no more than \(m\) electrons in the highest set of orbitals (called RAS III). An intermediate set of orbitals, if present (RAS II), has no restrictions placed upon it. All determinants satisfying these rules are included in the RAS CI.

The DETCI module is also very efficient at computing full configuration interaction wavefunctions, and it is used in this capacity in the complete-active-space self-consistent-field (CASSCF) code. It can also perform approximate CASSCF computations in which one uses RAS restrictions on the CI excitations, rather than doing a full CI in the active space. This is called a RASSCF. CASSCF and RASSCF computations are types of multi-configurational self-consistent-field procedures, and are described in MCSCF: Multi-Configurational Self-Consistent-Field.

As mentioned above, the DETCI module is designed for challenging chemical systems for which simple CISD is not suitable. Because CI wavefunctions which go beyond CISD (such as RAS CI) are fairly complex, typically the DETCI code will be used in cases where the tradeoffs between computational expense and completeness of the model space are nontrivial. Hence, the user is advised to develop a good working knowledge of multi-reference and RAS CI methods before attempting to use the program for a production-level project. This user’s manual will provide only an elementary introduction to the most important keywords. Additional information is available in the complete list of keywords for DETCI provided in Appendix DETCI.

For single-reference CI computations, the easiest way to invoke a CI computation with DETCI is simply to call energy(), optimize(), etc., with the common name for that CI wavefunction, like energy('cisd') for a CISD single-point energy. The Python driver recognizes cisd, cisdt, and cisdtq. As mentioned above, codes written specifically for CISD will be more efficient than DETCI for a CISD computation, and energy('cisd') by default will call other, more efficient modules. To force a CISD computation with DETCI, set QC_MODULE = DETCI.

Higher order single-reference CI wavefunctions, like those including singles through 6-fold excitations, can be invoked using numbers, like ci6. A full CI can be specified by fci. More complicated CI computations, like RASCI, can be performed by setting the appropriate keywords and calling the module generically like energy('detci'). The latter approach will also work for any of the previously-mentioned CI wavefunctions for which the driver has built-in shortcuts, so long as the relevant options (especially EX_LEVEL) are set appropriately. Some examples of single-refence CI, RASCI, and full CI computations are provided in psi4/samples.

Orbital spaces for CI computations

CI (e.g., CISD, FCI)

RASCI

CASCI

FROZEN_UOCC

FROZEN_UOCC

FROZEN_UOCC [1]

(all orbitals not in FROZEN_UOCC or FROZEN_DOCC are included in CI)

RAS4

ACTIVE

RAS3

RAS2

RAS1

FROZEN_DOCC

FROZEN_DOCC

FROZEN_DOCC

The table above shows the relevant orbitals spaces for CI computations (an analogous table for MCSCF is also available). The third column of the table refers to CASCI, in which a full CI is performed in some smaller set of active orbitals; it is equivalent to CASSCF except without any orbital optimization. It can be invoked via energy('fci') with appropriate values selected for FROZEN_DOCC and ACTIVE. For CI computations, there is no difference between FROZEN_DOCC and RESTRICTED_DOCC, or between FROZEN_UOCC and RESTRICTED_UOCC. There are differences between these keywords for MCSCF: Multi-Configurational Self-Consistent-Field.

Basic DETCI Keywords

REFERENCE

Reference wavefunction type

  • Type: string

  • Possible Values: RHF, ROHF

  • Default: RHF

R_CONVERGENCE

Convergence criterion for CI residual vector in the Davidson algorithm (RMS error). The default is 1e-4 for energies and 1e-7 for gradients.

EX_LEVEL

The CI excitation level

  • Type: integer

  • Default: 2

FCI

Do a full CI (FCI)? If TRUE, overrides the value of EX_LEVEL

FROZEN_DOCC

An array containing the number of frozen doubly-occupied orbitals per irrep (these are not excited in a correlated wavefunction, nor can they be optimized in MCSCF. This trumps NUM_FROZEN_DOCC and FREEZE_CORE

  • Type: array

  • Default: No Default

RESTRICTED_DOCC

An array giving the number of restricted doubly-occupied orbitals per irrep (not excited in CI wavefunctions, but orbitals can be optimized in MCSCF)

  • Type: array

  • Default: No Default

RESTRICTED_UOCC

An array giving the number of restricted unoccupied orbitals per irrep (not occupied in CI wavefunctions, but orbitals can be optimized in MCSCF)

  • Type: array

  • Default: No Default

FROZEN_UOCC

An array containing the number of frozen unoccupied orbitals per irrep (these are not populated in a correlated wavefunction, nor can they be optimized in MCSCF. This trumps NUM_FROZEN_UOCC

  • Type: array

  • Default: No Default

CI_MAXITER

Maximum number of iterations to diagonalize the Hamiltonian

  • Type: integer

  • Default: 24

NUM_ROOTS

number of CI roots to find

  • Type: integer

  • Default: 1

ICORE

Specifies how to handle buffering of CI vectors. A value of 0 makes the program perform I/O one RAS subblock at a time; 1 uses entire CI vectors at a time; and 2 uses one irrep block at a time. Values of 0 or 2 cause some inefficiency in the I/O (requiring multiple reads of the C vector when constructing H in the iterative subspace if DIAG_METHOD = SEM), but require less core memory.

  • Type: integer

  • Default: 1

DIAG_METHOD

This specifies which method is to be used in diagonalizing the Hamiltonian. The valid options are: RSP, to form the entire H matrix and diagonalize using libciomr to obtain all eigenvalues (n.b. requires HUGE memory); OLSEN, to use Olsen’s preconditioned inverse subspace method (1990); MITRUSHENKOV, to use a 2x2 Olsen/Davidson method; and DAVIDSON (or SEM) to use Liu’s Simultaneous Expansion Method, which is identical to the Davidson method if only one root is to be found. The SEM method is the most robust, but it also requires \(2NM+1\) CI vectors on disk, where \(N\) is the maximum number of iterations and \(M\) is the number of roots.

  • Type: string

  • Possible Values: RSP, DAVIDSON, SEM

  • Default: SEM

OPDM

Do compute one-particle density matrix if not otherwise required?

TDM

Do compute the transition density? Note: only transition densities between roots of the same symmetry will be evaluated. DETCI does not compute states of different irreps within the same computation; to do this, lower the symmetry of the computation.

DIPMOM

Do compute the dipole moment?

MPN

Do compute the MPn series out to kth order where k is determined by MAX_NUM_VECS ? For open-shell systems REFERENCE is ROHF, WFN is ZAPTN), DETCI will compute the ZAPTn series. GUESS_VECTOR must be set to UNIT, HD_OTF must be set to TRUE, and HD_AVG must be set to orb_ener; these should happen by default for MPN = TRUE.

For larger computations, additional keywords may be required, as described in the DETCI section of the Appendix DETCI.

Spin Multiplicities of Higher Roots

As mentioned above, DETCI works in a basis of Slater determinants, rather than configuration state functions. The correct value of \(M_s\) is easily enforced by fixing the number of alpha and beta electrons to be constant across all determinants selected for the CI computation. However, determinant-based codes like DETCI do not necessarily enforce the correct spin \(S\). For example, diagonalizing the Hamiltonian in a space spanned by determinants with \(M_s = 0\) can yield both singlet and triplet solutions, because triplets (\(S = 1\)) also have an \(M_s = 0\) component. (Indeed, even higher spin multiplicities may be encountered if the excitation level is high enough). For closed-shell references with \(M_s = 0\), the program will assume by default that a singlet (\(S = 0\)) computation is desired, and will utilize alpha/beta interchange symmetries to speed up the computation (this is controlled by the advanced keyword MS0, which defaults to TRUE). Thus, if a user requests multiple roots (NUM_ROOTS = \(n\)), the program will typically return singlets and not triplets. However, if enough roots are sought, higher-multiplicities may enter in. This can be avoided by ensuring that all the guess vectors have the correct spin multiplicity, by setting CALC_S_SQUARED to TRUE). It is also possible to ask DETCI to compute roots of higher multiplicities. The desired value of spin may be provided by setting S = \(S\). Typically, it would be a good idea in this context to also set CALC_S_SQUARED to TRUE to ensure the guess roots have the right spin. However, be advised that seeking these higher roots may cause convergence problems, because roundoff may allow the lower-lying roots of lower multiplicities to re-enter the computation (reducing convergence criteria may help).

For open-shell systems, the MS0 keyword is typically not relevant, and there is no control over spin multiplicities of higher roots unless|detci__calc_s_squared| is used.

Arbitrary Order Perturbation Theory

The DETCI module is capable of computing energies for arbitrary order Møller–Plesset perturbation theory (MPn, for closed-shell systems with an RHF reference) and for Z-averaged perturbation theory (ZAPTn, open-shell systems with a ROHF reference). However, please note that these computations are essentially doing high-order CI (up to full CI) computations to obtain these results, and hence they will only be possible for very small systems (generally a dozen electrons or less).

The simplest way to run high-order perturbation theory computations is to call, e.g., energy('mp10') to invoke a MP10 computation or energy('zapt25') to invoke a ZAPT25 computation. This will automatically set several additional user options to their appropriate values. The program uses the Wigner (2n+1) rule to obtain higher-order energies from lower-order wavefunctions.

For the interested reader, the additional user options that are automatically set up by the calls above are as follows. A call like energy('mp10') sets MPN to TRUE. The program uses the Wigner (2n+1) rule by default (MPN_WIGNER = TRUE) and figures out what order of wavefunction is necessary to reach the desired order in the energy. The program then sets MAX_NUM_VECS to the required order in the wavefunction. By default, the requested n-th order energy is saved as the current energy to the process environment. ZAPTN works essentially the same way for an ROHF reference.

Arbitrary Order Coupled-Cluster Theory

This DETCI-based version of this feature is not yet released. However, the current version of the code does include an interface to Kallay’s MRCC code.

The DETCI module is also capable of computing arbitrary-order coupled-cluster energies, using an approach similar to that of Hirata and Bartlett [Hirata:2000:216], or of Olsen [Olsen:2000:7140]. Notably, the approach in DETCI also allows arbitrary-order active space coupled-cluster procedures. The general algorithm for doing this in DETCI is inefficient compared to optimized lower-order coupled-cluster codes and should not be used for CCSD, where the CCENERGY module is much more efficient. For higher-order CC (like CCSDT and beyond), the code is also not as efficient as the MRCC code by Kállay, to which PSI4 can interface (see Section Interface to MRCC by M. Kállay); however, it may allow certain truncations of the model space that might not be available presently in MRCC. For very small systems, the code can be useful for testing of, for example, CCSDTQ or its active-space CCSDtq analog [Piecuch:1999:6103].

To perform arbitrary-order coupled-cluster, set the DETCI option CC to TRUE, and set CC_EX_LEVEL (note: not EX_LEVEL) to the desired coupled-cluster excitation level, and invoke energy('detci'). Various other DETCI options have a similar option for coupled-cluster, usually named beginning with CC. The full list of options is given in Appendix DETCI.