quantum_package/src/README.rst

======================
Programming guidelines
======================

Each module (directory) contains the following:

* A ``README.rst`` file to document the current module.
* An ``ASSUMPTIONS.rst`` file. This file should document all the implicit
  assumptions used in the module. For example, if the atomic orbitals are
  assumed to be normalized, this should be mentioned in the
  ``AOs/ASSUMPTIONS.rst`` file.
* A ``NEEDED_MODULES`` file which contains the list of modules on which the
  current module depends
* A set of ``.irp.f`` files containing provider, subroutines and functions
* A ``tests`` directory that should contain the test programs of the module
  (see testing section)
* A ``Makefile`` that should compile
* Optionally some ``*.ezfio_config`` configuration files for the EZFIO
  library

A new module may be created by invoking the ``create_module.sh`` script.

Every subroutine, function or provider should be documented using the
BEGIN_DOC ... END_DOC block. The documentation should be written in
ReStructured Text format to enable the automatic generation of the Sphinx
documentation.

When the current module depends on other modules, the list of modules should
be added in the ``NEEDED_MODULES`` file.


Creating a new module
=====================

Every new module should be created using the interactive ``create_module.sh``
script located in the ``${QPACKAGE_ROOT}/scripts`` directory. This will create
all the required files with correct templates.


Makefiles
=========

Use the structure of Makefiles provided by the ``create_module.sh`` script. If
you need to re-create the Makefile, you can use the ``create_Makefile.sh``
script in the current module directory.

If you need to add some Fortran or C files that should not be tracked by IRPF90,
you have to add them manually to the Makefile in the ``SRC`` variable.
You also need to add the corresponding ``*.o`` file prefixed by ``IRPF90_temp/``.
For example

.. code-block:: Makefile

  SRC=map_module.f90
  OBJ=IRPF90_temp/map_module.o



Testing
=======

Each module contains a ``tests/`` directory which contains the test script.
Each module should be tested by running::

  make test

Before merging into the master branch, the module should pass **all** the tests.
This enables the possibility to use ``git bisect`` to quickly find bugs.


Input data
==========

Every program is supposed to use an EZFIO database containing all the
persistent data. This database can be modified in using the generated Fortran
functions or the generated Python module.

The definition of the data needed by the module should be put in the
``*.ezfio_config`` file.

Input data can also be read from the standard input to enable the use of
a program with a pipe, but the read statements should be present **only** in
the main program.


Output data
===========

Print to stdout statements should only appear in programs, not in providers,
subroutines or functions. This enables the possibility easily use the programs
with pipes.

To print, you should write in an output file provided by the ``Output``
module. Every module has its own output file. Before printing something,
a timestamp should be put in the output with the ``write_time`` function.
This allows an external script to read all the pieces of the output files
and put them in a sequential order. The format of the output should be
in ReStructured Text for easy transformation of the output data to pdf,
HTML, man, etc.


Creating a shell script
=======================

Shell scripts should be located in the ``${QPACKAGE_ROOT}/scripts`` directory.
Relative paths should be avoided as much as possible, and the result of commands
should be always checked. For example, when creating a directory the existence
of the directory has to be checked.


Needed Modules
==============

.. Do not edit this section. It was auto-generated from the
.. NEEDED_MODULES file.

* `AOs <http://github.com/LCPQ/quantum_package/tree/master/src/AOs>`_
* `BiInts <http://github.com/LCPQ/quantum_package/tree/master/src/BiInts>`_
* `Bitmask <http://github.com/LCPQ/quantum_package/tree/master/src/Bitmask>`_
* `CISD <http://github.com/LCPQ/quantum_package/tree/master/src/CISD>`_
* `CISD_SC2_selected <http://github.com/LCPQ/quantum_package/tree/master/src/CISD_SC2_selected>`_
* `CISD_selected <http://github.com/LCPQ/quantum_package/tree/master/src/CISD_selected>`_
* `DensityMatrix <http://github.com/LCPQ/quantum_package/tree/master/src/DensityMatrix>`_
* `Dets <http://github.com/LCPQ/quantum_package/tree/master/src/Dets>`_
* `Electrons <http://github.com/LCPQ/quantum_package/tree/master/src/Electrons>`_
* `Ezfio_files <http://github.com/LCPQ/quantum_package/tree/master/src/Ezfio_files>`_
* `Full_CI <http://github.com/LCPQ/quantum_package/tree/master/src/Full_CI>`_
* `Generators_full <http://github.com/LCPQ/quantum_package/tree/master/src/Generators_full>`_
* `Hartree_Fock <http://github.com/LCPQ/quantum_package/tree/master/src/Hartree_Fock>`_
* `MOGuess <http://github.com/LCPQ/quantum_package/tree/master/src/MOGuess>`_
* `MonoInts <http://github.com/LCPQ/quantum_package/tree/master/src/MonoInts>`_
* `MOs <http://github.com/LCPQ/quantum_package/tree/master/src/MOs>`_
* `MP2 <http://github.com/LCPQ/quantum_package/tree/master/src/MP2>`_
* `Nuclei <http://github.com/LCPQ/quantum_package/tree/master/src/Nuclei>`_
* `Output <http://github.com/LCPQ/quantum_package/tree/master/src/Output>`_
* `Perturbation <http://github.com/LCPQ/quantum_package/tree/master/src/Perturbation>`_
* `SC2 <http://github.com/LCPQ/quantum_package/tree/master/src/SC2>`_
* `Selectors_full <http://github.com/LCPQ/quantum_package/tree/master/src/Selectors_full>`_
* `SingleRefMethod <http://github.com/LCPQ/quantum_package/tree/master/src/SingleRefMethod>`_
* `Utils <http://github.com/LCPQ/quantum_package/tree/master/src/Utils>`_

Documentation
=============

.. Do not edit this section. It was auto-generated from the
.. NEEDED_MODULES file.