10
0
mirror of https://github.com/QuantumPackage/qp2.git synced 2024-11-05 05:33:52 +01:00
QuantumPackage/docs/source/programmers_guide/programming.rst

112 lines
4.8 KiB
ReStructuredText
Raw Normal View History

2019-01-25 11:39:31 +01:00
=======================
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>`_,
and programmers are encouraged to visit this manual.
|IRPF90| make programming very simple. The only information a programmer needs
in order to write a new program is the name of the required |IRPF90| entities
which may already exist in other modules. For example, writing a program which
prints the Hartree-Fock energy is as simple as:
.. code:: fortran
program print_hf_energy
implicit none
BEGIN_DOC
! Program which prints the Hartree-Fock energy
! to the standard output
END_DOC
print *, 'HF energy = ', HF_energy
end
The only required information was the existence of a provider for
:command:`hf_energy`. A detailed list of all the providers, subroutines
and functions of the |qp| can be found in the appendix of this manual.
Architecture
============
As |IRPF90| is used, the programmer doesn't have a full control of the sequence
of instructions in the produced Fortran code. This explains why the input data
is stored in a database rather than in sequential text files. Indeed, the
programmer can't know by advance in which order the files will be read, so a
simple random access to persistent data is needed. The |EZFIO| library generator
is a practical answer to this problem.
The |qp| uses a collection of programs inter-operating together. Each of these
programs is reading and/or modifying information in the |EZFIO| database.
This is done mostly using the command line or scripting.
.. important::
Each command modifies the state of the |EZFIO| database, so running twice the
same program on the same database may have different behaviors because of the
state of the database. For reproducibility, users are encouraged to run scripts
where a fresg new |EZFIO| database is created at the beginning of the
script. This way of running the |qp| makes calculations reproducible.
The computational part |qp| is organized in **modules**. A module is a
directory which contains multiple |IRPF90| files, a |README| and a |NEED| file.
The |README| file contains documentation about the module, that is
automatically included in the documentation of the |qp|. The documentation is
generated by the `Sphinx documentation builder <http://www.sphinx-doc.org>`_,
and it should be written using the |rst| format.
The |NEED| file contains the list of the modules which are needed for the
current module. When a module is needed, it means that all the |IRPF90| files
it contains should be included in the current module. This is done
automatically during the building process, by creating symbolic links in the
current directory.
To compile the program, the |Ninja| build system is used, and all the building
process is fully automated such that the programmer will never have to modify a
file by hand. Running :command:`ninja` inside a module will compile only the
module, and running :command:`ninja` at the root of the |qp| will build all the
modules, as well as the tools.
Develop (#15) * fixed laplacian of aos * corrected the laplacians of aos * added dft_one_e * added new feature for new dft functionals * changed the configure to add new functionals * changed the configure * added dft_one_e/README.rst * added README.rst in new_functionals * added source/programmers_guide/new_ks.rst * Thesis Yann * Added gmp installation in configure * improved qp_e_conv_fci * Doc * Typos * Added variance_max * Fixed completion in qp_create * modif TODO * fixed DFT potential for n_states gt 1 * improved pot pbe * trying to improve sr PBE * fixed potential pbe * fixed the vxc smashed for pbe sr and normal * Comments in selection * bug fixed by peter * Fixed bug with zero beta electrons * Update README.rst * Update e_xc_new_func.irp.f * Update links.rst * Update quickstart.rst * Update quickstart.rst * updated cipsi * Fixed energies of non-expected s2 (#9) * Moved diag_algorithm in Davdison * Add print_ci_vector in tools (#11) * Fixed energies of non-expected s2 * Moved diag_algorithm in Davdison * Fixed travis * Added print_ci_vector * Documentation * Cleaned qp_set_mo_class.ml * Removed Core in taskserver * Merge develop-toto and manus (#12) * Fixed energies of non-expected s2 * Moved diag_algorithm in Davdison * Fixed travis * Added print_ci_vector * Documentation * Cleaned qp_set_mo_class.ml * Removed Core in taskserver * Frozen core for heavy atoms * Improved molden module * In sync with manus * Fixed some of the documentation errors * Develop toto (#13) * Fixed energies of non-expected s2 * Moved diag_algorithm in Davdison * Fixed travis * Added print_ci_vector * Documentation * Cleaned qp_set_mo_class.ml * Removed Core in taskserver * Frozen core for heavy atoms * Improved molden module * In sync with manus * Fixed some of the documentation errors * Develop manus (#14) * modified printing for rpt2 * Comment * Fixed plugins * Scripting for functionals * Documentation * Develop (#10) * fixed laplacian of aos * corrected the laplacians of aos * added dft_one_e * added new feature for new dft functionals * changed the configure to add new functionals * changed the configure * added dft_one_e/README.rst * added README.rst in new_functionals * added source/programmers_guide/new_ks.rst * Thesis Yann * Added gmp installation in configure * improved qp_e_conv_fci * Doc * Typos * Added variance_max * Fixed completion in qp_create * modif TODO * fixed DFT potential for n_states gt 1 * improved pot pbe * trying to improve sr PBE * fixed potential pbe * fixed the vxc smashed for pbe sr and normal * Comments in selection * bug fixed by peter * Fixed bug with zero beta electrons * Update README.rst * Update e_xc_new_func.irp.f * Update links.rst * Update quickstart.rst * Update quickstart.rst * updated cipsi * Fixed energies of non-expected s2 (#9) * Moved diag_algorithm in Davdison * some modifs * modified gfortran_debug.cfg * fixed automatization of functionals * modified e_xc_general.irp.f * minor modifs in ref_bitmask.irp.f * modifying functionals * rs_ks_scf and ks_scf compiles with the automatic handling of functionals * removed prints * fixed configure * fixed the new functionals * Merge toto * modified automatic functionals * Changed python into python2 * from_xyz suppressed * Cleaning repo * Update README.md * Update README.md * Contributors * Update GITHUB.md * bibtex
2019-03-07 16:29:06 +01:00
Algorithms
==========
The `PhD thesis of Yann Garniron <https://doi.org/10.5281/zenodo.2558127>`_
gives all the details about the implementation of:
* The data structure for the two-electron integrals (:file:`utils/map_module.f`)
* The Davdison diagonalization (module :ref:`module_davidson`)
* The CIPSI selection (module :ref:`module_cipsi`)
* The hybrid stochastic/deterministic PT2 correction (module :ref:`module_cipsi`)
* The hybrid stochastic/deterministic matrix dressing (module :ref:`module_dressing`)
Extracting results for use with other codes
===========================================
The |AOs| and |MOs| can be seen with :ref:`qp_edit`. We also provide a utility
to create a file which can be read by `molden` for visualizing the |MOs| (see
:ref:`molden`). For using external |CI| solvers, we provide a utility that
generates a file containing the two-electron integrals in the |MO| basis set
in the `FCIDUMP` format (see :ref:`fcidump`).
All the results are stored in the |EZFIO| directory, so users willing to fetch
data such as the |MOs| or the |CI| coefficients should use the |EZFIO| API.
There multiple major ways to do this:
* Write a script in Python or OCaml and use the Python |EZFIO| API. The script
:file:`$QP_ROOT/bin/qp_convert_output_to_ezfio` is a good example to understand
how to use the |EZFIO| API in Python,
* Write an independent program in Fortran or C, link it with the |EZFIO| library
located at :file:`$QP_ROOT/external/ezfio/lib/libezfio.a` and call directly
the |EZFIO| routines,
* Write a new module for the |qp| printing the desired quantities in a suitable
text format. The program :ref:`fcidump` is an example of such a program.
2019-01-25 11:39:31 +01:00