..
    : PyBEST: Pythonic Black-box Electronic Structure Tool
    : Copyright (C) 2016-- The PyBEST Development Team
    :
    : This file is part of PyBEST.
    :
    : PyBEST is free software; you can redistribute it and/or
    : modify it under the terms of the GNU General Public License
    : as published by the Free Software Foundation; either version 3
    : of the License, or (at your option) any later version.
    :
    : PyBEST is distributed in the hope that it will be useful,
    : but WITHOUT ANY WARRANTY; without even the implied warranty of
    : MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    : GNU General Public License for more details.
    :
    : You should have received a copy of the GNU General Public License
    : along with this program; if not, see <http://www.gnu.org/licenses/>
    : --


.. _user_ip_long:

The IP module with various CC reference functions
#################################################

Please, first read the Quick Guide on all available IP-CC methods :ref:`here <user_ipcc_intro>`.

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 :py:class:`~pybest.io.iodata.IOData` container attributes
mentioned in the Quick Guide above, the :py:class:`~pybest.ip_eom.xip_base.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


.. _ip_keywords:

Summary of keyword arguments
============================

The :py:class:`~pybest.ip_eom.eom_base.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 :math:`3N^4`. Due to the storage of the two-electron integrals,
                 the total amount of memory increases to :math:`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``).


.. _ip_trouble_shooting:

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:

  .. code-block:: python

      # 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:

  .. code-block:: python

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