mirror of
https://github.com/LCPQ/quantum_package
synced 2024-08-30 16:13:42 +02:00
133 lines
5.0 KiB
ReStructuredText
133 lines
5.0 KiB
ReStructuredText
======================
|
|
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>`_
|
|
* `Bitmask <http://github.com/LCPQ/quantum_package/tree/master/src/Bitmask>`_
|
|
* `Electrons <http://github.com/LCPQ/quantum_package/tree/master/src/Electrons>`_
|
|
* `Ezfio_files <http://github.com/LCPQ/quantum_package/tree/master/src/Ezfio_files>`_
|
|
* `MOs <http://github.com/LCPQ/quantum_package/tree/master/src/MOs>`_
|
|
* `Nuclei <http://github.com/LCPQ/quantum_package/tree/master/src/Nuclei>`_
|
|
* `Output <http://github.com/LCPQ/quantum_package/tree/master/src/Output>`_
|
|
* `Utils <http://github.com/LCPQ/quantum_package/tree/master/src/Utils>`_
|
|
* `Hartree_Fock <http://github.com/LCPQ/quantum_package/tree/master/src/Hartree_Fock>`_
|
|
* `BiInts <http://github.com/LCPQ/quantum_package/tree/master/src/BiInts>`_
|
|
* `MonoInts <http://github.com/LCPQ/quantum_package/tree/master/src/MonoInts>`_
|
|
* `MOGuess <http://github.com/LCPQ/quantum_package/tree/master/src/MOGuess>`_
|
|
* `Dets <http://github.com/LCPQ/quantum_package/tree/master/src/Dets>`_
|
|
* `DensityMatrix <http://github.com/LCPQ/quantum_package/tree/master/src/DensityMatrix>`_
|
|
* `CISD <http://github.com/LCPQ/quantum_package/tree/master/src/CISD>`_
|
|
|