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

Quick Guide: RCIS/RCID/RCISD
############################

This is a concise step-by-step guide to different CI calculations available in PyBEST.
An example input file for the water molecule can be found in the section :ref:`rci_example`.


Preliminaries
-------------

Before proceeding, it's imperative to review the general introduction outlined in :ref:`user_posthf_intro`. This part of the Documentation builds upon it.
PyBEST allows you also to perform Restricted Configuration Interaction calculations on top of any single-reference wave function. Similar to the previous modules,
we will assume the following names for all PyBEST objects

    :lf: A :py:class:`~pybest.linalg.base.LinalgFactory` instance (see :ref:`user_linalg_intro`).
    :occ_model: An Aufbau occupation model of the :py:class:`~pybest.scf.occ.AufbauOccModel`
                class
    :kin:   The kinetic energy integrals
    :ne:    The nucleus-electron attraction integrals
    :eri:   The two-electron repulsion integrals

Currently, PyBEST supports the following variants of CI calculations

    * restricted Configuration Interaction Singles (RCIS)
    * restricted Configuration Interaction Doubles (RCID)
    * restricted Configuration Interaction Singles and Doubles (RCISD)

For all methods with an RHF reference function, PyBEST supports two calculation techniques that introduce the wave function as a Slater determinant (SD) or configuration state function (CSF).
The CSF is the default.

.. _qg_rci:

RCI on top of RHF
-----------------

We assume that you have performed a restricted Hartree-Fock calculation, whose
results are stored in the :py:class:`~pybest.io.iodata.IOData` container ``hf_out``
(see :ref:`user_hf`).
The code snippet below demonstrates how to perform default RCIS/RCID/RCISD calculations with
an RHF reference function in PyBEST,

.. code-block:: python

    rcis = RCIS(lf, occ_model)
    rcis_out = rcis(kin, ne, eri, hf_out)

    rcid = RCID(lf, occ_model)
    rcid_out = rcid(kin, ne, eri, hf_out)

    rcisd = RCISD(lf, occ_model)
    rcisd_out = rcisd(kin, ne, eri, hf_out)

.. note::

    By default, only one root is calculated. That is, for :py:class:`~pybest.ci.rcis.RCIS`
    only the lowest-lying excited state is determined, while for :py:class:`~pybest.ci.rcid.RCID`
    and :py:class:`~pybest.ci.rcisd.RCISD` only the ground-state root is optimized.
    See :ref:`rci_keywords` for more details.


The results are returned as an :py:class:`~pybest.io.iodata.IOData` container
and can be found in the ``./pybest-results`` directory, where all data is stored in the ``checkpoint_CIS.h5``, ``checkpoint_CID.h5``, and
``checkpoint_CISD.h5`` files, respectively.
Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains
the following attributes

    :e_corr: The RCIS/RCID/RCISD correlation energy
    :civ:  The eigenvectors of the RCIS/RCID/RCISD Hamiltonian
    :e_ref:  The energy of the reference determinant (here, the Hartree-Fock
                determinant)


.. _qg_rci_pccd:

RCI on top of pCCD
------------------

If you use this module, please cite [nowak2023]_.

We assume that you have performed a restricted pCCD calculation, whose
results are stored in the :py:class:`~pybest.io.iodata.IOData` container ``pccd_out``
(see :ref:`user_pccd`).
The code snippet below demonstrates how to perform default pCCD-CID/pCCD-CISD calculations with
a pCCD reference function in PyBEST,

.. code-block:: python

    rcid = RpCCDCID(lf, occ_model)
    rcid_out = rcid(kin, ne, er, pccd_out)

    rcisd = RpCCDCISD(lf, occ_model)
    rcisd_out = rcisd(kin, ne, er, pccd_out)

.. note::

    By default, only one root is calculated. That is, only the ground-state root is optimized.
    See :ref:`rci_keywords_pccd` for more details.

.. note::

    By default, electron-pair excitations are excluded. Thus, all CID-type corrections do not
    consider electron-pair excitations in their ansatz.


The results are returned as an :py:class:`~pybest.io.iodata.IOData` container
and can be found in the ``./pybest-results`` directory, where all data is stored in the ``checkpoint_pCCD-CID.h5``
and ``checkpoint_pCCD-CISD.h5`` files, respectively.
Specifically, the :py:class:`~pybest.io.iodata.IOData` container contains
the following attributes

    :e_ci: The RCID/RCISD correlation energy
    :civ:  The eigenvectors of the RCID/RCISD Hamiltonian
    :e_ref:  The energy of the reference pCCD wave function