"Fossies" - the Fresh Open Source Software Archive

Member "abinit-9.6.2/shared/libpaw/README" (9 Nov 2021, 4210 Bytes) of package /linux/misc/abinit-9.6.2.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "README": 9.2.2_vs_9.4.0.

    1 ==========================================================================
    2 ==                    Note for libPAW developers                        ==
    3 ==                          Coding rules                                ==
    4 ==========================================================================
    5                                              M.T. Jan 2015, rev April 2015
    6 
    7 Copyright (C) 2012-2021 ABINIT group. This file is distributed under the
    8 terms of the GNU General Public License, see or gnu.org/copyleft/gpl.txt.
    9 
   10 The following coding rules are mandatory in order to preserve portability
   11 of libPAW library. Only files in src/??_libpaw are covered by these rules.
   12 
   13 
   14 --------------------------------------------------------------------------
   15 How to check libPAW coding
   16 --------------------------------------------------------------------------
   17 First, compile ABINIT.
   18 
   19 Then, execute libPAW special test:
   20   cd ~abinit_build_dir
   21   ~abinit_top_dir/special/scripts/check-libpaw.py ""
   22 
   23 
   24 --------------------------------------------------------------------------
   25 Dependencies and portability
   26 --------------------------------------------------------------------------
   27 IMPORTANT: LibPAW files should not depend on modules/routines outside
   28 src/??_libpaw folder!!
   29 
   30 The libpaw.h file contain a set of cpp macros intended to integrate libPAW
   31 files into a host code.
   32 
   33 Compiled in ABINIT, libPAW files use some low level routines and
   34 constants from: defs_basis, wrtout, m_xmpi
   35 
   36 Compiled in another code, libPAW files use low level routines from the
   37 2 following modules: m_libpaw_defs, m_libpaw_tools, m_libpaw_mpi
   38 
   39 m_libpaw_defs is an excerpt of defs_basis.
   40 
   41 
   42 --------------------------------------------------------------------------
   43 Allocation/deallocation of allocatable arrays and pointers
   44 --------------------------------------------------------------------------
   45 Avoid direct use of allocate/Deallocate Fortran statements!
   46 
   47 For standard arrays (basic Fortran types), using only sizes, use:
   48   LIBPAW_ALLOCATE(array,(sizes))
   49   LIBPAW_DEALLOCATE(array)
   50 
   51 For standard pointers (basic Fortran types), using only sizes, use:
   52   LIBPAW_POINTER_ALLOCATE(pointer,(sizes))
   53   LIBPAW_POINTER_DEALLOCATE(pointer)
   54 
   55 For standard arrays (basic Fortran types), using explicit bounds use:
   56 For 1D-array allocation
   57   LIBPAW_BOUND1_ALLOCATE(array,BOUNDS(lbound,ubound))
   58 For 2D-array allocation
   59   LIBPAW_BOUND2_ALLOCATE(array,BOUNDS(lbnd1,ubnd1),BOUNDS(lbnd2,ubnd2))
   60 For array deallocation
   61   LIBPAW_DEALLOCATE(array)
   62 
   63 For user-defined datatype arrays or pointers, using sizes or bounds, use:
   64   LIBPAW_DATATYPE_ALLOCATE(array,(sizes))
   65   LIBPAW_DATATYPE_DEALLOCATE(array)
   66 
   67 Other cases are not covered (but could be on demand)
   68 
   69 
   70 --------------------------------------------------------------------------
   71 Input/output in text files
   72 --------------------------------------------------------------------------
   73 Use wrtout routine (see m_libpaw_tools.F90) to print message.
   74 
   75 Use following macros to print messages:
   76   MSG_COMMENT(msg)
   77   MSG_WARNING(msg)
   78 
   79 Use following macros to print messages and then stop:
   80   MSG_ERROR(msg)
   81   MSG_BUG(msg)
   82 
   83 
   84 --------------------------------------------------------------------------
   85 MPI wrappers
   86 --------------------------------------------------------------------------
   87 This section is not yet relevant.
   88 For MPI wrappers, use m_xmpi routines
   89 
   90 #MPI functions used in libPAW have to be wrapped.
   91 #
   92 #The wrappers are defined in the m_libpaw_mpi.F90 module.
   93 #The all have the "xpaw_mpi_" prefix.
   94 #
   95 #m_libpaw_mpi is an excerpt of m_xmpi.
   96 #If a new object from m_xmpi is needed, it is mandatory to add it
   97 #in m_libpaw_mpi, replacing "xmpi_" prefix by "xpaw_mpi_".
   98 
   99 
  100 --------------------------------------------------------------------------
  101 Adding a new file in libPAW
  102 --------------------------------------------------------------------------
  103 libPAW should only contain Fortran modules!
  104 
  105 The header of the new file should look like this:
  106 
  107 |    #include "libpaw.h"
  108 |
  109 |    MODULE m_newmodule
  110 |
  111 |     USE_DEFS
  112 |     USE_MSG_HANDLING       [if messages have to be printed]
  113 |     USE_MPI_WRAPPERS       [if MPI has to be used]
  114 |     USE_MEMORY_PROFILING
  115 
  116 Note this use of cpp macros instead of "use module" statements.