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

DGKTRN--For a General Sparse Matrix, Convert Between Diagonal-Out and Profile-In Skyline Storage Mode

This subroutine converts general sparse matrix A of order n from one skyline storage mode to another--that is, between the following:

• Diagonal-out skyline storage mode
• Profile-in skyline storage mode

Syntax

On Entry

n

is the order of general sparse matrix A. Specified as: a fullword integer; n >= 0.

au

is the array, referred to as AU, containing the upper triangular part of general sparse matrix A, stored as follows, where:

If ITRAN(1) = 0, A is stored in diagonal-out skyline storage mode.

If ITRAN(1) = 1, A is stored in profile-in skyline storage mode.

Specified as: a one-dimensional array of (at least) length nu, containing long-precision real numbers.

nu

is the length of array AU. Specified as: a fullword integer; nu >= 0 and nu >= (IDU(n+1)-1).

idu

is the array, referred to as IDU, containing the relative positions of the diagonal elements of matrix A in input array AU. Specified as: a one-dimensional array of (at least) length n+1, containing fullword integers.

al

is the array, referred to as AL, containing the lower triangular part of general sparse matrix A, stored as follows, where:

If ITRAN(1) = 0, A is stored in diagonal-out skyline storage mode.

If ITRAN(1) = 1, A is stored in profile-in skyline storage mode.

Note:

Entries in AL for diagonal elements of A are assumed not to have meaningful values.

Specified as: a one-dimensional array of (at least) length nl, containing long-precision real numbers.

nl

is the length of array AL. Specified as: a fullword integer; nl >= 0 and nl >= (IDL(n+1)-1).

idl

is the array, referred to as IDL, containing the relative positions of the diagonal elements of matrix A in input array AL. Specified as: a one-dimensional array of (at least) length n+1, containing fullword integers.

itran

is an array of parameters, ITRAN(i), where:

• ITRAN(1) indicates the input storage mode used for matrix A. This determines the arrangement of data in arrays AU, IDU, AL, and IDL on input, where:

  If ITRAN(1) = 0, diagonal-out skyline storage mode is used.

  If ITRAN(1) = 1, profile-in skyline storage mode is used.

• ITRAN(2) indicates the output storage mode used for matrix A. This determines the arrangement of data in arrays AU, IDU, AL, and IDL on output, where:

  If ITRAN(2) = 0, diagonal-out skyline storage mode is used.

  If ITRAN(2) = 1, profile-in skyline storage mode is used.

• ITRAN(3) indicates the direction of sweep that ESSL uses through the matrix A, allowing you to optimize performance (see Notes), where:

  If ITRAN(3) = 1, matrix A is transformed in the positive direction, starting in row or column 1 and ending in row or column n.

  If ITRAN(3) = -1, matrix A is transformed in the negative direction, starting in row or column n and ending in row or column 1.

Specified as: a one-dimensional array of (at least) length 3, containing fullword integers, where:

ITRAN(1) = 0 or 1

ITRAN(2) = 0 or 1

ITRAN(3) = -1 or 1

aux

has the following meaning:

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

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

Specified as: an area of storage, containing naux long-precision real numbers.

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, DGKTRN dynamically allocates the work area used by this subroutine. The work area is deallocated before control is returned to the calling program.

Otherwise, naux >= 2n.

On Return

au

is the array, referred to as AU, containing the upper triangular part of general sparse matrix A, stored as follows, where:

If ITRAN(2) = 0, A is stored in diagonal-out skyline storage mode.

If ITRAN(2) = 1, A is stored in profile-in skyline storage mode.

Returned as: a one-dimensional array of (at least) length nu, containing long-precision real numbers.

idu

is the array, referred to as IDU, containing the relative positions of the diagonal elements of matrix A in output array AU. Returned as: a one-dimensional array of (at least) length n+1, containing fullword integers.

al

is the array, referred to as AL, containing the lower triangular part of general sparse matrix A, stored as follows, where:

If ITRAN(2) = 0, A is stored in diagonal-out skyline storage mode.

If ITRAN(2) = 1, A is stored in profile-in skyline storage mode.

Note:

You should assume that entries in AL for diagonal elements of A do not have meaningful values.

Returned as: a one-dimensional array of (at least) length nl, containing long-precision real numbers.

idl

is the array, referred to as IDL, containing the relative positions of the diagonal elements of matrix A in output array AL. Returned as: a one-dimensional array of (at least) length n+1, containing fullword integers.

Notes

1. Your various arrays must have no common elements; otherwise, results are unpredictable.
2. The ITRAN(3) argument allows you to specify the direction of travel through matrix A that ESSL takes during the transformation. By properly specifying ITRAN(3), you can optimize the performance of the transformation, which is especially beneficial when transforming large matrices.

   The direction specified by ITRAN(3) should be opposite the most recent direction of access through the matrix performed by the DGKFS or DGKFSP subroutine, as indicated in the following table:
   

   Most Recent Computation Performed by DGKFS/DGKFSP	Direction Used by DGKFS/DGKFSP	Direction to Specify in ITRAN(3)
   Factor and Solve	Negative	Positive (ITRAN(3) = 1)
   Factor Only	Positive	Negative (ITRAN(3) = -1)
   Solve Only	Negative	Positive (ITRAN(3) = 1)

3. For a description of how sparse matrices are stored in skyline storage mode, see Profile-In Skyline Storage Mode and Diagonal-Out Skyline Storage Mode.
4. 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 general sparse matrix A, stored in diagonal-out or profile-in skyline storage mode is converted to either of these same two storage modes. (Generally, you convert from one to the other, but the capability exists to specify the same storage mode for input and output.) The argument ITRAN(3) indicates the direction in which you want the transformation performed on matrix A, allowing you to optimize your performance in this subroutine. This is especially beneficial for large matrices.

