.. _fci:

************************************
Full configuration interaction (FCI)
************************************

===========
Description
===========

FCI exactly diagonalizes the molecular Hamiltonian within the space spanned by all of the Slater determinants.
This FCI section is closely related to that for the :ref:`casscf` method.

==================
Prerequisites
==================

A reference wavefunction generated by a :ref:`HF <hf>` or :ref:`CASSCF <casscf>` calculation.

============
Keywords
============


.. topic:: ``maxiter (or maxiter_fci)``

   | **Description:** Maximum number of iterations in the FCI algorithm.
   | **Datatype:** int
   | **Default:** 100

.. topic:: ``thresh (or thresh_fci)``

   | **Description:** Threshold for the convergence of the selected CI algorithm.
   | **Datatype:** double
   | **Default:** 1.0e-10

.. topic:: ``algorithm``

   | **Description:** FCI algorithm to be used. 
   | **Datatype:** string
   | **Values:**
   |    ``KH, Knowles, Handy``: Use the Knowles--Handy algorithm.
   |    ``HZ, Harrison, Zarrabian``: Use the Harrison--Zarrabian algorithm.
   |    ``Dist, parallel``: Use a parallel algorithm based on HZ.
   | **Default:** KH or Dist depending on the size of the calculation and the number of MPI processes.

.. topic:: ``frozen``

   | **Description:** Use of the freeze core approximation.
   | **Datatype:** bool
   | **Default:** false 

.. topic:: ``ncore``

   | **Description:** Number of frozen core orbitals. ``ncore`` overides ``frozen``. 
   | **Datatype:** int 
   | **Default:** If ``frozen`` is true, subvalence orbitals are frozen. If false, zero. 

.. topic:: ``norb``

   | **Description:** Number of correlated orbitals. Any high-energy orbitals in excess of this number will be excluded.
   | **Datatype:** int
   | **Default:** All molecular orbitals except those excluded using ncore. 

.. topic:: ``active``

   | **Description:** Orbital indices for the orbitals to be included. Note that orbital numbers start from 1. 
   | **Datatype:** vector<int>
   | **Default:** Frontier orbitals are used. 

.. topic:: ``charge``

   | **Description:** The total charge of the system.
   | **Datatype:** int
   | **Default:**  0

.. topic:: ``nspin``

   | **Description:** The number associated with the spin states: 0 for singlet, 1 for doublet, 2 for triplet, etc. 
   | **Datatype:** int
   | **Default:** 0

.. topic:: ``nstate``

   | **Description:** Number of states to be calculated.
   | **Datatype:** int
   | **Default:** 1

.. topic:: ``davidson_subspace``

   | **Description:**  Number of vectors retained in the limited-memory Davidson algorithm.
   | **Datatype:** int
   | **Default:** 20
   | **Recommendation:** Reduce if an insufficient amount of memory is available (do not reduce to a value lower than 3). 

.. topic:: ``nguess``

   | **Description:** Number of guess configurations 
   | **Datatype:** int 
   | **Default:** ``nstate`` 

.. topic:: ``only_ints``

   | **Description:** If true, calculates integrals and dumps to a file. This is used to interface BAGEL to an external program.
   | **Datatype:** bool
   | **Default:** false

.. topic:: ``dipoles``

   | **Description:** Calculate dipoles 
   | **Datatype:** bool
   | **Default:** false

.. topic:: ``restart``

   | **Description:** Generate binary archive files that can be used to restart a calculation.
   | **Datatype:** bool
   | **Default:** false

.. topic:: ``print_thresh``

   | **Description:** Threshold below which CI coefficients are not printed 
   | **Datatype:** double
   | **Default:** 0.05 

=======
Example
=======
A Hartree--Fock and FCI calculation on an oxygen molecule with an elongated bond. The HF calculation is a references for the FCI calculation. Please refer to :ref:`molden` for more information on the print input block.

Sample input
============

.. code-block:: javascript

   { "bagel" : [ 

   {
     "title" : "molecule",
     "basis" : "sto-3g",
     "df_basis" : "cc-pvdz-jkfit",
     "angstrom" : true,
     "geometry" : [ 
       { "atom" : "H",  "xyz" : [ 0.0, 0.0, 1.5 ]}, 
       { "atom" : "F",  "xyz" : [ 0.0, 0.0, 0.0 ]}
     ]
   },

   {
     "title" : "hf"
   },

   {
     "title" : "fci",
     "thresh" : 1.0e-6,
     "nstate" : 2 
   }

   ]}

from which one obtains

.. code-block:: javascript

  ---------------------------
        FCI calculation      
  ---------------------------

  Performs exactly the same way as Knowles & Handy 1984 CPL

  o alpha-beta strings
      length:            12
  o size of the space 
      determinant space:  36
      spin-adapted space: 21

  o single displacement lists (alpha)
      length:            60
  o single displacement lists (beta)
      length:            60
    * Integral transformation done. Elapsed time: 0.00

     guess   0:   closed 11111.               open ......              
     guess   1:   closed 111.1.               open ...1.1              

  === FCI iteration ===

      0  0       -98.41480561     4.76e-02      0.00
      0  1       -98.26379090     4.50e-02      0.00

      1  0       -98.51664721     1.09e-02      0.00
      1  1       -98.41322803     1.00e-02      0.00

      2  0       -98.51931832     1.71e-03      0.00
      2  1       -98.41524119     1.91e-04      0.00

      3  0       -98.51940404     3.13e-04      0.00
      3  1 *     -98.41524124     2.55e-14      0.00

      4  0       -98.51940654     4.91e-05      0.00
      4  1 *     -98.41524124     2.80e-14      0.00

      5  0       -98.51940660     2.62e-06      0.00
      5  1 *     -98.41524124     1.86e-14      0.00

      6  0 *     -98.51940660     1.96e-07      0.00
      6  1 *     -98.41524124     2.02e-14      0.00

     * ci vector, state   0, <S^2> = 0.0000
       22222.    -0.9320921105
       2222.2     0.3574718122

     * ci vector, state   1, <S^2> = -0.0000
       222a2b     0.6167681811
       222b2a     0.6167681811
       222ab2    -0.3441653374
       222ba2    -0.3441653374

    * METHOD: FCI                                  0.00


==========
References
==========

+-----------------------------------------------+----------------------------------------------------------------------------------+
|          Description of Reference             |                           Reference                                              |
+===============================================+==================================================================================+
| Efficient calculation of sigma vectors (KH)   | P\. J\. Knowles and N\. C\. Handy, Chem. Phys. Lett. **111**, 315 (1984).        |
+-----------------------------------------------+----------------------------------------------------------------------------------+
| Efficient calculation of sigma vectors (HZ)   | R\. J\. Harrison and S\. Zarrabian, Chem. Phys. Lett. **158**, 393 (1989).       |
+-----------------------------------------------+----------------------------------------------------------------------------------+
