MPI Subroutine Reference

MPI_TYPE_CREATE_SUBARRAY, MPI_Type_create_subarray

Purpose

Returns a new datatype that represents an ndims-dimensional subarray of an ndims-dimensional array.

C synopsis

#include <mpi.h>
int MPI_Type_create_subarray (int ndims,int array_of_sizes[],
			      int array_of_subsizes[],int array_of_starts[],
			      int order,MPI_Datatype oldtype,MPI_Datatype *newtype);
    

C++ synopsis

#include mpi.h
MPI::Datatype MPI::Datatype::Create_subarray(int ndims, const int array_of_sizes[],
					     const int array_of_subsizes[],
					     const int array_of_starts[],
					     int order) const;

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_TYPE_CREATE_SUBARRAY (INTEGER NDIMS,INTEGER ARRAY_OF_SUBSIZES(*),
			  INTEGER ARRAY_OF_SIZES(*),INTEGER ARRAY_OF_STARTS(*),
			  INTEGER ORDER,INTEGER OLDTYPE,INTEGER NEWTYPE,INTEGER IERROR)
    

Parameters

ndims

is the number of array dimensions(positive integer)(IN)

array_of_sizes

is the number of elements of type oldtype in each dimension of the full array (array of positive integers) (IN)

array_of_subsizes

is the number of type oldtype in each dimension of the subarray (array of positive integers) (IN)

array_of_starts

is the starting coordinates of the subarray in each dimension (array of nonnegative integers) (IN)

order

is the array storage order flag (state) (IN)

oldtype

is the array element datatype (handle)(IN)

newtype

is the new datatype (handle)(OUT)

IERROR

is the FORTRAN return code. It is always the last argument.

Description

MPI_TYPE_CREATE_SUBARRAY creates an MPI datatype describing an ndims-dimensional subarray of an ndims-dimensional array. The subarray may be situated anywhere within the full array and may be of any nonzero size up to the size of the larger array as long as it is confined within this array.

This function facilitates creating filetypes to access arrays distributed in blocks among tasks to a single file that contains the full array.

Errors

Fatal errors:

MPI not initialized

MPI already finalized

Invalid dimension count

ndims must be a positive integer

Invalid array element

Each element of array_of_sizes and array_of_subsizes must be a positive integer, and each element of array_of_starts must be a nonnegative integer

Invalid order

order must be either MPI_ORDER_C or MPI_ORDER_FORTRAN

MPI_DATATYPE_NULL not valid

oldtype cannot be equal to MPI_DATATYPE_NULL

Undefined datatype

oldtype is not a defined datatype

Invalid datatype

oldtype cannot be: MPI_LB, MPI_PACKED, or MPI_UB

Invalid subarray size

Each element of array_of_subsizes cannot be greater than the same element of array_of_sizes

Invalid start element

The subarray must be fully contained within the full array.

Stride overflow

Extent overflow

Size overflow

Upper or lower bound overflow

Related information

MPI_TYPE_COMMIT

MPI_TYPE_FREE

MPI_TYPE_GET_CONTENTS

MPI_TYPE_GET_ENVELOPE