Originally by RolfRabenseifner on 2010-09-01 10:39:40 -0500

230-B: New module "USE mpi_f08"See Ticket #229-A for an overview on the New MPI-3 Fortran Support.

Description

-Major decisions in this ticket:*

Full compile-time argument checking with this new mpi_f08 module.
A new mpi_f08 module for all new features to keep compatibility for existing Fortran interface with existing mpi module.
Transition from a history-based wording (Basic & Extended Fortran Support) to a consistent description of the Fortran support in MPI-3.

Further details are handled in further tickets:

Individual handle types for handle arguments, variables, and constants, see Ticket #231-C.
Void * arguments are presented by TYPE(*) DIMENSION(..) . With this, non-contiguous sub-arrays can now be used with nonblocking routines. This feature requires Fortran 2008 support, details see Ticket #234-F.
All MPI routines will have a new Fortran 2008 function specification (The existing Fortran function specifications meet "INCLUDE mpif.h" and "USE mpi"), for details see Ticket #247-S.
Solving problems with nonblocking MPI operations sub-arrays and registers through usage of keyword "ASYNCHRONOUS", see Ticket #238-J.
Extended Scope

None.

History

Current MPI-2.2 requires that mpif.h contains full MPI-2.2 because in the Extended Fortran Support, the standard requires (MPI-2.2, page 489, line 7):

Applications may use either the mpi module or the mpif.h include file.

Proposed Solution

