Tips for ABINIT users and developers - OBSOLETE!

User Tools

Site Tools

Trace:
developers:coding_rules

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
developers:coding_rules [2018/05/26 20:48] – [ABINIT style for Fortran programming] Xavier Gonzedevelopers:coding_rules [2024/09/02 14:20] (current) – Maryam Azizi
Line 1: Line 1:
 +<WRAP important>**IMPORTANT WARNING**\\ **<color #ed1c24>This Page is obsolete.</color>** Please refer to www.abinit.org!</WRAP>
 +
 ~~DISCUSSION~~ ~~DISCUSSION~~
 ====== ABINIT style for Fortran programming ====== ====== ABINIT style for Fortran programming ======
  
 (revised many times from the original draft in 1991, BUT NOT REALLY UP_TO_DATE ... SHOULD BE REVISED ONCE MORE) (revised many times from the original draft in 1991, BUT NOT REALLY UP_TO_DATE ... SHOULD BE REVISED ONCE MORE)
- 
-The following sections are covered: 
- 
-    * Foreword. 
-    * Declarations. 
-    * Variables 
-    * File format 
-    * Constructs for flow control 
-    * Use of arrays 
-    * Coding practice 
-    * Exception handling, I/Os 
-    * To be avoided. 
-    * Use of BLAS and LAPACK subroutines. 
-    * Modules 
-    * Derived datatypes 
-    * Other topics 
-    * Useful links 
- 
 ====== 1. Foreword ====== ====== 1. Foreword ======
  
-The ABINIT code should conform to the ANSI Fortran norm (Fortran 95). +The ABINIT code should conform to the ANSI Fortran norm (Fortran 2003). 
-This norm is abbreviated F95, while the older norm, Fortran 77, is abbreviated F77. +Still, most of the following rules can already used with Fortran95. This norm is abbreviated F95, while the older norm, Fortran 77, is abbreviated F77. 
-The following set of rules complements the F95 standard.+The following set of rules complements the F95 (or Fortran2003) standard.
 The ABINIT code conforms to most of these additional rules already. The ABINIT code conforms to most of these additional rules already.
 Each modification, or new routine is expected to adopt all Each modification, or new routine is expected to adopt all
Line 351: Line 335:
 If a long fraction sentence is found, "!! $\displaystyle equation $" may be better for visualization. If a long fraction sentence is found, "!! $\displaystyle equation $" may be better for visualization.
  
-In some cases, "!!\begin{equation} ...!!\end{equation}" or +In some cases,  
-"!!\begin{eqnarray} ...!!\end{eqnarray}" format might be better, especially for very long equation lines.+ 
 +  !!\begin{equation} ...!!\end{equation} 
 + 
 +or 
 + 
 +  !!\begin{eqnarray} ...!!\end{eqnarray} 
 + 
 +format might be better, especially for very long equation lines.
  
 3.m. Additional information about Src2tex and Robodoc. 3.m. Additional information about Src2tex and Robodoc.
Line 394: Line 385:
 In all other cases, specify an 'intent(inout)' and detail (with comments) the status for each field. In all other cases, specify an 'intent(inout)' and detail (with comments) the status for each field.
  
-====== 4. Constructs for flow control ======+====== 5. Constructs for flow control ======
  
-4.a. Do not use numeral labels. These can be avoided through the use of the construct+5.a. Do not use numeral labels. These can be avoided through the use of the construct
  
    DO ...    DO ...
Line 413: Line 404:
 A character string can be explicitly declared, then initialized, if it is to be used more than once. (enforced) A character string can be explicitly declared, then initialized, if it is to be used more than once. (enforced)
  
-4.b. Literal labels or comment lines must be used for each construct that is longer than one page of a screen (about 20 lines), both at the beginning and at the end of the construct. (enforced)+5.b. Literal labels or comment lines must be used for each construct that is longer than one page of a screen (about 20 lines), both at the beginning and at the end of the construct. (enforced)
  
-====== 5. Use of arrays ======+====== 6. Use of arrays ======
  
-5.a. Distinguish explicitly a vector operation from its scalar counterpart, by specifying colons:+6.a. Distinguish explicitly a vector operation from its scalar counterpart, by specifying colons:
  
 suppose suppose
