test

Sun S3L 3.0 Programming and Reference Guide

S3L_read_sparse

Description

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:

These two formats are described below.

S3L_SPARSE_COO - Coordinate Format

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.

Note -

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

MatrixMarket Notes

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.

S3L_SPARSE_CSR - Compressed Sparse Row Format

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

Syntax

The C and Fortran syntax for S3L_read_sparse are shown below.

C/C++ Syntax

Example 8-19 

#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

F77/F90 Syntax

Example 8-20 

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

Input

Output

This function uses the following argument for output:

Error Handling

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:

Examples

../examples/s3l/sparse/ex_sparse.c
../examples/s3l/sparse-f/ex_sparse.f

Related Functions

S3L_declare_sparse(3)
S3L_matvec_sparse(3)
S3L_rand_sparse(3)