From c1bb8278e97a2ee8127866b02121edc3f70cc7e9 Mon Sep 17 00:00:00 2001 From: Emmanuel Giner Date: Fri, 11 Jan 2019 16:21:19 +0100 Subject: [PATCH] modify the doc --- docs/source/index.rst | 1 + docs/source/users_guide/natural_orbitals.rst | 41 +++++++++- docs/source/users_guide/plugins.rst | 4 +- docs/source/users_guide/printing.rst | 29 +++++++ docs/source/users_guide/quickstart.rst | 80 +------------------- 5 files changed, 73 insertions(+), 82 deletions(-) create mode 100644 docs/source/users_guide/printing.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 4c9ad947..bf6f2456 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -25,6 +25,7 @@ users_guide/interfaces users_guide/excited_states users_guide/natural_orbitals + users_guide/printing users_guide/plugins users_guide/qp_plugins users_guide/index diff --git a/docs/source/users_guide/natural_orbitals.rst b/docs/source/users_guide/natural_orbitals.rst index fbec2b01..9ff35a92 100644 --- a/docs/source/users_guide/natural_orbitals.rst +++ b/docs/source/users_guide/natural_orbitals.rst @@ -1,8 +1,8 @@ Natural orbitals ================ -.. TODO - +Summary +------- To produce state-average natural orbitals, run :: qp_run save_natorb file.ezfio @@ -12,3 +12,40 @@ are invalidated as well. +Extracting natural orbitals +--------------------------- + +Once obtained the near |FCI| wave function, one can obtain many quantities related to it. +One of these quantities are the natural orbitals which have the properties of diagonalizing the one-body density matrix: + + .. math:: + + \rho_{ij} = \delta_{ij} + +where the element of the one-body density matrix :math:`\rho_{ij}` is define as: + + + .. math:: + + \rho_{ij} = \langle \Psi | \left( a^{\dagger}_{j,\alpha} a_{i,\alpha} + a^{\dagger}_{j,\beta} a_{i,\beta} \right) | \Psi \rangle + + +These orbitals are in general known to be better than the usual |HF| |MOs| as they are obtained from a correlated wave function. To use these orbitals for future calculations, one has to replace the current |MOs| by the natural orbitals. To do so, just run: + +.. code:: + + qp_run save_natorb hcn + + +Hands on +-------- + +.. important:: + + As the |MOs| are changed, for the sake of coherence of future calculations, the save_natorb program + *automatically removes the current wave function* stored in the |EZFIO| database and replace + it by a single Slater determinant corresponding to a |HF| occupation of the new spin orbitals. + 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|. + + diff --git a/docs/source/users_guide/plugins.rst b/docs/source/users_guide/plugins.rst index 9f6ecb96..8139284c 100644 --- a/docs/source/users_guide/plugins.rst +++ b/docs/source/users_guide/plugins.rst @@ -47,5 +47,7 @@ To remove the module, run qp_plugins uninstall ext_module -For a more detailed explanation and an example, see :ref:`qp_plugins`. +.. seealso:: + + For a more detailed explanation and an example, see :ref:`qp_plugins`. diff --git a/docs/source/users_guide/printing.rst b/docs/source/users_guide/printing.rst new file mode 100644 index 00000000..f97e2746 --- /dev/null +++ b/docs/source/users_guide/printing.rst @@ -0,0 +1,29 @@ +Printing the near |FCI| wave function +===================================== + +Once obtained the near |FCI| energy, one can also take a closer look at the wave function stored in the |EZFIO| database. +If the wave function contains less than :math:`10^4` determinants, you can directly read it with the +:ref:`qp_edit` command. Just run + +.. code:: + + qp_edit hcn + + +.. important:: + + The :ref:`qp_edit` mode virtually makes human-friendly the architecture of the |EZFIO| database + through *vim*-like editor. + + +Then, look for the word "hand" when you are in the :ref:`qp_edit` mode. If the research is negative, +then it means that the wave function stored in the |EZFIO| database is too large to be edited +interactively in :ref:`qp_edit` mode. An alternative is to use the :command:`print_wf` command: + +.. code:: + + qp_run print_wf hcn | tee hcn.fci_natorb.wf + +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. + + diff --git a/docs/source/users_guide/quickstart.rst b/docs/source/users_guide/quickstart.rst index 0badde49..ee0d858d 100644 --- a/docs/source/users_guide/quickstart.rst +++ b/docs/source/users_guide/quickstart.rst @@ -130,7 +130,7 @@ To have a pictural illustration of the convergence of the |CIPSI| algorithm, jus qp_e_conv_fci hcn.fci.out -This will create the files "hcn.fci.out.conv" containing the data of the convergence of the energy that can be plotted, together with the file "hcn.fci.out.conv.eps" which is obtained from the gnuplot plot file "hcn.fci.out.conv.plt". +This will create the files "hcn.fci.out.conv" containing the data of the convergence of the energy that can be plotted, together with the file "hcn.fci.out.conv.1.eps" which is obtained from the gnuplot plot file "hcn.fci.out.conv.plt". The estimated |FCI| energy of HCN is ``-93.0501`` au. @@ -139,84 +139,7 @@ The estimated |FCI| energy of HCN is ``-93.0501`` au. The documentation of the :ref:`fci` module. -Extracting natural orbitals ---------------------------- -Once obtained the near |FCI| wave function, one can obtain many quantities related to it. -One of these quantities are the natural orbitals which have the properties of diagonalizing the one-body density matrix: - - .. math:: - - \rho_{ij} = \delta_{ij} - -where the element of the one-body density matrix :math:`\rho_{ij}` is define as: - - - .. math:: - - \rho_{ij} = \langle \Psi | \left( a^{\dagger}_{j,\alpha} a_{i,\alpha} + a^{\dagger}_{j,\beta} a_{i,\beta} \right) | \Psi \rangle - - -These orbitals are in general known to be better than the usual |HF| |MOs| as they are obtained from a correlated wave function. To use these orbitals for future calculations, one has to replace the current |MOs| by the natural orbitals. To do so, just run: - -.. code:: - - qp_run save_natorb hcn - - -Hands on -======== - -.. important:: - - As the |MOs| are changed, for the sake of coherence of future calculations, the save_natorb program - *automatically removes the current wave function* stored in the |EZFIO| database and replace - it by a single Slater determinant. - - -Then, you can run another |CIPSI| calculation to see how the use of natural orbital affect the convergence of the algorithm. For instance: - -.. code:: - - qp_run fci hcn | tee hcn.fci_natorb.out - -and then - -.. code:: - - qp_e_conv_fci hcn.fci_natorb.out - - -Printing the near |FCI| wave function -------------------------------------- - -Once obtained the near |FCI| energy, one can also take a closer look at the wave function stored in the |EZFIO| database. -If the wave function contains less than :math:`10^4` determinants, you can directly read it with the -:ref:`qp_edit` command. Just run - -.. code:: - - qp_edit hcn - - -.. important:: - - The :ref:`qp_edit` mode virtually makes human-friendly the architecture of the |EZFIO| database - through *vim*-like editor. - - -Then, look for "hand" when you are in the :ref:`qp_edit` mode. If the research is negative, -then it means that the wave function stored in the |EZFIO| database is too large to be edited in :ref:`qp_edit` mode. -An alternative is to use the :command:`print_wf` command: - -.. code:: - - qp_run print_wf hcn | tee hcn.fci_natorb.wf - -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. - - -The Range Separated Hybrids --------------------------- TODO @@ -229,5 +152,4 @@ TODO * Parameters for Hartree-Fock * Parameters for Davidson * Running in parallel - * Parameters for selection (Generators/selectors)