Line 433: Line 424:
 However, this rule can lead to problems with the stack size, see rules 5c-e. (enforced) (JB:I think the stack size has really increased and for a small routine that need temporary array of small size this is better that spending time for allocation/deallocation. ) However, this rule can lead to problems with the stack size, see rules 5c-e. (enforced) (JB:I think the stack size has really increased and for a small routine that need temporary array of small size this is better that spending time for allocation/deallocation. )
  
-5.b. In order to improve the readability of the code, use vector operations instead of explicit DO-loop constructs. Use also the intrinsic subroutines ''DOT_PRODUCT'', or ''MATMUL'', as well as+6.b. In order to improve the readability of the code, use vector operations instead of explicit DO-loop constructs. Use also the intrinsic subroutines ''DOT_PRODUCT'', or ''MATMUL'', as well as
 functions like ''SUM'' or ''MAXVAL''. However, avoid using segments as arguments.  functions like ''SUM'' or ''MAXVAL''. However, avoid using segments as arguments. 
 Use directly the array name: you do not need to distinguish this operation from an hypothetical scalar counterpart. Use directly the array name: you do not need to distinguish this operation from an hypothetical scalar counterpart.
Line 440: Line 431:
 do not lead to as good a readability (see later). (partially enforced) do not lead to as good a readability (see later). (partially enforced)
  
-5.c DO NOT pass as an argument of a subroutine, a segment of an array. For example :+6.c DO NOT pass as an argument of a subroutine, a segment of an array. For example :
  
    call routine(aa(1:naa))         ! to be avoided    call routine(aa(1:naa))         ! to be avoided
Line 458: Line 449:
 (enforced, with the restrictions mentioned) (enforced, with the restrictions mentioned)
  
-5.d Avoid the following construct, except when the segment size is sufficiently small:+6.d Avoid the following construct, except when the segment size is sufficiently small:
  
   aa(:,ii)=aa(:,jj)   aa(:,ii)=aa(:,jj)
  
   (JB: Is there really a problem there ? I think I do that and I don't have trouble)   (JB: Is there really a problem there ? I think I do that and I don't have trouble)
-  (JB:NB: all the implicit loop are good for new cpus since then can vectorize the intrusction. So loops should really be though carefully)+  (JB:NB: all the implicit loop are good for new cpus since then can vectorize the instruction. So loops should really be though carefully)
 On the DEC machines, the compiler thinks it must first store the segment aa(:,jj) in the stack, then copy the stack in aa(:,ii). On the DEC machines, the compiler thinks it must first store the segment aa(:,jj) in the stack, then copy the stack in aa(:,ii).
 This not only doubles the time for copying, but can lead to stack size problems.  This not only doubles the time for copying, but can lead to stack size problems. 
Line 471: Line 462:
 (enforced) (enforced)
  
-5.e Avoid the use of large segments in read or write operations (**MG: not easy to accomplish, especially for binary IO**)+6.e Avoid the use of large segments in read or write operations (**MG: not easy to accomplish, especially for binary IO**)
  
   read(6,*)aa(:,ii)   read(6,*)aa(:,ii)
Line 490: Line 481:
 (enforced) (enforced)
  
-5.f For allocation and deallocation of arrays use the macros ABI_ALLOCATE(array, (dim1, dim2))) and ABI_DEALLOCATE(array) defined in ~abinit/src/incs/abi_common.h. Use ABI_DATATYPE_ALLOCATE(foo, shape) and ABI_DATATYPE_DEALLOCATE(foo) if foo is a user-defined datatype+6.f For allocation and deallocation of arrays use the macros ABI_ALLOCATE(array, (dim1, dim2))) and ABI_DEALLOCATE(array) defined in ~abinit/src/incs/abi_common.h. Use ABI_DATATYPE_ALLOCATE(foo, shape) and ABI_DATATYPE_DEALLOCATE(foo) if foo is a user-defined datatype
  
