S3L_declare_sparse

Description

S3L_declare_sparse creates an internal S3L array handle that describes a sparse matrix. The sparse matrix may be represented in either the Coordinate format or the Compressed Sparse Row (CSR) format. Upon successful completion, S3L_declare_sparse returns an S3L array handle in A that describes the distributed sparse matrix.

The Coordinate format consists of three arrays: a, r, and c. Array a stores the nonzero elements of the sparse matrix in any order. r and c are integer arrays that hold the corresponding row and column indices of the sparse matrix, respectively.

The contents of r, c, and a are supplied by the arguments row, col, and val, respectively. row, col, and val are all rank 1 parallel arrays.

The CSR format stores the sparse matrix in arrays ia, ja, and a. As with the Coordinate format, array a stores the nonzero elements of the matrix. ja, an integer array, contains the column indices of the nonzeros as stored in the array a. ia, also an integer array, contains pointers to the beginning of each row in arrays a and ja.

The ia, ja, and a arrays take their contents from the row, col, and val arguments, respectively. As with the Coordinate format, row, col, and val are all rank 1 parallel arrays.

Because row, col, and val are copied to working arrays, they can be deallocated immediately following the S3L_declare_sparse call.

S3L_declare_sparse assumes that the row and column indices of the sparse matrix are stored using zero-based indexing when called by C or C++ applications and one-based indexing when called by F77 or F90 applications. See "S3L_read_sparse " for a discussion of S3L_read_sparse.

Syntax

The C and Fortran syntax for S3L_declare_sparse are noted next.

C/C++ Syntax

Example 8-11

#include <s3l/s3l-c.h>
#include <s3l/s3l_errno-c.h>
int
S3L_declare_sparse(A, spfmt, m, n, row, col, val)
    S3L_array_t             *A
    S3L_sparse_storage_t    spfmt
    int                     m
    int                     n
    int                     row
    int                     col
    int                     val 

F77/F90 Syntax

Example 8-12

include `s3l/s3l-f.h'
include `s3l/s3l_errno-f.h'
subroutine
S3L_declare_sparse(A, spfmt, m, n, row, col, val, ier)
    integer*8               *A
    integer*8               spfmt
    integer*4               m
    integer*4               n
    integer*4               row
    integer*4               col
    integer*4               val 
    integer*4               ier 

Input

• spfmt - Indicates the sparse storage format used for representing the sparse matrix. Use S3L_SPARSE_COO to specify the Coordinate format and S3L_SPARSE_CSR for the Compressed Sparse Row format.

• m - Indicates the total number of rows in the sparse matrix.

• n - Indicates the total number of columns in the sparse matrix.

• row - Integer parallel array of rank 1. Its length and content can vary, depending on the sparse storage format used.

  • S3L_SPARSE_COO - row is of the same size as arrays col and val. and contains row indices of the nonzero elements in array val.

  • S3L_SPARSE_CSR- row is of size m+1 and contains pointers to the beginning of each row in arrays col and val.

• col - Integer global array of rank 1 with the same length as array val. It contains column indices of the corresponding elements stored in array val.

• val - Parallel array of rank 1, containing the nonzero elements of the sparse matrix. For S3L_SPARSE_COO, nonzero elements can be stored in any order. For S3L_SPARSE_CSR, they should be stored row by row, from the first row to the last. The length of val for both S3L_SPARSE_COO and S3L_SPARSE_CSR is, nnz, the total number of nonzero elements in the sparse matrix. The data type of array elements can be real or complex (single- or double-precision).

Output

This function uses the following arguments for output:

• A - Upon return, A contains an S3L internal array handle for the global general sparse matrix. This handle can be used in subsequent calls to other S3L sparse array functions.

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

Error Handling

On success, S3L_declare_sparse returns S3L_SUCCESS.

The S3L_declare_sparse routine 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 conditions will cause these functions to terminate and return the associated error code:

• S3L_ERR_SPARSE_FORMAT - Invalid storage format. It must be either S3L_SPARSE_COO or S3L_SPARSE_CSR.

• S3L_ERR_ARG_EXTENTS - Invalid m or n. Each must be > 0.

• S3L_ERR_ARG_NULL - Invalid arrays row, col, or val. They must all be preallocated S3L arrays.

• S3L_ERR_MATCH_RANK - Ranks of arrays row, col, and val are mismatched. They all must be rank 1 arrays.

• S3L_ERR_MATCH_DTYPE - Arrays row and col data types do not match. They must be of type S3L_integer.

• S3L_ERR_MATCH_EXTENTS - The lengths of arrays row, col, and val are mismatched. For S3L_SPARSE_COO, they all must be of the same size. For S3L_SPARSE_CSR, the length of array col must be equal to that of array val and array row must be of size m+1.

Examples

../examples/s3l/sparse/ex_sparse2.c
../examples/s3l/dense_matrix_ops-f/outer_prod.f

Related Functions

S3L_matvec_sparse(3)
S3L_rand_sparse(3)
S3L_read_sparse(3)