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

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

    :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-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 ionized 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``).