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

SGTNPF, DGTNPF, CGTNPF, and ZGTNPF--General Tridiagonal Matrix Factorization with No Pivoting

These subroutines factor tridiagonal matrix A, stored in tridiagonal storage mode, using Gaussian elimination. To solve a tridiagonal system of linear equations with one or more right-hand sides, follow the call to these subroutines with one or more calls to SGTNPS, DGTNPS, CGTNPS, or ZGTNPS, respectively.

Table 112. Data Types

Notes:

1. The output from these factorization subroutines should be used only as input to the solve subroutines SGTNPS, DGTNPS, CGTNPS, and ZGTNPS, respectively.

2. In general, the _GTNP subroutines provide better performance than the _GTNPF and _GTNPS subroutines; however, in the following instances, you get better performance by using _GTNPF and _GTNPS:
   • For small n
   • When performing a single factorization followed by multiple solves

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

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

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

iopt

indicates the type of computation to be performed, where:

If iopt = 0 or 1, Gaussian elimination is used to factor the matrix.

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

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

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

e

is the vector e, containing part of the factorization of 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 112. It has the same length as E on entry.

Note

For a description of how tridiagonal matrices are stored, see General Tridiagonal Matrix.

Function

The factorization of a diagonally-dominant tridiagonal matrix A is computed using Gaussian elimination, This factorization can then be used by SGTNPS, DGTNPS, CGTNPS, or ZGTNPS respectively, to solve the tridiagonal systems of linear equations. See reference [77].

No pivoting is done by these subroutines. Therefore, these subroutines should not be used when pivoting is necessary to maintain the numerical accuracy of the solution. Overflow may occur if small main diagonal elements are generated. Underflow or accuracy loss may occur if large main diagonal elements are generated.

For performance reasons, complex divides are done without scaling. Computing the inverse in this way restricts the range of numbers for which ZGTNPF works properly.

For performance reasons, divides are done in a way that reduces the effective exponent range for which DGTNPF and ZGTNPF work properly; therefore, you may want to scale your problem, such that the diagonal elements are close to 1.0 for DGTNPF and (1.0, 0.0) for ZGTNPF.

Error Conditions

Computational Errors

None

Input-Argument Errors

1. n < 0
2. iopt <> 0 or 1

Example 1

This example shows a factorization of the tridiagonal matrix A, of order 4:

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

Call Statement and Input

             N   C   D   E   IOPT
             |   |   |   |    |
CALL DGTNPF( 4 , C , D , E ,  0   )
 
C        =  ( . , 1.0, 1.0, 1.0)
D        =  (1.0, 2.0, 3.0, 1.0)
E        =  (1.0, 1.0, 1.0, .  )

Output

C        =  ( . , -1.0, -1.0, 1.0)
D        =  (-1.0, -1.0, -1.0, -1.0)
E        =  (1.0, 1.0, -1.0, . )

Example 2

This example shows a factorization of the tridiagonal matrix A, of order 4:

             *                                               *
             | (7.0, 7.0) (4.0, 4.0) (0.0, 0.0)   (0.0, 0.0) |
             | (1.0, 1.0) (8.0, 8.0) (5.0, 5.0)   (0.0, 0.0) |
             | (0.0, 0.0) (2.0, 2.0) (9.0, 9.0)   (6.0, 6.0) |
             | (0.0, 0.0) (0.0, 0.0) (3.0, 3.0) (10.0, 10.0) |
             *                                               *

Call Statement and Input

             N   C   D   E   IOPT
             |   |   |   |    |
CALL ZGTNPF( 4 , C , D , E ,  0   )
 
C        =  ( . , (1.0, 1.0), (2.0, 2.0), (3.0, 3.0))
D        =  ((7.0, 7.0), (8.0, 8.0), (9.0, 9.0), (10.0, 10.0))
E        =  ((4.0, 4.0), (5.0, 5.0), (6.0, 6.0), . )

Output

C        =  ( . , (-0.142, 0.0), (-0.269, 0.0), (3.0, 3.0))
D        =  ((-0.0714, 0.0714), (-0.0673, 0.0673), (-0.0854, 0.0854),
             (-0.05, 0.05))
E        =  ((4.0, 4.0), (5.0, 5.0), (-0.6, 0.0), . )

Notes:  

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