Sun S3L 4.0 Software Programming Guide
|    
|
| Sun S3L 4.0 Software Programming Guide
|
|
| C H A P T E R 9 |
|
Extracting Information From Sun S3L Arrays and Process Grids |
Sun S3L provides several functions for extracting information about Sun S3L arrays and process grids, as well as accessing the contents of the arrays. These functions are discussed in the following sections:
S3L_describe prints information about a Sun S3L array or process grid to standard output. It has the following argument syntax:
S3L_describe(A, info_node, ier) |
A is a Sun S3L handle for either a Sun S3L array or a process grid, whichever object is to be described.
info_node is a scalar integer variable that specifies the rank of the process from which the information is to be taken.
|
Note - Some array parameters, such as subgrid size and address values, will vary from process to process. |
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_describe(3) man page or the corresponding description in the Sun S3L Software Reference Manual.
Examples showing S3L_describe in use can be found in:
/opt/SUNWhpc/examples/s3l/utils/scalapack_conv.c /opt/SUNWhpc/examples/s3l/utils-f/scalapack_conv.f |
Sun S3L provides a function, S3L_get_attribute, for extracting specific details about a Sun S3L array's attributes. TABLE 9-1 lists the attributes that can be acquired with S3L_get_attribute.
S3L_ELEM_TYPE |
Returns the Sun S3L data type of the elements of a Sun S3L array or sparse matrix. |
S3L_ELEM_SIZE |
Returns the size (in bytes) of the elements of a Sun S3L dense array or sparse matrix. |
S3L_RANK |
Returns the rank (number of dimensions) of a Sun S3L dense array or sparse matrix. |
S3L_EXTENT |
If requesting a Sun S3L array extent attribute, returns the extent of a Sun S3L dense array or sparse matrix along the specified axis.
|
S3L_BLOCK_SIZE |
Returns the block size of the block-cyclic distribution of a Sun S3L dense array along the specified dimension. |
S3L_BLOCK_START |
Returns the index of the starting process of the block-cyclic distribution of a Sun S3L dense array along the specified dimension. |
S3L_SGRID_SIZE |
Returns the subgrid size of the block-cyclic distribution of a Sun S3L dense array along the specified dimension. |
S3L_AXIS_LOCAL |
Returns 0 if the axis is local (not distributed) and 1 if it is distributed. |
S3L_SGRID_ADDRESS |
Returns the starting address of the local subgrid (local per-process part) of a Sun S3L dense array. |
S3L_MAJOR |
If requesting a Sun S3L array attribute, returns the majorness of the elements in the local part of the array. If requesting a process grid attribute, returns the majorness (F77 or C) of the process grid. In either case, the majorness value may be either S3L_MAJOR_COLUMN (F77 major) or S3L_MAJOR_ROW (C major). |
S3L_ALLOC_TYPE |
Returns one of the predefined memory allocation types for dense Sun S3L arrays. See the description of the atype argument in Creating and Destroying Array Handles for Dense Sun S3L Arrays for descriptions of the supported allocation types. |
S3L_SHARED_ADDR |
For dense Sun S3L arrays that have been allocated in shared memory (single SMP case), returns the global starting address of the array. All processes can directly access all elements of such arrays without the need for explicit interprocess communication. |
S3L_PGRID_DESC |
Returns the process grid descriptor associated with a Sun S3L dense array or sparse matrix. |
S3L_SCALAPACK_DESC |
For 1D and 2D Sun S3L dense arrays, returns the ScaLAPACK array descriptor associated with the array. |
S3L_SPARSE_FORMAT |
For a Sun S3L sparse matrix, returns the sparse format in which the matrix is stored. |
S3L_NONZEROS |
For a Sun S3L sparse matrix, returns the number of nonzero elements of the matrix. |
S3L_RIDX_SGRID_ADDR |
For a Sun S3L sparse matrix stored in the S3L_SPARSE_COO format, returns the starting address of an array of index sets containing the local row numbers that comprise each local submatrix. For a Sun S3L sparse matrix stored in the S3L_SPARSE_CSR format, it returns the starting address of an array containing pointers to the beginning of each row of the local submatrix. |
S3L_CIDX_SGRID_ADDR |
For a Sun S3L sparse matrix stored in either the S3L_SPARSE_COO or S3L_SPARSE_CSR format, returns the starting address of an array of index sets containing the global column numbers that comprise each local submatrix. |
S3L_NRZS_SGRID_ADDR |
For a Sun S3L sparse matrix stored in either the S3L_SPARSE_COO or S3L_SPARSE_CSR format, S3L_NZRS_SGRID_ADDR returns the starting address of an array containing nonzero elements of the local submatrix. |
S3L_RIDX_SGRID_SIZE |
For a Sun S3L sparse matrix stored in the S3L_SPARSE_COO format, returns the size of an array of index sets containing the local row numbers that comprise each local submatrix. For a Sun S3L sparse matrix stored in the S3L_SPARSE_CSR format, returns the size of an array containing the pointers to the beginning of each row of the local submatrix. |
S3L_CIDX_SGRID_SIZE |
For a Sun S3L sparse matrix stored in either the S3L_SPARSE_COO or S3L_SPARSE_CSR format, returns the size of an array of index sets containing the global column numbers that comprise each local submatrix. |
S3L_NRZS_SGRID_SIZE |
For a Sun S3L sparse matrix stored in either the S3L_SPARSE_COO or S3L_SPARSE_CSR format, returns the size of an array containing nonzero elements of the local submatrix. |
S3L_COORD |
Returns the coordinate of the calling process in a Sun S3L process grid, along the dimension given in axis. |
S3L_ON_SINGLE_SMP |
Returns 1 if a Sun S3L process grid is defined on a single SMP and 0 if not. |
S3L_get_attribute has the following argument syntax:
S3L_get_attribute(a, req_attr, axis, attr, ier) |
a is a pointer to a descriptor of an unknown type.
req_attr is the predefined value that specifies the attribute to be accessed. See TABLE 9-1 for the list of values that this argument can have.
axis is a scalar integer variable that is used to access attributes that are axis-specific, such as extents or block sizes.
On exit, attr contains the attribute value.
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_get_attribute(3) man page or the corresponding descriptions in the Sun S3L Software Reference Manual.
Examples showing S3L_get_attribute in use can be found in:
/opt/SUNWhpc/examples/s3l/utils/get_attribute.c /opt/SUNWhpc/examples/s3l/utils-f/get_attribute.f |
Sun S3L provides the following routines for accessing specific array elements in a distributed array:
These functions locate the target elements by means of their global coordinates, which the programmer supplies.
Use S3L_get_array_element to obtain the value of a specific element from a distributed array. The argument coor specifies the global coordinates of the target element. The process that contains the array element specified in coor will return the value of that element in val.
Each process that contains a subgrid of the Sun S3L array checks to see if the global coordinates in coor map to their local subgrid. The process that has the target element in its local subgrid stores the value of the element in the local variable, val. All other processes exit from S3L_get_array_element without modifying their local val variables.
FIGURE 9-1 illustrates this with a diagram of a 1 x 16 array that is distributed over a
1 x 4 process grid. S3L_get_array_element is used to obtain the value of the array element at global coordinate 6.
|
Note - For clarity, symbols such as `!' and `@' are used to represent the values stored in the various array elements. |
S3L_get_array_element has the following argument syntax:
S3L_get_array_element(a, coor, val, ier) |
a is a Sun S3L array handle for the distributed array containing the element of interest.
coor is an integer vector that specifies the global coordinates of a particular element in the Sun S3L array described by a.
val is an array variable. On exit, the val that is local to the process containing the target element will contain the value of the target element.
S3L_set_array_element assigns the value stored in val to the array element whose global coordinates are in the argument coor.
Each process that contains a subgrid of the Sun S3L array will store the value to be assigned to the target element in a local copy of the val variable and will check to see if the global coordinates in coor map to the local subgrid. The process that has the target element in its local subgrid will assign the contents of val to the element. All other processes exit S3L_set_array_element without modifying any elements in their subgrids.
FIGURE 9-2 illustrates this with the same 1 x 16 Sun S3L array and 1 x 4 process grid. In this case, the S3L_set_array_element call will assign the value W to the array element at global coordinate 6. All processes in the process grid will call S3L_set_array_element, but only the process with MPI rank 1 will update a local array element--the element at local coordinate 2
S3L_set_array_element has the following argument syntax:
S3L_set_array_element(a, coor, val, ier) |
a is a Sun S3L array handle describing the distributed array that contains the element(s) of interest.
coor is an integer vector that specifies the global coordinates of one or more elements in the array described by a.
val is an array variable that contains the value(s) to be assigned to the element(s) specified in coor.
|
Note - If you know the MPI rank of the process that contains the array element to be set, you can limit execution of S3L_set_array_element to that process, avoiding the need for communication operations by the other processes. This is illustrated in FIGURE 9-3. |
S3L_get_array_element_on_proc is similar to S3L_get_array_element, except the target element(s) must be local to a specific MPI process. In other words, one or more target elements are specified by their global coordinates in coor and a particular process is specified in the argument pnum. The target process will assign the value(s) of any local array elements specified in coor to the local val variable. FIGURE 9-4 illustrates the use of S3L_get_array_element_on_proc.
The value in pnum is the MPI rank of the process, which is defined in the global communicator, MPI_COMM_WORLD.
S3L_get_array_element_on_proc has the following argument syntax:
S3L_get_array_element_on_proc(a, coor, val, pnum, ier) |
a is a Sun S3L array handle describing the distributed array that contains the element(s) of interest.
coor is an integer vector that specifies the global coordinates of one or more elements in the array described by a.
val is an array variable that contains value(s) obtained from the element(s) that are specified in coor and are local to the process whose rank is specified in pnum.
pnum is an integer variable that specifies the MPI rank of the target process.
Use S3L_set_array_element_on_proc to set the value of one or more array elements that are local to a specific process. Pass the global coordinates of the target elements in coor, the value(s) to be assigned in val, and the MPI rank of the target process in pnum. FIGURE 9-5 shows S3L_set_array_element_on_proc in use.
S3L_set_array_element_on_proc has the following argument syntax:
S3L_set_array_element_on_proc(a, coor, val, pnum, ier) |
a is a Sun S3L array handle describing the distributed array that contains the element(s) of interest.
coor is an integer vector that specifies the global coordinates of one or more elements in the array described by a.
val is an array variable that contains the value(s) to be assigned to the element(s) specified in coor that are local to the process whose MPI rank is in pnum.
pnum is an integer variable that specifies the MPI rank of the target process.
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 these routines, see the S3L_get_array_element(3), S3L_set_array_element(3), S3L_get_array_element_on_proc(3), and S3L_set_array_element_on_proc(3) man pages or the corresponding descriptions in the Sun S3L Software Reference Manual.
Examples showing the S3L_get_array_element and S3L_set_array_element functions in use can be found in:
/opt/SUNWhpc/examples/s3l/utils/cshift_reduce.c /opt/SUNWhpc/examples/s3l/utils-f/cshift_reduce.f /opt/SUNWhpc/examples/s3l/utils/copy_array.c /opt/SUNWhpc/examples/s3l/utils-f/copy_array.f |
Examples showing the S3L_get_array_element_on_proc and S3L_set_array_element_on_proc functions in use can be found in:
| Sun S3L 4.0 Software Programming Guide
| 817-0086-10 |
|
Copyright © 2003, Sun Microsystems, Inc. All rights reserved.