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

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

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

Since most of the EA-CC flavors implemented in PyBEST offer similar functionality,
all features mentioned below are applicable to all EA-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.ea_eom.rea_base.RREACC`
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


.. _ea_keywords:

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

The :py:class:`~pybest.ea_eom.eom_base.REACC` module supports various keyword
arguments that allow us to optimize electron-attached states (electron affinities and the eigenvectors).
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.

    :nparticle: (int) the number of particle operators to describe the (electron-attached) states
            (default ``2`` for EA, ``3`` for DEA)

    :nroot: (int) the number of targeted (electron-attached) 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_ea`` is larger than the threshold in absolute
                value, the corresponding electron attachment 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).

Some keyword arguments are working together with the ``Davidson`` solver:

    :tolerance: (float) convergence threshold for each electron affinities
                (default ``1e-6``)

    :tolerancev: (float) convergence threshold for each eigenvector optimization
                 (default ``1e-5``)

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

    :nguessv: (int) total number of guess vectors (default ``nroots*10``,
              that is, 10 vectors per electron-attached 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``).