S3L_rand_sparse

Description

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.

Syntax

The C and Fortran syntax for S3L_rand_sparse are shown below.

C/C++ Syntax

Example 8-15

#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

F77/F90 Syntax

Example 8-16

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

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.

• 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.

Output

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.

Error Handling

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

../examples/s3l/iter/ex_iter.c
../examples/s3l/iter-f/ex_iter.f

Related Functions

S3L_declare_sparse(3)
S3L_matvec_sparse(3)
S3L_read_sparse(3)