Working on doc

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

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``

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::

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

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

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
 

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

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

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::  [<provider_name>]
+
+   The name of the provider in irp.f90 and in the EZFIO lib
+
+.. option:: doc:<str>
+
+   The plain text documentation
+
+.. option:: type:<str>
+
+   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:<str>
+
+   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:<str>
+
+   The default value needed if ``ocaml`` is in interface list.
+   No default can be set for arrays.
+
+.. option:: size:<str>
+
+   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:<str>
+
+   The name in the |EZFIO| API (by default is ``<provider_name>``)
+
+
+\*.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)
+
+
+
+
+
+
+

docs/source/programmers_guide/index.rst

@@ -0,0 +1,12 @@
+================
+Index of Modules
+================
+
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /modules/*
+
+

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 <http://scemama.gitbooks.io/irpf90>`_.
+the `IRPF90`_ code generator. A gitbook can be found
+`here <http://scemama.gitbooks.io/irpf90>`_.
 
 
 .. interface AOs / MOs => resultsFile

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 

docs/source/users_guide/qp_run.rst

@@ -14,7 +14,12 @@ Usage
 
 .. code:: bash
 
-   qp_run [-slave] <PROGRAM> <EZFIO_DIRECTORY>
+   qp_run [-slave] [-help] <PROGRAM> <EZFIO_DIRECTORY>
+
+
+.. option:: -help
+
+   Displays the list of available |qp| programs. 
 
 
 .. option:: -slave

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]  <EZFIO_DIRECTORY>
+
+
+.. option:: -q 
+
+    Prints in the standard output the number of core electrons.
+
+

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

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 ->

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
 

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
 

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
 

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}`.

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