.. _fci:

.. program:: fci

.. default-role:: option

===
FCI
===

Selected Full Configuration Interaction.

The :command:`FCI` program starts with a single determinant, or with the wave
function in the |EZFIO| database if :option:`determinants read_wf` is |true|.
Then, it will iteratively:

* Select the most important determinants from the external space and add them to the
  internal space
* If :option:`determinants s2_eig` is |true|, add all the necessary
  determinants to allow the eigenstates of |H| to be eigenstates of |S^2|
* Diagonalize |H| in the enlarged internal space
* Compute (stochastically) the second-order perturbative contribution to the energy 
* Extrapolate the variational energy by fitting
  :math:`E=E_\text{FCI} - \alpha\, E_\text{PT2}`


The number of selected determinants at each iteration will be such that the
size of the wave function will double at every iteration. If :option:`determinants
s2_eig` is |true|, then the number of selected determinants will be 1.5x the
current number, and then all the additional determinants will be added.

By default, the program will stop when more than one million determinants have
been selected, or when the |PT2| energy is below :math:`10^{-4}`.

The variational and |PT2| energies of the iterations are stored in the
|EZFIO| database, in the :ref:`IterativeSave` module.



Computation of the |PT2| energy
-------------------------------

At each iteration, the |PT2| energy is computed considering the Epstein-Nesbet
zeroth-order Hamiltonian:

.. math::

  E_{\text{PT2}} = \sum_{ \alpha }
    \frac{|\langle \Psi_S | \hat{H} | \alpha \rangle|^2}
         {E - |\langle \alpha | \hat{H} | \alpha \rangle}

where the |kalpha| determinants are generated by applying all the single and
double excitation operators to all the determinants of the wave function
:math:`\Psi_G`.

When the hybrid-deterministic/stochastic algorithm is chosen
(default), :math:`Psi_G = \Psi_S = \Psi`, the full wavefunction expanded in the
internal space.
When the deterministic algorithm is chosen (:option:`perturbation do_pt2`
is set to |false|), :math:`Psi_G` is a truncation of |Psi| using
:option:`determinants threshold_generators`, and :math:`Psi_S` is a truncation
of |Psi| using :option:`determinants threshold_selectors`, and re-weighted
by :math:`1/\langle \Psi_s | \Psi_s \rangle`. 

At every iteration, while computing the |PT2|, the variance of the wave
function is also computed:

.. math:: 

  \sigma^2 & = \langle \Psi | \hat{H}^2 | \Psi \rangle -
               \langle  \Psi | \hat{H}   | \Psi \rangle^2 \\
           & = \sum_{i \in \text{FCI}}
               \langle \Psi | \hat{H} | i \rangle 
               \langle i | \hat{H} | \Psi \rangle -
               \langle  \Psi | \hat{H} | \Psi \rangle^2 \\
           & = \sum_{ \alpha }
               \langle |\Psi | \hat{H} | \alpha \rangle|^2.

The expression of the variance is the same as the expression of the |PT2|, with
a denominator of 1. It measures how far the wave function is from the |FCI|
solution. Note that the absence of denominator in the Heat-Bath selected |CI|
method is selection method by minimization of the variance, whereas |CIPSI| is
a selection method by minimization of the energy.


If :option:`perturbation do_pt2` is set to |false|, then the stochastic
|PT2| is not computed, and an approximate value is obtained from the |CIPSI|
selection. The calculation is faster, but the extrapolated |FCI| value is 
less accurate. This way of running the code should be used when the only
goal is to generate a wave function, as for using |CIPSI| wave functions as
trial wave functions of |QMC| calculations for example.


The :command:`PT2` program reads the wave function of the |EZFIO| database
and computes the energy and the |PT2| contribution.


State-averaging
---------------

Extrapolated |FCI| energy
-------------------------

An estimate of the |FCI| energy is computed by extrapolating

.. math::

  E=E_\text{FCI} - \alpha\, E_\text{PT2}

This extrapolation is done for all the requested states, and excitation
energies are printed as energy differences between the extrapolated
energies of the excited states and the extrapolated energy of the ground
state.

The extrapolations are given considering the 2 last points, the 3 last points, ...,
the 7 last points. The extrapolated value should be chosen such that the extrpolated
value is stable with the number of points.




EZFIO parameters
----------------

.. option:: energy

   Calculated Selected |FCI| energy


.. option:: energy_pt2

   Calculated |FCI| energy + |PT2|