======================= 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 `_, 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 `_, 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. Algorithms ========== The `PhD thesis of Yann Garniron `_ 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.