''The ticket numbers in parenthesis (#xxx-X) indicate sentences that are removed if the appropriate ticket is not voted in.''

-MPI-2.2, Chapter 1, Introduction, Page 1, lines 23-25 read*

MPI is not a language, and all MPI operations are expressed as functions, subroutines, or methods, according to the appropriate language bindings, which for C, C++, Fortran-77, and Fortran-95, are part of the MPI standard.

-but should read*

MPI is not a language, and all MPI operations are expressed as functions, subroutines, or methods, according to the appropriate language bindings, which for C, C++, ~~Fortran-77, and Fortran-95,~~ and Fortran, are part of the MPI standard.

-MPI-2.2, Chapter 1, Introduction, Page 2, line 1 reads*

Allow convenient C, C++, Fortran-77, and Fortran-95 bindings for the interface.

-but should read*

Allow convenient C, C++, ~~Fortran-77, and Fortran-95,~~ and Fortran bindings for the interface.

-MPI-2.2, Chapter 1, Introduction, Page 4, line 34: Add in the new section "1.6 Background of MPI-3.0":*

A new Fortran mpi_f08 module is introduced to provide extended compile-time argument checking and buffer handling in nonblocking routines. (#230-B) The existing mpi module provides compile-time argument checking on the basis of existing MPI-2.2 routine definitions. (#232-D) The use of mpif.h is strongly discouraged. (#233-E)

-MPI-2.2, Chapter 2, Terms and Convention, Page 9, line 18 reads*

Some of the major areas of difference are the naming conventions, some semantic definitions, file objects, Fortran 90 vs Fortran 77, C++, processes, and interaction with signals.

-and should not be modified*

-MPI-2.2, Chapter 2, Terms and Convention, Section 2.3 Procedure Specification, page 11, lines 20-23 read*

All MPI functions are first specified in the language-independent notation. Immediately below this, the ISO C version of the function is shown followed by a version of the same function in Fortran and then the C++ binding. Fortran in this document refers to Fortran 90; see Section 2.6.

-but should read*

All MPI functions are first specified in the language-independent notation. Immediately below this, language dependent bindings follow:

The ISO C version of the function.
The Fortran version of the same function used with USE mpi or INCLUDE 'mpif.h'.
The Fortran version used with USE mpi_f08.
The C++ binding (which is deprecated). [[BR]] Fortran in this document refers to Fortran 90 and higher; see Section 2.6.

-MPI-2.2, Chapter 2, Terms and Conventions, Section 2.6.2 Fortran Binding Issues, page 18, line 6-9 reads*

The MPI Fortran binding is inconsistent with the Fortran 90 standard in several respects. These inconsistencies, such as register optimization problems, have implications for user codes that are discussed in detail in Section 16.2.2. They are also inconsistent with Fortran 77.

-but should read*

The MPI Fortran bindings are is inconsistent with the Fortran 90 standard in several respects. These inconsistencies, such as register optimization problems, have implications for user codes that are discussed in detail in Section 16.2.2. ~~They are also inconsistent with Fortran 77.~~

-_MPI-2.2, Section 13.6.7 MPIOffset Type, page 442, lines 14-15 read*

In Fortran, the corresponding integer is an integer of kind MPI_OFFSET_KIND, defined in mpif.h and the mpi module.

-but should read*

In Fortran, the corresponding integer is an integer with of kind parameter MPI_OFFSET_KIND, which is defined in the mpi_f08 module, the mpi module and the
mpif.h include file.

'''MPI-2.2, Chapter 16.2, Fortran Support: [[BR]] Section 16.2.1 Overview, MPI-2.2, page 480, lines 23-47 '''

The Fortran MPI-2 language bindings have been designed to be compatible with the Fortran 90 standard (and later). These bindings are in most cases compatible with Fortran 77, implicit-style interfaces.

-Rationale.* Fortran 90 contains numerous features designed to make it a more "modern"
language than Fortran 77. It seems natural that MPI should be able to take
advantage of these new features with a set of bindings tailored to Fortran 90. MPI
does not (yet) use many of these features because of a number of technical difficulties.
-(End of rationale.)*

MPI defines two levels of Fortran support, described in Sections 16.2.3 and 16.2.4. In the rest of this section, "Fortran" and "Fortran 90" shall refer to "Fortran 90" and its successors, unless qualified.

Basic Fortran Support An implementation with this level of Fortran support provides the original Fortran bindings specified in MPI-1, with small additional requirements specified in Section 16.2.3.
Extended Fortran Support An implementation with this level of Fortran support provides Basic Fortran Support plus additional features that specifically support Fortran 90, as described in Section 16.2.4.

A compliant MPI-2 implementation providing a Fortran interface must provide Extended Fortran Support unless the target compiler does not support modules or KIND- parameterized types.

-together with MPI-2.2, page 488, lines 19-24*

A new set of functions to provide additional support for Fortran intrinsic numeric types, including parameterized types: MPI_SIZEOF, MPI_TYPE_MATCH_SIZE, MPI_TYPE_CREATE_F90_INTEGER, MPI_TYPE_CREATE_F90_REAL and MPI_TYPE_CREATE_F90_COMPLEX. Parameterized types are Fortran intrinsic types which are specified using KIND type parameters. These routines are described in detail in Section 16.2.5.

-together with MPI-2.2, page 489, lines 7-14*

Applications may use either the mpi module or the mpif.h include file. An implementation may require use of the module to prevent type mismatch errors (see below).

-Advice to users.* It is recommended to use the mpi module even if it is not necessary to
use it to avoid type mismatch errors on a particular system. Using a module provides
several potential advantages over using an include file. *(End of advice to users.)*

It must be possible to link together routines some of which USE mpi and others of which INCLUDE mpif.h.

-but should read (TODO: check whether "the only new language feature" is true)*

The Fortran MPI-2 language bindings have been designed to be generally compatible with the Fortran 90 standard (and later). ~~These bindings are in most cases compatible with Fortran 77, implicit-style interfaces.~~

-Rationale.* Fortran 90 contains numerous features designed to make it a more "modern"
language than Fortran 77. It seems natural that MPI should be able to take
advantage of these new features with a set of bindings tailored to Fortran 90.
~~MPI does not (yet) use many of these features because of a number of technical difficulties.~~
__In Fortran 2008, the only new language features used, are  of assumed type and assumed rank.
They were defined to
allow the definition of choice arguments as part of the Fortran language.__
-(End of rationale.)*

MPI defines ~~two levels~~ three methods of Fortran support: ~~, described in Sections 16.2.3 and 16.2.4. In the rest of this section, "Fortran" and "Fortran 90" shall refer to "Fortran 90" and its successors, unless qualified.~~

1. __**`INCLUDE 'mpif.h'`**__ ~~**Basic Fortran Support**~~
__This method is described__
~~An implementation with this level of Fortran support provides
the original Fortran bindings specified in MPI-1, with small additional requirements
specified~~
in Section 16.2.3.
__The use of the include file `mpif.h` is strongly discouraged since MPI-3.0 **(#233-E)**.__

2. __**`USE mpi`**__ ~~**Extended Fortran Support**~~
__This method is__
~~An implementation with this level of Fortran support
provides Basic Fortran Support plus additional features that specifically support
Fortran 90, as~~ described
in Section 16.2.4__ and requires compile-time argument checking__.

3. __**`USE mpi_f08`** This method is described in Section 16.2.5
and requires compile-time argument checking that includes also unique handle types.__

A compliant MPI-23 implementation providing a Fortran interface must provide ~~Extended Fortran Support unless the target compiler does not support modules or KIND- parameterized types~~all three Fortran support methods.

Applications subroutines and functions may use either one of the ~~mpi~~ modules or the mpif.h include file. An implementation may require use of one of the modules to prevent type mismatch errors~~ (see below)~~.

-Advice to users.* It is recommended to use __one of__ the ~~mpi~~__MPI__ module__s__ even
if it is not necessary to
use it to avoid type mismatch errors on a particular system. Using a module provides
several potential advantages over using an include file. *(End of advice to users.)*

In a single application, it must be possible to link together routines some of which USE mpi and others of which USE mpi_f08 or INCLUDE mpif.h.

The INTEGER compile-time constant MPI_SUBARRAYS is MPI_SUBARRAYS_SUPPORTED if all choice arguments are defined in explicit interfaces with standardized assumed type and assumed rank, otherwise it equals MPI_SUBARRAYS_UNSUPPORTED. This constant exists with each Fortran support method, but not in the C/C++ header files. The value may be different for each Fortran support method. (#234-F)****

Section 16.2.2 gives an overview on known problems when using Fortran together with MPI. Section 16.2.5new and (#238-J) Section 16.2.5 describe additional functionality that is part of the Fortran support. func{MPI_F_SYNC_REG} is needed for one of the methods to prevent register optimization problems. (#238-J) A ~~new~~ set of functions to provide additional support for Fortran intrinsic numeric types, including parameterized types. The functions are: MPI_SIZEOF, MPI_TYPE_MATCH_SIZE, MPI_TYPE_CREATE_F90_INTEGER, MPI_TYPE_CREATE_F90_REAL and MPI_TYPE_CREATE_F90_COMPLEX. Parameterized types are Fortran intrinsic types which are specified using KIND type parameters. ~~These routines are described in detail in Section 16.2.5.~~

-MPI-2.2, Section 16.2.3 Basic Fortran Support, page 487, line 43 - page 488, line 4, reads*

16.2.3 Basic Fortran Support

Because Fortran 90 is (for all practical purposes) a superset of Fortran 77, Fortran 90 (and future) programs can use the original Fortran interface. The following additional requirements are added:

Implementations are required to provide the file mpif.h, as described in the original MPI-1 specification.
mpif.h must be valid and equivalent for both fixed- and free- source form.

-but should read *

16.2.3 ~~Basic~~ Fortran Support Through the mpif.h Include File

The use of the mpif.h include file is strongly discouraged (#233-E).

Because Fortran 90 is (for all practical purposes) a superset of Fortran 77, Fortran 90 (and future) programs can use the original Fortran interface. The Fortran bindings are compatible with Fortran 77 implicit-style interfaces in most cases. ~~The following additional requirements are added:~~ The include file mpif.h must:

~~1. Implementations are required to provide the file mpif.h, as described in the original MPI-1 specification.~~

Define all named MPI constants.
Declare MPI functions that return a value.
Define all handles as INTEGER. This is reflected in the first of the two Fortran interfaces in each MPI function definition.
~~2. mpif.h must~~ Be valid and equivalent for both fixed- and free- source form.

For each MPI routine, an implementation can choose to use an implicit or explicit interface.

-MPI-2.2, Section 16.2.4 Extended Fortran Support, page 488, lines 14-40 read*

16.2.4 Extended Fortran Support

Implementations with Extended Fortran support must provide:

1. An mpi module
2. A new set of functions to provide additional support for Fortran intrinsic numeric
types, including parameterized types: MPI_SIZEOF, MPI_TYPE_MATCH_SIZE,
MPI_TYPE_CREATE_F90_INTEGER, MPI_TYPE_CREATE_F90_REAL and
MPI_TYPE_CREATE_F90_COMPLEX. Parameterized types are Fortran intrinsic types
which are specified using KIND type parameters. These routines are described in detail
in Section 16.2.5.

Additionally, high-quality implementations should provide a mechanism to prevent fatal type mismatch errors for MPI routines with choice arguments.

The mpi Module

An MPI implementation must provide a module named mpi that can be used in a Fortran 90 program. This module must:

Define all named MPI constants.
Declare MPI functions that return a value.

An MPI implementation may provide in the mpi module other features that enhance the usability of MPI while maintaining adherence to the standard. For example, it may:
Provide interfaces for all or for a subset of MPI routines.
Provide INTENT information in these interface blocks.

-but should read*

16.2.4 ~~Extended~~ Fortran Support Through the mpi Module

~~Implementations with Extended Fortran support must provide:~~

~~1. An mpi module~~[[BR]]
~~2. A new set of functions to provide additional support for Fortran intrinsic numeric
types, including parameterized types: MPI_SIZEOF, MPI_TYPE_MATCH_SIZE,
MPI_TYPE_CREATE_F90_INTEGER, MPI_TYPE_CREATE_F90_REAL and
MPI_TYPE_CREATE_F90_COMPLEX. Parameterized types are Fortran intrinsic types
which are specified using KIND type parameters. These routines are described in detail
in Section 16.2.5.~~

~~Additionally, high-quality implementations should provide a mechanism to prevent fatal type mismatch errors for MPI routines with choice arguments.~~

~~The mpi Module~~

An MPI implementation must provide a module named mpi that can be used in a Fortran 90 program. This module must:

Define all named MPI constants
Declare MPI functions that return a value.
Provide explicit interfaces for all MPI routines, i.e., this module guarantees compile-time argument checking, and allows positional and keyword-based argument lists. (#232-D)****
Define all handles as INTEGER. This is reflected in the first of the two Fortran interfaces in each MPI function definition.
Define also all the named handle types (#231-C) and MPI_Status (#243-O) that are used in the mpi_f08 module. They are needed only when the application needs to convert and old-style INTEGER handle into a new-style handle with a named type. (#231-C)

An MPI implementation may provide other features in the mpi module ~~other features~~ that enhance the usability of MPI while maintaining adherence to the standard. For example, it may: provide INTENT information in these interface blocks.
~~Provide interfaces for all or for a subset of MPI routines.~~ (#232-D)
~~Provide INTENT information in these interface blocks.~~

'''MPI-2.2, Section 16.2.4, page 489, lines 7-14 are removed (they have been already used in Section 16.2.1)'''

-After MPI-2.2, Section 16.2.4, page 489, line 30, the following section is added* (for better readability of this ticket, the following new text is not underlined although it should):

16.2.5 Fortran Support Through the mpi_f08 Module

An MPI implementation must provide a module named mpi_f08 that can be used in a Fortran program. With this module, new Fortran definitions are added for each MPI routine (#247-S), except for routines that are deprecated (#241-M). This module must:

Define all named MPI constants.
Declare MPI functions that return a value.
Provide explicit interfaces for all MPI routines, i.e., this module guarantees compile-time argument checking.
Define all handles with uniquely named handle types (instead of INTEGER handles in the mpi module). This is reflected in the second of the two Fortran interfaces in each MPI function definition. -(#231-C)*
Set the INTEGER compile-time constant MPI_SUBARRAYS to MPI_SUBARRAYSSUPPORTED and declare choice buffers with the Fortran 2008 feature assumed-type and assumed-rank "TYPE(), DIMENSION(..)" if the underlying Fortran compiler supports it. With this, non-contiguous sub-arrays are valid also in nonblocking routines. *_(#234-F)**
Set the MPI_SUBARRAYS compile-time constant to MPI_SUBARRAYS_UNSUPPORTED and declare choice buffers with a compiler-dependent mechanism that overrides type checking if the underlying Fortran compiler does not support the Fortran 2008 assumed-type and assumed-rank notation. In this case, the use of non-contiguous sub-arrays in nonblocking calls may be restricted as with the mpi module. (#234-F)

-Advice to implementors.* In this case, the choice argument may be implemented with an explicit interface with compiler directives, for example:

!DEC$ ATTRIBUTES NO_ARG_CHECK :: BUF[[BR]] !$PRAGMA IGNORE_TKR BUF[[BR]] REAL, DIMENSION(*) :: BUF

-(End of advice to implementors.) (#234-F) *
Declare each argument with an INTENT=IN, OUT, or INOUT as appropriate (#242-N).
Declare all status and array_of_statuses output arguments as optional through function overloading, instead of using MPI_STATUS_IGNORE (#244-P).
Declare all array_of_errcodes output arguments as optional through function overloading, instead of using MPI_ERRCODES_IGNORE (#244-P).
Declare all ierror output arguments as OPTIONAL, except for user-defined callback functions (e.g., COMM_COPY_ATTR_FUNCTION) and their predefined callbacks (e.g., MPI_NULL_COPY_FN). (#239-K)

-Rationale. For user-defined callback functions (e.g., comm_copy_attr_fn) and their predefined callbacks (e.g., MPI_NULL_COPY_FN), the ierror argument is not optional, i.e., these user-defined functions need not to check whether the MPI library calls these routines with or without an actual ierror output argument. -(End of rationale.) (#239-K)

The MPI Fortran bindings in the mpi_f08 module are designed based on the Fortran 2008 standard [fortran2008] together with the Technical Report (TR) on Further Interoperability with C [fortran2008:tr-interop:N1845] of the ISO/IEC JTC1/SC22/WG5 (Fortran) working group.

-Rationale.* The TR on further interoperability with C was defined by WG5 to support the MPI-3.0 standardization. "It is the intention of ISO/IEC JTC1/SC22/WG5 that the semantics and syntax specified by this technical report be included in the next revision of the Fortran International Standard without change unless experience in the implementation and use of this feature identifies errors that need to be corrected, or changes are needed to achieve proper integration, in which case every reasonable effort
will be made to minimize the impact of such changes on existing implementations."footnote([fortran2008:tr-interop:N1845] page iv, sentence 7.)

This TR contains language features that are needed for the MPI bindings in the mpi_f08 module: assumed type and assumed rank. Here, it is important that any possible actual argument can be used for such dummy arguments, e.g., scalars, arrays, assumed-shape arrays, assumed-size arrays, allocatable arrays, and with any element type, e.g., REAL, REAL*4, CHARACTER*5, CHARACTERR*(*), derived types.

Furthermore, the implementors of the MPI Fortran bindings can freely choose whether all bindings are defined as BIND(C). This is important to implement the Fortran mpi_f08 interface with only one set of portabLe wrapper routines written in C. For this implementation goal, the following additional features are used: BIND(C) together with OPTIONAL, and with standard Fortran types like INTEGER and CHARACTER (i.e., not only with INTEGER(C_INT)).

The MPI Forum wants to acknoledge this important effort by the Fortran WG5 committee. -(End of rationale.)*

-With the following new entries in refs.bib:*

@Manual{fortran2008,
  title        = "Information technology -- Programming languages 
                  -- Fortran -- Part 1: Base language",
  organization = "International Organization for Standardization",
  address      = "Geneva",
  year         = 2010, 
  month        = "November",
  annote       = "ISO/IEC 1539-1:2010"
}

@Manual{fortran2008:tr-interop:N1845,
  title        = "TR on further interoperability with C",
  organization = "International Organization for Standardization, 
                  ISO/IEC/SC22/WG5 (Fortran)",
  address      = "Geneva",
  year         = 2011, 
  month        = "March, 3",
  annote       = "Draft N1845 TR29113",
  source={http://www.nag.co.uk/sc22wg5/ and 
          ftp://ftp.nag.co.uk/sc22wg5/N1801-N1850/N1845.pdf}
}

'''Renumbering of MPI-2.2, Section 16.2.5 in Section 16.2.6, on page 489, line 31.

Impact on Implementations

This module requires mainly

Module interface due to new MPI-3.0 interface, for details, see Ticket #247-S
For all choice buffer arguments (<type> buf(*)), new MPI datatype handling must be implemented based on the internal Fortran argument descriptor used with the "TYPE(*), DIMENSION(..)" declarations, for details see Ticket #234-F.
Impact on Applications / Users

None, as long they do not use this new module.

If they want to use this new mpi_f08 module then they must modify:

Corrections if there are syntactical errors in the application due to strong typing.
Substitute "include 'mpif.h'" or "USE mpi" with "USE mpi_f08"
Substitute all declarations of INTEGER handle variables with the new TYPE(MPI_Comm), etc. (only if Ticket #231-C is voted in)
Alternative Solutions

Entry for the Change Log

MPI-2.2, Section xxxx on page xxx.[[BR]] yyy.

mpi-forum / mpi-forum-historic

New MPI-3 Fortran Support - #B: New module "USE mpi_f08" #230

230-B: New module "USE mpi_f08"See Ticket #229-A for an overview on the New MPI-3 Fortran Support.

Description

Extended Scope

History

Proposed Solution

Impact on Implementations

Impact on Applications / Users

Alternative Solutions

Entry for the Change Log