20.1.9. Additional Support for Fortran Numeric Intrinsic Types

PreviousUpNext
Up: Support for Fortran Next: Parameterized Datatypes with Specified Precision and Exponent Range Previous: Additional Support for Fortran Register-Memory-Synchronization

MPI provides a small number of named datatypes that correspond to named intrinsic types supported by C and Fortran. These include MPI_INTEGER, MPI_REAL, MPI_INT, MPI_DOUBLE, etc., as well as the optional types MPI_REAL4, MPI_REAL8, etc. There is a one-to-one correspondence between language declarations and MPI types.

Fortran (starting with Fortran 90) provides so-called KIND-parameterized types. These types are declared using an intrinsic type (one of INTEGER, REAL, COMPLEX, LOGICAL, and CHARACTER) with an optional integer KIND parameter that selects from among one or more variants. The specific meaning of different KIND values themselves are implementation dependent and not specified by the language. Fortran provides the KIND selection functions selected_real_kind for REAL and COMPLEX types, and selected_int_kind for INTEGER types that allow users to declare variables with a minimum precision or number of digits. These functions provide a portable way to declare KIND-parameterized REAL, COMPLEX, and INTEGER variables in Fortran. This scheme is backward compatible with Fortran 77. REAL and INTEGER Fortran variables have a default KIND if none is specified. Fortran DOUBLE PRECISION variables are of intrinsic type REAL with a nondefault KIND. The following two declarations are equivalent:

Image file

MPI provides two orthogonal methods for handling communication buffers of numeric intrinsic types. The first method (see the following section) can be used when variables have been declared in a portable way---using default KIND or using KIND parameters obtained with the selected_int_kind or selected_real_kind functions. With this method, MPI automatically selects the correct data size (e.g., 4 or 8 bytes) and provides representation conversion in heterogeneous environments. The second method (see ``Support for size-specific MPI Datatypes'' on page Support for Size-specific MPI Datatypes) gives the user complete control over communication by exposing machine representations.


PreviousUpNext
Up: Support for Fortran Next: Parameterized Datatypes with Specified Precision and Exponent Range Previous: Additional Support for Fortran Register-Memory-Synchronization


20.1.9.1. Parameterized Datatypes with Specified Precision and Exponent Range

PreviousUpNext
Up: Additional Support for Fortran Numeric Intrinsic Types Next: Support for Size-specific MPI Datatypes Previous: Additional Support for Fortran Numeric Intrinsic Types

MPI provides named datatypes corresponding to standard Fortran 77 numeric types: MPI_INTEGER, MPI_COMPLEX, MPI_REAL, MPI_DOUBLE_PRECISION and MPI_DOUBLE_COMPLEX. MPI automatically selects the correct data size and provides representation conversion in heterogeneous environments. The mechanism described in this section extends this model to support portable parameterized numeric types.

The model for supporting portable parameterized types is as follows. Real variables are declared (perhaps indirectly) using selected_real_kind(p, r) to determine the KIND parameter, where p is decimal digits of precision and r is an exponent range. Implicitly MPI maintains a two-dimensional array of predefined MPI datatypes D(p, r). D(p, r) is defined for each value of (p, r) supported by the compiler, including pairs for which one value is unspecified. Attempting to access an element of the array with an index (p, r) not supported by the compiler is erroneous. MPI implicitly maintains a similar array of COMPLEX datatypes. For integers, there is a similar implicit array related to selected_int_kind and indexed by the requested number of digits r. Note that the predefined datatypes contained in these implicit arrays are not the same as the named MPI datatypes MPI_REAL, etc., but a new set.


Advice to implementors.

The above description is for explanatory purposes only. It is not expected that implementations will have such internal arrays. ( End of advice to implementors.)

Advice to users.

selected_real_kind() maps a large number of (p,r) pairs to a much smaller number of KIND parameters supported by the compiler. KIND parameters are not specified by the language and are not portable. From the language point of view intrinsic types of the same base type and KIND parameter are of the same type. In order to allow interoperability in a heterogeneous environment, MPI is more stringent. The corresponding MPI datatypes match if and only if they have the same (p,r) value ( REAL and COMPLEX) or r value ( INTEGER). Thus MPI has many more datatypes than there are fundamental language types. ( End of advice to users.)

MPI_TYPE_CREATE_F90_REAL(p, r, newtype)
IN pprecision, in decimal digits (integer)
IN rdecimal exponent range (integer)
OUT newtypethe requested MPI datatype (handle)
C binding
int MPI_Type_create_f90_real(int p, int r, MPI_Datatype *newtype)
Fortran 2008 binding
MPI_Type_create_f90_real(p, r, newtype, ierror)

