Sun S3L 3.0 Programming and Reference Guide

Extracting Information About S3L Parallel Arrays

The functions described in this section allow users to retrieve information about parallel arrays for which an array handle exists.

`S3L_describe`

Description

S3L_describe prints information about a parallel array or a process grid to standard output. If an array handle is supplied in argument A, the parallel array is described. If a process grid is supplied in A, the associated process grid is described. The info_node argument specifies the MPI rank of the process on which the subgrid of interest is located.

If A is an S3L array handle, the following is provided:

Information on the rank extents and the data type of the array, as well as the starting address in memory of its subgrid.

Note: If the entire array fits on the process specified by info_node, all parts of the S3L_describe output apply to the full array. Otherwise, some parts of the output, such as subgrid size, will apply only to the portion of the array that is on process info_node.

A description of the underlying grid of processes to which data is mapped.

If A is a process grid handle, S3L_describe provides only a description of the underlying grid of processes to which data is mapped.

To determine what value to enter for info_node, run MPI_Comm_rank on the process of interest.

Syntax

The C and Fortran syntax for S3L_describe are shown below.

C/C++ Syntax

Example 7-37

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_describe(A, info_node)
    S3L_array_t        A
    int                info_node

F77/F90 Syntax

Example 7-38

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_zero_elements(A, ier)
    integer*8          A
    integer*4          info_node
    integer*4          ier

Input

S3L_describe accepts the following arguments as input:

A - May be a parallel array handle or a process grid handle.

info_node - Scalar integer variable that specifies the index or rank of the process from which the information will be gathered. Note that certain array parameters, such as the subgrid size and addresses, will vary from process to process.

Output

S3L_describe uses the following argument for output:

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

Error Handling

On success, S3L_describe returns S3L_SUCCESS.

S3L_describe performs generic checking of the validity of 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 error code.

S3L_ERR_ARG_ARRAY - A is not a valid parallel array or process grid handle.

Examples

../examples/s3l/utils/scalapack_conv.c
../examples/s3l/utils-f/scalapack_conv.f

Related Functions

MPI_Comm_rank(3)
S3L_declare(3)
S3L_declare_detailed(3)
S3L_set_process_grid(3)

`S3L_get_attribute`

Description

S3L_get_attribute returns a requested attribute of an S3L dense array or sparse matrix. The user specifies one of a set of predefined req_attr values and, on return, the integer value of the requested attribute is stored in attr. For attributes associated with array axes--such as the extents or blocksizes of an array--the user specifies the axis as well.

The req_attr entry must be one of the following:

S3L_ELEM_TYPE - Retrieves in attr the S3L type of the elements of an S3L dense array or sparse matrix as they are defined in s3l-c.h or s3l-f.h.

S3L_ELEM_SIZE - Retrieves in attr the size (in bytes) of the elements of an S3L dense array or sparse matrix.

S3L_RANK - Retrieves in attr the rank (number of dimensions) of an S3L dense array or sparse matrix.

S3L_EXTENT - If a is an S3L array handle, S3L_EXTENT retrieves in attr the extent of an S3L dense array or sparse matrix along the dimension given in axis. If a is an S3L process grid handle, it returns in attr the number of processes over which a given axis of an array is distributed.

S3L_BLOCK_SIZE - Retrieves in attr the block size of the block-cyclic distribution of an S3L dense array along the dimension given in axis.

S3L_BLOCK_START - Retrieves in attr the index of the starting process of the block-cyclic distribution of an S3L dense array along the dimension given in axis.

S3L_SGRID_SIZE - Retrieves in attr the subgrid size of the block-cyclic distribution of an S3L dense array along the dimension given in axis.

S3L_AXIS_LOCAL - Assigns 0 to attr if the axis is not distributed and 1 if it is.

S3L_SGRID_ADDRESS - Returns in attr the starting address of the local subgrid (local per-process part) of an S3L dense array.

S3L_MAJOR - If a is an S3L dense array, S3L_MAJOR returns in attr the majorness of the elements in the local part of the array. It can be either S3L_MAJOR_COLUMN (F77 major) or S3L_MAJOR_ROW (C major). If a is an S3L process grid descriptor, it returns in attr the majorness (F77 or C) of the internal process grid associated with an S3L process grid.

S3L_ALLOC_TYPE - Returns in attr one of the predefined allocation types for dense S3L arrays. The user can use this option to determine, for example, whether the array has been allocated in shared memory, whether the local (per-process) parts of the array are 64-bit aligned, and so forth.

