.. _cis:

.. program:: cis

.. default-role:: option

===
cis
===

This module contains a CIS program. 

The user point of view
----------------------

The :command:`cis` program performs the CI of the ROHF-like + all single excitations on top of it. 
This program can be very useful to :

* **Ground state calculations**: generate a guess for the ground state wave function if one is not sure that the :c:func:`scf` program gave the lowest SCF solution. In combination with :c:func:`save_natorb` it can produce new |MOs| in order to reperform an :c:func:`scf` optimization. 

* **Excited states calculations**: generate guess for all the :option:`determinants n_states` wave functions, that will be used by the :c:func:`fci` program. 


The main keywords/options to be used are:

* :option:`determinants n_states` : number of states to consider for the |CIS| calculation

* :option:`determinants s2_eig` : force all states to have the desired value of :math:`S^2`

* :option:`determinants expected_s2` : desired value of :math:`S^2`




The programmer point of view
----------------------------

This module have been built by setting the following rules:

* The only generator determinant is the Hartree-Fock (single-reference method)
* All generated singly excited determinants are included in the wave function (no perturbative
  selection)

These rules are set in the ``H_apply.irp.f`` file.





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

.. option:: energy

    Variational |CIS| energy



Subroutines / functions
-----------------------



.. c:function:: cis

    .. code:: text

        subroutine cis

    File: :file:`cis.irp.f`

    Configuration Interaction with Single excitations. 

    This program takes a reference Slater determinant of ROHF-like occupancy, 

    and performs all single excitations on top of it, disregarding spatial symmetry and compute the "n_states" lowest eigenstates of that CI matrix. (see  :option:`determinants n_states`) 

    This program can be useful in many cases: 

    * GROUND STATE CALCULATION: to be sure to have the lowest scf solution, perform an :c:func:`scf` (see the :ref:`hartree_fock` module), then a :c:func:`cis`, save the natural orbitals (see :c:func:`save_natorb`) and reperform an :c:func:`scf` optimization from this MO guess 

    

    

    

    * EXCITED STATES CALCULATIONS: the lowest excited states are much likely to be dominanted by single-excitations. Therefore, running a :c:func:`cis` will save the "n_states" lowest states within the CIS space in the EZFIO folder, which can afterward be used as guess wave functions for a further multi-state fci calculation if you specify "read_wf" = True before running the fci executable (see :option:`determinants read_wf`). Also, if you specify "s2_eig" = True, the cis will only retain states having the good value :math:`S^2` value (see :option:`determinants s2_eig` and :option:`determinants expected_s2`). If "s2_eig" = False, it will take the lowest n_states, whatever multiplicity they are. 

    

    

    Note: if you would like to discard some orbitals, use :ref:`qp_set_mo_class` to specify: 

    * "core" orbitals which will be always doubly occupied 

    * "act" orbitals where an electron can be either excited from or to 

    * "del" orbitals which will be never occupied





.. c:function:: h_apply_cis

    .. code:: text

        subroutine H_apply_cis()

    File: :file:`h_apply.irp.f_shell_8`

    Calls H_apply on the |HF| determinant and selects all connected single and double excitations (of the same symmetry). Auto-generated by the ``generate_h_apply`` script.





.. c:function:: h_apply_cis_diexc

    .. code:: text

        subroutine H_apply_cis_diexc(key_in, key_prev, hole_1,particl_1, hole_2, particl_2, fock_diag_tmp, i_generator, iproc_in  )

    File: :file:`h_apply.irp.f_shell_8`

    





.. c:function:: h_apply_cis_diexcorg

    .. code:: text

        subroutine H_apply_cis_diexcOrg(key_in,key_mask,hole_1,particl_1,hole_2, particl_2, fock_diag_tmp, i_generator, iproc_in  )

    File: :file:`h_apply.irp.f_shell_8`

    Generate all double excitations of key_in using the bit masks of holes and particles. Assume N_int is already provided.





.. c:function:: h_apply_cis_diexcp

    .. code:: text

        subroutine H_apply_cis_diexcP(key_in, fs1, fh1, particl_1, fs2, fh2, particl_2, fock_diag_tmp, i_generator, iproc_in  )

    File: :file:`h_apply.irp.f_shell_8`

    





.. c:function:: h_apply_cis_monoexc

    .. code:: text

        subroutine H_apply_cis_monoexc(key_in, hole_1,particl_1,fock_diag_tmp,i_generator,iproc_in  )

    File: :file:`h_apply.irp.f_shell_8`

    Generate all single excitations of key_in using the bit masks of holes and particles. Assume N_int is already provided.