added the introduction to the plugins tutorial

docs/source/appendix/contributors.rst

@@ -46,6 +46,7 @@ The following people have contributed to this project (by alphabetical order):
 * Nicolas Renon
 * Lorenzo Tenti
 * Julien Toulouse
+* Diata Traoré
 * Mikaël Véril
 
 

docs/source/index.rst

@@ -39,9 +39,9 @@
    programmers_guide/programming
    programmers_guide/ezfio
    programmers_guide/plugins
+   programmers_guide/plugins_tuto_intro
    programmers_guide/new_ks
    programmers_guide/index
-   programmers_guide/plugins
 
 
 .. toctree::
@@ -52,5 +52,6 @@
    appendix/benchmarks
    appendix/license
    appendix/contributors
+   appendix/references
 
 

external/irpf90

@@ -1 +1 @@
-Subproject commit ba1a2837aa61cb8f9892860cec544d7c6659badd
+Subproject commit 4ab1b175fc7ed0d96c1912f13dc53579b24157a6

plugins/README.rst

@@ -3,76 +3,128 @@ Tutorial for creating a plugin
 ==============================
 
 Introduction: what is a plugin, and what this tuto will be about ?
-============================================================
+==================================================================
-The QP is split into two kinds of routines/global variables (i.e. providers): 
- i)  the core modules locatedin qp2/src/, which contains all the bulk of a quantum chemistry software (integrals, matrix elements between Slater determinants, linear algebra routines, DFT stuffs etc..)
- ii) the plugins which are external stuffs connected to the qp2/src/ stuffs.
 