INTEGER, INTENT(IN) :: p, r
TYPE(MPI_Datatype), INTENT(OUT) :: newtype
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_TYPE_CREATE_F90_REAL(P, R, NEWTYPE, IERROR)

INTEGER P, R, NEWTYPE, IERROR

This function returns a predefined MPI datatype that matches a REAL variable of KIND selected_real_kind(p, r). In the model described above it returns a handle for the element D(p, r). Either p or r may be omitted from calls to selected_real_kind(p, r) (but not both). Analogously, either p or r may be set to MPI_UNDEFINED. In communication, an MPI datatype A returned by MPI_TYPE_CREATE_F90_REAL matches a datatype B if and only if B was returned by MPI_TYPE_CREATE_F90_REAL called with the same values for p and r or B is a duplicate of such a datatype. Restrictions on using the returned datatype with the "external32" data representation are given on page Parameterized Datatypes with Specified Precision and Exponent Range.

It is erroneous to supply values for p and r not supported by the compiler.

MPI_TYPE_CREATE_F90_COMPLEX(p, r, newtype)
IN pprecision, in decimal digits (integer)
IN rdecimal exponent range (integer)
OUT newtypethe requested MPI datatype (handle)
C binding
int MPI_Type_create_f90_complex(int p, int r, MPI_Datatype *newtype)
Fortran 2008 binding
MPI_Type_create_f90_complex(p, r, newtype, ierror)

INTEGER, INTENT(IN) :: p, r
TYPE(MPI_Datatype), INTENT(OUT) :: newtype
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_TYPE_CREATE_F90_COMPLEX(P, R, NEWTYPE, IERROR)

INTEGER P, R, NEWTYPE, IERROR

This function returns a predefined MPI datatype that matches a COMPLEX variable of KIND selected_real_kind(p, r). Either p or r may be omitted from calls to selected_real_kind(p, r) (but not both). Analogously, either p or r may be set to MPI_UNDEFINED. Matching rules for datatypes created by this function are analogous to the matching rules for datatypes created by MPI_TYPE_CREATE_F90_REAL. Restrictions on using the returned datatype with the "external32" data representation are given on page Parameterized Datatypes with Specified Precision and Exponent Range.

It is erroneous to supply values for p and r not supported by the compiler.

MPI_TYPE_CREATE_F90_INTEGER(r, newtype)
IN rdecimal exponent range, i.e., number of decimal digits (integer)
OUT newtypethe requested MPI datatype (handle)
C binding
int MPI_Type_create_f90_integer(int r, MPI_Datatype *newtype)
Fortran 2008 binding
MPI_Type_create_f90_integer(r, newtype, ierror)

INTEGER, INTENT(IN) :: r
TYPE(MPI_Datatype), INTENT(OUT) :: newtype
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_TYPE_CREATE_F90_INTEGER(R, NEWTYPE, IERROR)

INTEGER R, NEWTYPE, IERROR

This function returns a predefined MPI datatype that matches an INTEGER variable of KIND selected_int_kind(r). Matching rules for datatypes created by this function are analogous to the matching rules for datatypes created by MPI_TYPE_CREATE_F90_REAL. Restrictions on using the returned datatype with the "external32" data representation are given on page Parameterized Datatypes with Specified Precision and Exponent Range.

It is erroneous to supply a value for r that is not supported by the compiler.


Example Fortran selected integer and real kind buffers in MPI communications.

Image file


Advice to users.

The datatypes returned by the procedures in Example Parameterized Datatypes with Specified Precision and Exponent Range are predefined datatypes. They cannot be freed; they do not need to be committed; they can be used with predefined reduction operations. There are two situations in which they behave differently syntactically, but not semantically, from the MPI named predefined datatypes.

    1. MPI_TYPE_GET_ENVELOPE returns special combiners that allow a program to retrieve the values of p and r.
    2. Because the datatypes are not named, they cannot be used as compile-time initializers or otherwise accessed before a call to one of the MPI_TYPE_CREATE_F90_ XXX routines.
If a variable was declared specifying a nondefault KIND value that was not obtained with selected_real_kind() or selected_int_kind(), the only way to obtain a matching MPI datatype is to use the size-based mechanism described in the next section. ( End of advice to users.)

Advice to implementors.

An application may often repeat a call to MPI_TYPE_CREATE_F90_ XXX with the same combination of ( XXX, p, r). The application is not allowed to free the returned predefined, unnamed datatype handles. To prevent the creation of a potentially huge amount of handles, a high quality MPI implementation should return the same datatype handle for the same ( REAL/ COMPLEX/ INTEGER, p, r) combination. Checking for the combination ( p, r) in the preceding call to MPI_TYPE_CREATE_F90_ XXX and using a hash table to find formerly generated handles should limit the overhead of finding a previously generated datatype with same combination of ( XXX, p, r). ( End of advice to implementors.)

