==========================================================================
==                    Note for libPAW developers                        ==
==                          Coding rules                                ==
==========================================================================
                                                             M.T. Jan 2015

Copyright (C) 2012-2014 ABINIT group. This file is distributed under the
terms of the GNU General Public License, see or gnu.org/copyleft/gpl.txt.

The following coding rules are mandatory in order to preserve portability
of libPAW library. Only files in src_??libPAW are covered by these rules.


--------------------------------------------------------------------------
How to check libPAW coding
--------------------------------------------------------------------------
First, compile ABINIT.

Then, execute libPAW special test:
  cd ~abinit_build_dir
  ~abinit_top_dir/special/scripts/check-libpaw.py ""


--------------------------------------------------------------------------
Dependencies and portability
--------------------------------------------------------------------------
IMPORTANT: LibPAW files should not depend on modules/routines outside
src_??libPAW folder!!

The libpaw.h file contain a set of cpp macros intended to integrate libPAW
files into a host code.

Compiled in ABINIT, libPAW files use some low level routines and
constants from: defs_basis, m_xmpi, wrtout 

Compiled in another code, libPAW files use low level routines from the
3 following modules: m_libpaw_defs, m_libpaw_mpi, m_libpaw_tools

m_libpaw_mpi (resp. m_libpaw_defs) is an excerpt of m_xmpi (resp.
defs_basis).
If a new object from m_xmpi is needed, it is mandatory (for libPAW
portability) to add it in m_libpaw_mpi, replacing "m_xmpi" prefix
by "m_xpaw_mpi_".

--------------------------------------------------------------------------
Allocation/deallocation of allocatable arrays and pointers
--------------------------------------------------------------------------
Avoid direct use of allocate/Deallocate Fortran statements!

For standard arrays (basic Fortran types), using only sizes, use:
  LIBPAW_ALLOCATE(array,(sizes))
  LIBPAW_DEALLOCATE(array)

For standard pointers (basic Fortran types), using only sizes, use:
  LIBPAW_POINTER_ALLOCATE(pointer,(sizes))
  LIBPAW_POINTER_DEALLOCATE(pointer)

For standard arrays (basic Fortran types), using explicit bounds use:
For 1D-array allocation
  LIBPAW_BOUND1_ALLOCATE(array,BOUNDS(lbound,ubound))
For 2D-array allocation
  LIBPAW_BOUND2_ALLOCATE(array,BOUNDS(lbnd1,ubnd1),BOUNDS(lbnd2,ubnd2))
For array deallocation
  LIBPAW_DEALLOCATE(array)

For user-defined datatype arrays or pointers, using sizes or bounds, use:
  LIBPAW_DATATYPE_ALLOCATE(array,(sizes))
  LIBPAW_DATATYPE_DEALLOCATE(array)

Other cases are not covered (but could be on demand)


--------------------------------------------------------------------------
Input/output in text files
--------------------------------------------------------------------------
Use wrtout routine (see m_libpaw_tools.F90) to print message.

Use following macros to print messages:
  MSG_COMMENT(msg)
  MSG_WARNING(msg)

Use following macros to print messages and then stop:
  MSG_ERROR(msg)
  MSG_BUG(msg)
  
  
--------------------------------------------------------------------------
Adding a new file in libPAW
--------------------------------------------------------------------------
libPAW should only contain Fortran modules!

The header of the new file should look like this:

|    #include "libpaw.h"
|
|    MODULE m_newmodule
|
|     USE_DEFS
|     USE_MSG_HANDLING       [if messages have to be printed]
|     USE_MPI_WRAPPERS       [if MPI has to be used]
|     USE_MEMORY_PROFILING

Note this use of cpp macros instead of "use module" statements.
