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

DSMTM--Transpose a Sparse Matrix in Compressed-Matrix Storage Mode

This subprogram transposes sparse matrix A, stored in compressed-matrix storage mode, where A contains long-precision real numbers.

Syntax

On Entry

m

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

nz

is the maximum number of nonzero elements in each row of sparse matrix A. Specified as: a fullword integer; nz >= 0.

ac

is the m by n sparse matrix A, stored in compressed-matrix storage mode in an array, referred to as AC. Specified as: an lda by (at least) nz array, containing long-precision real numbers.

ka

is the array, referred to as KA, containing the column numbers of the matrix A elements stored in the corresponding positions in array AC. Specified as: an lda by (at least) nz array, containing fullword integers, where 1 <= (elements of KA) <= n.

lda

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

n

is the number of columns in sparse matrix A. Specified as: a fullword integer; 0 <= n <= ldt and n >=  (maximum column index in KA).

nt

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

at

See On Return.

kt

See On Return.

ldt

is the size of the leading dimension of the arrays specified for at and kt. Specified as: a fullword integer; ldt > 0 and ldt >= n.

aux

has the following meaning:

If naux = 0 and error 2015 is unrecoverable, aux is ignored.

Otherwise, it is a storage work area used by this subroutine. Its size is specified by naux.

Specified as: an area of storage, containing long-precision real numbers. They can have any value.

naux

is the size of the work area specified by aux--that is, the number of elements in aux. Specified as: a fullword integer, where:

If naux = 0 and error 2015 is unrecoverable, DSMTM dynamically allocates the work area used by this subroutine. The work area is deallocated before control is returned to the calling program.

Otherwise, naux >= n.

On Return

n

is the number of rows in the transposed matrix A^T. Returned as: a fullword integer; n = (maximum column index in KA).

nt

is the maximum number of nonzero elements, nt, in each row of the transposed matrix A^T. Returned as: a fullword integer; nt <= m.

at

is the n by (at least) m sparse matrix transpose A^T, stored in compressed-matrix storage mode in an array, referred to as AT. Returned as: an ldt by (at least) nt array, containing long-precision real numbers.

kt

is the array, referred to as KT, containing the column numbers of the transposed matrix A^T elements, stored in the corresponding positions in array AT. Returned as: an ldt by (at least) nt array, containing fullword integers, where 1 <= (elements of KT) <= m.

Notes

1. In your C program, arguments n and nt must be passed by reference.
2. The value specified for input argument nt should be greater than or equal to the number of nonzero elements you estimate to be in each row of the transposed sparse matrix A^T. The output value is less than or equal to the input value you specify.
3. For the KA array, where there are no corresponding nonzero elements in AC, you must still fill in a number between 1 and n. See the Example.
4. For a description of how sparse matrices are stored in compressed-matrix storage mode, see Compressed-Matrix Storage Mode.
5. If your sparse matrix is stored by rows, as defined in Storage-by-Rows, you should first use the DSRSM utility subroutine, described in DSRSM--Convert a Sparse Matrix from Storage-by-Rows to Compressed-Matrix Storage Mode, to convert your sparse matrix to compressed-matrix storage mode.
6. You have the option of having the minimum required value for naux dynamically returned to your program. For details, see Using Auxiliary Storage in ESSL.

Function

A sparse matrix A, stored in arrays AC and KA in compressed-matrix storage mode, is transposed, forming A^T, and is stored in arrays AT and KT in compressed-matrix storage mode. See reference [73]. This subroutine is provided for when you want to do a matrix-vector product using a transposed matrix, A^T. First, you transpose a matrix, A, using this subroutine, then you call DSMMX with the transposed matrix A^T. This results in the following computation being performed: y<--A^Tx.

If your program uses a sparse matrix stored by rows and you want to use this subroutine, you should first convert your sparse matrix to compressed-matrix storage mode by using the DSRSM utility subroutine described in DSRSM--Convert a Sparse Matrix from Storage-by-Rows to Compressed-Matrix Storage Mode.

Error Conditions

Resource Errors

Error 2015 is unrecoverable, naux = 0, and unable to allocate work area.

Computational Errors

None

Input-Argument Errors

1. m, n < 0
2. lda, ldt < 1
3. lda < m
4. ldt < n
5. nz < 0
6. n is less than the maximum column index in KA.
7. nt or ldt are too small.
8. When the following two errors occur, arrays AT, KT, and AUX are overwritten:

   naux < n

   nt <= 0

9. Error 2015 is recoverable or naux<>0, and naux is too small--that is, less than the minimum required value. Return code 1 is returned if error 2015 is recoverable.

Example

This example shows how to transpose the following 5 by 4 sparse matrix A, which is stored in compressed-matrix storage mode in arrays AC and KA. Matrix A is:

                        *                        *
                        | 11.0   0.0   0.0   0.0 |
                        | 21.0   0.0  23.0   0.0 |
                        |  0.0   0.0  33.0  34.0 |
                        |  0.0  42.0   0.0  44.0 |
                        | 51.0   0.0  53.0   0.0 |
                        *                        *

The resulting 4 by 5 matrix transpose A^T, stored in compressed-matrix storage mode in arrays AT and KT, is as follows. Matrix A^T is:

                     *                              *
                     | 11.0  21.0   0.0   0.0  51.0 |
                     |  0.0   0.0   0.0  42.0   0.0 |
                     |  0.0  23.0  33.0   0.0  53.0 |
                     |  0.0   0.0  34.0  44.0   0.0 |
                     *                              *

As shown here, the value of N is larger than the actual number of columns in the matrix A. On output, the exact number of rows in the transposed matrix is returned in the output argument N.

On output, row 6 of AT and KT is is not accessed or modified by the subroutine. Column 4 and row 5 are accessed and modified. They are of no use in further computations and will not be used, because NT = 3 and M = 4.

Call Statement and Input

            M   NZ  AC   KA  LDA  N   NT  AT   KT   LDT  AUX  NAUX
            |   |   |    |    |   |   |   |    |     |    |    |
CALL DSMTM( 5 , 2 , AC , KA , 5 , 5 , 4 , AT , KT ,  6 , AUX , 5  )

        *            *
        | 11.0   0.0 |
        | 21.0  23.0 |
AC   =  | 33.0  34.0 |
        | 42.0  44.0 |
        | 51.0  53.0 |
        *            *

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

Output

N        =  4
NT       =  3

        *                       *
        | 11.0  21.0  51.0  0.0 |
        | 42.0   0.0   0.0  0.0 |
AT   =  | 33.0  23.0  53.0  0.0 |
        | 34.0  44.0   0.0  0.0 |
        |  0.0   0.0   0.0  0.0 |
        |   .     .     .    .  |
        *                       *

        *            *
        | 1  2  5  1 |
        | 4  1  1  1 |
KT   =  | 3  2  5  1 |
        | 3  4  1  1 |
        | 1  1  1  1 |
        | .  .  .  . |
        *            *