-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathlibpaw-coding-rules.txt
116 lines (86 loc) · 4.12 KB
/
libpaw-coding-rules.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
==========================================================================
== Note for libPAW developers ==
== Coding rules ==
==========================================================================
M.T. Jan 2015, rev April 2015
Copyright (C) 2012-2022 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.