From 1ac2423571258b357a1e8d0ae95053da7ac5aaa2 Mon Sep 17 00:00:00 2001 From: Anthony Scemama Date: Fri, 23 Nov 2018 17:00:51 +0100 Subject: [PATCH] Working on doc --- docs/Makefile | 2 +- docs/source/_static/links.rst | 3 +- docs/source/index.rst | 10 +- docs/source/modules/ao_basis.rst | 2 +- docs/source/modules/davidson.rst | 6 +- docs/source/modules/determinants.rst | 4 +- docs/source/modules/fci.rst | 20 ++++ docs/source/modules/hartree_fock.rst | 2 +- docs/source/programmers_guide/ezfio.rst | 112 ++++++++++++++++++ docs/source/programmers_guide/index.rst | 12 ++ docs/source/programmers_guide/programming.rst | 3 +- .../qp_convert_output_to_ezfio.rst | 4 +- docs/source/users_guide/qp_run.rst | 7 +- .../source/users_guide/qp_set_frozen_core.rst | 31 +++++ docs/source/users_guide/quickstart.rst | 64 ++++++++-- ocaml/qp_set_mo_class.ml | 2 + src/AO_Basis/EZFIO.cfg | 2 +- src/Davidson/EZFIO.cfg | 6 +- src/Determinants/EZFIO.cfg | 4 +- src/FCI/README.rst | 20 ++++ src/Hartree_Fock/EZFIO.cfg | 2 +- 21 files changed, 279 insertions(+), 39 deletions(-) create mode 100644 docs/source/programmers_guide/ezfio.rst create mode 100644 docs/source/programmers_guide/index.rst create mode 100644 docs/source/users_guide/qp_set_frozen_core.rst diff --git a/docs/Makefile b/docs/Makefile index a7a916b3..49962dac 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = -v +SPHINXOPTS = SPHINXBUILD = sphinx-build SOURCEDIR = source BUILDDIR = build diff --git a/docs/source/_static/links.rst b/docs/source/_static/links.rst index 81a079f4..d849f36f 100644 --- a/docs/source/_static/links.rst +++ b/docs/source/_static/links.rst @@ -68,4 +68,5 @@ .. |H| replace:: :math:`\hat H` .. |Psi| replace:: :math:`|\Psi \rangle` .. |S^2| replace:: :math:`\widehat{S^2}` - +.. |true| replace:: ``true`` +.. |false| replace:: ``false`` diff --git a/docs/source/index.rst b/docs/source/index.rst index 88fae966..6bd307ab 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,15 +31,6 @@ users_guide/interfaces -.. toctree:: - :maxdepth: 1 - :caption: Index of Modules - :glob: - :hidden: - - modules/* - - .. toctree:: :maxdepth: 1 @@ -48,6 +39,7 @@ programmers_guide/programming programmers_guide/ezfio + programmers_guide/index .. toctree:: diff --git a/docs/source/modules/ao_basis.rst b/docs/source/modules/ao_basis.rst index d6e18431..3cd910fa 100644 --- a/docs/source/modules/ao_basis.rst +++ b/docs/source/modules/ao_basis.rst @@ -86,6 +86,6 @@ EZFIO parameters .. option:: ao_cartesian - If true, use |AOs| in Cartesian coordinates (6d,10f,...) + If |true|, use |AOs| in Cartesian coordinates (6d,10f,...) Default: false diff --git a/docs/source/modules/davidson.rst b/docs/source/modules/davidson.rst index 98b538a4..0193c20b 100644 --- a/docs/source/modules/davidson.rst +++ b/docs/source/modules/davidson.rst @@ -41,18 +41,18 @@ EZFIO parameters .. option:: state_following - If true, the states are re-ordered to match the input states + If |true|, the states are re-ordered to match the input states Default: False .. option:: disk_based_davidson - If true, disk space is used to store the vectors + If |true|, disk space is used to store the vectors Default: False .. option:: distributed_davidson - If true, use the distributed algorithm + If |true|, use the distributed algorithm Default: True diff --git a/docs/source/modules/determinants.rst b/docs/source/modules/determinants.rst index b7a02a6f..639dc54b 100644 --- a/docs/source/modules/determinants.rst +++ b/docs/source/modules/determinants.rst @@ -35,7 +35,7 @@ EZFIO parameters .. option:: read_wf - If true, read the wave function from the |EZFIO| file + If |true|, read the wave function from the |EZFIO| file Default: False @@ -106,7 +106,7 @@ EZFIO parameters .. option:: store_full_H_mat - If True, the Davidson diagonalization is performed by storing the full |H| matrix up to n_det_max_stored. Be careful, it can cost a lot of memory but can also save a lot of CPU time + If |true|, the Davidson diagonalization is performed by storing the full |H| matrix up to n_det_max_stored. Be careful, it can cost a lot of memory but can also save a lot of CPU time Default: False diff --git a/docs/source/modules/fci.rst b/docs/source/modules/fci.rst index 1779a586..481a1905 100644 --- a/docs/source/modules/fci.rst +++ b/docs/source/modules/fci.rst @@ -10,6 +10,26 @@ FCI Selected Full Configuration Interaction. +The program start with a single determinant, or with the wave function in the |EZFIO| database if :option:`determinants read_wf` is |true|. Then, it will iteratively: + +* Select the most important determinants from the external space and add them to the + internal space +* If :option:`determinants s2_eig` is |true|, add all the necessary + determinants to allow the eigenstates of |H| to be eigenstates of |S^2| +* Diagonalize |H| in the enlarged internal space +* Compute (stochastically) the second-order perturbative contribution to the energy +* Extrapolate the variational energy by fitting + :math:`E=E_\text{FCI} - \alpha\, E_\text{PT2}` + + +The number of selected determinants at each iteration will be such that the +size of the wave function will double at every iteration. + + + +By default, the program will stop when more than one million determinants have +been selected, or when the |PT2| energy is below :math:`10^{-4}`. + EZFIO parameters diff --git a/docs/source/modules/hartree_fock.rst b/docs/source/modules/hartree_fock.rst index 5cfcbb73..c9f73694 100644 --- a/docs/source/modules/hartree_fock.rst +++ b/docs/source/modules/hartree_fock.rst @@ -92,6 +92,6 @@ EZFIO parameters .. option:: no_oa_or_av_opt - If true, skip the (inactive+core) --> (active) and the (active) --> (virtual) orbital rotations within the |SCF| procedure + If |true|, skip the (inactive+core) --> (active) and the (active) --> (virtual) orbital rotations within the |SCF| procedure Default: False diff --git a/docs/source/programmers_guide/ezfio.rst b/docs/source/programmers_guide/ezfio.rst new file mode 100644 index 00000000..e96883bb --- /dev/null +++ b/docs/source/programmers_guide/ezfio.rst @@ -0,0 +1,112 @@ +===== +EZFIO +===== + + +EZFIO.cfg +========= + +The simplest way to add control parameters in the |EZFIO| directory is to create a +:file:`EZFIO.cfg` file in the module. An example can be found in existing modules +such as :ref:`hartree_fock`:: + + [max_dim_diis] + type: integer + doc: Maximum size of the |DIIS| extrapolation procedure + interface: ezfio,provider,ocaml + default: 15 + + [threshold_diis] + type: Threshold + doc: Threshold on the convergence of the |DIIS| error vector during a Hartree-Fock calculation. If 0. is chosen, the square root of thresh_scf will be used. + interface: ezfio,provider,ocaml + default: 0. + + [thresh_scf] + type: Threshold + doc: Threshold on the convergence of the Hartree Fock energy. + interface: ezfio,provider,ocaml + default: 1.e-10 + + + +The syntax obeys the following rules: + +Required +-------- + +.. option:: [] + + The name of the provider in irp.f90 and in the EZFIO lib + +.. option:: doc: + + The plain text documentation + +.. option:: type: + + A type supported by the |OCaml| modules. The complete list of supported + types can be obtained by:: + + ei_handler.py list_supported_types + + +.. option:: interface: + + The interface is a list of strings sepeared by "," which can contain : + + - ``ezfio`` : to build the |EZFIO| API + - ``provider`` : to build the corresponding providers + - ``ocaml`` : to build the corresponding bindings in |OCaml| + +If an ``EZFIO.cfg`` file is used, the compilation of the module will generate +the ``ezfio_interface.irp.f`` file which contains the generated providers. +This file should not be added to the repository + +Optional +-------- + +.. option:: default: + + The default value needed if ``ocaml`` is in interface list. + No default can be set for arrays. + +.. option:: size: + + The size of the variable, which is one by default (scalar). + + Examples : ``1``; ``=sum(ao_num)``; ``(ao_basis.ao_num,3)`` + + .. warning:: + + The module and the value are separed by a ``.`` not a ``_``. + For example ``(determinants.n_det)`` + +.. option:: ezfio_name: + + The name in the |EZFIO| API (by default is ````) + + +\*.ezfio_config +=============== + +It is possible to directly add to the current module |EZFIO| configuration +files, named with the ``.ezfio_config`` suffix. An example is in the +:ref:`bitmask` module. + +.. code:: text + + bitmasks + N_int integer + bit_kind integer + N_mask_gen integer + generators integer*8 (bitmasks_N_int*bitmasks_bit_kind/8,2,6,bitmasks_N_mask_gen) + N_mask_cas integer + cas integer*8 (bitmasks_N_int*bitmasks_bit_kind/8,2,bitmasks_N_mask_cas) + + + + + + + diff --git a/docs/source/programmers_guide/index.rst b/docs/source/programmers_guide/index.rst new file mode 100644 index 00000000..b33dde58 --- /dev/null +++ b/docs/source/programmers_guide/index.rst @@ -0,0 +1,12 @@ +================ +Index of Modules +================ + + +.. toctree:: + :maxdepth: 1 + :glob: + + /modules/* + + diff --git a/docs/source/programmers_guide/programming.rst b/docs/source/programmers_guide/programming.rst index 36d1858e..49cfeb52 100644 --- a/docs/source/programmers_guide/programming.rst +++ b/docs/source/programmers_guide/programming.rst @@ -2,7 +2,8 @@ Programming in the |qp| ======================= To program in the |qp|, it is required that you are familiar with -the `IRPF90`_ code generator. A gitbook can be found `here `_. +the `IRPF90`_ code generator. A gitbook can be found +`here `_. .. interface AOs / MOs => resultsFile diff --git a/docs/source/users_guide/qp_convert_output_to_ezfio.rst b/docs/source/users_guide/qp_convert_output_to_ezfio.rst index efd9e908..fb77172a 100644 --- a/docs/source/users_guide/qp_convert_output_to_ezfio.rst +++ b/docs/source/users_guide/qp_convert_output_to_ezfio.rst @@ -6,8 +6,8 @@ qp_convert_output_to_ezfio .. program:: qp_convert_output_to_ezfio This Python script uses the `resultsFile`_ Python library to gather the -geometry, |AOs| and |MOs| from output files of |GAMESS| or Gaussian, and creates an -|EZFIO| directory with this information. Some constraints are necessary in the +geometry, |AOs| and |MOs| from output files of |GAMESS| or Gaussian, and +puts this data in an |EZFIO| database. Some constraints are necessary in the output file : the run needs to be a single point |HF|, |DFT| or |CAS| |SCF|. Usage diff --git a/docs/source/users_guide/qp_run.rst b/docs/source/users_guide/qp_run.rst index 5f14dc1a..31d010cc 100644 --- a/docs/source/users_guide/qp_run.rst +++ b/docs/source/users_guide/qp_run.rst @@ -14,7 +14,12 @@ Usage .. code:: bash - qp_run [-slave] + qp_run [-slave] [-help] + + +.. option:: -help + + Displays the list of available |qp| programs. .. option:: -slave diff --git a/docs/source/users_guide/qp_set_frozen_core.rst b/docs/source/users_guide/qp_set_frozen_core.rst new file mode 100644 index 00000000..2aea8862 --- /dev/null +++ b/docs/source/users_guide/qp_set_frozen_core.rst @@ -0,0 +1,31 @@ +.. _qp_set_frozen_core: + +================== +qp_set_frozen_core +================== + +.. program:: qp_set_frozen_core + +Automatically finds :math:`n`, the number of core electrons. Calls +:ref:`qp_set_mo_class` setting all |MOs| as ``Active``, except the :math:`n/2` +first ones which are set as ``Core``. If pseudo-potentials are used, all the +|MOs| are set as ``Active``. + +For elements on the right of the periodic table, `qp_set_frozen_core` will +work as expected. But for elements on the left, a small core will be chosen. For +example, a Carbon atom will have 2 core electrons, but a Lithium atom will have +zero. + +Usage +----- + +.. code:: bash + + qp_set_frozen_core [-q] + + +.. option:: -q + + Prints in the standard output the number of core electrons. + + diff --git a/docs/source/users_guide/quickstart.rst b/docs/source/users_guide/quickstart.rst index 96a812ae..290def34 100644 --- a/docs/source/users_guide/quickstart.rst +++ b/docs/source/users_guide/quickstart.rst @@ -3,7 +3,17 @@ Quick-start guide ================= This tutorial should talk you through everything you need to get started with -the |qp|. As an example, we will run a CIPSI calculation on the HCN molecule. +the |qp|. As an example, we will run a |CIPSI| calculation on the HCN molecule. + + +Demo video +========== + +.. Include demo video here + + +Hands on +======== .. important:: @@ -11,12 +21,8 @@ the |qp|. As an example, we will run a CIPSI calculation on the HCN molecule. :file:`quantum_package.rc` if it has not been done already in the current shell. - -.. Include demo video here - - Create the EZFIO database -========================= +------------------------- The data relative to calculations are stored in an |EZFIO| database. |EZFIO| is a hierarchical data format which uses the hierarchy of the file @@ -37,7 +43,7 @@ The file :file:`hcn.xyz` contains:: N 0.0 0.0 -1.156 -This xyz file is now used with the :ref:`qp_create_ezfio_from_xyz` command to +This xyz file is now used with the :command:`qp_create_ezfio_from_xyz` command to create an |EZFIO| database with the 6-31G basis set: .. code:: bash @@ -63,22 +69,60 @@ just run qp_run SCF hcn -The expected energy is ``-92.8278566979`` au. +The expected energy is ``-92.827856698`` au. .. seealso:: The documentation of the :ref:`Hartree_Fock` module. +Choose the target |MO| space +---------------------------- +Now, modify to |EZFIO| database to make |CIPSI| calculation in the +full set of valence |MOs|, keeping the core |MOs| frozen. The simple +command :command:`qp_set_frozen_core` does this automatically: + +.. code:: bash + + qp_set_frozen_core hcn + + +Run the |CIPSI| calculation +---------------------------- + +We will now use the |CIPSI| algorithm to estimate the |FCI| energy. + +.. code:: + + qp_run FCI hcn + + +The program will start with a single determinant and will iteratively: + +* Select the most important determinants from the external space and add them to the + internal space +* Add all the necessary determinants to allow the eigenvector of |H| to be + also an eigenstate of |S^2| +* Diagonalize |H| in the enlarged internal space +* Compute (stochastically) the second-order perturbative contribution to the energy +* Extrapolate the variational energy by fitting + :math:`E=E_\text{FCI} - \alpha\, E_\text{PT2}` + +By default, the program will stop when more than one million determinants have +entered in the internal space, or when the |PT2| energy is below :math:`10^{-4}`. + +The estimated |FCI| energy of HCN is ``-93.0501`` au. + +.. seealso:: + + The documentation of the :ref:`FCI` module. .. important:: TODO .. include:: /work.rst - * qp_run - * qp_convert * Interfaces : molden/fcidump * Natural orbitals * Parameters for Hartree-Fock diff --git a/ocaml/qp_set_mo_class.ml b/ocaml/qp_set_mo_class.ml index e12a2d75..3c41d527 100644 --- a/ocaml/qp_set_mo_class.ml +++ b/ocaml/qp_set_mo_class.ml @@ -162,7 +162,9 @@ let set ~core ~inact ~act ~virt ~del = ] in + (* Debug masks in output List.iter ~f:(fun x-> print_endline (Bitlist.to_string x)) result; + *) (* Write masks *) let result = List.map ~f:(fun x -> diff --git a/src/AO_Basis/EZFIO.cfg b/src/AO_Basis/EZFIO.cfg index 8fed2668..c3e2761b 100644 --- a/src/AO_Basis/EZFIO.cfg +++ b/src/AO_Basis/EZFIO.cfg @@ -51,7 +51,7 @@ interface: ezfio, provider [ao_cartesian] type: logical -doc: If true, use |AOs| in Cartesian coordinates (6d,10f,...) +doc: If |true|, use |AOs| in Cartesian coordinates (6d,10f,...) interface: ezfio, provider default: false diff --git a/src/Davidson/EZFIO.cfg b/src/Davidson/EZFIO.cfg index af910f58..b1b5d013 100644 --- a/src/Davidson/EZFIO.cfg +++ b/src/Davidson/EZFIO.cfg @@ -18,19 +18,19 @@ interface: ezfio,provider,ocaml [state_following] type: logical -doc: If true, the states are re-ordered to match the input states +doc: If |true|, the states are re-ordered to match the input states default: False interface: ezfio,provider,ocaml [disk_based_davidson] type: logical -doc: If true, disk space is used to store the vectors +doc: If |true|, disk space is used to store the vectors default: False interface: ezfio,provider,ocaml [distributed_davidson] type: logical -doc: If true, use the distributed algorithm +doc: If |true|, use the distributed algorithm default: True interface: ezfio,provider,ocaml diff --git a/src/Determinants/EZFIO.cfg b/src/Determinants/EZFIO.cfg index 64278e05..cdf41f92 100644 --- a/src/Determinants/EZFIO.cfg +++ b/src/Determinants/EZFIO.cfg @@ -18,7 +18,7 @@ default: 1 [read_wf] type: logical -doc: If true, read the wave function from the |EZFIO| file +doc: If |true|, read the wave function from the |EZFIO| file interface: ezfio,provider,ocaml default: False @@ -91,7 +91,7 @@ default: 0. [store_full_H_mat] type: logical -doc: If True, the Davidson diagonalization is performed by storing the full |H| matrix up to n_det_max_stored. Be careful, it can cost a lot of memory but can also save a lot of CPU time +doc: If |true|, the Davidson diagonalization is performed by storing the full |H| matrix up to n_det_max_stored. Be careful, it can cost a lot of memory but can also save a lot of CPU time interface: ezfio,provider,ocaml default: False diff --git a/src/FCI/README.rst b/src/FCI/README.rst index 54b96310..2a32150f 100644 --- a/src/FCI/README.rst +++ b/src/FCI/README.rst @@ -3,3 +3,23 @@ FCI === Selected Full Configuration Interaction. + +The program start with a single determinant, or with the wave function in the |EZFIO| database if :option:`determinants read_wf` is |true|. Then, it will iteratively: + +* Select the most important determinants from the external space and add them to the + internal space +* If :option:`determinants s2_eig` is |true|, add all the necessary + determinants to allow the eigenstates of |H| to be eigenstates of |S^2| +* Diagonalize |H| in the enlarged internal space +* Compute (stochastically) the second-order perturbative contribution to the energy +* Extrapolate the variational energy by fitting + :math:`E=E_\text{FCI} - \alpha\, E_\text{PT2}` + + +The number of selected determinants at each iteration will be such that the +size of the wave function will double at every iteration. + + + +By default, the program will stop when more than one million determinants have +been selected, or when the |PT2| energy is below :math:`10^{-4}`. diff --git a/src/Hartree_Fock/EZFIO.cfg b/src/Hartree_Fock/EZFIO.cfg index c1574999..22d2447e 100644 --- a/src/Hartree_Fock/EZFIO.cfg +++ b/src/Hartree_Fock/EZFIO.cfg @@ -47,7 +47,7 @@ interface: ezfio [no_oa_or_av_opt] type: logical -doc: If true, skip the (inactive+core) --> (active) and the (active) --> (virtual) orbital rotations within the |SCF| procedure +doc: If |true|, skip the (inactive+core) --> (active) and the (active) --> (virtual) orbital rotations within the |SCF| procedure interface: ezfio,provider,ocaml default: False