qp2/docs/source/programmers_guide/programming.rst

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

.. cache compile
.. interface AOs / MOs => resultsFile
.. interface integrals => AO / MO
.. interface integrals MO => FCIDUMP
.. TODO : molden module in resultsFile

.. include:: /work.rst