8 - C H A P T E R -

C H A P T E R 8

Creating and Freeing Custom Process Grids

This chapter explains how to create and free a process grid with user-defined parameters. It contains the following sections:

Creating a Custom Process Grid

Deallocating a Process Grid

Creating a Custom Process Grid

S3L_set_process_grid enables you to define various aspects of the process grid and associate it with a Sun S3L array handle. It has the following argument syntax:

S3L_set_process_grid(pgrid, rank, majorness, grid_extents, plist_length, process_list, ier)

Upon exit, pgrid contains the handle for the process grid.

rank specifies the number of dimensions the process grid is to have. This must be the same as the rank of the Sun S3L array with which it will be associated.

majorness specifies the order in which execution will proceed within the process grid. Use one of the following predefined values for this argument:

`S3L_MAJOR_COLUMN`	Execution proceeds from leftmost axis to rightmost axis.
`S3L_MAJOR_ROW`	Execution proceeds from leftmost axis to rightmost axis.

For example, if (i,j) represents the indices for a process grid's first and second axes, specifying S3L_MAJOR_COLUMN will cause i to be the inner loop index and j to be the outer loop index. For S3L_MAJOR_ROW, the sequence would be the opposite.

grid_extents is an integer vector whose length equals the rank of the process grid. Each element in grid_extents specifies the extent of the corresponding axis of the process grid. Axis indexing is zero-based for the C interface and one-based for the Fortran interface.

plist_length specifies the length of the process_list argument, which is described below.

process_list is an integer array whose length is specified in plist_length. It contains a list of the processes that will be included in the process grid. For example, if your program is running on MPI processes 0 through 3, but you want to create a process grid for a particular Sun S3L array consisting only of processes 1 and 3, set plist_length to 2 and have:

process_list[0] = 1

process_list[1] = 3

If plist_length is 0, process_list will be ignored. The process grid is then created using all available processes in MPI_COMM_WORLD.

Note - If the product of all grid extents is N and if a value greater than N is specified for plist_length, only the first N elements of process_list will be used.

If the call is made from a Fortran program, error status will be in ier.

For detailed descriptions of the Fortran and C bindings for this routine, see the S3L_set_process_grid(3) man page or the corresponding description in the Sun S3L Software Reference Manual.

Set Process Grid Example

The following F77 example shows how to specify a two-dimensional process grid that is defined over a set of eight processes having MPI ranks 0 through 7. The process grid has extents of 2x4 and is assigned column-major ordering.

include `s3l/s3l-f.h'

integer*8 pg

integer*4 rank

integer*4 pext(2),process_list(8)

integer*4 i,ier

rank = 2

pext(1) = 2

pext(2) = 4

do i=1,8

    process_list(i)=i-1

end do

call s3l_set_process_grid(pg,rank,S3L_MAJOR_COLUMN,

    pext,8,process_list,ier)

Further examples showing S3L_set_process_grid in use can be found in:

/opt/SUNWhpc/examples/s3l/utils/scalapack_conv.c

/opt/SUNWhpc/examples/s3l/utils-f/scalapack_conv.f

Deallocating a Process Grid

S3L_free_process_grid frees the process grid handle returned by a previous call to S3L_set_process_grid. It has the following argument syntax:

S3L_set_process_grid(pgrid, ier)

pgrid is the process grid handle to be deallocated.

If the call is made from a Fortran program, error status will be in ier.

For detailed descriptions of the Fortran and C bindings for this routine, see the S3L_free_process_grid(3) man page or the corresponding description in the Sun S3L Software Reference Manual.

Examples showing S3L_free_process_grid in use can be found in:

/opt/SUNWhpc/examples/s3l/utils/scalapack_conv.c

/opt/SUNWhpc/examples/s3l/utils-f/scalapack_conv.f