Tips for ABINIT users and developers - OBSOLETE!

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<WRAP important>**IMPORTANT WARNING**\\ **<color #ed1c24>This Page is obsolete.</color>** Please refer to www.abinit.org!</WRAP>

====== New FORTRAN 2003 features for ABINIT 8 ======
\\ \\  
During the 6<sup>th</sup> ABINIT International Developer meeting (April 2013 in Dinard, France), it has been decided to allow the use of a subset of ''FORTRAN 2003'' features in ABINIT. The present document is a first proposal of such a set of F2003 features; it is submitted for discussion.

To choose this set of features, we tried to respect the following rules:

  * The F2003 features must be supported by a large majority of recent compilers. An exhaustive list of compilers and their F2003 features can be found at:\\ [[http://fortranwiki.org/fortran/show/Fortran+2003+status]]

  * We have focused on the features that are of significant importance for high-performance computing and on the language extensions that help improve the readability and the portability of the code

This is a first attempt; other F2003 extensions are not admitted for the moment, but their inclusion could be taken into consideration in the next versions.
Important: introduction of the new F2003 extensions implies that, from now, not all compilers can be supported by ABINIT (see first section of the document).

//M. Torrent (CEA-Bruyères-le-Châtel)//\\
//M. Giantomassi (UC Louvain)//
\\ \\ 

<HTML><hr></HTML>
===== I. Notes on Fortran compilers and ABINIT =====
<HTML><br></HTML>

  * All the new features proposed hereafter have already been tested on the ABINIT test farm. If someone wants ABINIT to be compatible with another computing environment, a new //buildbot// slave should be added to the test farm

  * Some of these extensions are **mandatory** in the sense that it won’t be possible to compile the code if the compiler does not support these F2003 features (e.g. ''ALLOCATABLE'' arrays in data types). Mandatory extensions are presented in Section II.

  * Other extensions are **optional** since they can be made available in a portable way via CPP macros and/or wrapper functions so that code semantics is preserved (e.g. ''CONTIGUOUS'' attribute). Optional extensions are presented in Section III.

We propose to divide the compilers in the following four categories:

  - **Officially supported**\\ All tests are OK, the most important libraries and plugins are enabled and tested.\\ \\ 
  - **Deprecated**\\ Still officially supported but users are strongly encouraged to upgrade to a more recent version or to use one of the officially supported compilers since future releases of ABINIT may drop support for this version of the compiler.\\ Example: //g95// (no more maintained)\\ \\ 
  - **Unstable**\\ We cannot ensure that all the features of ABINIT and the most important plugins and libraries work as expected with this version of the compiler.\\ Example: //PGI v9+//\\ \\ 
  - **Unsupported\\ **Due to the introduction of the F2003 extensions, some old compilers will be excluded //de facto//.\\ Example: //gfortran// versions before 4.3, //ifort// versions before 8.x, //open64//, //ORACLE//
\\ 
<HTML><hr></HTML>
===== II. Fortran 2003 features allowed in ABINIT =====
//Mandatory extensions, implemented in (almost) all recent compilers//
<HTML><br></HTML>

==== ALLOCATABLE arrays inside user-defined datatypes and as routine arguments ====

This was not possible in F95 but it is perfectly legit in F2003.\\ 
Note that ''ALLOCATABLE'' arrays are much more efficient than pointers because:
  - An allocatable array is always continuous in memory and the compiler can perform important optimizations that are not possible when pointers are involved. Pointers, indeed, may point to non-contiguous memory locations, and the compiler MUST take this possibility into account thus leading to suboptimal code.
  - The initial status of a pointer is ''undefined'' and this forces the developers to add a lot of boilerplate code just to nullify the pointers declared in a data type. The use of allocatable arrays solves this.
  - Runtime errors are much easier to detect and debug.

Example of a user-defined data type with an allocatable entity:
<code fortran>
 type (pawtab_type) 
   real(dp),allocatable :: phi(:, :)
 end type pawtab_type

 type(pawtab_type) :: pawtab

 !Allocate memory
 allocate(pawtab%phi(300, 5))

 !Deallocate memory
 if (allocated(pawtab%phi)) deallocate(pawtab%phi)
</code>

//As a rule of thumb, avoid pointers as much a possible. Use allocatable arrays if you need dynamic memory in a datatype or if you want to allocate memory inside a procedure and return it to the caller.//

Example of a procedure that allocates memory and returns it to the caller:
<code fortran>
 subroutine foo(out_array)

  integer,allocatable,intent(out) :: out_array(:)

  !Compute the size of out_array
  n = ...

  !Allocate contiguous memory
  allocate(out_array(n)
  out_array = ...

 end subroutine foo
</code>
\\ 
==== INTENT attribute for pointers ====

Following the ABINIT coding rules, each argument of routine should have an ''INTENT'' attribute, even pointers. This is now possible in F2003.

Example:
<code fortran>
 real(dp), pointer, intent(in) :: cg_ptr(:,:)
</code>

Note that the intent refers to the __association status of the pointer__ without any reference to the target. If you are not sure about which intent should be used, use ''intent(in)''.
\\ \\ 
==== Access to computing environment ====

F2003 gives access to a lot of information about the computing environment.

Example:
<code fortran>
 CALL GET_ENVIRONMENT_VARIABLE(…) ! to get an environment variable
 CALL GET_COMMAND(..)
 CALL COMMAND_ARGUMENT_COUNT(..)
 CALL GET_COMMAND_ARGUMENT(,…) ! to access to the command line
</code>

These features can be used to improve the user interface (e.g. command line options can be passed to ABINIT), or to modify the behavior at run-time depending on the value of the environment variables.
\\ \\ 
==== Array constructor with [ ] syntax ====

This simple extension makes the array constructor syntax more readable. Developers are encouraged to use the new syntax whenever possible in order to improve the readability of the code.

Example :
<code fortran>
 integer, parameter :: cute(4)=[1,2,3,4]
</code>
\\ 
==== Named constants in complex constant declaration ====

A very simple – but useful – feature.

Example:
<code fortran>
 complex(dpc), parameter :: CC=(0._dp,pi)
</code>
\\ 
==== Use of interoperability with C ====

The F2003 intrinsic module ''ISO_C_BINDINGS'' provides a standardized interface that facilitates the interoperability between Fortran and C. This new feature is of paramount importance for high-performance computing since one can:
  * Call C procedures from Fortran (e.g. FFTW3),
  * Pass complex arguments to Fortran functions having an explicit interface with reals without having to perform a detrimental copy-in, copy out.
For this, the availability of the ''ISO_C_BINDINGS'' module is required; this is OK for all recent compilers.

At present, ABINIT requires a ''ISO_C_BINDINGS'' module providing:
  * C types: ''C_INT'', ''C_SHORT'', ''C_LONG'', etc…
  * C pointer ''C_PTR'' type
  * ''C_LOC'' and ''C_F_POINTER'' functions.\\ ''C_LOC'' returns the location of a C pointer associated to a Fortran object.\\ ''C_F_POINTER'' returns a Fortran pointer from a C pointer.
  * ''C_BIND'' attribute that allows the developer to rename a C function as Fortran one or to define a Fortran datatype that is interoperable with a C structure.

These features are already used in important parts such as ''CUDA'' or ''FFTW3''.

Example (how to call a C function):
<code fortran>
 type(C_PTR) :: blabla
 complex(C_INT) :: data
 blabla = my_c_function(data)
</code>

Example:\\ 
How to avoid a copy while passing real arrays to a procedure that expects complex arguments and has an explicit interface\\ 
Copy //real// array ''data1_real'' in ''data2_real'' using //complex// function ''zcopy'':
<code fortran>
 real(dp),target :: data1_real(2,nn),data2_real(2,nn)
 complex(dpc), ABI_CONTIGUOUS pointer :: data1_cplx(:),data2_cplx(:)

 call C_F_POINTER(C_LOC(data1_real),data1_cplex, shape=[nn])
 call C_F_POINTER(C_LOC(data2_real),data2_cplex, shape=[nn])

 !If zcopy has an explicit interface, the compiler won’t
 !allow you to pass data1_real because the procedure expects
 !an argument of type complex(dpc)

 call zcopy(nn,data1_cplx,data2_cplx)
</code>

We propose to hide all this stuff in a «helper function» that will return a complex Fortran pointer from a real Fortran array.
\\ \\ 
==== IMPORT statement ====

Used in interfaces, it allows the access to the variables and the types defined in modules.

Example:
<code fortran>
 use m_pawtab, only : pawtab_type

 interface
   subroutine my_rout(pawtab)
   IMPORT :: pawtab_type
   type(pawtab_type), intent(inout) :: pawtab
 end interface
</code>
\\ \\ 

<HTML><hr></HTML>
===== III. Fortran 2003 features allowed in ABINIT only by the use of specific functions =====
//Optional extensions, implemented in the majority of compilers, but not all//
<HTML><br></HTML>

==== Flush statement ====

The execution of a ''FLUSH'' statement for an external file causes data written to it to be available to other processes.

One should flush Fortran files though the ''flush_unit'' helper function or by calling ''wrtout'' with the optional argument ''do_flush''.\\ 
The reason for such limitation is that not all the compilers provide a standard Fortran ''flush'' and ''flush_unit'' uses CPP options to implement this feature in a semi-portable way.

Example:
<code fortran>
 open(unit=unt, file=”foo.dat”)
 write(unt, *)”hello world”
 call flush_unit(unt)

 !For flushing ab_out or std_out, use
 call wrtout(std_out,message,'COLL',do_flush=.true.)
</code>

Note that the ''flush'' statement is very important to avoid race conditions that can occur when multiple ''MPI'' processors are reading and writing from the same file.

Example:
<code fortran>
 open(unit=unt, file=”foo.dat”)

 if (me==master) then
   write(unt,*)”hello”
   !Flush the unit so that we force the writing of the string
   !that will be read by the other nodes
   call flush_unit(unt)
 end if

 call xmpi_barrier(comm)
 if (me /= master) then
   !Can safely read the string because master called flush_unit
   read(unt,*)string
 end if
</code>

The ''MPI'' library provides an interface to flush the IO buffer but only if the file has been open with ''MPI_FILE_OPEN''.
\\ \\ 
==== IOMSG and NEWUNIT specifiers in a OPEN statement ====

**''IOMSG''** is a string with a description of the error that may occur during an IO operation (e.g not enough permissions, disk quota error, non-existent file when reading ...)

**''NEWUNIT''** is used to receive a free unit, i.e. a logical Fortran unit that is not already in use in other parts of the code.

Developers should take advantage of these new features through the ''open_file'' helper function defined in the ''m_io_tools'' module.

Example:
<code fortran>
 use m_io_tools, only : open_file

 ii = open_file(filename,iomsg,newunit=tmp_unit, &
 &              form="formatted",action="write")

 !If IOError, print a message describing the error and stop the code
 if (ii/=0) MSG_ERROR(iomsg)
</code>
\\ 
==== Use of IEEE Arithmetic ====

This extension allows one to trap or to signal possible floating point exceptions at run time without compiling the code in debug mode. Developers can use the procedures defined in the ''m_xiee.F90'' module for debugging/testing purposes (these functions are empty if the compiler does not support IEEE arithmetic).

Production code should not contain debugging sections with calls to the procedures defined in ''m_xieee.F90'' in order to avoid a significant slowdown of the code. Note that one can easily trap/signal floating-point exceptions thanks to the // command line options// ''--ieee-halt'' and ''--ieee-signal''.
\\ \\ 
==== Fortran extensions supported via CPP macros ====

This section discusses a set of features belonging to F2003/F2008 that are vey useful for optimizing CPU-critical parts or for constructing reliable software. The features described in this section are made available in a portable way via CPP macros defined in ''abi_common.h''.

The most important attributes supported at the time of writing are:
  * **''CONTIGUOUS''** attribute, emulated by **''ABI_CONTIGUOUS''** macro,
  * **''ASYNCHRONOUS''** attribute emulated by **''ABI_ASYNCH''** macro,
  * **''PROTECTED''** attribute, emulated by **''ABI_PROTECTED''** macro,
  * **''PRIVATE''** attribute, emulated by **''ABI_PRIVATE''** macro.

The ''CONTIGUOUS'' attribute is principally used for pointers that are used to point contiguous portions of memory. ''PROTECTED'' and ''PRIVATE'' are mainly used for data hiding and the design of libraries and robust code.

Example:
<code fortran>
 integer, ABI_CONTIGUOUS pointer :: ptr(:)
</code>