14.2. The EOM module with various CC reference functions

Please, first read the Quick Guide on all available EOM-CC methods here.

Since most of the EOM-CC flavors implemented in PyBEST offer similar functionality, we will group them in different subsections depending on the supported features of the EOM-CC method in question. Specifically, we distinguish between modules that

  1. support only the Davidson diagonalization of the EOM Hamiltonian

  2. support both exact and Davidson diagonalization of the EOM Hamiltonian

In addition to the IOData container attributes mentioned in the Quick Guide above, the REOMCC containers include the following information

orb_a:

A copy of the orbitals used in the CC reference calculation

olp:

The overlap integrals used in the CC reference calculation

14.2.1. Exact diagonalization

Due to their simplicity, the effective Hamiltonian of EOM-CCS, EOM-pCCD, EOM-pCCD+S, and EOM-pCCD-CCS can be explicitly constructed and exactly diagonalized. If you wish to solve for the eigenvalues and eigenvalues iteratively, you can specify the Davidson diagonalizer using the corresponding davidson keyword argument. For instance, if you target the excited states of large systems, the exact diagonalization might be prohibitive. For very large systems, we thus recommend to keep the default setting and exploit the Davidson diagonalizer,

###############################################################################
### Do REOM-pCCD+S calculation using exact diagonalization ####################
###############################################################################
eom = REOMpCCDS(lf, occ_model)
eom_output = eom(kin, ne, eri, oopccd_output, nroot=3, davidson=False)

If you, however, want to use exact diagonalization, you can do this by setting the davidson keyword argument to False.

Note

The davidson keyword argument works for all REOMCC modules in PyBEST.

14.2.2. Summary of keyword arguments

The REOMCC module supports various keyword arguments that allow us to steer the optimization of excited states (excitation energies and the eigenvectors of the targeted states). In the following, all supported keyword arguments are listed together with their default values. Please note that for most cases, the default values should be sufficient to reach convergence.

indextrans:

(str) 4-index Transformation. The choice between tensordot (default) and einsum. tensordot is faster than einsum, but requires more memory. If DenseLinalgFactory is used, the memory requirement scales as \(2N^4\) for einsum and \(3N^4\) for tensordot, respectively. Due to the storage of the two-electron integrals, the total amount of memory increases to \(3N^4\) for einsum and \(4N^4\) for tensordot, respectively

nroot:

(int) the number of targeted (excited) states, excluding the ground state (default 1)

davidson:

(boolean) type of solver used. If set to True PyBEST’s internal Davidson diagonalizer is used, where only the lowest nroot states are optimized. If set to False, only the lowest nroot are returned and printed (default True)

Note

For very large systems switching davidson to True might save memory. For small- and medium-sized systems, an exact diagonalization is typically of similar cost due to the simplicity of the model.

threshold:

(float) printing threshold for the eigenvectors. If a (row) element of civ_ee is larger than the threshold in absolute value, the corresponding excitation contribution is printed (default 0.1)

tco:

(str) the flavor of tensor contraction operations used. Either td or einsum (default td)

Note

tco has only effect if multiple operations are supported. Otherwise, PyBEST always refers to einsum.

Some keyword arguments are only working together with the davidson solver. If exact diagonalization is used, they have no effect. These are:

tolerance:

(float) optimization threshold for each excitation energy (default 1e-6)

tolerancev:

(float) optimization threshold for each excited state eigenvector (default 1e-4)

maxiter:

(int) maximum number of total Davidson diagonalization steps (default 200)

nguessv:

(int) total number of guess vectors (default (nroots-1)*4+1, that is, 4 vectors per excited state)

maxvectors:

(int) maximum number of Davidson vectors. If additional vectors are added, a subspace collapse is performed (default (nroots-1)*10, that is, 10 vectors per excited state)

todisk:

(boolean) if set to True all intermediates are stored to disk. This reduces memory requirements. However, due to the intensive I/O operations, the code is slowed down significantly (default False).