diff --git a/docs/source/appendix/contributors.rst b/docs/source/appendix/contributors.rst index e3574e5a..74837282 100644 --- a/docs/source/appendix/contributors.rst +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 4231b1f8..e7e63260 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/external/irpf90 b/external/irpf90 index ba1a2837..4ab1b175 160000 --- a/external/irpf90 +++ b/external/irpf90 @@ -1 +1 @@ -Subproject commit ba1a2837aa61cb8f9892860cec544d7c6659badd +Subproject commit 4ab1b175fc7ed0d96c1912f13dc53579b24157a6 diff --git a/plugins/README.rst b/plugins/README.rst index 7fc011a3..3214a619 100644 --- a/plugins/README.rst +++ b/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. +================================================================== + +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, +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, - print out these providers, - 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, - V) obtain the AOs and MOs on the DFT grid, together with the density, + +i) print out **one- and two-electron integrals** on the AO/MO basis, creates two providers which manipulate these objects, print out these providers, + +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 **Lapack or Davidson**, + +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. -!!!! WARNING: The plugins are NECESSARILY located in qp2/plugins/ !!!! +Then, you need to known **where** you want to create your plugin, and what is the **name** of the plugin. + +.. 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: -a) What do I need to compute what I want, which means what are the objects that I need ? +.. code:: bash + + 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 - Ex: the routine "lapack_diagd" (which diagonalises a real hermitian matrix) is located in the 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 - 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 - 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 - 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" -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 +2) **Where do I find** these objects ? -TIPS ----- -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 -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 : -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. + 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 :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 :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 :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` file . + +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: + +.. code:: bash + + cat NEED + + 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.