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 cupy, tensordot (default) and einsum. tensordot is faster than einsum. If DenseLinalgFactory is used, the memory requirement scales roughly as \(3N^4\). Due to the storage of the two-electron integrals, the total amount of memory increases to \(4N^4\)

Note

If Cupy is not available or unsuccessful, td is selected instead.

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 | None) the flavor of tensor contraction operations used. Either cupy, td or einsum (default None)

Note

PyBEST takes the most efficient tensor contraction operations for specific contractions. By default, selected operations are exported to the GPU using Cupy. If Cupy is not available, td is selected. einsum is taken if all other flavors are unsupported.

We do not recommend changing the default unless you know what you are doing.

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).