qp2/docs/source/modules/cis.rst

.. _module_cis: 
 
.. program:: cis 
 
.. default-role:: option 
 
===
cis
===

This module contains a |CIS| program.

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

The :ref:`cis` program performs the CI to obtain the ROHF reference + 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 :ref:`scf` program gave the lowest |SCF|
  solution. In combination with :ref:`save_natorb` it can produce new |MOs| in
  order to reperform an :ref:`scf` optimization.

* **Excited states calculations**: generate guesses for all the
  :option:`determinants n_states` wave functions, that will be used by the
  :ref:`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 |S^2|

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




The programmer's point of view
------------------------------

This module was 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
 
 
 
Programs 
-------- 
 
 * :ref:`cis` 
 
Subroutines / functions 
----------------------- 
 
.. c:function:: h_apply_cis:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

        subroutine H_apply_cis()


    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.

    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`psi_coef`
       * :c:data:`n_states`
       * :c:data:`generators_bitmask`
       * :c:data:`mo_num`
       * :c:data:`mo_two_e_integrals_in_map`
       * :c:data:`h_apply_buffer_allocated`
       * :c:data:`n_det`
       * :c:data:`s2_eig`
       * :c:data:`n_det_generators`
       * :c:data:`i_bitmask_gen`
       * :c:data:`n_int`
       * :c:data:`psi_det`
       * :c:data:`psi_det_generators`
       * :c:data:`psi_det_generators`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`build_fock_tmp`
       * :c:func:`copy_h_apply_buffer_to_wf`
       * :c:func:`dsort`
       * :c:func:`h_apply_cis_diexc`
       * :c:func:`h_apply_cis_monoexc`
       * :c:func:`make_s2_eigenfunction`
       * :c:func:`wall_time`

    Touches:

    .. hlist::
       :columns: 3

       * :c:data:`n_det`
       * :c:data:`psi_occ_pattern`
       * :c:data:`c0_weight`
       * :c:data:`psi_coef`
       * :c:data:`psi_det_sorted_bit`
       * :c:data:`psi_det`
       * :c:data:`psi_det_size`
       * :c:data:`psi_det_sorted_bit`
       * :c:data:`psi_occ_pattern`

 
.. c:function:: h_apply_cis_diexc:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

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



    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`n_int`
       * :c:data:`n_det`
       * :c:data:`mo_num`

    Called by:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_diexcp`

 
.. c:function:: h_apply_cis_diexcorg:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

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


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

    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`n_int`
       * :c:data:`elec_alpha_num`
       * :c:data:`mo_num`

    Called by:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_diexcp`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`bitstring_to_list_ab`
       * :c:func:`fill_h_apply_buffer_no_selection`

 
.. c:function:: h_apply_cis_diexcp:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

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



    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`n_int`
       * :c:data:`n_det`
       * :c:data:`mo_num`

    Called by:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_diexc`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_diexcorg`

 
.. c:function:: h_apply_cis_monoexc:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

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


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

    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`n_int`
       * :c:data:`elec_alpha_num`
       * :c:data:`mo_num`

    Called by:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`bitstring_to_list_ab`
       * :c:func:`fill_h_apply_buffer_no_selection`

 
.. c:function:: h_apply_cis_sym:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

        subroutine H_apply_cis_sym()


    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.

    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`psi_coef`
       * :c:data:`n_states`
       * :c:data:`generators_bitmask`
       * :c:data:`mo_num`
       * :c:data:`mo_two_e_integrals_in_map`
       * :c:data:`h_apply_buffer_allocated`
       * :c:data:`n_det`
       * :c:data:`s2_eig`
       * :c:data:`n_det_generators`
       * :c:data:`i_bitmask_gen`
       * :c:data:`n_int`
       * :c:data:`psi_det`
       * :c:data:`psi_det_generators`
       * :c:data:`psi_det_generators`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`build_fock_tmp`
       * :c:func:`copy_h_apply_buffer_to_wf`
       * :c:func:`dsort`
       * :c:func:`h_apply_cis_sym_diexc`
       * :c:func:`h_apply_cis_sym_monoexc`
       * :c:func:`make_s2_eigenfunction`
       * :c:func:`wall_time`

    Touches:

    .. hlist::
       :columns: 3

       * :c:data:`n_det`
       * :c:data:`psi_occ_pattern`
       * :c:data:`c0_weight`
       * :c:data:`psi_coef`
       * :c:data:`psi_det_sorted_bit`
       * :c:data:`psi_det`
       * :c:data:`psi_det_size`
       * :c:data:`psi_det_sorted_bit`
       * :c:data:`psi_occ_pattern`

 
.. c:function:: h_apply_cis_sym_diexc:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

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



    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`n_int`
       * :c:data:`n_det`
       * :c:data:`mo_num`

    Called by:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_sym`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_sym_diexcp`

 
.. c:function:: h_apply_cis_sym_diexcorg:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

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


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

    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`n_int`
       * :c:data:`elec_alpha_num`
       * :c:data:`mo_num`

    Called by:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_sym_diexcp`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`bitstring_to_list_ab`
       * :c:func:`connected_to_hf`
       * :c:func:`fill_h_apply_buffer_no_selection`

 
.. c:function:: h_apply_cis_sym_diexcp:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

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



    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`n_int`
       * :c:data:`n_det`
       * :c:data:`mo_num`

    Called by:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_sym_diexc`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_sym_diexcorg`

 
.. c:function:: h_apply_cis_sym_monoexc:


    File : :file:`h_apply.irp.f_shell_13`

    .. code:: fortran

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


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

    Needs:

    .. hlist::
       :columns: 3

       * :c:data:`n_int`
       * :c:data:`elec_alpha_num`
       * :c:data:`mo_num`

    Called by:

    .. hlist::
       :columns: 3

       * :c:func:`h_apply_cis_sym`

    Calls:

    .. hlist::
       :columns: 3

       * :c:func:`bitstring_to_list_ab`
       * :c:func:`connected_to_hf`
       * :c:func:`fill_h_apply_buffer_no_selection`