Parallel Transpose

S3L_trans

Description

S3L_trans performs a generalized transposition of a parallel array. A generalized transposition is defined as a general permutation of the axes. The array axis_perm contains a description of the permutation to be performed.

The distribution characteristics of a and b must be compatible--that is, they must have the same rank and type and corresponding axes must be of the same length.

A faster algorithm is used in the 2D case when the array meets the following conditions:

• The first axis of the array is local.

• The second axis of the array is global.

• The size of each dimension is divisible by the number of processes.

• The blocksizes are equal to the result of the division.

Syntax

The C and Fortran syntax for S3L_trans are shown below.

C/C++ Syntax

Example 8-122

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_trans(a, b, axis_perm)
    S3L_array_t       a
    S3L_array_t       b
    int               *axis_perm

F77/F90 Syntax

Example 8-123

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_trans(a, b, axis_perm, ier)
    integer*8         a
    integer*8         b
    integer*4         axis_perm
    integer*4         ier

where <type> is real*4 or real*8 for both C/C++ and F77/F90.

Input

• a - S3L_array handle for the parallel array to be transposed.

• axis_perm - A vector of integers that specifies the axis permutation to be performed.

Output

These functions use the following arguments for output:

• b - S3L_array handle for a parallel array. Upon successful completion, S3L_trans stores the transposed array in b.

• ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.

Error Handling

On success, S3L_trans returns S3L_SUCCESS.

S3L_trans checks the arrays it accepts as arguments. If an array argument contains an invalid or corrupted value, the function terminates and an error code indicating which value of the array handle was invalid is returned. See Appendix A of this manual for a detailed list of these error codes.

In addition, the following condition will cause the function to terminate and return the associated code:

• S3L_ERR_MATCH_RANK - The ranks of a and b do not match.

• S3L_ERR_MATCH_EXTENTS - The extents of a and b are not compatible with the transpose operation requested. That is, the following relationship is not satisfied for all array axes i.

ext(a,axis_perm[i])=ext(b,i)

• S3L_ERR_TRANS_PERMAX - The supplied permutation is not valid (every axis must appear exactly once).

• S3L_ERR_ARG_AXISNUM - The axis argument has an invalid value. The correct values for axis are

  • 0 <= axis < rank of the array (C/C++)

  • 0 < axis <= rank of the array (F77/F90)

Examples

../examples/s3l/transpose/transp.c
../examples/s3l/transpose/ex_trans1.c
../examples/s3l/transpose-f/transp.f