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.
The C and Fortran syntax for S3L_declare_sparse are noted next.
#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 |
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 |
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).
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.
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/s3l/sparse/ex_sparse2.c ../examples/s3l/dense_matrix_ops-f/outer_prod.f
S3L_matvec_sparse(3) S3L_rand_sparse(3) S3L_read_sparse(3)
S3L_free_sparse deallocates the memory reserved for a sparse matrix and the associated array handle.
The C and Fortran syntax for S3L_free_sparse are shown below.
#include <s3l/s3l-c.h> #include <s3l/s3l_errno-c.h> int S3L_free_sparse(A) S3L_array_t *A |
include `s3l/s3l-f.h' include `s3l/s3l_errno-f.h' subroutine S3L_free_sparse(A ier) integer*8 *A integer*4 ier |
S3L_free_sparse accepts the following argument as input:
A - Handle for the parallel S3L array that was allocated via a previous call to S3L_declare_sparse, S3L_read_sparse, or S3L_rand_sparse.
S3L_free_sparse uses the following argument for output:
ier (Fortran only) - When called from a Fortran program, S3L_free_sparse returns error status in ier.
On success, S3L_free_sparse returns S3L_SUCCESS.
On error, the following error code may be returned:
S3L_ERR_ARG_ARRAY - A is a NULL pointer (C/C++) or 0 (F77/F90).
../examples/s3l/sparse/ex_sparse.c ../examples/s3l/sparse/ex_sparse2.c ../examples/s3l/iter/ex_iter.c ../examples/s3l/sparse-f/ex_sparse.f ../examples/s3l/iter-f/ex_iter.f
S3L_declare_sparse(3) S3L_read_sparse(3) S3L_rand_sparse(3)
S3L_rand_sparse creates a random sparse matrix with random sparsity pattern in either the Coordinate format or the Compressed Sparse Row format. Upon successful completion, it returns an S3L array handle in A representing this random sparse matrix.
The C and Fortran syntax for S3L_rand_sparse are shown below.
#include <s3l/s3l-c.h> #include <s3l/s3l_errno-c.h> int S3L_rand_sparse(A, spfmt, stype, m, n, density, type, seed) S3L_array_t *A S3L_sparse_storage_t spfmt sparse_rand_t stype int m int m real4 density S3L_data_type type int seed |
include `s3l/s3l-f.h' include `s3l/s3l_errno-f.h' subroutine S3L_rand_sparse(A, spfmt, stype, m, n, density, type, seed, ier) integer*8 A integer*4 spfmt integer*4 stype integer*4 m integer*4 n real*4 density integer*4 type integer*4 seed integer*4 ier |
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.
stype - A character string that specifies the type of random pattern to be used, as follows:
S3L_SPARSE_RAND - A random pattern.
S3L_SPARSE_DRND - A random pattern with guaranteed nonzero diagonal.
S3L_SPARSE_SRND - A random symmetric sparse array.
S3L_SPARSE_DSRN - A random symmetric sparse array with guaranteed nonzero diagonal.
m - Indicates the total number of rows in the sparse matrix.
n - Indicates the total number of columns in the sparse matrix.
density - Positive parameter less than or equal to 1.0, which suggests the approximate density of the array. For example, if density = 0.1, approximately 10% of the array elements will have nonzero values..
type - The type of the sparse array, which must be one of: S3L_integer, S3L_float, S3L_double, S3L_complex, or S3L_dcomplex.
seed - An integer that is used internally to initialize the random number generators. It affects both the pattern and the values of the array elements. The results are independent of the number of processes on which the function is invoked.
Note: The number of nonzero elements generated will depend primarily on the combination of the density argument value and the array extents given by m and n. The following guidelines provide additional detail:
Usually, the number of nonzero elements will approximately equal m*n*density.The behavior of the algorithm may cause the actual number of nonzero elements to be somewhat smaller than m*n*density.Regardless of the value supplied for the density argument, the number of nonzero elements will always be >= m.
This function uses the following arguments for output:
A - On return, contains an S3L internal array handle for the distributed random sparse matrix. The handle can be used in subsequent calls to some other S3L sparse array functions.
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.
On success, S3L_rand_sparse returns S3L_SUCCESS.
The S3L_rand_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 this function 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_DENSITY - Invalid density value. It must be 0.0 < density <= 1.0.
S3L_ERR_ARG_OP - Invalid random pattern. It must be one of: S3L_SPARSE_RAND, S3L_SPARSE_DRND, S3L_SPARSE_SRND, or S3L_SPARSE_DSRN.
S3L_ERR_ARRNOTSQ - Invalid matrix size. When stype does not equal S3L_SPARSE_RAND, m must equal n.
../examples/s3l/iter/ex_iter.c ../examples/s3l/iter-f/ex_iter.f
S3L_declare_sparse(3) S3L_matvec_sparse(3) S3L_read_sparse(3)
S3L_matvec_sparse computes the product of a global general sparse matrix with a global dense vector. The sparse matrix is described by the S3L array handle A. The global dense vector is described by the S3L array handle x. The result is stored in the global dense vector described by the S3L array handle y.
The array handle A is produced by a prior call to one of the following routines:
S3L_declare_sparse
S3L_read_sparse
S3L_rand_sparse
The C and Fortran syntax for S3L_matvec_sparse are shown below.
#include <s3l/s3l-c.h> #include <s3l/s3l_errno-c.h> int S3L_matvec_sparse(y, A, x) S3L_array_t y S3L_array_t A S3L_array_t x |
include `s3l/s3l-f.h' include `s3l/s3l_errno-f.h' subroutine S3L_matvec_sparse(y, A, x, ier) integer*8 y integer*8 A integer*4 x integer*4 ier |
A - S3L array handle for the global general sparse matrix
x - Global array of rank 1, with the same data type and precision as A and y and with a length equal to the number of columns in the sparse matrix.
These functions use the following arguments for output:
y - Global array of rank 1, with the same data type and precision as A and x and with a length equal to the number of rows in the sparse matrix. Upon completion, y contains the product of the sparse matrix A and x.
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.
On success, S3L_matvec_sparse returns S3L_SUCCESS.
The S3L_matvec_sparse routines perform generic checking of the validity of the arrays they accept 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 this function to terminate and return the associated error code:
S3L_ERR_ARG_NULL - Invalid array x or y or sparse matrix A. x and y must be preallocated S3L arrays and A must be a preallocated sparse matrix.
S3L_ERR_ARG_RANK - Invalid rank for arrays x and y. They must be rank 1 arrays.
S3L_ERR_MATCH_RANK - The ranks of x and y do not match.
S3L_ERR_MATCH_DTYPE - Arrays x, y, and A do not have the same data type.
S3L_ERR_MATCH_EXTENTS - The lengths of x and y are mismatched with the size of sparse matrix A. The length of x must be equal to the number of columns in A and the length of y must be equal to the number of rows in A.
../examples/s3l/sparse/ex_sparse.c ../examples/s3l/sparse-f/ex_sparse.f ../examples/s3l/iter/ex_iter.c ../examples/s3l/iter-f/ex_iter.f
S3L_declare_sparse(3) S3L_read_sparse(3) S3L_rand_sparse(3)
S3L_read_sparse reads sparse matrix data from an ASCII file and distributes the data to all participating processes. Upon successful completion, S3L_read_sparse returns an S3L array handle in A that represents the distributed sparse matrix.
S3L_read_sparse supports the following sparse matrix storage formats:
S3L_SPARSE_COO - Coordinate format.
S3L_SPARSE_CSR - Compressed Sparse Row format.
These two formats are described below.
S3L_SPARSE_COO files consist of three sections, which are illustrated below and described immediately after.
% <comments> % % m n nnz i1 j1 a(i1, j1) i1 j1 a(i1, j1) i1 j1 a(i1, j1) i1 j1 a(i1, j1) : : : innz jnnz a(innz, jnnz) |
The first section can be used for comments. It consists of one or more lines, each of which begins with the percent "%" character.
The second section consists of a single line containing three integers, shown above as m, n, and nnz. m and n indicate the number of rows and columns of the matrix, respectively, and nnz indicates the total number of nonzero values in the matrix.
The third section lists all nonzero values in the matrix, one value per line. The first two entries on a line are the row and column indices for that value and the third entry is the value itself.
S3L_read_sparse assumes that row and column indices are stored using zero-based indexing when called by C or C++ applications and one-based indexing when called by F77 or F90 applications.
This is illustrated by the following 4x6 sample matrix.
3.14 0 0 20.04 0 0 0 27 0 0 -0.6 0 0 0 -0.01 0 0 0 -0.031 0 0 0.08 0 314.0 |
This sample matrix could have the S3L_SPARSE_COO files consist of three sections, which are below and described immediately after.
% Example: 4x6 sparse matrix in an S3L_SPARSE_COO file, % row-major order, zero-based indexing: % % 4 6 8 0 0 3.140e+00 0 3 2.004e+01 1 1 2.700e+01 1 4 -6.000e-01 2 2 -1.000e-02 3 0 -3.100e-02 3 3 8.000e-02 3 5 3.140e+02 |
The layout used for this example is row-major, but any order is supported, including random. The next two examples show this same 4x6 matrix stored in two S3L_SPARSE_COO files, both in random order. The first example illustrates zero-based indexing and the second one-based indexing.
% Example: 4x6 sparse matrix in an S3L_SPARSE_COO file, % random-major order, zero-based indexing: % % 4 6 8 3 5 3.140e+02 1 1 2.700e+01 0 3 2.004e+01 3 3 8.000e-02 2 2 -1.000e-02 0 0 3.140e+00 1 4 -6.000e-01 3 0 -3.100e-02 |
% Example: 4x6 sparse matrix in an S3L_SPARSE_COO file, % random-major order, one-based indexing: % % 4 6 8 4 4 8.000e-02 2 2 2.700e+01 1 1 3.140e+00 4 1 -3.100e-02 3 3 -1.000e-02 4 6 3.140e+02 1 4 2.004e+01 2 5 -6.000e-01 |
Under S3L_SPARSE_COO format, S3L_read_sparse can also read data supplied in either of two Coordinate formats distributed by MatrixMarket (http://gams.nist.gov/MatrixMarket/). The two supported MatrixMarket formats are real general and complex general.
MatrixMarket files always use one-based indexing. Consequently, they can only be used directly by Fortran programs, which also implement one-based indexing. For a C or C++ program to use a MatrixMarket file, it must call the F77 application program interface. The program example ex_sparse.c illustrates an F77 call from a C program. See the Examples section for the path to this sample program.
The S3L_SPARSE_CSR files also consist of three sections. The first two sections are the same as in S3L_SPARSE_COO files. The third section stores the sparse matrix in the arrays a, ja, and ia. As with S3L_SPARSE_COO, array a stores the nnz elements of the matrix. ja, an integer array, contains the column indices of the nonzeros and ia, also an integer array, contains pointers to the beginning of each row in arrays a and ja.
For example, the same 4x6 sparse matrix used in previous examples could be stored under S3L_SPARSE_CSR in the manner shown in (using zero-based indexing).
% Example: 4x6 sparse matrix in an S3L_SPARSE_CSR file, % zero-based indexing: % % 4 6 8 0 2 4 5 8 0 3 4 1 2 0 5 3 3.140000 200.400000 -0.600000 27.000000 -0.010000 -0.031000 314.000000 0.080000 |
The C and Fortran syntax for S3L_read_sparse are shown below.
#include <s3l/s3l-c.h> #include <s3l/s3l_errno-c.h> int S3L_read_sparse(A, spfmt, m, n, nnz, type, fname, dfmt) S3L_array_t *A S3L_sparse_storage_t spfmt sparse_rand_t stype int m int m int nnz S3L_data_type type char *fname char *dfmt |
include `s3l/s3l-f.h' include `s3l/s3l_errno-f.h' subroutine S3L_read_sparse(A, spfmt, m, n, nnz, type, fname, dfmt, ier) integer*8 A integer*4 spfmt integer*4 m integer*4 n integer*4 nnz integer*4 type character*1 fname character*1 dfmt integer*4 ier |
spfmt - Specifies the sparse storage format used for representing the sparse matrix. The supported formats are S3L_SPARSE_COO and S3L_SPARSE_CSR.
m - Indicates the total number of rows in the sparse matrix.
n - Indicates the total number of columns in the sparse matrix.
nnz - Indicates the total number of nonzero elements in the sparse matrix.
type - The type of the sparse array, which must be one of: S3L_float, S3L_double, S3L_complex, or S3L_dcomplex.
fname - Scalar character variable that names the ASCII file containing the sparse matrix data.
dfmt - Specifies the format of the data to be read from the data file. The supported format is ASCII.
This function uses the following argument for output:
A - S3L internal array handle for the global general sparse matrix output.
ier (Fortran only) - When called from a Fortran program, this function returns error status in ier.
On success, S3L_read_sparse returns S3L_SUCCESS.
The S3L_read_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 this function to terminate and return the associated error code:
S3L_ERR_ARG_EXTENTS - Invalid m, n, or nnz. These arguments must all be > 0.
S3L_ERR_SPARSE_FORMAT - Invalid storage format. It must be either S3L_SPARSE_COO or S3L_SPARSE_CRS.
S3L_ERR_ARG_DTYPE - Invalid data type. It must be S3L_float, S3L_double, S3L_complex, or S3L_dcomplex.
S3L_ERR_IO_FILENAME - Invalid file name.
S3L_ERR_IO_FORMAT - Invalid data file format. The error could be either of the following:
The dfmt value supplied was not 'ascii'.
An unsupported MatrixMarket format was supplied. When a MatrixMarket file is used, the first line of its comment section must contain either the words 'real general' or 'complex general'.
S3L_ERR_FILE_OPEN - Failed to open the data file; the file either does not exist or the name is specified incorrectly.
S3L_ERR_EOF - The input data ends before expected.
../examples/s3l/sparse/ex_sparse.c ../examples/s3l/sparse-f/ex_sparse.f
S3L_declare_sparse(3) S3L_matvec_sparse(3) S3L_rand_sparse(3)
S3L_print_sparse prints all nonzero values of a global general sparse matrix and their corresponding row and column indices to standard output.
For example, the following 4x6 sample matrix
3.14 0 0 20.04 0 0 0 27 0 0 -0.6 0 0 0 -0.01 0 0 0 -0.031 0 0 0.08 0 314.0 |
could be printed by a C program in the following manner.
4 6 8 0 0 3.14000 0 3 200.040000 1 1 27.000000 1 4 -0.600000 2 2 -0.010000 3 0 -0.031000 3 3 0.080000 3 5 314.000000 |
Note that, for C-language applications, zero-based indices are used. When S3L_print_sparse is called from a Fortran program,one-basedindices are used, as shown below.
4 6 8 1 1 3.14000 1 4 200.040000 2 2 27.000000 2 5 -0.600000 3 3 -0.010000 4 1 -0.031000 4 4 0.080000 4 6 314.000000 |
The C and Fortran syntax for S3L_print_sparse are shown below.
#include <s3l/s3l-c.h> #include <s3l/s3l_errno-c.h> int S3L_print_sparse(A) S3L_array_t A |
include `s3l/s3l-f.h' include `s3l/s3l_errno-f.h' subroutine S3L_print_sparse(A, ier) integer*8 A integer*4 ier |
A - S3L internal array handle for the global general sparse matrix that is produced by a prior call to one of the following sparse routines:
S3L_declare_sparse
S3L_read_sparse
S3L_rand_sparse
S3L_print_sparse uses the following argument for output:
ier (Fortran only) - When called from a Fortran program, S3L_print_sparse returns error status in ier.
On success, S3L_print_sparse returns S3L_SUCCESS.
The S3L_print_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.
On error, it returns the following code.
S3L_ERR_ARG_NULL - The value specified for A is invalid; no such S3L sparse matrix has been defined.
../examples/s3l/sparse/ex_sparse.c ../examples/s3l/sparse/ex_sparse2.c ../examples/s3l/sparse-f/ex_sparse.f
S3L_declare_sparse(3) S3L_read_sparse(3) S3L_rand_sparse(3)