..
    : 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 ``tensordot``
                 (default) and ``einsum``. ``tensordot`` is faster than ``einsum``,
                 but requires more memory. If ``DenseLinalgFactory`` is used,
                 the memory requirement scales as :math:`2N^4` for ``einsum``
                 and :math:`3N^4` for ``tensordot``, respectively. Due to the
                 storage of the two-electron integrals, the total amount of memory
                 increases to :math:`3N^4` for ``einsum`` and :math:`4N^4` for
                 ``tensordot``, respectively

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

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