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

The EOM module with a pCCD reference function
#############################################

Please, first read the Quick Guide on EOM-pCCD available :ref:`here <qg_eompccd>`.

.. _eom_pccd:

EOM-pCCD and EOM-pCCD+S
=======================

If you use this module, please cite [boguslawski2016a]_ and [boguslawski2017c]_.

In addition to the :py:class:`~pybest.io.iodata.IOData` container attributes
mentioned in the Quick Guide above, the :py:class:`~pybest.eomcc.eom_cc.REOMpCCD`
and :py:class:`~pybest.eomcc.eom_cc.REOMpCCDS` containers include the following
information

    :orb_a: A copy of the orbitals used in the pCCD reference calculation
    :olp:   The overlap integrals used in the pCCD calculation

Due to their simplicity, the effective Hamiltonian of any EOM-pCCD model can be
explicitly constructed and exactly diagonalized. If you wish to solve for the
eigenvalues and eigenvalues iteratively, you can use the Davidson
diagonalizer using the corresponding ``davidson`` keyword argument. 
For instance, if you target the excited states of large systems, the exact diagonalization
might be prohibitive. For very large systems, we thus recommend to keep the default setting and exploit the
Davidson diagonalizer,

.. literalinclude:: ../src/pybest/data/examples/eom/reompccd_water_cc-pvdz.py
    :lines: 69-70

If you, however, want to use exact diagonalization, you can do this by 
setting the ``davidson`` keyword argument to ``False``. 

.. note::

    The ``davidson`` keyword argument works for all
    :py:class:`~pybest.eomcc.eom_cc.REOCC` modules in PyBEST.

.. _eom_pccd_keywords:

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

The :py:class:`~pybest.eomcc.eom_cc.REOCC` module supports various keyword
arguments that allow us to steer the optimization of excited states (excitation
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.

    :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

    :nroot: (int) the number of targeted states, including the ground state
             (default ``2``)

    :davidson: (boolean) type of solver used. If set to ``True`` PyBEST's
                internal Davidson diagonalizer is used, where only the lowest
                ``nroot`` states are optimized. If set to ``False``, only the
                lowest ``nroot`` are returned and printed (default ``True``)

                .. note::

                    For very large systems switching ``davidson`` to ``True``
                    might save memory. For small- and medium-sized systems, an
                    exact diagonalization is typically of similar cost due to the
                    simplicity of the model.

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

    :tco: (str) the flavor of tensor contraction operations used.
           Either ``td`` or ``einsum`` (default ``td``)
           
           .. note::

                ``tco`` has only effect if multiple operations are supported.
                Otherwise, PyBEST always refers to ``einsum``.

Some keyword arguments are only working together with the ``davidson`` solver.
If exact diagonalization is used, they have no effect.

    :tolerance: (float) optimization threshold for each excitation energy
                (default ``1e-6``)

    :tolerancev: (float) optimization threshold for each excited 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 excited 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 downed significantly
              (default ``False``).


.. _eom_pccd_examples:

Example Python scripts
======================

Several complete examples can be found in the directory ``data/examples/eom``.

EOM-pCCD and EOM-pCCD+S calculations on the water molecule
----------------------------------------------------------

This is a basic example of how to perform a EOM-pCCD and EOM-pCCD+S calculation in PyBEST.
This script performs a RHF calculation followed by a pCCD calculation and two
different EOM flavors with a pCCD reference function
on the water molecule using the cc-pVDZ basis set.

.. literalinclude:: ../src/pybest/data/examples/eom/reompccd_water_cc-pvdz.py
    :caption: data/examples/eom/reompccd_water_cc-pvdz.py
    :lines: 3-


EOM-pCCD and EOM-pCCD+S calculations on the water molecule using a frozen core
------------------------------------------------------------------------------

This is a basic example on how to perform a EOM-pCCD and EOM-pCCD+S calculation in PyBEST.
This script performs a RHF calculation followed by a pCCD calculation and two
different EOM flavors with a pCCD reference function
on the water molecule using the cc-pVDZ basis set and freezing the lowest orbital.

.. literalinclude:: ../src/pybest/data/examples/eom/reompccd_core_water_cc-pvdz.py
    :caption: data/examples/eom/reompccd_core_water_cc-pvdz.py
    :lines: 3-