5. DDT Library

DDT (Derived Data Types) provides a simple way to create user defined datatypes. With standard datatypes such as int, double, char one can use a contiguous memory space. Often it is desirable to use data that is not homogeneous such as structure or that is not contiguous in memory such as some selection in array. This library allows The user to define derived datatypes, that specify more general data layouts. These derived datatypes can then be used in a similar way as basic datatypes.

Some examples where user might want to use derived datatypes are: using only upper tringle of a matrix, using only elements in alternate rows and columns in a 2D array. It might be cumbersome to program it in user code every time it is needed. DDT library provides a simple and convinient way to create such datatypes, find out their lengths and extents.
Currently supported datatypes are

• Contiguous - Contiguous datatype constructs a typemap consisting of the replication of a datatype into contiguous locations.
• Vector - Vector datatype allows replication of a datatype into locations that consist of equally spaced blocks.
• HVector - Similar to Vector except that it allows a stride which consists of an arbitrary number of bytes as opposed to stride being multiple of block size in Vector.
• Indexed - The Indexed datatype allows one to specify a noncontiguous data layout where displacements between successive blocks need not be equal.
• HIndexed - Similar to Indexed except that displacement can be arbitrary number of bytes.
• Struct - This is the most general type constructor. It allows each block to consist of replications of different datatypes.

Derived datatypes can be constructed from basic datatypes as well as derived data types. For example, a Struct datatype can be made of contiguous, vector datatypes.


DDT library provides following functionality.
- First, a pool of datatypes should be created, by calling new DDT().
- new data types can be created by calling newContiguous(), newVector() etc functions of DDT which will give an integer index for a datatype. This index can be used later to refer to this derived datatype. Creating a datatype just initializes the type, extent, size of a datatype. It does not copy buffers.
- DDT_datatype can be retrieved using getType() function of DDT. Previously created index needs to be passed to this function.
- To copy non-contiguous bytes based on a data type, serialize funtion needs to be called on DDT_Datatype.
- Also, getSize(), getExtent() functions can be used to get size and extent of a datatype.

//file test.C

#include "ddt.h"

myDDT = new DDT((void*)0);

DDT_Type  newType1, newType2 ;

//Create a new contiguous datatype which will copy the given buffer (in this
// case, int) count times in a new buffer

myDDT->newContiguous(count, DDT_INT, &newType1) ;

//Create a new vector datatype which will copy count elements of type DDT_DOUBLE
// with length blocklength, spaced stride apart in the original buffer.
myDDT->newVector(count, blocklength, stride, DDT_DOUBLE, newtype);

//newType1 and newType2 can be used for further refering to contiguous and
//vector type of datatype.

// Create a new buffer with characteristics specified while creating
// the new datatype.

DDT_DataType *ddt = myDDT->getType(newType1);

ddt->serialize(buf1, buf2, size, dir);

// dir = 1, specifies that data is copied from buf1 to buf2, buf1 being old
// buffer and buf2 being the new buffer which should contains only the
// selected data.

//When needed to do the reverse, keep dir = -1

Following datatype constants are supported.
Primitive Datatypes:
DDT_DOUBLE, DDT_INT, DDT_FLOAT, DDT_COMPLEX, DDT_LOGICAL, DDT_CHAR, DDT_BYTE,DDT_PACKED, DDT_SHORT, DDT_LONG, DDT_UNSIGNED_CHAR, DDT_UNSIGNED_SHORT, DDT_UNSIGNED, DDT_UNSIGNED_LONG, DDT_LONG_DOUBLE Derived Datatypes:
DDT_CONTIGUOUS, DDT_VECTOR, DDT_HVECTOR, DDT_INDEXED, DDT_HINDEXED, DDT_STRUCT


DDT library provides following interface - To create new datatypes.

class DDT {
 public:
 void newContiguous(int count, DDT_Type  oldType, DDT_Type* newType);
 void newVector(int count, int blocklength, int stride, DDT_Type oldtype,
     DDT_Type* newtype) ;
 void newHVector(int count, int blocklength, int stride, DDT_Type oldtype,
      DDT_Type* newtype);
 void newIndexed(int count, int* arrbLength, int* arrDisp , DDT_Type oldtype, DDT_Type* newtype);
 void newHIndexed(int count, int* arrbLength, int* arrDisp , DDT_Type oldtype, DDT_Type* newtype);
 void newStruct(int count, int* arrbLength, int* arrDisp , DDT_Type *oldtype, DDT_Type* newtype);
}

- To Use the derived datatype.

class DDT_Datatype {
 public:
 virtual int getSize();
 virtual int getExtent();
 virtual int serialize(char* userdata, char* buffer, int num, int dir);
}

Examples of Derived Datatype

• Contiguous -

  If oldType is a derived datatype struct consisting a char and a double,

   ddt->newContiguous(5, oldType, &newType1) ;
  
  creates a contiguous datatype which has char, double, char, double, char, double, char double, char double

• Vector and HVector - To select alternate elements from each row and to select alternate rows in a 5 X 5 2-D array of doubles.
   ddt->newVector(3,1,2, DDT_DOUBLE, &oneSlice) ;
  
  This will give a row in which alternate elements are selected.
   ddt->newHVector(3, 1, 5*sizeof(double), oneSlice, &twoSlice) ;
  
  This will give three rows each of type oneSlice.

• Indexed -

  To select 2, 3, 4 blocks of Integer spaced 4,5,6 blocks in a given 1-D array of integers. blength[3] = 2, 3, 4 ; stride[3] = 4, 5, 6 ;

   ddt->Indexed(1, blength, stride, MPI_INT, &newArray);
  

• HIndexed -

  To select 2, 3, 4 blocks of Integer spaced 4,5,6 bytes in a given 1-D array of integers. blength[3] = 2, 3, 4 ; stride[3] = 4, 5, 6 ;

   ddt->HIndexed(1, blength, stride, MPI_INT, &newArray);
  

  In Indexed datatype, displacements will be 4, 5 and 6 multiples of int, while in HIndexed, displacements will be 4, 5 and 6 bytes.