diff --git a/TODO b/TODO index bec2dff1..5874f2a2 100644 --- a/TODO +++ b/TODO @@ -12,6 +12,8 @@ Problem with EMSL * Creer une page web pas trop degueu et la mettre ici : http://lcpq.github.io/quantum_package +* Creer une page avec la liste de tous les exectuables + # Exterieur diff --git a/docs/ref b/docs/ref new file mode 100644 index 00000000..2af16245 --- /dev/null +++ b/docs/ref @@ -0,0 +1,22 @@ +* See docs/source/_static/links.rst file for many useful macros +* option provider :option:`name_of_module provider` +* subroutine :c:func:`my_subroutine` +* module :ref:`module` +* provider :c:data:`my_subroutine` +* qp_command :ref:`qp_command` +* linux command :command:`qp_command` +* linux command with option :command:`qp_command -o` +* environment variable :envvar:`VARIABLE` +* file :file:`filename` +* for a file to be referenced, type +.. _myref: +in the head of the file. +(see https://www.sphinx-doc.org/en/1.7/markup/inline.html) +Then, to reference for "myref" just type :ref:`myref` +* roles like warning, note, etc : see http://www.sphinx-doc.org/en/1.6/markup/para.html +* URL : ``_ + or use `IRPF90`_ and define + _IRPF90: http://irpf90.ups-tlse.fr + somewhere +* References of published results with QP should be added into docs/source/research.bib in bibtex + format diff --git a/docs/source/modules/cis.rst b/docs/source/modules/cis.rst index 9ba5c4c7..05c1e0be 100644 --- a/docs/source/modules/cis.rst +++ b/docs/source/modules/cis.rst @@ -8,7 +8,34 @@ cis === -This module contains a CIS program, built by setting the following rules: +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 @@ -42,7 +69,35 @@ Subroutines / functions File: :file:`cis.irp.f` - Configuration Interaction with Single excitations. + 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 diff --git a/docs/source/modules/cisd.rst b/docs/source/modules/cisd.rst index d1cc56d7..bbd282de 100644 --- a/docs/source/modules/cisd.rst +++ b/docs/source/modules/cisd.rst @@ -8,7 +8,32 @@ cisd ==== -This module contains a CISD program, built by setting the following rules: +This module contains a CI of single and double excitations. + +The user point of view +---------------------- + +The :command:`cisd` program performs the CI of the ROHF-like + all single and double 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 |cisd| 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 determinants are included in the wave function (no perturbative @@ -42,7 +67,33 @@ Subroutines / functions File: :file:`cisd.irp.f` - Configuration Interaction with Single and Double excitations. + Configuration Interaction with Single and Double excitations. + + This program takes a reference Slater determinant of ROHF-like occupancy, + + and performs all single and double 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: if even after a :c:func:`cis` calculation, natural orbitals (see :c:func:`save_natorb`) and then :c:func:`scf` optimization, you are not sure to have the lowest scf solution, do the same strategy with the :c:func:`cisd` executable instead of the :c:func:`cis` exectuable to generate the natural orbitals as a guess for the :c:func:`scf`. + + + + + + * EXCITED STATES CALCULATIONS: the lowest excited states are much likely to be dominanted by single- or double-excitations. Therefore, running a :c:func:`cisd` will save the "n_states" lowest states within the CISD 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 cisd will only retain states having the good value :math:`S^2` value (see :option:`determinants expected_s2` and :option:`determinants s2_eig`). 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 diff --git a/docs/source/modules/density_for_dft.rst b/docs/source/modules/density_for_dft.rst index ecb217ac..ecae22f2 100644 --- a/docs/source/modules/density_for_dft.rst +++ b/docs/source/modules/density_for_dft.rst @@ -39,60 +39,6 @@ Providers --------- -.. c:var:: one_body_dm_alpha_ao_for_dft - - .. code:: text - - double precision, allocatable :: one_body_dm_alpha_ao_for_dft (ao_num,ao_num,N_states) - double precision, allocatable :: one_body_dm_beta_ao_for_dft (ao_num,ao_num,N_states) - - File: :file:`density_for_dft.irp.f` - - one body density matrix on the AO basis based on one_body_dm_mo_alpha_for_dft - - - - -.. c:var:: one_body_dm_average_mo_for_dft - - .. code:: text - - double precision, allocatable :: one_body_dm_average_mo_for_dft (mo_num,mo_num) - - File: :file:`density_for_dft.irp.f` - - - - - - -.. c:var:: one_body_dm_beta_ao_for_dft - - .. code:: text - - double precision, allocatable :: one_body_dm_alpha_ao_for_dft (ao_num,ao_num,N_states) - double precision, allocatable :: one_body_dm_beta_ao_for_dft (ao_num,ao_num,N_states) - - File: :file:`density_for_dft.irp.f` - - one body density matrix on the AO basis based on one_body_dm_mo_alpha_for_dft - - - - -.. c:var:: one_body_dm_mo_alpha_for_dft - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_alpha_for_dft (mo_num,mo_num,N_states) - - File: :file:`density_for_dft.irp.f` - - density matrix for alpha electrons in the MO basis used for all DFT calculations based on the density - - - - .. c:var:: one_body_dm_mo_alpha_one_det .. code:: text @@ -107,19 +53,6 @@ Providers -.. c:var:: one_body_dm_mo_beta_for_dft - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_beta_for_dft (mo_num,mo_num,N_states) - - File: :file:`density_for_dft.irp.f` - - density matrix for beta electrons in the MO basis used for all DFT calculations based on the density - - - - .. c:var:: one_body_dm_mo_beta_one_det .. code:: text @@ -134,19 +67,6 @@ Providers -.. c:var:: one_body_dm_mo_for_dft - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_for_dft (mo_num,mo_num,N_states) - - File: :file:`density_for_dft.irp.f` - - - - - - .. c:var:: one_e_dm_alpha_ao_for_dft .. code:: text diff --git a/docs/source/modules/determinants.rst b/docs/source/modules/determinants.rst index bc8d370a..3878e945 100644 --- a/docs/source/modules/determinants.rst +++ b/docs/source/modules/determinants.rst @@ -550,196 +550,6 @@ Providers -.. c:var:: one_body_dm_ao_alpha - - .. code:: text - - double precision, allocatable :: one_body_dm_ao_alpha (ao_num,ao_num) - double precision, allocatable :: one_body_dm_ao_beta (ao_num,ao_num) - - File: :file:`density_matrix.irp.f` - - One body density matrix on the |AO| basis : :math:`\rho_{AO}(\alpha), \rho_{AO}(\beta)` . - - - - -.. c:var:: one_body_dm_ao_beta - - .. code:: text - - double precision, allocatable :: one_body_dm_ao_alpha (ao_num,ao_num) - double precision, allocatable :: one_body_dm_ao_beta (ao_num,ao_num) - - File: :file:`density_matrix.irp.f` - - One body density matrix on the |AO| basis : :math:`\rho_{AO}(\alpha), \rho_{AO}(\beta)` . - - - - -.. c:var:: one_body_dm_dagger_mo_spin_index - - .. code:: text - - double precision, allocatable :: one_body_dm_dagger_mo_spin_index (mo_num,mo_num,N_states,2) - - File: :file:`density_matrix.irp.f` - - - - - - -.. c:var:: one_body_dm_mo - - .. code:: text - - double precision, allocatable :: one_body_dm_mo (mo_num,mo_num) - - File: :file:`density_matrix.irp.f` - - One-body density matrix - - - - -.. c:var:: one_body_dm_mo_alpha - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_alpha (mo_num,mo_num,N_states) - double precision, allocatable :: one_body_dm_mo_beta (mo_num,mo_num,N_states) - - File: :file:`density_matrix.irp.f` - - :math:`\alpha` and :math:`\beta` one-body density matrix for each state - - - - -.. c:var:: one_body_dm_mo_alpha_average - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_alpha_average (mo_num,mo_num) - double precision, allocatable :: one_body_dm_mo_beta_average (mo_num,mo_num) - - File: :file:`density_matrix.irp.f` - - :math:`\alpha` and :math:`\beta` one-body density matrix for each state - - - - -.. c:var:: one_body_dm_mo_beta - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_alpha (mo_num,mo_num,N_states) - double precision, allocatable :: one_body_dm_mo_beta (mo_num,mo_num,N_states) - - File: :file:`density_matrix.irp.f` - - :math:`\alpha` and :math:`\beta` one-body density matrix for each state - - - - -.. c:var:: one_body_dm_mo_beta_average - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_alpha_average (mo_num,mo_num) - double precision, allocatable :: one_body_dm_mo_beta_average (mo_num,mo_num) - - File: :file:`density_matrix.irp.f` - - :math:`\alpha` and :math:`\beta` one-body density matrix for each state - - - - -.. c:var:: one_body_dm_mo_diff - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_diff (mo_num,mo_num,2:N_states) - - File: :file:`density_matrix.irp.f` - - Difference of the one-body density matrix with respect to the ground state - - - - -.. c:var:: one_body_dm_mo_spin_index - - .. code:: text - - double precision, allocatable :: one_body_dm_mo_spin_index (mo_num,mo_num,N_states,2) - - File: :file:`density_matrix.irp.f` - - - - - - -.. c:var:: one_body_single_double_dm_mo_alpha - - .. code:: text - - double precision, allocatable :: one_body_single_double_dm_mo_alpha (mo_num,mo_num) - double precision, allocatable :: one_body_single_double_dm_mo_beta (mo_num,mo_num) - - File: :file:`density_matrix.irp.f` - - :math:`\alpha` and :math:`\beta` one-body density matrix for each state - - - - -.. c:var:: one_body_single_double_dm_mo_beta - - .. code:: text - - double precision, allocatable :: one_body_single_double_dm_mo_alpha (mo_num,mo_num) - double precision, allocatable :: one_body_single_double_dm_mo_beta (mo_num,mo_num) - - File: :file:`density_matrix.irp.f` - - :math:`\alpha` and :math:`\beta` one-body density matrix for each state - - - - -.. c:var:: one_body_spin_density_ao - - .. code:: text - - double precision, allocatable :: one_body_spin_density_ao (ao_num,ao_num) - - File: :file:`density_matrix.irp.f` - - One body spin density matrix on the |AO| basis : :math:`\rho_{AO}(\alpha) - \rho_{AO}(\beta)` - - - - -.. c:var:: one_body_spin_density_mo - - .. code:: text - - double precision, allocatable :: one_body_spin_density_mo (mo_num,mo_num) - - File: :file:`density_matrix.irp.f` - - :math:`\rho(\alpha) - \rho(\beta)` - - - - .. c:var:: one_e_dm_ao_alpha .. code:: text @@ -3755,20 +3565,6 @@ Subroutines / functions -.. c:function:: test_det - - .. code:: text - - subroutine test_det - - File: :file:`test_det.irp.f` - - - - - - - .. c:function:: u_0_s2_u_0 .. code:: text diff --git a/docs/source/modules/dft_utils_in_r.rst b/docs/source/modules/dft_utils_in_r.rst index cc3eb5d7..0c4c49d8 100644 --- a/docs/source/modules/dft_utils_in_r.rst +++ b/docs/source/modules/dft_utils_in_r.rst @@ -31,6 +31,7 @@ Providers double precision, allocatable :: aos_grad_in_r_array (ao_num,n_points_final_grid,3) double precision, allocatable :: aos_grad_in_r_array_transp (n_points_final_grid,ao_num,3) + double precision, allocatable :: aos_grad_in_r_array_transp_xyz (3,n_points_final_grid,ao_num) File: :file:`ao_in_r.irp.f` @@ -49,6 +50,26 @@ Providers double precision, allocatable :: aos_grad_in_r_array (ao_num,n_points_final_grid,3) double precision, allocatable :: aos_grad_in_r_array_transp (n_points_final_grid,ao_num,3) + double precision, allocatable :: aos_grad_in_r_array_transp_xyz (3,n_points_final_grid,ao_num) + + File: :file:`ao_in_r.irp.f` + + aos_grad_in_r_array(i,j,k) = value of the kth component of the gradient of ith ao on the jth grid point + + aos_grad_in_r_array_transp(i,j,k) = value of the kth component of the gradient of jth ao on the ith grid point + + k = 1 : x, k= 2, y, k 3, z + + + + +.. c:var:: aos_grad_in_r_array_transp_xyz + + .. code:: text + + double precision, allocatable :: aos_grad_in_r_array (ao_num,n_points_final_grid,3) + double precision, allocatable :: aos_grad_in_r_array_transp (n_points_final_grid,ao_num,3) + double precision, allocatable :: aos_grad_in_r_array_transp_xyz (3,n_points_final_grid,ao_num) File: :file:`ao_in_r.irp.f` @@ -195,126 +216,6 @@ Providers -.. c:var:: one_body_dm_alpha_at_r - - .. code:: text - - double precision, allocatable :: one_body_dm_alpha_at_r (n_points_final_grid,N_states) - double precision, allocatable :: one_body_dm_beta_at_r (n_points_final_grid,N_states) - - File: :file:`dm_in_r.irp.f` - - one_body_dm_alpha_at_r(i,istate) = n_alpha(r_i,istate) one_body_dm_beta_at_r(i,istate) = n_beta(r_i,istate) where r_i is the ith point of the grid and istate is the state number - - - - -.. c:var:: one_body_dm_beta_at_r - - .. code:: text - - double precision, allocatable :: one_body_dm_alpha_at_r (n_points_final_grid,N_states) - double precision, allocatable :: one_body_dm_beta_at_r (n_points_final_grid,N_states) - - File: :file:`dm_in_r.irp.f` - - one_body_dm_alpha_at_r(i,istate) = n_alpha(r_i,istate) one_body_dm_beta_at_r(i,istate) = n_beta(r_i,istate) where r_i is the ith point of the grid and istate is the state number - - - - -.. c:var:: one_body_grad_2_dm_alpha_at_r - - .. code:: text - - double precision, allocatable :: one_dm_and_grad_alpha_in_r (4,n_points_final_grid,N_states) - double precision, allocatable :: one_dm_and_grad_beta_in_r (4,n_points_final_grid,N_states) - double precision, allocatable :: one_body_grad_2_dm_alpha_at_r (n_points_final_grid,N_states) - double precision, allocatable :: one_body_grad_2_dm_beta_at_r (n_points_final_grid,N_states) - - File: :file:`dm_in_r.irp.f` - - one_dm_and_grad_alpha_in_r(1,i,i_state) = d\dx n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(2,i,i_state) = d\dy n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(3,i,i_state) = d\dz n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(4,i,i_state) = n_alpha(r_i,istate) one_body_grad_2_dm_alpha_at_r(i,istate) = d\dx n_alpha(r_i,istate)^2 + d\dy n_alpha(r_i,istate)^2 + d\dz n_alpha(r_i,istate)^2 where r_i is the ith point of the grid and istate is the state number - - - - -.. c:var:: one_body_grad_2_dm_beta_at_r - - .. code:: text - - double precision, allocatable :: one_dm_and_grad_alpha_in_r (4,n_points_final_grid,N_states) - double precision, allocatable :: one_dm_and_grad_beta_in_r (4,n_points_final_grid,N_states) - double precision, allocatable :: one_body_grad_2_dm_alpha_at_r (n_points_final_grid,N_states) - double precision, allocatable :: one_body_grad_2_dm_beta_at_r (n_points_final_grid,N_states) - - File: :file:`dm_in_r.irp.f` - - one_dm_and_grad_alpha_in_r(1,i,i_state) = d\dx n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(2,i,i_state) = d\dy n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(3,i,i_state) = d\dz n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(4,i,i_state) = n_alpha(r_i,istate) one_body_grad_2_dm_alpha_at_r(i,istate) = d\dx n_alpha(r_i,istate)^2 + d\dy n_alpha(r_i,istate)^2 + d\dz n_alpha(r_i,istate)^2 where r_i is the ith point of the grid and istate is the state number - - - - -.. c:var:: one_dm_alpha_in_r - - .. code:: text - - double precision, allocatable :: one_dm_alpha_in_r (n_points_integration_angular,n_points_radial_grid,nucl_num,N_states) - double precision, allocatable :: one_dm_beta_in_r (n_points_integration_angular,n_points_radial_grid,nucl_num,N_states) - - File: :file:`dm_in_r.irp.f` - - - - - - -.. c:var:: one_dm_and_grad_alpha_in_r - - .. code:: text - - double precision, allocatable :: one_dm_and_grad_alpha_in_r (4,n_points_final_grid,N_states) - double precision, allocatable :: one_dm_and_grad_beta_in_r (4,n_points_final_grid,N_states) - double precision, allocatable :: one_body_grad_2_dm_alpha_at_r (n_points_final_grid,N_states) - double precision, allocatable :: one_body_grad_2_dm_beta_at_r (n_points_final_grid,N_states) - - File: :file:`dm_in_r.irp.f` - - one_dm_and_grad_alpha_in_r(1,i,i_state) = d\dx n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(2,i,i_state) = d\dy n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(3,i,i_state) = d\dz n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(4,i,i_state) = n_alpha(r_i,istate) one_body_grad_2_dm_alpha_at_r(i,istate) = d\dx n_alpha(r_i,istate)^2 + d\dy n_alpha(r_i,istate)^2 + d\dz n_alpha(r_i,istate)^2 where r_i is the ith point of the grid and istate is the state number - - - - -.. c:var:: one_dm_and_grad_beta_in_r - - .. code:: text - - double precision, allocatable :: one_dm_and_grad_alpha_in_r (4,n_points_final_grid,N_states) - double precision, allocatable :: one_dm_and_grad_beta_in_r (4,n_points_final_grid,N_states) - double precision, allocatable :: one_body_grad_2_dm_alpha_at_r (n_points_final_grid,N_states) - double precision, allocatable :: one_body_grad_2_dm_beta_at_r (n_points_final_grid,N_states) - - File: :file:`dm_in_r.irp.f` - - one_dm_and_grad_alpha_in_r(1,i,i_state) = d\dx n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(2,i,i_state) = d\dy n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(3,i,i_state) = d\dz n_alpha(r_i,istate) one_dm_and_grad_alpha_in_r(4,i,i_state) = n_alpha(r_i,istate) one_body_grad_2_dm_alpha_at_r(i,istate) = d\dx n_alpha(r_i,istate)^2 + d\dy n_alpha(r_i,istate)^2 + d\dz n_alpha(r_i,istate)^2 where r_i is the ith point of the grid and istate is the state number - - - - -.. c:var:: one_dm_beta_in_r - - .. code:: text - - double precision, allocatable :: one_dm_alpha_in_r (n_points_integration_angular,n_points_radial_grid,nucl_num,N_states) - double precision, allocatable :: one_dm_beta_in_r (n_points_integration_angular,n_points_radial_grid,nucl_num,N_states) - - File: :file:`dm_in_r.irp.f` - - - - - - .. c:var:: one_e_dm_alpha_at_r .. code:: text diff --git a/docs/source/modules/fci.rst b/docs/source/modules/fci.rst index d4dce0d8..4be5b4eb 100644 --- a/docs/source/modules/fci.rst +++ b/docs/source/modules/fci.rst @@ -8,12 +8,47 @@ fci === + |CIPSI| algorithm in the full configuration interaction space. -* :command:`fci` performs the |CIPSI| calculation, -* :command:`pt2` computes the |PT2| contribution using the wave function stored in the |EZFIO| + +The user point of view +---------------------- + +* :c:func:`fci` performs |CIPSI| calculations using a stochastic scheme for both the selection and the |PT2| contribution, +* :c:func:`pt2` computes the |PT2| contribution using the wave function stored in the |EZFIO| database. + +The main keywords/options for this module are: + +* :option:`determinants n_det_max` : maximum number of Slater determinants in the CIPSI wave function. The :command:`fci` program will stop when the size of the CIPSI wave function will exceed :option:`determinants n_det_max`. + +* :option:`perturbation pt2_max` : absolute value of the |PT2| to stop the CIPSI calculation. Once the |PT2| :math:`<` :option:`perturbation pt2_max`, the CIPSI calculation stops. + +* :option:`determinants n_states` : number of states to consider in the CIPSI calculation. + +* :option:`determinants read_wf` : if False, starts with a ROHF-like determinant, if True, starts with the current wave function(s) stored in the |EZFIO| folder. + +.. note:: + For a multi-state calculation, it is recommended to start with :c:func:`cis` or :c:func:`cisd` + wave functions as a guess. + +* :option:`determinants s2_eig` : if True, systematically add all the determinants needed to have a pure value of :math:`S^2`. Also, if True, it tracks only the states having the good :option:`determinants expected_s2`. + +.. note:: + For a multi-state calculation, it is recommended to start with :c:func:`cis` or :c:func:`cisd` + wave functions as a guess. + +* :option:`determinants expected_s2` : expected value of :math:`S^2` for the desired spin multiplicity. + + + +The programmer point of view +---------------------------- + +This module have been created with the :ref:`cipsi` module. + .. seealso:: The documentation of the :ref:`cipsi` module. @@ -66,7 +101,45 @@ Subroutines / functions File: :file:`fci.irp.f` - Selected Full Configuration Interaction with stochastic selection and PT2. + Selected Full Configuration Interaction with stochastic selection and PT2 . + + This program performs a CIPSI-like selected CI using a stochastic scheme for both + + the selection of the important Slater determinants and the computation of the PT2 correction. + + This CIPSI-like algorithm will be performed for the "n_states" lowest states of the variational space (see :option:`determinants n_det_max`) + + The fci program will stop when reaching at least one the two following conditions: + + * number of Slater determinant > "n_det_max" (see :option:`determinants n_det_max`) + + * |PT2| < "pt2_max" (see :option:`perturbation pt2_max`) + + + + The following other options can be of interest: + + If "read_wf" = False, it starts with a ROHF-like Slater determinant as a guess wave function. + + If "read_wf" = True , it starts with the wave function(s) stored in the EZFIO folder as guess wave function(s). + + (see :option:`determinants read_wf`) + + If "s2_eig" = True, it will systematically add all necessary Slater determinants in order + + to have a pure spin wave function with an :math:`S^2` value corresponding to "expected_s2". + + (see :option:`determinants s2_eig` and :option:`determinants expected_s2`) + + + + + + + + For excited states calculations, it is recommended to start with a :c:func:`cis` or :c:func:`cisd` guess wave functions + + for the "n_states", and to set "s2_eig" = True. @@ -80,7 +153,13 @@ Subroutines / functions File: :file:`pt2.irp.f` - Second order perturbative correction to the wave function contained in the EZFIO directory. + Second order perturbative correction to the wave function contained in the EZFIO directory. + + This programs runs the stochastic PT2 correction on all "n_states" wave function stored in the EZFIO folder (see :option:`determinant n_states`). + + The option for the PT2 correction are the "pt2_relative_error" which is the relative stochastic + + error on the PT2 to reach before stopping the stochastic sampling. (see :option:`perturbation pt2_relative_error`) diff --git a/docs/source/modules/generators_full.rst b/docs/source/modules/generators_full.rst index 90b32a98..012457c0 100644 --- a/docs/source/modules/generators_full.rst +++ b/docs/source/modules/generators_full.rst @@ -33,33 +33,6 @@ Providers -.. c:var:: n_det_generators - - .. code:: text - - integer :: n_det_generators - - File: :file:`generators.irp.f` - - For Single reference wave functions, the number of generators is 1 : the Hartree-Fock determinant - - - - -.. c:var:: psi_coef_generators - - .. code:: text - - integer(bit_kind), allocatable :: psi_det_generators (N_int,2,psi_det_size) - double precision, allocatable :: psi_coef_generators (psi_det_size,N_states) - - File: :file:`generators.irp.f` - - For Single reference wave functions, the generator is the Hartree-Fock determinant - - - - .. c:var:: psi_coef_sorted_gen .. code:: text @@ -75,20 +48,6 @@ Providers -.. c:var:: psi_det_generators - - .. code:: text - - integer(bit_kind), allocatable :: psi_det_generators (N_int,2,psi_det_size) - double precision, allocatable :: psi_coef_generators (psi_det_size,N_states) - - File: :file:`generators.irp.f` - - For Single reference wave functions, the generator is the Hartree-Fock determinant - - - - .. c:var:: psi_det_sorted_gen .. code:: text @@ -117,29 +76,3 @@ Providers For Single reference wave functions, the generator is the Hartree-Fock determinant - - -.. c:var:: select_max - - .. code:: text - - double precision, allocatable :: select_max (size_select_max) - - File: :file:`generators.irp.f` - - Memo to skip useless selectors - - - - -.. c:var:: size_select_max - - .. code:: text - - integer :: size_select_max - - File: :file:`generators.irp.f` - - Size of the select_max array - - diff --git a/docs/source/modules/kohn_sham.rst b/docs/source/modules/kohn_sham.rst index d5939021..21ad409d 100644 --- a/docs/source/modules/kohn_sham.rst +++ b/docs/source/modules/kohn_sham.rst @@ -52,12 +52,162 @@ Providers --------- +.. c:var:: ao_potential_alpha_xc + + .. code:: text + + double precision, allocatable :: ao_potential_alpha_xc (ao_num,ao_num) + double precision, allocatable :: ao_potential_beta_xc (ao_num,ao_num) + + File: :file:`pot_functionals.irp.f` + + + + + + +.. c:var:: ao_potential_beta_xc + + .. code:: text + + double precision, allocatable :: ao_potential_alpha_xc (ao_num,ao_num) + double precision, allocatable :: ao_potential_beta_xc (ao_num,ao_num) + + File: :file:`pot_functionals.irp.f` + + + + + + +.. c:var:: e_correlation_dft + + .. code:: text + + double precision :: e_correlation_dft + + File: :file:`pot_functionals.irp.f` + + + + + + +.. c:var:: e_exchange_dft + + .. code:: text + + double precision :: e_exchange_dft + + File: :file:`pot_functionals.irp.f` + + + + + + +.. c:var:: fock_matrix_alpha_no_xc_ao + + .. code:: text + + double precision, allocatable :: fock_matrix_alpha_no_xc_ao (ao_num,ao_num) + double precision, allocatable :: fock_matrix_beta_no_xc_ao (ao_num,ao_num) + + File: :file:`fock_matrix_ks.irp.f` + + Mono electronic an Coulomb matrix in ao basis set + + + + +.. c:var:: fock_matrix_beta_no_xc_ao + + .. code:: text + + double precision, allocatable :: fock_matrix_alpha_no_xc_ao (ao_num,ao_num) + double precision, allocatable :: fock_matrix_beta_no_xc_ao (ao_num,ao_num) + + File: :file:`fock_matrix_ks.irp.f` + + Mono electronic an Coulomb matrix in ao basis set + + + + +.. c:var:: fock_matrix_energy + + .. code:: text + + double precision :: ks_energy + double precision :: two_e_energy + double precision :: one_e_energy + double precision :: fock_matrix_energy + double precision :: trace_potential_xc + + File: :file:`ks_enery.irp.f` + + Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. + + + + .. c:var:: ks_energy .. code:: text double precision :: ks_energy - double precision :: two_electron_energy + double precision :: two_e_energy + double precision :: one_e_energy + double precision :: fock_matrix_energy + double precision :: trace_potential_xc + + File: :file:`ks_enery.irp.f` + + Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. + + + + +.. c:var:: one_e_energy + + .. code:: text + + double precision :: ks_energy + double precision :: two_e_energy + double precision :: one_e_energy + double precision :: fock_matrix_energy + double precision :: trace_potential_xc + + File: :file:`ks_enery.irp.f` + + Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. + + + + +.. c:var:: trace_potential_xc + + .. code:: text + + double precision :: ks_energy + double precision :: two_e_energy + double precision :: one_e_energy + double precision :: fock_matrix_energy + double precision :: trace_potential_xc + + File: :file:`ks_enery.irp.f` + + Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. + + + + +.. c:var:: two_e_energy + + .. code:: text + + double precision :: ks_energy + double precision :: two_e_energy double precision :: one_e_energy double precision :: fock_matrix_energy double precision :: trace_potential_xc @@ -74,6 +224,20 @@ Subroutines / functions +.. c:function:: check_coherence_functional + + .. code:: text + + subroutine check_coherence_functional + + File: :file:`ks_scf.irp.f` + + + + + + + .. c:function:: srs_ks_cf .. code:: text diff --git a/docs/source/modules/kohn_sham_rs.rst b/docs/source/modules/kohn_sham_rs.rst index 2d76c0f5..544bb544 100644 --- a/docs/source/modules/kohn_sham_rs.rst +++ b/docs/source/modules/kohn_sham_rs.rst @@ -60,179 +60,12 @@ Providers --------- -.. c:var:: ao_potential_alpha_xc - - .. code:: text - - double precision, allocatable :: ao_potential_alpha_xc (ao_num,ao_num) - double precision, allocatable :: ao_potential_beta_xc (ao_num,ao_num) - - File: :file:`pot_functionals.irp.f` - - - - - - -.. c:var:: ao_potential_beta_xc - - .. code:: text - - double precision, allocatable :: ao_potential_alpha_xc (ao_num,ao_num) - double precision, allocatable :: ao_potential_beta_xc (ao_num,ao_num) - - File: :file:`pot_functionals.irp.f` - - - - - - -.. c:var:: e_correlation_dft - - .. code:: text - - double precision :: e_correlation_dft - - File: :file:`pot_functionals.irp.f` - - - - - - -.. c:var:: e_exchange_dft - - .. code:: text - - double precision :: e_exchange_dft - - File: :file:`pot_functionals.irp.f` - - - - - - -.. c:var:: fock_matrix_alpha_no_xc_ao - - .. code:: text - - double precision, allocatable :: fock_matrix_alpha_no_xc_ao (ao_num,ao_num) - double precision, allocatable :: fock_matrix_beta_no_xc_ao (ao_num,ao_num) - - File: :file:`fock_matrix_rs_ks.irp.f` - - Mono electronic an Coulomb matrix in AO basis set - - - - -.. c:var:: fock_matrix_beta_no_xc_ao - - .. code:: text - - double precision, allocatable :: fock_matrix_alpha_no_xc_ao (ao_num,ao_num) - double precision, allocatable :: fock_matrix_beta_no_xc_ao (ao_num,ao_num) - - File: :file:`fock_matrix_rs_ks.irp.f` - - Mono electronic an Coulomb matrix in AO basis set - - - - -.. c:var:: fock_matrix_energy - - .. code:: text - - double precision :: rs_ks_energy - double precision :: two_electron_energy - double precision :: one_e_energy - double precision :: fock_matrix_energy - double precision :: trace_potential_xc - - File: :file:`rs_ks_energy.irp.f` - - Range-separated Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. - - - - -.. c:var:: one_e_energy - - .. code:: text - - double precision :: rs_ks_energy - double precision :: two_electron_energy - double precision :: one_e_energy - double precision :: fock_matrix_energy - double precision :: trace_potential_xc - - File: :file:`rs_ks_energy.irp.f` - - Range-separated Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. - - - - -.. c:var:: one_electron_energy - - .. code:: text - - double precision :: rs_ks_energy - double precision :: two_electron_energy - double precision :: one_electron_energy - double precision :: fock_matrix_energy - double precision :: trace_potential_xc - - File: :file:`rs_ks_energy.irp.f` - - Range-separated Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. - - - - .. c:var:: rs_ks_energy .. code:: text double precision :: rs_ks_energy - double precision :: two_electron_energy - double precision :: one_e_energy - double precision :: fock_matrix_energy - double precision :: trace_potential_xc - - File: :file:`rs_ks_energy.irp.f` - - Range-separated Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. - - - - -.. c:var:: trace_potential_xc - - .. code:: text - - double precision :: rs_ks_energy - double precision :: two_electron_energy - double precision :: one_e_energy - double precision :: fock_matrix_energy - double precision :: trace_potential_xc - - File: :file:`rs_ks_energy.irp.f` - - Range-separated Kohn-Sham energy containing the nuclear repulsion energy, and the various components of this quantity. - - - - -.. c:var:: two_electron_energy - - .. code:: text - - double precision :: rs_ks_energy - double precision :: two_electron_energy + double precision :: two_e_energy double precision :: one_e_energy double precision :: fock_matrix_energy double precision :: trace_potential_xc @@ -249,20 +82,6 @@ Subroutines / functions -.. c:function:: check_coherence_functional - - .. code:: text - - subroutine check_coherence_functional - - File: :file:`rs_ks_scf.irp.f` - - - - - - - .. c:function:: rs_ks_scf .. code:: text diff --git a/docs/source/modules/single_ref_method.rst b/docs/source/modules/single_ref_method.rst index ae80a401..c0a6f43e 100644 --- a/docs/source/modules/single_ref_method.rst +++ b/docs/source/modules/single_ref_method.rst @@ -12,3 +12,74 @@ Include this module for single reference methods. Using this module, the only generator determinant is the Hartree-Fock determinant. + + +Providers +--------- + + +.. c:var:: n_det_generators + + .. code:: text + + integer :: n_det_generators + + File: :file:`generators.irp.f` + + For Single reference wave functions, the number of generators is 1 : the Hartree-Fock determinant + + + + +.. c:var:: psi_coef_generators + + .. code:: text + + integer(bit_kind), allocatable :: psi_det_generators (N_int,2,psi_det_size) + double precision, allocatable :: psi_coef_generators (psi_det_size,N_states) + + File: :file:`generators.irp.f` + + For Single reference wave functions, the generator is the Hartree-Fock determinant + + + + +.. c:var:: psi_det_generators + + .. code:: text + + integer(bit_kind), allocatable :: psi_det_generators (N_int,2,psi_det_size) + double precision, allocatable :: psi_coef_generators (psi_det_size,N_states) + + File: :file:`generators.irp.f` + + For Single reference wave functions, the generator is the Hartree-Fock determinant + + + + +.. c:var:: select_max + + .. code:: text + + double precision, allocatable :: select_max (1) + + File: :file:`generators.irp.f` + + Memo to skip useless selectors + + + + +.. c:var:: size_select_max + + .. code:: text + + integer :: size_select_max + + File: :file:`generators.irp.f` + + Size of select_max + + diff --git a/docs/source/modules/tools.rst b/docs/source/modules/tools.rst index 821d1b50..9305a423 100644 --- a/docs/source/modules/tools.rst +++ b/docs/source/modules/tools.rst @@ -25,7 +25,7 @@ Subroutines / functions File: :file:`diagonalize_h.irp.f` - program that extracts the N_states lowest states of the Hamiltonian within the set of Slater determinants stored in the EZFIO folder + program that extracts the `n_states` lowest states of the Hamiltonian within the set of Slater determinants stored in the EZFIO folder @@ -39,7 +39,17 @@ Subroutines / functions File: :file:`fcidump.irp.f` - Produce a FCIDUMP file + Produce a regular FCIDUMP file from the MOs stored in the EZFIO folder. + + To specify an active space, the class of the mos have to set in the EZFIO folder (see set_mo_class/qp_set_mo_class). + + The fcidump program supports 3 types of MO_class : + + * the "core" orbitals which are always doubly occupied in the calculation + + * the "del" orbitals that are never occupied in the calculation + + * the "act" orbitals that will be occupied by a varying number of electrons @@ -53,7 +63,11 @@ Subroutines / functions File: :file:`four_idx_transform.irp.f` - 4-index transformation of two-electron integrals from AO to MO integrals + 4-index transformation of two-electron integrals from AO to MO integrals. + + This program will compute the two-electron integrals on the MO basis and store it into the EZFIO folder. + + This program can be useful if the AO --> MO transformation is an expensive step by itself. @@ -81,7 +95,13 @@ Subroutines / functions File: :file:`print_e_conv.irp.f` - program that prints in a human readable format the convergence of the CIPSI algorithm + program that prints in a human readable format the convergence of the CIPSI algorithm. + + for all istate, this program produces + + * a file "EZFIO. :math:`istate.conv" containing the variational and var+PT2 energies as a function of N_det + + * for istate > 1, a file EZFIO.` istate.delta_e.conv containing the energy difference (both var and var+PT2) with the ground state as a function of N_det @@ -95,7 +115,7 @@ Subroutines / functions File: :file:`print_wf.irp.f` - print the wave function stored in the EZFIO folder in the intermediate normalization + print the wave function stored in the EZFIO folder in the intermediate normalization. it also prints a lot of information regarding the excitation operators from the reference determinant @@ -129,25 +149,15 @@ Subroutines / functions File: :file:`save_natorb.irp.f` - Save natural MOs into the EZFIO + Save natural MOs into the EZFIO + This program reads the wave function stored in the EZFIO folder, + extracts the corresponding natural orbitals and set them as the new MOs + If this is a multi-state calculation, the density matrix that produces the natural orbitals - -.. c:function:: save_one_body_dm - - .. code:: text - - subroutine save_one_body_dm - - File: :file:`save_one_body_dm.irp.f` - - programs that computes the one body density on the mo basis for alpha and beta electrons from the wave function stored in the EZFIO folder, and then save it into the EZFIO folder aux_quantities. - - Then, the global variable data_one_body_alpha_dm_mo and data_one_body_beta_dm_mo will automatically read the density in a further calculation. - - This can be used to perform dampin on the density in RS-DFT calculation (see the density_for_dft module). + is obtained from a state-averaged of the density matrices of each state with the corresponding state_average_weight (see the doc of state_average_weight). @@ -163,9 +173,9 @@ Subroutines / functions programs that computes the one body density on the mo basis for alpha and beta electrons from the wave function stored in the EZFIO folder, and then save it into the EZFIO folder aux_quantities. - Then, the global variable data_one_e_dm_alpha_mo and data_one_e_dm_beta_mo will automatically read the density in a further calculation. + Then, the global variable data_one_e_dm_alpha_mo and data_one_e_dm_beta_mo will automatically read this density in a further calculation. - This can be used to perform dampin on the density in RS-DFT calculation (see the density_for_dft module). + This can be used to perform damping on the density in RS-DFT calculation (see the density_for_dft module). @@ -179,7 +189,13 @@ Subroutines / functions File: :file:`save_ortho_mos.irp.f` - Save orthonormalized MOs in the EZFIO. + Save orthonormalized MOs in the EZFIO. + + This program reads the current MOs, computes the corresponding overlap matrix in the MO basis + + and perform a Lowdin orthonormalization : :math:`MO_{new} = S^{-1/2} MO_{guess}`. + + Thanks to the Lowdin orthonormalization, the new MOs are the most similar to the guess MOs. @@ -221,7 +237,7 @@ Subroutines / functions File: :file:`write_integrals_erf.irp.f` - Saves the two-electron erf integrals into the EZFIO + Saves the two-electron integrals with the :math:`erf(\mu r_{12})/r_{12}` oprerator into the EZFIO folder diff --git a/docs/source/programmers_guide/index_providers.rst b/docs/source/programmers_guide/index_providers.rst index 68d15ea0..17bc8b10 100644 --- a/docs/source/programmers_guide/index_providers.rst +++ b/docs/source/programmers_guide/index_providers.rst @@ -92,6 +92,7 @@ Index of Providers * :c:data:`aos_dvx_beta_pbe_w` * :c:data:`aos_grad_in_r_array` * :c:data:`aos_grad_in_r_array_transp` +* :c:data:`aos_grad_in_r_array_transp_xyz` * :c:data:`aos_in_r_array` * :c:data:`aos_in_r_array_transp` * :c:data:`aos_lapl_in_r_array` @@ -150,8 +151,6 @@ Index of Providers * :c:data:`damping_for_rs_dft` * :c:data:`data_energy_proj` * :c:data:`data_energy_var` -* :c:data:`data_one_body_alpha_dm_mo` -* :c:data:`data_one_body_beta_dm_mo` * :c:data:`data_one_e_dm_alpha_mo` * :c:data:`data_one_e_dm_beta_mo` * :c:data:`davidson_criterion` @@ -459,36 +458,8 @@ Index of Providers * :c:data:`nucl_num` * :c:data:`nucl_num_shell_aos` * :c:data:`nuclear_repulsion` -* :c:data:`one_body_dm_alpha_ao_for_dft` -* :c:data:`one_body_dm_alpha_at_r` -* :c:data:`one_body_dm_ao_alpha` -* :c:data:`one_body_dm_ao_beta` -* :c:data:`one_body_dm_average_mo_for_dft` -* :c:data:`one_body_dm_beta_ao_for_dft` -* :c:data:`one_body_dm_beta_at_r` -* :c:data:`one_body_dm_dagger_mo_spin_index` -* :c:data:`one_body_dm_mo` -* :c:data:`one_body_dm_mo_alpha` -* :c:data:`one_body_dm_mo_alpha_average` -* :c:data:`one_body_dm_mo_alpha_for_dft` * :c:data:`one_body_dm_mo_alpha_one_det` -* :c:data:`one_body_dm_mo_beta` -* :c:data:`one_body_dm_mo_beta_average` -* :c:data:`one_body_dm_mo_beta_for_dft` * :c:data:`one_body_dm_mo_beta_one_det` -* :c:data:`one_body_dm_mo_diff` -* :c:data:`one_body_dm_mo_for_dft` -* :c:data:`one_body_dm_mo_spin_index` -* :c:data:`one_body_grad_2_dm_alpha_at_r` -* :c:data:`one_body_grad_2_dm_beta_at_r` -* :c:data:`one_body_single_double_dm_mo_alpha` -* :c:data:`one_body_single_double_dm_mo_beta` -* :c:data:`one_body_spin_density_ao` -* :c:data:`one_body_spin_density_mo` -* :c:data:`one_dm_alpha_in_r` -* :c:data:`one_dm_and_grad_alpha_in_r` -* :c:data:`one_dm_and_grad_beta_in_r` -* :c:data:`one_dm_beta_in_r` * :c:data:`one_e_dm_alpha_ao_for_dft` * :c:data:`one_e_dm_alpha_at_r` * :c:data:`one_e_dm_alpha_in_r` @@ -516,7 +487,6 @@ Index of Providers * :c:data:`one_e_grad_2_dm_beta_at_r` * :c:data:`one_e_spin_density_ao` * :c:data:`one_e_spin_density_mo` -* :c:data:`one_electron_energy` * :c:data:`only_expected_s2` * :c:data:`output_cpu_time_0` * :c:data:`output_wall_time_0` @@ -725,7 +695,7 @@ Index of Providers * :c:data:`trace_v_hxc` * :c:data:`trace_v_xc` * :c:data:`transpose` -* :c:data:`two_electron_energy` +* :c:data:`two_e_energy` * :c:data:`unpaired_alpha_electrons` * :c:data:`used_weight` * :c:data:`var_pt2_ratio` @@ -1285,7 +1255,6 @@ Index of Subroutines/Functions * :c:func:`save_mos_truncated` * :c:func:`save_natorb` * :c:func:`save_natural_mos` -* :c:func:`save_one_body_dm` * :c:func:`save_one_e_dm` * :c:func:`save_ortho_mos` * :c:func:`save_ref_determinant` @@ -1326,7 +1295,6 @@ Index of Subroutines/Functions * :c:func:`tamiser` * :c:func:`task_done_to_taskserver` * :c:func:`tasks_done_to_taskserver` -* :c:func:`test_det` * :c:func:`testteethbuilding` * :c:func:`total_memory` * :c:func:`two_e_integrals_index` diff --git a/docs/source/users_guide/excited_states.rst b/docs/source/users_guide/excited_states.rst index 87798aca..8faf52d9 100644 --- a/docs/source/users_guide/excited_states.rst +++ b/docs/source/users_guide/excited_states.rst @@ -1,3 +1,5 @@ +.. _excited_states: + ============== Excited states ============== @@ -28,3 +30,7 @@ states have |MOs| of comparable quality. This allows for a faster convergence of excitation energies. +.. seealso:: + + The documentation of the :c:func:`scf`, :c:func:`cis` and :c:func:`fci` programs. + diff --git a/docs/source/users_guide/natural_orbitals.rst b/docs/source/users_guide/natural_orbitals.rst index 9ff35a92..99ef2c1c 100644 --- a/docs/source/users_guide/natural_orbitals.rst +++ b/docs/source/users_guide/natural_orbitals.rst @@ -48,4 +48,7 @@ Hands on Also, all the keywords to read the one- and two-electron integrals on the |MO| basis are set to "None" in order to be sure not to read integrals not corresponding to the current set of |MOs|. +.. seealso:: + The documentation of the :ref:`save_natorb` program. + diff --git a/docs/source/users_guide/printing.rst b/docs/source/users_guide/printing.rst index f97e2746..386f7e22 100644 --- a/docs/source/users_guide/printing.rst +++ b/docs/source/users_guide/printing.rst @@ -26,4 +26,8 @@ interactively in :ref:`qp_edit` mode. An alternative is to use the :command:`pri This program will, by default, print out the first :math:`10^4` determinants whatever the size of the wave function stored in the |EZFIO| folder. If you want to change the number of printed Slater determinants, just change the :option:`determinants n_det_print_wf` keyword using the :ref:`qp_edit` tool. +.. seealso:: + + The documentation of the :ref:`print_wf` program. + diff --git a/docs/source/users_guide/quickstart.rst b/docs/source/users_guide/quickstart.rst index ee0d858d..e988ef8d 100644 --- a/docs/source/users_guide/quickstart.rst +++ b/docs/source/users_guide/quickstart.rst @@ -74,7 +74,7 @@ The expected energy is ``-92.827856698`` au. .. seealso:: - The documentation of the :ref:`hartree_fock` module. + The documentation of the :ref:`hartree_fock` module and that of the :c:func:`scf` program. This creates the |MOs| in the |EZFIO| database that will be used to perform any other post-SCF method. The |qp| does not handle symmetry and the |MOs| are stored by increasing order of Fock energies. @@ -137,7 +137,7 @@ The estimated |FCI| energy of HCN is ``-93.0501`` au. .. seealso:: - The documentation of the :ref:`fci` module. + The documentation of the :ref:`fci` module and that of the :c:func:`fci` program. --------------------------- diff --git a/src/cis/README.rst b/src/cis/README.rst index b7f1ea19..04035490 100644 --- a/src/cis/README.rst +++ b/src/cis/README.rst @@ -2,7 +2,34 @@ cis === -This module contains a CIS program, built by setting the following rules: +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 diff --git a/src/cis/cis.irp.f b/src/cis/cis.irp.f index bdc62c52..fd920616 100644 --- a/src/cis/cis.irp.f +++ b/src/cis/cis.irp.f @@ -5,32 +5,35 @@ program cis ! ! 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`) + ! 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 scf (see the :ref:`hartree_fock` module), then a cis, - ! - ! save the natural orbitals (see :ref:`save_natorb`) and reperform an scf optimization from this MO guess + ! * 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 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. - ! - ! Also, if you specify "s2_eig" = True, the cis will only retain states having the good value :math:`S^2` value (see expected_s2). ! + ! * 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 qp_set_mo_class to specify: + ! 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 ! diff --git a/src/cisd/README.rst b/src/cisd/README.rst index 268b6609..001352e9 100644 --- a/src/cisd/README.rst +++ b/src/cisd/README.rst @@ -2,7 +2,32 @@ cisd ==== -This module contains a CISD program, built by setting the following rules: +This module contains a CI of single and double excitations. + +The user point of view +---------------------- + +The :command:`cisd` program performs the CI of the ROHF-like + all single and double 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 |cisd| 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 determinants are included in the wave function (no perturbative diff --git a/src/cisd/cisd.irp.f b/src/cisd/cisd.irp.f index c94d1ee9..c3748b9b 100644 --- a/src/cisd/cisd.irp.f +++ b/src/cisd/cisd.irp.f @@ -5,32 +5,37 @@ program cisd ! ! This program takes a reference Slater determinant of ROHF-like occupancy, ! - ! and performs all single and double excitations on top of it, disregarding spatial symmetry and compute the "n_states" lowest eigenstates of that CI matrix. + ! and performs all single and double 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: if even after a cis calculation, natural orbitals and then scf optimization, you are not sure to have the lowest scf solution, - - ! do the same strategy with the cisd executable to generate the natural orbitals as a guess for the scf. + ! * GROUND STATE CALCULATION: if even after a :c:func:`cis` calculation, natural + ! orbitals (see :c:func:`save_natorb`) and then :c:func:`scf` optimization, you are not sure to have the lowest scf + ! solution, + ! do the same strategy with the :c:func:`cisd` executable instead of the :c:func:`cis` exectuable to generate the natural + ! orbitals as a guess for the :c:func:`scf`. ! ! ! - ! * EXCITED STATES CALCULATIONS: the lowest excited states are much likely to be dominanted by single- or double-excitations. - ! - ! Therefore, running a cis will save the "n_states" lowest states within the CISD 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. - ! - ! Also, if you specify "s2_eig" = True, the cisd will only retain states having the good value :math:`S^2` value (see expected_s2). - ! - ! If "s2_eig" = False, it will take the lowest n_states, whatever multiplicity they are. + ! * EXCITED STATES CALCULATIONS: the lowest excited states are much likely to + ! be dominanted by single- or double-excitations. + ! Therefore, running a :c:func:`cisd` will save the "n_states" lowest states within + ! the CISD 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 cisd will only retain states + ! having the good value :math:`S^2` value + ! (see :option:`determinants expected_s2` and :option:`determinants s2_eig`). + ! 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 qp_set_mo_class to specify: + ! 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 ! diff --git a/src/fci/README.rst b/src/fci/README.rst index 52128bb2..3b380c49 100644 --- a/src/fci/README.rst +++ b/src/fci/README.rst @@ -2,12 +2,47 @@ fci === + |CIPSI| algorithm in the full configuration interaction space. -* :command:`fci` performs the |CIPSI| calculation, -* :command:`pt2` computes the |PT2| contribution using the wave function stored in the |EZFIO| + +The user point of view +---------------------- + +* :c:func:`fci` performs |CIPSI| calculations using a stochastic scheme for both the selection and the |PT2| contribution, +* :c:func:`pt2` computes the |PT2| contribution using the wave function stored in the |EZFIO| database. + +The main keywords/options for this module are: + +* :option:`determinants n_det_max` : maximum number of Slater determinants in the CIPSI wave function. The :command:`fci` program will stop when the size of the CIPSI wave function will exceed :option:`determinants n_det_max`. + +* :option:`perturbation pt2_max` : absolute value of the |PT2| to stop the CIPSI calculation. Once the |PT2| :math:`<` :option:`perturbation pt2_max`, the CIPSI calculation stops. + +* :option:`determinants n_states` : number of states to consider in the CIPSI calculation. + +* :option:`determinants read_wf` : if False, starts with a ROHF-like determinant, if True, starts with the current wave function(s) stored in the |EZFIO| folder. + +.. note:: + For a multi-state calculation, it is recommended to start with :c:func:`cis` or :c:func:`cisd` + wave functions as a guess. + +* :option:`determinants s2_eig` : if True, systematically add all the determinants needed to have a pure value of :math:`S^2`. Also, if True, it tracks only the states having the good :option:`determinants expected_s2`. + +.. note:: + For a multi-state calculation, it is recommended to start with :c:func:`cis` or :c:func:`cisd` + wave functions as a guess. + +* :option:`determinants expected_s2` : expected value of :math:`S^2` for the desired spin multiplicity. + + + +The programmer point of view +---------------------------- + +This module have been created with the :ref:`cipsi` module. + .. seealso:: The documentation of the :ref:`cipsi` module. diff --git a/src/fci/fci.irp.f b/src/fci/fci.irp.f index 63113c90..74c4ddd5 100644 --- a/src/fci/fci.irp.f +++ b/src/fci/fci.irp.f @@ -1,7 +1,7 @@ program fci implicit none BEGIN_DOC -! Selected Full Configuration Interaction with stochastic selection and PT2. +! Selected Full Configuration Interaction with stochastic selection and PT2 . ! ! This program performs a CIPSI-like selected CI using a stochastic scheme for both ! @@ -33,7 +33,7 @@ program fci ! ! ! -! For excited states calculations, it is recommended to start with a cis or cisd guess wave functions +! For excited states calculations, it is recommended to start with a :c:func:`cis` or :c:func:`cisd` guess wave functions ! ! for the "n_states", and to set "s2_eig" = True. END_DOC diff --git a/src/tools/diagonalize_h.irp.f b/src/tools/diagonalize_h.irp.f index 902ef0cd..c0393c72 100644 --- a/src/tools/diagonalize_h.irp.f +++ b/src/tools/diagonalize_h.irp.f @@ -1,7 +1,11 @@ program diagonalize_h implicit none BEGIN_DOC -! program that extracts the `n_states` lowest states of the Hamiltonian within the set of Slater determinants stored in the EZFIO folder +! Program that extracts the :option:`determinants n_states` lowest states of the Hamiltonian within the set of Slater determinants stored in the EZFIO folder. +! +! If :option:`determinants s2_eig` = True, it will retain only states +! +! which corresponds to the desired value of :option:`determinants expected_s2`. END_DOC read_wf = .True. touch read_wf diff --git a/src/tools/fcidump.irp.f b/src/tools/fcidump.irp.f index 3d97cb26..2df3b500 100644 --- a/src/tools/fcidump.irp.f +++ b/src/tools/fcidump.irp.f @@ -1,9 +1,9 @@ program fcidump implicit none BEGIN_DOC -! Produce a regular FCIDUMP file from the MOs stored in the EZFIO folder. +! Produce a regular FCIDUMP file from the |MOs| stored in the |EZFIO| folder. ! -! To specify an active space, the class of the mos have to set in the EZFIO folder (see set_mo_class/qp_set_mo_class). +! To specify an active space, the class of the mos have to set in the |EZFIO| folder (see :ref:`qp_set_mo_class`). ! ! The fcidump program supports 3 types of MO_class : ! diff --git a/src/tools/four_idx_transform.irp.f b/src/tools/four_idx_transform.irp.f index 9b11be84..019aa22d 100644 --- a/src/tools/four_idx_transform.irp.f +++ b/src/tools/four_idx_transform.irp.f @@ -1,9 +1,9 @@ program four_idx_transform implicit none BEGIN_DOC -! 4-index transformation of two-electron integrals from AO to MO integrals. +! 4-index transformation of two-electron integrals from |AO| to |MO| integrals. ! -! This program will compute the two-electron integrals on the MO basis and store it into the EZFIO folder. +! This program will compute the two-electron integrals on the |MO| basis and store it into the |EZFIO| folder. ! ! This program can be useful if the AO --> MO transformation is an expensive step by itself. END_DOC diff --git a/src/tools/print_e_conv.irp.f b/src/tools/print_e_conv.irp.f index 64d5af8b..8781ee22 100644 --- a/src/tools/print_e_conv.irp.f +++ b/src/tools/print_e_conv.irp.f @@ -5,7 +5,7 @@ program print_e_conv ! ! for all istate, this program produces ! -! * a file "EZFIO.$istate.conv" containing the variational and var+PT2 energies as a function of N_det +! * a file "EZFIO.istate.conv" containing the variational and var+PT2 energies as a function of N_det ! ! * for istate > 1, a file EZFIO.$istate.delta_e.conv containing the energy difference (both var and var+PT2) with the ground state as a function of N_det END_DOC @@ -14,8 +14,11 @@ program print_e_conv call routine end -subroutine routine +subroutine routine_e_conv implicit none + BEGIN_DOC +! routine called by :c:func:`print_e_conv` + END_DOC integer :: N_iter_tmp integer :: i,istate character*(128) :: output diff --git a/src/tools/print_wf.irp.f b/src/tools/print_wf.irp.f index a0e9c112..5ae2e829 100644 --- a/src/tools/print_wf.irp.f +++ b/src/tools/print_wf.irp.f @@ -1,9 +1,9 @@ program print_wf implicit none BEGIN_DOC - ! print the wave function stored in the EZFIO folder in the intermediate normalization. + ! Print the ground state wave function stored in the |EZFIO| folder in the intermediate normalization. ! - ! it also prints a lot of information regarding the excitation operators from the reference determinant + ! It also prints a lot of information regarding the excitation operators from the reference determinant ! ! and a first-order perturbative analysis of the wave function. ! diff --git a/src/tools/save_one_e_dm.irp.f b/src/tools/save_one_e_dm.irp.f index 1c54f31f..8c6c4772 100644 --- a/src/tools/save_one_e_dm.irp.f +++ b/src/tools/save_one_e_dm.irp.f @@ -15,8 +15,11 @@ program save_one_e_dm end -subroutine routine - +subroutine routine_save_one_e_dm + implicit none + BEGIN_DOC + ! routine called by :c:func:`save_one_e_dm` + END_DOC call ezfio_set_aux_quantities_data_one_e_dm_alpha_mo(one_e_dm_mo_alpha) call ezfio_set_aux_quantities_data_one_e_dm_beta_mo(one_e_dm_mo_beta) end