abinit/shared/libpaw

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

Copyright (C) 2012-2025 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, wrtout, m_xmpi

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

m_libpaw_defs is an excerpt of defs_basis.


--------------------------------------------------------------------------
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)


--------------------------------------------------------------------------
MPI wrappers
--------------------------------------------------------------------------
This section is not yet relevant.
For MPI wrappers, use m_xmpi routines

#MPI functions used in libPAW have to be wrapped.
#
#The wrappers are defined in the m_libpaw_mpi.F90 module.
#The all have the "xpaw_mpi_" prefix.
#
#m_libpaw_mpi is an excerpt of m_xmpi.
#If a new object from m_xmpi is needed, it is mandatory to add it
#in m_libpaw_mpi, replacing "xmpi_" prefix by "xpaw_mpi_".


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