16.2. The IP module with various CC reference functions

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

Since most of the IP-CC flavors implemented in PyBEST offer similar functionality, all features mentioned below are applicable to all IP-CC methods if not mentioned otherwise. All modules support only the Davidson diagonalization of the EOM Hamiltonian.

In addition to the IOData container attributes mentioned in the Quick Guide above, the RXIPCC 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

e_ref

The total energy of the CC reference function

16.2.1. Summary of keyword arguments

The RIPCC module supports various keyword arguments that allow us to steer the optimization of ionized states (ionization 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.

nhole

(int) the number of hole operators to describe the (ionized) states (default 2 for IP, 3 for DIP)

nroot

(int) the number of targeted (ionized) states (default 1)

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.

threshold

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

dump_cache

(boolean) effective Hamiltonian elements are loaded and dumped to the disk whenever needed. Since large arrays are dumped to/read from disk, this implementation is slower but more memory-effective (default True if the number of active orbitals exceeds 300). This feature is only supported for all DIP models.

Some keyword arguments are working together with the Davidson solver:

tolerance

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

tolerancev

(float) optimization threshold for each ionized state eigenvector (default 1e-5)

maxiter

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

nguessv

(int) total number of guess vectors (default nroots*5, that is, 5 vectors per ionized state)

maxvectors

(int) maximum number of Davidson vectors. If additional vectors are added, a subspace collapse is performed (default nroots*20, that is, 20 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).

16.2.2. Trouble Shooting

Below, we list some possible difficulties and common problems when optimizing an IP or DIP solution.

• Davidson did not converge all roots:

  In some cases, the Davidson diagonalization does not capture the proper (lowest-lying) roots. To tweak convergence, increasing the number of initial guess vectors and/or the number of targeted roots helps:

  # Change the keyword arguments of nroot=10
  ip_output = ip(kin, ne, eri, cc_output, nroot=10)
  # Or increase in addition nguessv=60 (or some other bigger number)
  ip_output = ip(kin, ne, eri, cc_output, nroot=10, nguessv=60)
  

• Not enough memory during Davidson diagonalization:

  If you target a lot of roots and keep a lot of intermediate states, the Davidson diagonalization might cost a lot of memory (to store all Davidson vectors in the RAM). To overcome this problem, the maximum number of Davidson vectors can be reduced so that a subspace collapse is performed more frequently. This option should be combined together with restricting the initial number of guess vectors to prevent the problem from the start:

  # Target 10 roots, but decrease the number of guess and Davidson vectors to 20
  # (by default, up to 200 vectors are kept in memory)
  ip_output = ip(kin, ne, eri, cc_output, nroot=10, nguessv=20, maxvectors=20)
  # The number of guess vectors can be bigger than the number of Davidson vectors.
  # After the first iteration, a subspace collapse is performed
  ip_output = ip(kin, ne, eri, cc_output, nroot=10, nguessv=40, maxvectors=20)