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

SGTF and DGTF--General Tridiagonal Matrix Factorization

These subroutines compute the standard Gaussian factorization with partial pivoting for tridiagonal matrix A, stored in tridiagonal storage mode. To solve a tridiagonal system with one or more right-hand sides, follow the call to these subroutines with one or more calls to SGTS or DGTS, respectively.

Table 109. Data Types

Note:

The output from these factorization subroutines should be used only as input to the solve subroutines SGTS and DGTS, respectively.

Syntax

On Entry

n

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

c

is the vector c, containing the lower subdiagonal of matrix A in positions 2 through n in an array, referred to as C. Specified as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 109.

d

is the vector d, containing the main diagonal of matrix A, in positions 1 through n in an array, referred to as D. Specified as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 109.

e

is the vector e, containing the upper subdiagonal of matrix A, in positions 1 through n-1 in an array, referred to as E. Specified as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 109.

f

See On Return.

ipvt

See On Return.

On Return

c

is the vector c, containing part of the factorization of matrix A in positions 1 through n in an array, referred to as C. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 109.

d

is the vector d, containing part of the factorization of matrix A in an array, referred to as D. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 109.

e

is the vector e, containing part of the factorization of the matrix A in positions 1 through n in an array, referred to as E. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 109.

f

is the vector f, containing part of the factorization of matrix A in the first n positions in an array, referred to as F. Returned as: a one-dimensional array of (at least) length n, containing numbers of the data type indicated in Table 109.

ipvt

is the integer vector ipvt of length n, containing the pivot information. Returned as: a one-dimensional array of (at least) length n, containing fullword integers.

Notes

1. For a description of how tridiagonal matrices are stored, see General Tridiagonal Matrix.
2. ipvt is not a permutation vector in the strict sense. It is used to record column interchanges in the tridiagonal matrix due to partial pivoting.
3. The factorization matrix A is stored in nonstandard format.

Function

The standard Gaussian elimination with partial pivoting of tridiagonal matrix A is computed. The factorization is returned by overwriting input arrays C, D, and E, and by writing into output array F, along with pivot information in vector ipvt. This factorization can then be used by SGTS or DGTS, respectively, to solve tridiagonal systems of linear equations. See references [43], [54], [55], and [90]. If n is 0, no computation is performed.

Error Conditions

Computational Errors

Matrix A is singular or nearly singular.

• A pivot element has a value that cannot be reciprocated or is equal to 0. The index i of the element is identified in the computational error message.
• The return code is set to 1.
• i can be determined at run time by use of the ESSL error-handling facilities. To obtain this information, you must use ERRSET to change the number of allowable errors for error code 2105 in the ESSL error option table; otherwise, the default value causes your program to terminate when this error occurs. For details, see What Can You Do about ESSL Computational Errors?.

Input-Argument Errors

n < 0

Example

This example shows how to factor the following tridiagonal matrix A of order 4:

                          *                    *
                          | 2.0  2.0  0.0  0.0 |
                          | 1.0  3.0  2.0  0.0 |
                          | 0.0  1.0  3.0  2.0 |
                          | 0.0  0.0  1.0  3.0 |
                          *                    *

Call Statement and Input

           N   C   D   E   F   IPVT
           |   |   |   |   |    |
CALL DGTF( 4 , C , D , E , F , IPVT )
 
C        =  ( . , 1.0, 1.0, 1.0)
D        =  (2.0, 3.0, 3.0, 3.0)
E        =  (2.0, 2.0, 2.0, . )

Output

C        =  ( . , -0.5, -0.5, -0.5)
D        =  (-0.5, -0.5, -0.5, -0.5)
E        =  (2.0, 2.0, 2.0, . )
IPVT     =  (X'00', X'00', X'00', X'00')

Notes:  

1. F is stored in an internal format and is passed unchanged to the solve subroutine.
2. A "." means you do not have to store a value in that position in the array. However, these storage positions are required and may be overwritten during the computation.