Rationale.

The MPI_TYPE_CREATE_F90_REAL/COMPLEX/INTEGER interface needs as input the original range and precision values to be able to define useful and compiler-independent external (Section External Data Representation: "external32") or user-defined (Section User-Defined Data Representations) data representations, and in order to be able to perform automatic and efficient data conversions in a heterogeneous environment. ( End of rationale.)
We now specify how the datatypes described in this section behave when used with the "external32" external data representation described in Section External Data Representation: "external32".

The "external32" representation specifies data formats for integer and floating point values. Integer values are represented in two's complement big-endian format. Floating point values are represented by one of three IEEE formats. These are the IEEE ``Single,'' ``Double,'' and ``Double Extended'' formats, requiring 4, 8, and 16 bytes of storage, respectively. For the IEEE ``Double Extended'' formats, MPI specifies a Format Width of 16 bytes, with 15 exponent bits, bias = +10383, 112 fraction bits, and an encoding analogous to the ``Double'' format.

The "external32" representations of the datatypes returned by MPI_TYPE_CREATE_F90_REAL/COMPLEX/INTEGER are given by the following rules.
For MPI_TYPE_CREATE_F90_REAL:

   if      (p > 33) or (r > 4931) then  external32 representation 
                                        is undefined 
   else if (p > 15) or (r >  307) then  external32_size = 16 
   else if (p >  6) or (r >   37) then  external32_size =  8 
   else                                 external32_size =  4 
For MPI_TYPE_CREATE_F90_COMPLEX: twice the size as for MPI_TYPE_CREATE_F90_REAL.
For MPI_TYPE_CREATE_F90_INTEGER:
   if      (r > 38) then  external32 representation is undefined 
   else if (r > 18) then  external32_size =  16 
   else if (r >  9) then  external32_size =  8 
   else if (r >  4) then  external32_size =  4 
   else if (r >  2) then  external32_size =  2 
   else                   external32_size =  1 
If the "external32" representation of a datatype is undefined, the result of using the datatype directly or indirectly (i.e., as part of another datatype or through a duplicated datatype) in operations that require the "external32" representation is undefined. These operations include MPI_PACK_EXTERNAL, MPI_UNPACK_EXTERNAL, and many MPI_FILE functions, when the "external32" data representation is used. The ranges for which the "external32" representation is undefined are reserved for future standardization.


PreviousUpNext
Up: Additional Support for Fortran Numeric Intrinsic Types Next: Support for Size-specific MPI Datatypes Previous: Additional Support for Fortran Numeric Intrinsic Types


20.1.9.2. Support for Size-specific MPI Datatypes

PreviousUpNext
Up: Additional Support for Fortran Numeric Intrinsic Types Next: Communication With Size-specific Types Previous: Parameterized Datatypes with Specified Precision and Exponent Range

MPI provides named datatypes corresponding to optional Fortran 77 numeric types that contain explicit byte lengths--- MPI_REAL4, MPI_INTEGER8, etc. This section describes a mechanism that generalizes this model to support all Fortran numeric intrinsic types.

We assume that for each typeclass (integer, real, complex) and each word size n there is a unique machine representation. For every pair ( typeclass, n) supported by a compiler, MPI must provide a named size-specific datatype. The name of this datatype is of the form MPI_<TYPECLASS>< n> in C and Fortran where <TYPECLASS> is one of REAL, INTEGER, or COMPLEX, and < n> is the length in bytes of the machine representation. This datatype locally matches all variables of type ( typeclass, n) in Fortran. The list of names for such types includes:

MPI_REAL4 
MPI_REAL8 
MPI_REAL16 
MPI_COMPLEX8 
MPI_COMPLEX16 
MPI_COMPLEX32 
MPI_INTEGER1 
MPI_INTEGER2 
MPI_INTEGER4 
MPI_INTEGER8 
MPI_INTEGER16 
One datatype is required for each representation supported by the Fortran compiler.


Rationale.

Particularly for the longer floating-point types, C and Fortran may use different representations. For example, a Fortran compiler may define a 16-byte REAL type with 33 decimal digits of precision while a C compiler may define a 16-byte long double type that implements an 80-bit (10 byte) extended precision floating point value. Both of these types are 16 bytes long, but they are not interoperable. Thus, these types are defined by Fortran, even though C may define types of the same length. ( End of rationale.)
To be backward compatible with the interpretation of these types in MPI-1, we assume that the nonstandard declarations REAL*n, INTEGER*n, always create a variable whose representation is of size n. These datatypes may also be used for variables declared with KIND=INT8/16/32/64 or KIND=REAL32/64/128, which are defined in the ISO_FORTRAN_ENV intrinsic module. Note that the MPI datatypes and the REAL*n, INTEGER*n declarations count bytes whereas the Fortran KIND values count bits. All these datatypes are predefined.

