10.2.5.1 Parameterized Datatypes with Specified Precision and Exponent Range

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 MPI-/ 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
p precision, in decimal digits (integer)
IN
r decimal exponent range (integer)
OUT
newtype the requested MPI-/ datatype (handle)

int MPI_Type_create_f90_real(int p, int r, MPI_Datatype *newtype)



MPI_TYPE_CREATE_F90_REAL(P, R, NEWTYPE, IERROR)INTEGER P, R, NEWTYPE, IERROR



int MPI::Datatype::Create_f90_real(int p, int r)



static MPI::Datatype

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 [*].

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



MPI_TYPE_CREATE_F90_COMPLEX(p, r, newtype)

IN
p precision, in decimal digits (integer)
IN
r decimal exponent range (integer)
OUT
newtype the requested MPI-/ datatype (handle)

int MPI_Type_create_f90_complex(int p, int r, MPI_Datatype *newtype)



MPI_TYPE_CREATE_F90_COMPLEX(P, R, NEWTYPE, IERROR)INTEGER P, R, NEWTYPE, IERROR



int MPI::Datatype::Create_f90_complex(int p, int r)



static MPI::Datatype

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 [*].

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



MPI_TYPE_CREATE_F90_INTEGER(r, newtype)

IN
r decimal exponent range, i.e., number of decimal digits (integer)
OUT
newtype the requested MPI-/ datatype (handle)

int MPI_Type_create_f90_integer(int r, MPI_Datatype *newtype)



MPI_TYPE_CREATE_F90_INTEGER(R, NEWTYPE, IERROR)INTEGER R, NEWTYPE, IERROR



int MPI::Datatype::Create_f90_integer(int r)



static MPI::Datatype

This function returns a predefined MPI-/ datatype that matches a 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 [*].

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

Example:

   integer       longtype, quadtype
   integer, parameter :: long = selected_int_kind(15)
   integer(long) ii(10)
   real(selected_real_kind(30)) x(10)
   call MPI_TYPE_CREATE_F90_INTEGER(15, longtype, ierror)
   call MPI_TYPE_CREATE_F90_REAL(30, MPI_UNDEFINED, quadtype, ierror)
   ...

   call MPI_SEND(ii, 10, longtype, ...)
   call MPI_SEND(x,  10, quadtype, ...)

Advice to users. The datatypes returned by the above functions 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_ routines.
If a variable was declared specifying a non-default 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.)

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 9.5.2 on page [*]) or user-defined (Section 9.5.3 on page [*]) 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 9.5.2 on page [*].

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.

MPI-Standard for MARMOT