-More precisely, a plugin of the QP is a directory where you can create routines, 
+The |QP| is split into two kinds of routines/global variables (i.e. *providers*): 
+ i)  the **core modules** locatedin qp2/src/, which contains all the bulk of a quantum chemistry software (integrals, matrix elements between Slater determinants, linear algebra routines, DFT stuffs etc..)
+ ii) the **plugins** which are external routines/*providers* connected to the qp2/src/ routines/*providers*.
+ 
+More precisely, a **plugin** of the |QP| is a directory where you can create routines, 
 providers and executables that use all the global variables/functions/routines already created 
-in the modules ofqp2/src or in other plugins. 
+in the modules of qp2/src or in other plugins. 
 
 Instead of giving a theoretical lecture on what is a plugin, 
 we will go through a series of examples that allow you to do the following thing: 
- I)   print out one- and two-electron integrals on the AO/MO basis,  
+
-      creates two providers which manipulate these objects, 
+i)   print out **one- and two-electron integrals** on the AO/MO basis, creates two providers which manipulate these objects, print out these providers, 
-      print out these providers, 
+
- II)  browse the Slater determinants stored in the EZFIO wave function and compute their matrix elements, 
+ii)  browse the **Slater determinants stored** in the |EZFIO| wave function and compute their matrix elements, 
- III) build the Hamiltonian matrix and diagonalize it either with Lapck or Davidson,
+
- IV)  print out the one- and two-electron rdms, 
+iii) build the **Hamiltonian matrix** and **diagonalize** it either with **Lapack or Davidson**,
- V)   obtain the AOs and MOs on the DFT grid, together with the density,
+
+iv)  print out the **one- and two-electron rdms**, 
+
+v)   obtain the **AOs** and **MOs** on the **DFT grid**, together with the **density**,
 
 How the tutorial will be done
 -----------------------------
+
 This tuto is as follows: 
- i)  you READ THIS FILE UNTIL THE END in order to get the big picture and vocabulary, 
+
- ii) you go to the directory qp2/plugins/tuto_plugins/ and you will find detailed tuto there for each of the 5 examples. 
+ i)  you **READ THIS FILE UNTIL THE END** in order to get the big picture and vocabulary, 
+
+ ii) you go to the directory :file:`qp2/plugins/tuto_plugins/` and you will find detailed tutorials for each of the 5 examples. 
 
 Creating a plugin: the basic
 ----------------------------
+
 The first thing to do is to be in the QPSH mode: you execute the qp2/bin/qpsh script that essentially loads all 
 the environement variables and allows for the completion of command lines in bash (that is an AMAZING feature :) 
 
-Then, you need to known where you want to create your plugin, and what is the name of the plugin. 
+Then, you need to known **where** you want to create your plugin, and what is the **name** of the plugin. 
-!!!! WARNING: The plugins are NECESSARILY located in qp2/plugins/ !!!!
+
+.. important::
+
+  The plugins are **NECESSARILY** located in qp2/plugins/, and from there you can create any structures of directories.
+
+
 Ex: If you want to create a plugin named "my_fancy_plugin" in the directory plugins/plugins_test/, 
 this goes with the command 
-qp plugins create -n my_fancy_plugin -r plugins_test/
 
-Then, to create plugin of your dreams, the two questions you need to answer are the following: 
+.. code:: bash
-a) What do I need to compute what I want, which means what are the objects that I need ?
+
+    qp plugins create -n my_fancy_plugin -r plugins_test/
+
+Then, to create the plugin of your dreams, the two questions you need to answer are the following: 
+
+1) What do I **need** to compute what I want, which means what are the **objects** that I need ?
+
    There are two kind of objects:
-   + the routines/functions 
+
+   + the *routines/functions*: 
+
      Ex: Linear algebra routines, integration routines etc ...
-   + the global variables which are called the PROVIDERS
+
+   + the global variables which are called the *providers*: 
+
      Ex: one-electron integrals, Slater determinants, density matrices etc ...
-b) Where do I find these objects ? 
+
-   The objects (routines/functions/providers) are necessarily created in other modules/plugins 
+2) **Where do I find** these objects ? 
-     Ex: the routine "lapack_diagd" (which diagonalises a real hermitian matrix) is located in the file 
+
-         qp2/src/utils/linear_algebra.irp.f
+   The objects (routines/functions/providers) are necessarily created in other *modules/plugins*.  
+
+.. seealso::
+
+   The routine :c:func:`lapack_diagd` (which diagonalises a real hermitian matrix) is located in the file 
+   :file:`qp2/src/utils/linear_algebra.irp.f` 
    therefore it "belongs" to the module "utils" 
-       : the routine "ao_to_mo" (which converts a given matrix A from the AO basis to the MO basis) is located in the file
+
-         qp2/src/mo_one_e_ints/ao_to_mo.irp.f
+   The routine :c:func:`ao_to_mo` (which converts a given matrix A from the AO basis to the MO basis) is located in the file 
+   :file:`qp2/src/mo_one_e_ints/ao_to_mo.irp.f`
    therefore it "belongs" to the module "mo_one_e_ints"
-       : the provider "ao_one_e_integrals" (which is the integrals of one-body part of H on the AO basis) is located in the file 
+
-         qp2/src/mo_one_e_ints/ao_to_mo.irp.f 
+   The provider :c:data:`ao_one_e_integrals` (which is the integrals of one-body part of H on the AO basis) is located in the file 
+   :file:`qp2/src/mo_one_e_ints/ao_to_mo.irp.f` 
    therefore it belongs to the module "mo_one_e_ints" 
-       : the provider "one_e_dm_mo_beta_average" (which is the state average beta density matrix on the MO basis) is located in the file 
+
-         qp2/src/determinants/density_matrix.irp.f 
+   The provider :c:data:`one_e_dm_mo_beta_average` (which is the state average beta density matrix on the MO basis) is located in the file 
+   :file:`qp2/src/determinants/density_matrix.irp.f`
    therefore it belongs to the module "determinants"
 
-To import all the variables that you need, you just need to write the name of the plugins in the file "NEED"
+To import all the variables that you need, you just need to write the name of the plugins in the :file:`NEED` file .
-Ex: to import all the variables/routines of the module "utils", "determinants" and "mo_one_e_ints" you will have the following NEED file:
-utils
-determinants
-mo_one_e_ints
 
-TIPS 
+To import all the variables/routines of the module "utils", "determinants" and "mo_one_e_ints", the  :file:`NEED` file you will need is simply the following:
-----
+
-There are many many routines/providers in the core modules of QP. Nevertheless, as everything is coded with the IRPF90, you can use the following amazing tools: irpman
+.. code:: bash
-irpman can be used in command line in bash to obtain all the info on a routine or variable ! 
+
-Ex: execute the following command line : 
+ cat NEED
-irpman ao_one_e_integrals
+
-Then it appears all the information you want on ao_one_e_integrals, including where it is created, the type, dimension if it is an array, what providers it needs to be built, and what providers need this provider. 
+ utils
+ determinants
+ mo_one_e_ints
+
+
+.. important::
+
+  There are **many** routines/providers in the core modules of QP. 
+
+  Nevertheless, as everything is coded with the |IRPF90|, you can use the following amazing tools: :command:`irpman`
+
+  :command:`irpman` can be used in command line in bash to obtain all the info on a routine or variable ! 
+
+
+Example: execute the following command line : 
+
+.. code:: bash
+
+  irpman ao_one_e_integrals
+
+Then all the information you need on :c:data:`ao_one_e_integrals` will appear on the screen. 
+This includes
+ - **where** the provider is created, (*i.e.* the actual file where the provider is designed)
+ - the **type** of the provider (*i.e.* a logical, integer etc ...)
+ - the **dimension** if it is an array, 
+ - what other *providers* are **needed** to build this provider, 
+ - what other *providers* **need** this provider.