Engineering and Scientific Subroutine Library for AIX Version 3 Release 3: Guide and Reference

DSRSM--Convert a Sparse Matrix from Storage-by-Rows to Compressed-Matrix Storage Mode

This subroutine converts either m by n general sparse matrix A or symmetric sparse matrix A of order n from storage-by-rows to compressed-matrix storage mode, where matrix A contains long-precision real numbers.

Syntax

On Entry

iopt

indicates the storage variation used for sparse matrix A storage-by-rows:

If iopt = 0, matrix A is a general sparse matrix, where all the nonzero elements in matrix A are used to set up the storage arrays.

If iopt = 1, matrix A is a symmetric sparse matrix, where only the upper triangle and diagonal elements are used to set up the storage arrays.

Specified as: a fullword integer; iopt = 0 or 1.

ar

is the sparse matrix A, stored by rows in an array, referred to as AR. The iopt argument indicates the storage variation used for storing matrix A. Specified as: a one-dimensional array, containing long-precision real numbers. The number of elements, ne, in this array can be determined by subtracting 1 from the value in IA(m+1).

ja

is the array, referred to as JA, containing the column numbers of each nonzero element in sparse matrix A. Specified as: a one-dimensional array, containing fullword integers; 1 <= (JA elements) <= n. The number of elements, ne, in this array can be determined by subtracting 1 from the value in IA(m+1).

ia

is the row pointer array, referred to as IA, containing the starting positions of each row of matrix A in array AR and one position past the end of array AR. Specified as: a one-dimensional array of (at least) length m+1, containing fullword integers; IA(i+1) >= IA(i) for i = 1, m+1.

m

is the number of rows in sparse matrix A. Specified as: a fullword integer; m >= 0.

nz

is the number of columns in output arrays AC and KA that are available for use. Specified as: a fullword integer; nz > 0.

ac

See On Return.

ka

See On Return.

lda

is the size of the leading dimension of the arrays specified for ac and ka. Specified as: a fullword integer; 0 < lda <= m.

On Return

nz

is the maximum number of nonzero elements, nz, in each row of matrix A, which is stored in compressed-matrix storage mode. Returned as: a fullword integer; (input argument) nz <= (output argument) nz.

ac

is the m by n general sparse matrix A or symmetric matrix A of order n stored in compressed-matrix storage mode in an array, referred to as AC. Returned as: an lda by at least (input argument) nz array, containing long-precision real numbers, where only the first (output argument) nz columns are used to store the matrix.

ka

is the array, referred to as KA, containing the column numbers of the matrix A elements that are stored in the corresponding positions in array AC. Returned as: an lda by at least (input argument) nz array, containing fullword integers, where only the first (output argument) nz columns are used to store the column numbers.

Notes

1. In your C program, argument nz must be passed by reference.
2. The value specified for input argument nz should be greater than or equal to the number of nonzero elements you estimate to be in each row of sparse matrix A. The value returned in output argument nz corresponds to the nz value defined for compressed-matrix storage mode. This value is less than or equal to the value specified for input argument nz.
3. For a description of the storage modes for sparse matrices, see Compressed-Matrix Storage Mode and Storage-by-Rows.

Function

A sparse matrix A is converted from storage-by-rows (using arrays AR, JA, and IA) to compressed-matrix storage mode (using arrays AC and KA). The argument iopt indicates whether the input matrix A is stored by rows using the storage variation for general sparse matrices or for symmetric sparse matrices. See reference [73].

This subroutine is meant for existing programs that need to convert their sparse matrices to a storage mode compatible with some of the ESSL sparse matrix subroutines, such as DSMMX.

Error Conditions

Computational Errors

None

Input-Argument Errors

1. iopt <> 0 or 1
2. m < 0
3. lda < 1
4. lda < m
5. nz <= 0
6. IA(m+1) < 1
7. IA(i+1)-IA(i) < 0, for any i = 1, m
8. nz is too small to store matrix A in array AC, where:
   • If iopt = 0 , AC and KA are not modified.
   • If iopt = 1 , AC and KA are modified.

Example 1

This example shows a general sparse matrix A, which is stored by rows and converted to compressed-matrix storage mode, where sparse matrix A is:

                    *                        *
                    | 11.0   0.0   0.0  14.0 |
                    |  0.0  22.0   0.0  24.0 |
                    |  0.0   0.0  33.0  34.0 |
                    |  0.0   0.0   0.0  44.0 |
                    *                        *

Because there is a maximum of only two nonzero elements in each row of A, and argument nz is specified as 5, columns 3 through 5 of arrays AC and KA are not used.

Call Statement and Input

           IOPT  AR   JA   IA   M   NZ  AC   KA  LDA
            |    |    |    |    |   |   |    |    |
CALL DSRSM( 0  , AR , JA , IA , 4 , 5 , AC , KA , 4 )
 
AR       =  (11.0, 14.0, 22.0, 24.0, 33.0, 34.0, 44.0)
JA       =  (1, 4, 2, 4, 3, 4, 4)
IA       =  (1, 3, 5, 7, 8)

Output

NZ       =  2
 
        *                     *
        | 11.0  14.0  .  .  . |
AC   =  | 22.0  24.0  .  .  . |
        | 33.0  34.0  .  .  . |
        | 44.0   0.0  .  .  . |
        *                     *

        *               *
        | 1  4  .  .  . |
KA   =  | 2  4  .  .  . |
        | 3  4  .  .  . |
        | 4  4  .  .  . |
        *               *

Example 2

This example shows a symmetric sparse matrix A, which is stored by rows and converted to compressed-matrix storage mode, where sparse matrix A is:

                    *                        *
                    | 11.0   0.0   0.0  14.0 |
                    |  0.0  22.0   0.0  24.0 |
                    |  0.0   0.0  33.0  34.0 |
                    | 14.0  24.0  34.0  44.0 |
                    *                        *

Because there is a maximum of only four nonzero elements in each row of A, and argument nz is specified as 6, columns 5 and 6 of arrays AC and KA are not used.

Call Statement and Input

           IOPT  AR   JA   IA   M   NZ  AC   KA  LDA
            |    |    |    |    |   |   |    |    |
CALL DSRSM( 1  , AR , JA , IA , 4 , 6 , AC , KA , 4 )
 
AR       =  (11.0, 14.0, 22.0, 24.0, 33.0, 34.0, 44.0)
JA       =  (1, 4, 2, 4, 3, 4, 4)
IA       =  (1, 3, 5, 7, 8)

Output

NZ       =  4
 
        *                              *
        | 11.0  14.0   0.0   0.0  .  . |
AC   =  | 22.0  24.0   0.0   0.0  .  . |
        | 33.0  34.0   0.0   0.0  .  . |
        | 44.0  24.0  34.0  14.0  .  . |
        *                              *

        *                  *
        | 1  4  4  4  .  . |
KA   =  | 2  4  4  4  .  . |
        | 3  4  4  4  .  . |
        | 4  2  3  1  .  . |
        *                  *