-====== 6. Coding practice ======+====== 7. Coding practice ======
  
   * Run innermost loop fastest in looping. This is simply less CPU time consuming in Fortran.(JB:I'm sad it cannot be enforced :o()   * Run innermost loop fastest in looping. This is simply less CPU time consuming in Fortran.(JB:I'm sad it cannot be enforced :o()
Line 500: Line 491:
   * ***MG_TOO_COMPLICATED_USEFASTLIBS_INSTEAD*** On many machines cache memory conflicts, which slow down performance, are avoided by not using dimension of arrays in multiples of 256. Thus it is recommended to avoid array lengths which are multiples of 256. This becomes especially important in the use of Fast Fourier Transforms. (usually enforced)   * ***MG_TOO_COMPLICATED_USEFASTLIBS_INSTEAD*** On many machines cache memory conflicts, which slow down performance, are avoided by not using dimension of arrays in multiples of 256. Thus it is recommended to avoid array lengths which are multiples of 256. This becomes especially important in the use of Fast Fourier Transforms. (usually enforced)
  
-====== 7. Exception handling and I/Os ======+====== 8. Exception handling and I/Os ======
  
 MG: This part must be rewritten. We should stop the code via macros such as MSG_ERROR MG: This part must be rewritten. We should stop the code via macros such as MSG_ERROR
Line 571: Line 562:
 (enforced) (enforced)
  
-====== 8. To be avoided ======+====== 9. To be avoided ======
  
   * Use   * Use
Line 607: Line 598:
        ! although grammatically incorrect. (usually enforced)        ! although grammatically incorrect. (usually enforced)
                
-====== 9. Use of BLAS and LAPACK subroutines ======+====== 10. Use of BLAS and LAPACK subroutines ======
  
 BLAS and LAPACK subroutines are public domain subroutines, gathered BLAS and LAPACK subroutines are public domain subroutines, gathered
Line 665: Line 656:
 (at present, no other BLAS routines than those called by LAPACK are used in ABINIT, so these rules are indications for the future) (at present, no other BLAS routines than those called by LAPACK are used in ABINIT, so these rules are indications for the future)
  
-====== Modules ======+====== 11. Modules ======
  
 MG: This section should be rewritten from scratch! MG: This section should be rewritten from scratch!
Line 688: Line 679:
 Be cautious when you introduce such a feature, and mention it to the ABINIT coordinator. Be cautious when you introduce such a feature, and mention it to the ABINIT coordinator.
  
-====== Derived datatypes ======+====== 12. Derived datatypes ======
  
-Derived datatypes should be declared in the adequate module (MG: And this rule is not followed in many places, e.g dataset_type, header_type ...)+12.a. Derived datatypes should be declared in the adequate module (MG: And this rule is not followed in many places, e.g dataset_type, header_type ...)
 These are powerful F90 constructs, but the information about them is not local to the subroutine  These are powerful F90 constructs, but the information about them is not local to the subroutine 
 where they are used, so they should be introduced in a controlled way, in order for the programmers to become sufficiently easily familiarized with them: the introduction of a new derived datatype must be made in agreement with the coordinator of ABINIT. where they are used, so they should be introduced in a controlled way, in order for the programmers to become sufficiently easily familiarized with them: the introduction of a new derived datatype must be made in agreement with the coordinator of ABINIT.
 The introduction of appropriate derived datatypes in ABINIT is one of the central issues of v3.2 and later versions. The introduction of appropriate derived datatypes in ABINIT is one of the central issues of v3.2 and later versions.
  
-11.b. Suffix a type identifier with '_type'. (MG: What about ''obj_t'' At present we use both!) For example:+12.b. Suffix a type identifier with '_type'. (MG: What about ''obj_t'' At present we use both!) For example:
  
     TYPE ipe_type              ! information on program execution     TYPE ipe_type              ! information on program execution
Line 706: Line 697:
    TYPE(ipe_type) :: ipe    TYPE(ipe_type) :: ipe
  
-11.c. Pros and cons.+12.c. Pros and cons.
  
 Grouping connected variables into structured types is interesting for readability (it avoids too long Grouping connected variables into structured types is interesting for readability (it avoids too long
Line 716: Line 707:
 However, source code itself may become less readable. Also, remember that the use of structured types is never more efficient for CPU: complex declarations should be avoided. However, source code itself may become less readable. Also, remember that the use of structured types is never more efficient for CPU: complex declarations should be avoided.
  
-====== 12. Other topics ======+====== 13. Other topics ======
  
 For the time being, pointers are only allowed when an array has to be allocated in a subprogram, and For the time being, pointers are only allowed when an array has to be allocated in a subprogram, and
developers/coding_rules.1527367684.txt.gz · Last modified: 2018/05/26 20:48 by Xavier Gonze