.. _zfci:

****************************************************
Relativistic full configuration interaction (RelFCI)
****************************************************

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

Relativistic CI differs from non-relativistic CI primarily in the Hamiltonian which is used in the exact diagonalization.
Use of a relativistic Hamiltonian includes spin-orbit coupling and the associated mixing of different spin-multiplets.
It is worth noting that all of the states within a given spin multiplet are treated individually; therefore, there may be some degenerate solutions.

=============
Prerequisites
=============
A reference wavefunction generated by a :ref:`HF <hf>`, :ref:`CASSCF <casscf>`, :ref:`FCI <fci>`, or :ref:`DHF <dhf>` calculation.
However, it should be noted that if the reference wavefunction is not from a previous :ref:`dhf` calculation,
a :ref:`DHF <dhf>` calculation is run automatically to generate a relativistic reference. 

========
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:: ``frozen``

   | **Description**: Freeze core orbitals. 
   | **Datatype**: bool
   | **Default**: false

.. topic:: ``ncore``

   | **Description:** Number of frozen core orbitals.
   | **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. 
   | **Datatype**: vector<int>
   | **Default**: Frontier orbitals are used. 

.. topic:: ``gaunt``

   | **Description**: Turns on the Gaunt interaction in the Hamiltonian.
   | **Datatype**: bool
   | **Default**: false

.. topic:: ``breit``

   | **Description**: Turns on the full Breit interaction in the Hamiltonian. 
   | **Datatype**: bool
   | **Default**: value copied from "gaunt" (if gaunt is true, breit is true)
   | **Recommendation**: Usually the Breit contribution is not important for molecular properties.

.. topic:: ``charge``

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

.. topic:: ``state``

   | **Description**: Number of states computed for each spin value.
   | **Datatype**: vector<int>
   | **Default**: There is no default; this parameter must be supplied in the input.  
   | **Note**: An array of integers is supplied, where each one indicates the number of states for a given spin value.  For example, the input [ 1 ] gives a singlet ground state, while [ 3, 0, 1 ] gives three singlets and one triplet (6 states total).  Be careful!  While the spin values you specified are used in generating the guess CI coefficients, the spin vectors will mix, and the algorithm returns the *n* lowest eigenstates regardless of their spin expectation values.  

.. topic:: ``davidson_subspace``

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

.. 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:: ``restart``

   | **Description**: Generates 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

.. topic:: ``spin_adapt``

   | **Description**: Spin-adapts the starting guess. 
   | **Datatype**: bool
   | **Default**: true
   | **Recommendation**: Use false if the error "generate_guess produced an invalid determinant" is generated. 

.. topic:: ``aniso``

   | **Description**: Performs magnetic anisotropy analysis (g-factors and zero-field splitting parameters). 
   | **Datatype**: int

=======
Example
=======
A RelFCI calculation on selenium dioxide.

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

.. code-block:: javascript

   { "bagel" : [ 

   {
    "title" : "molecule",
    "angstrom" : true,
    "basis" : "svp",
    "df_basis" : "tzvpp-jkfit",
    "geometry" : [ 
      { "atom" : "O",  "xyz" :  [  0.000,  0.000,  0.500  ] },
      { "atom" : "O",  "xyz" :  [  0.000,  0.000,  1.500  ] } 
    ]
   },

   {
     "title" : "hf"
   },

   {
     "title" : "dhf",
     "gaunt" : false,
     "breit" : false
   },

   {
     "title" : "zfci",
     "spin" : 1 , 
     "state" : [0,0,1],
     "ncore" : 2,
     "norb" :  8
   }

   ]}


from which one obtains

.. code-block:: javascript

  ----------------------------
  Relativistic FCI calculation
  ----------------------------

    * Correlation of 12 active electrons in 8 orbitals.
    * Time-reversal symmetry will be assumed.
    * gaunt    : false
    * breit    : false
    * nstate   :      3
    * nclosed  :      2
    * nact     :      8
    * nvirt    :     46
  *** Geometry (Relativistic) ***
       - 3-index ints post                         0.00
       - 3-index ints prep                         0.00
       - 3-index ints                              0.02
       - 3-index ints post                         0.00

       - Geometry relativistic (total)             0.02

       - Coulomb: half trans                       0.02
       - Coulomb: metric multiply                  0.05
       - Coulomb: J operator                       0.00
       - Coulomb: K operator                       0.01
       - Coulomb: half trans                       0.01
       - Coulomb: metric multiply                  0.03
       - Coulomb: J operator                       0.00
       - Coulomb: K operator                       0.00
    * Integral transformation done. Elapsed time: 0.10

       - jop, kop                                  0.00
       - denom                                     0.00
     guess   0:   closed 11111...             open .....11.            

     guess   1:   closed 11111...             open .....11.            

     guess   2:   closed 11111...             open .....11.            

                 * guess generation                            0.00
  === Relativistic FCI iteration ===

                 * sigma vector                                0.17
                 * davidson                                    0.00
                 * error                                       0.00
                 * denominator                                 0.00
      0   0       -149.49154103     5.51e-03      0.17
      0   1       -149.49154101     5.51e-03      0.00
      0   2       -149.49152458     5.51e-03      0.00

                 ..............................
                       after 18 iteration 
                 ..............................


     19   0  *    -149.52141423     4.71e-11      0.07
     19   1  *    -149.52140961     7.60e-11      0.00
     19   2  *    -149.52140960     7.40e-11      0.00

     * ci vector, state   0

     * ci vector, state   1

     * ci vector, state   2

     * ci vector, state   0

     * ci vector, state   1
       22222bb.  (0.6996793603,0.0199412517)
       22b2b22.  (-0.0847754623,-0.0024161521)

     * ci vector, state   2
       22222bb.  (-0.0011564447,0.6999374631)
       22b2b22.  (0.0001401229,-0.0848067421)

     * ci vector, state   0
       22222ab.  (-0.6998438169,0.0000592354)
       22222ba.  (-0.6998438169,0.0000591810)
       22a2b22.  (0.0847936889,-0.0000071744)
       22b2a22.  (0.0847936889,-0.0000071731)

     * ci vector, state   1

     * ci vector, state   2

     * ci vector, state   0

     * ci vector, state   1
       22222aa.  (0.6992592283,0.0308274507)
       22a2a22.  (-0.0847245580,-0.0037351516)

     * ci vector, state   2
       22222aa.  (0.0120504704,-0.6998597262)
       22a2a22.  (-0.0014600707,0.0847973233)

     * ci vector, state   0

     * ci vector, state   1

     * ci vector, state   2

    * METHOD: ZFCI                                 2.97


  
  ===============================================================

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

+----------------------------------------------------+--------------------------------------------------------------------+
|          Description of Reference                  |                          Reference                                 |
+====================================================+====================================================================+
| Efficient calculation of sigma vector              | P\. J. Knowles and N. C. Handy, Chem. Phys. Lett. **111**, 315     |
|                                                    | (1984).                                                            |
+----------------------------------------------------+--------------------------------------------------------------------+
| General text on relativistic quantum chemistry     | K\. G. Dyall and K. Faegri Jr.,                                    |
|                                                    | *Introduction to Relativistic Quantum Chemistry*                   |
|                                                    | (Oxford University Press, Oxford, 2007).                           |
+----------------------------------------------------+--------------------------------------------------------------------+
| Restricted kinetic balance basis                   | W\. Kutzelnigg, Int. J. Quantum Chem. **25**, 107 (1984).          |
+----------------------------------------------------+--------------------------------------------------------------------+