This subroutine is meant to be used in conjunction with DGKFS and DGKFSP, which process matrices stored in these skyline storage modes.

Error Conditions

Resource Errors

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

Computational Errors

None

Input-Argument Errors

1. n < 0
2. nu < 0
3. IDU(n+1) > nu+1
4. IDU(i+1) <= IDU(i) for i = 1, n
5. IDU(i+1) > IDU(i)+i and ITRAN(1) = 0 for i = 1, n
6. IDU(i) > IDU(i-1)+i and ITRAN(1) = 1 for i = 2, n
7. nl < 0
8. IDL(n+1) > nl+1
9. IDL(i+1) <= IDL(i) for i = 1, n
10. IDL(i+1) > IDL(i)+i and ITRAN(1) = 0 for i = 1, n
11. IDL(i) > IDL(i-1)+i and ITRAN(1) = 1 for i = 2, n
12. ITRAN(1) <> 0 or 1
13. ITRAN(2) <> 0 or 1
14. ITRAN(3) <> -1 or 1
15. 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 1

This example shows how to convert a 9 by 9 general sparse matrix A from diagonal-out skyline storage mode to profile-in skyline storage mode. Matrix A is:

     *                                                      *
     | 11.0  12.0  13.0   0.0   0.0   0.0   0.0   0.0   0.0 |
     | 21.0  22.0  23.0  24.0  25.0   0.0   0.0   0.0  29.0 |
     | 31.0  32.0  33.0  34.0  35.0   0.0  37.0   0.0  39.0 |
     | 41.0  42.0  43.0  44.0  45.0  46.0  47.0   0.0  49.0 |
     |  0.0   0.0   0.0  54.0  55.0  56.0  57.0  58.0  59.0 |
     |  0.0  62.0  63.0  64.0  65.0  66.0  67.0  68.0  69.0 |
     |  0.0   0.0   0.0  74.0  75.0  76.0  77.0  78.0  79.0 |
     |  0.0   0.0   0.0  84.0  85.0  86.0  87.0  88.0  89.0 |
     | 91.0  92.0  93.0  94.0  95.0  96.0  97.0  98.0  99.0 |
     *                                                      *

Assuming that DGKFS last performed a solve on matrix A, the direction of the transformation is positive; that is, ITRAN(3) is 1. This provides the best performance here.

Note:

On input and output, the diagonal elements in AL do not have meaningful values.

Call Statement and Input

             N   AU   NU   IDU   AL   NL   IDL   ITRAN   AUX   NAUX
             |   |    |     |    |    |     |      |      |     |
CALL DGKTRN( 9 , AU , 33 , IDU , AL , 35 , IDL , ITRAN , AUX ,  18

AU       =  (11.0, 22.0, 12.0, 33.0, 23.0, 13.0, 44.0, 34.0, 24.0,
             55.0, 45.0, 35.0, 25.0, 66.0, 56.0, 46.0, 77.0, 67.0,
             57.0, 47.0, 37.0, 88.0, 78.0, 68.0, 58.0, 99.0, 89.0,
             79.0, 69.0, 59.0, 49.0, 39.0, 29.0)
IDU      =  (1, 2, 4, 7, 10, 14, 17, 22, 26, 34)
AL       =  ( . , . , 21.0, . , 32.0, 31.0, . , 43.0, 42.0, 41.0, . ,
             54.0, . , 65.0, 64.0, 63.0, 62.0, . , 76.0, 75.0, 74.0,
             . , 87.0, 86.0, 85.0, 84.0, . , 98.0, 97.0, 96.0, 95.0,
             94.0, 93.0, 92.0, 91.0)
IDL      =  (1, 2, 4, 7, 11, 13, 18, 22, 27, 36)
ITRAN    =  (0, 1, 1)

Output

AU       =  (11.0, 12.0, 22.0, 13.0, 23.0, 33.0, 24.0, 34.0, 44.0,
             25.0, 35.0, 45.0, 55.0, 46.0, 56.0, 66.0, 37.0, 47.0,
             57.0, 67.0, 77.0, 58.0, 68.0, 78.0, 88.0, 29.0, 39.0,
             49.0, 59.0, 69.0, 79.0, 89.0, 99.0)
IDU      =  (1, 3, 6, 9, 13, 16, 21, 25, 33, 34)
AL       =  ( . , 21.0, . , 31.0, 32.0, . , 41.0, 42.0, 43.0, . , 54.0,
             . , 62.0, 63.0, 64.0, 65.0, . , 74.0, 75.0, 76.0, . ,
             84.0, 85.0, 86.0, 87.0, . , 91.0, 92.0, 93.0, 94.0, 95.0,
             96.0, 97.0, 98.0, . )
IDL      =  (1, 3, 6, 10, 12, 17, 21, 26, 35, 36)

Example 2

This example shows how to convert the same 9 by 9 general sparse matrix A in Example 1 from profile-in skyline storage mode to diagonal-out skyline storage mode.

Assuming that DGKFS last performed a factorization on matrix A, the direction of the transformation is negative; that is, ITRAN(3) is -1. This provides the best performance here.

Note:

On input and output, the diagonal elements in AL do not have meaningful values.

Call Statement and Input

             N   AU   NU   IDU   AL   NL   IDL   ITRAN   AUX   NAUX
             |   |    |     |    |    |     |      |      |     |
CALL DGKTRN( 9 , AU , 33 , IDU , AL , 35 , IDL , ITRAN , AUX ,  18

Output