S3L_SHARED_ADDR - For dense S3L arrays that have been allocated in shared memory (single SMP case), S3L_SHARED_ADDR returns in attr the global starting address of the array. All processes can directly access all elements of such arrays without the need for explicit intperprocess communication.

S3L_PGRID_DESC - Returns in attr the process grid descriptor associated with an S3L dense array or sparse matrix.

S3L_SCALAPACK_DESC - For 1D and 2D S3L dense arrays, S3L_SCALAPACK_DESC returns in attr the ScaLAPACK array descriptor associated with the distribution of that array.

S3L_NONZEROS - For an S3L sparse matrix, S3L_NONZEROS returns in attr the number of nonzero elements of that matrix.

S3L_RIDX_SGRID_ADDR - For an S3L sparse matrix stored in the S3L_SPARSE_COO format, S3L_RIDX_SGRID_ADDR returns in attr the starting address of an array of index sets containing the local row numbers that comprise each local submatrix (per-process).

For an S3L sparse matrix stored in the S3L_SPARSE_CSR format, S3L_RIDX_SGRID_ADDR returns in attr the starting address of an array containing the pointers to the beginning of each row of the local submatrix (per-process).

Note: Users must not change the data returned in attr. It is created for internal use only.

S3L_CIDX_SGRID_ADDR - For an S3L sparse matrix, S3L_CIDX_SGRID_ADDR returns in attr the starting address of an array of index sets containing the global column numbers that comprise each local submatrix (per-process).

Note: User must not change the data returned in attr. It is created for internal use only.

S3L_NRZS_SGRID_ADDR - For an S3L sparse matrix, S3L_NZRS_SGRID_ADDR returns in attr the starting address of an array containing nonzero elements of the local submatrix (per-process).

S3L_RIDX_SGRID_SIZE - For an S3L sparse matrix stored in the S3L_SPARSE_COO format, S3L_RIDX_SGRID_SIZE returns in attr the size of an array of index sets containing the local row numbers that comprise each local submatrix (per-process).

For an S3L sparse matrix stored in the S3L_SPARSE_CSR format, S3L_RIDX_SGRID_SIZE returns in attr the size of an array containing the pointers to the beginning of each row of the local submatrix (per-process).

S3L_CIDX_SGRID_SIZE - For an S3L sparse matrix, S3L_CIDX_SGRID_SIZE returns in attr the size of an array of index sets containing the global column numbers that comprise each local submatrix (per-process).

S3L_NRZS_SGRID_SIZE - For an S3L sparse matrix, S3L_NZRS_SGRID_SIZE returns in attr the size of an array containing nonzero elements of the local submatrix (per-process).

S3L_COORD - It returns in attr the coordinate of the calling process in an S3L process grid, along the dimension given in axis.

S3L_ON_SINGLE_SMP - It returns 1 in attr if an S3L process grid is defined on a single SMP and 0 if not.

Syntax

The C and Fortran syntax for S3L_get_attribute are shown below.

C/C++ Syntax

Example 7-39

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_S3L_get_attribute(a, req_attr, axis, attr)
    S3L_array_t           a
    int                   req_attr
    int                   axis
    void                  *attr

F77/F90 Syntax

Example 7-40

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_get_attribute(a, req_attr, axis, attr, ier)
    integer*8          a
    integer*4          req_attr
    integer*4          axis
    <type>             attr
    integer*4          ier

where <type> is either of integer*4 type or of pointer type. When attr is an address, it should be of type pointer. In all other cases, it should be of type integer*4.

Input

S3L_get_attribute accepts the following arguments as input:

a - Pointer to a descriptor of an unknown type.

req_attr - A predefined value that specifies the attribute to be retrieved. See the Description section for a list of valid req_attr entries.

axis - Scalar integer variable. To retrieve axis-specific attributes, such as, extents or blocksizes, use this parameter to specify the axis of interest.

attr - Pointer to a variable of the appropriate type that will hold the retrieved attribute value.

Output

S3L_get_attribute uses the following argument for output:

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

Error Handling

On success, S3L_get_attribute returns S3L_SUCCESS.

S3L_get_attribute performs generic checking of the validity of 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 error code:

S3L_ERR_ATTR_INVALID - Invalid attribute; the supplied descriptor does not have the requested attribute type.

Examples

../examples/s3l/utils/get_attribute.c
../examples/s3l/utils-f/get_attribute.f

Related Functions

S3L_set_array_element(3)
S3L_set_array_element_on_proc(3)