The following function allows a user to obtain a size-specific MPI datatype for any intrinsic Fortran type.

MPI_TYPE_MATCH_SIZE(typeclass, size, datatype)
IN typeclassgeneric type specifier (integer)
IN sizesize, in bytes, of representation (integer)
OUT datatypedatatype with correct type, size (handle)
C binding
int MPI_Type_match_size(int typeclass, int size, MPI_Datatype *datatype)
Fortran 2008 binding
MPI_Type_match_size(typeclass, size, datatype, ierror)

INTEGER, INTENT(IN) :: typeclass, size
TYPE(MPI_Datatype), INTENT(OUT) :: datatype
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_TYPE_MATCH_SIZE(TYPECLASS, SIZE, DATATYPE, IERROR)

INTEGER TYPECLASS, SIZE, DATATYPE, IERROR

typeclass is one of MPI_TYPECLASS_REAL, MPI_TYPECLASS_INTEGER and MPI_TYPECLASS_COMPLEX, corresponding to the desired typeclass. The function returns an MPI datatype matching a local variable of type ( typeclass, size).

This function returns a reference (handle) to one of the predefined named datatypes, not a duplicate. This type cannot be freed. MPI_TYPE_MATCH_SIZE can be used to obtain a size-specific type that matches a Fortran numeric intrinsic type by first calling storage_size() in order to compute the variable size in bits, dividing it by eight, and then calling MPI_TYPE_MATCH_SIZE to find a suitable datatype. In C, one can use the C operator sizeof() (which returns the size in bytes) instead of storage_size() (which returns the size in bits). In addition, for variables of default kind the variable's size can be computed by a call to MPI_TYPE_GET_EXTENT, if the typeclass is known. It is erroneous to specify a size not supported by the compiler.


Rationale.

This is a convenience function. Without it, it can be tedious to find the correct named type. See note to implementors below. ( End of rationale.)

Advice to implementors.

This function could be implemented as a series of tests.
Example Example of an implementation of MPI_TYPE_MATCH_SIZE.

Image file

( End of advice to implementors.)


PreviousUpNext
Up: Additional Support for Fortran Numeric Intrinsic Types Next: Communication With Size-specific Types Previous: Parameterized Datatypes with Specified Precision and Exponent Range


20.1.9.3. Communication With Size-specific Types

PreviousUpNext
Up: Additional Support for Fortran Numeric Intrinsic Types Next: Problems With Fortran Bindings for MPI Previous: Support for Size-specific MPI Datatypes

The usual type matching rules apply to size-specific datatypes: a value sent with datatype MPI_<TYPECLASS>< n> can be received with this same datatype on another MPI process. Most modern computers use two's complement for integers and IEEE format for floating point. Thus, communication using these size-specific datatypes will not entail loss of precision or truncation errors.


Advice to users.

Care is required when communicating in a heterogeneous environment. Consider the following code:
Example Unsafe heterogeneous communication due to the use of MPI_TYPE_MATCH_SIZE.

Image file

This may not work in a heterogeneous environment if the value of size is not the same on the MPI processes with ranks 0 and 1. There should be no problem in a homogeneous environment. To communicate in a heterogeneous environment, there are at least four options. The first is to declare variables of default type and use the MPI datatypes for these types, e.g., declare a variable of type REAL and use MPI_REAL. The second is to use selected_real_kind or selected_int_kind and with the functions of the previous section. The third is to declare a variable that is known to be the same size on all architectures (e.g., selected_real_kind(12) on almost all compilers will result in an 8-byte representation). The fourth is to carefully check representation size before communication. This may require explicit conversion to a variable of size that can be communicated and handshaking between sender and receiver to agree on a size.

Note finally that using the "external32" representation for I/O requires explicit attention to the representation sizes. Consider the following code:


Example Unsafe heterogeneous MPI file I/O due to the use of MPI_TYPE_MATCH_SIZE.

Image file

If the MPI processes with ranks 0 and 1 are on different machines, this code may not work as expected if the size is different on the two machines. ( End of advice to users.)


PreviousUpNext
Up: Additional Support for Fortran Numeric Intrinsic Types Next: Problems With Fortran Bindings for MPI Previous: Support for Size-specific MPI Datatypes


Return to MPI-4.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-4.1 of November 2, 2023
HTML Generated on November 19, 2023