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

SGEF, DGEF, CGEF, and ZGEF--General Matrix Factorization

This subroutine factors a square general matrix A using Gaussian elimination with partial pivoting. To solve the system of equations with one or more right-hand sides, follow the call to these subroutines with one or more calls to SGES/SGESM, DGES/DGESM, CGES/CGESM, or ZGES/ZGESM, respectively. To compute the inverse of matrix A, follow the call to these subroutines with a call to SGEICD or DGEICD, respectively.

Table 87. Data Types

Note:

The output from these factorization subroutines should be used only as input to the following subroutines for performing a solve or inverse: SGES/SGESM/SGEICD, DGES/DGESM/DGEICD, CGES/CGESM, and ZGES/ZGESM, respectively.

Syntax

On Entry

a

is the n by n general matrix A to be factored. Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 87.

lda

is the leading dimension of the array specified for a. Specified as: a fullword integer; lda > 0 and lda >= n.

n

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

ipvt

See On Return.

On Return

a

is the n by n transformed matrix A, containing the results of the factorization. See Function. Returned as: an lda by (at least) n array, containing numbers of the data type indicated in Table 87.

ipvt

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

Notes

1. Calling SGEFCD or DGEFCD with iopt = 0 is equivalent to calling SGEF or DGEF.
2. On both input and output, matrix A conforms to LAPACK format.

Function

The matrix A is factored using Gaussian elimination with partial pivoting (ipvt) to compute the LU factorization of A, where (A = PLU) :

L is a unit lower triangular matrix.

U is an upper triangular matrix.

P is the permutation matrix.

On output, the transformed matrix A contains U in the upper triangle and L in the strict lower triangle where ipvt contains the pivots representing permutation P, such that A = PLU.

If n is 0, no computation is performed. See references [36] and [38].

Error Conditions

Resource Errors

Unable to allocate internal work area.

Computational Errors

Matrix A is singular.

• One or more columns of L and the corresponding diagonal of U contain all zeros (all columns of L are checked). The first column, i, of L with a corresponding U = 0 diagonal 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 2103 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

1. lda <= 0
2. n < 0
3. n > lda

Example 1

This example shows a factorization of a real general matrix A of order 9.

Call Statement and Input

           A  LDA  N   IPVT
           |   |   |    |
CALL SGEF( A , 9 , 9 , IPVT )

        *                                                *
        | 1.0  1.0  1.0  1.0  0.0  0.0   0.0   0.0   0.0 |
        | 1.0  1.0  1.0  1.0  1.0  0.0   0.0   0.0   0.0 |
        | 4.0  1.0  1.0  1.0  1.0  1.0   0.0   0.0   0.0 |
        | 0.0  5.0  1.0  1.0  1.0  1.0   1.0   0.0   0.0 |
A    =  | 0.0  0.0  6.0  1.0  1.0  1.0   1.0   1.0   0.0 |
        | 0.0  0.0  0.0  7.0  1.0  1.0   1.0   1.0   1.0 |
        | 0.0  0.0  0.0  0.0  8.0  1.0   1.0   1.0   1.0 |
        | 0.0  0.0  0.0  0.0  0.0  9.0   1.0   1.0   1.0 |
        | 0.0  0.0  0.0  0.0  0.0  0.0  10.0  11.0  12.0 |
        *                                                *

Output

        *                                                                             *
        | 4.0000  1.0000  1.0000  1.0000   1.0000   1.0000   0.0000   0.0000   0.0000 |
        | 0.0000  5.0000  1.0000  1.0000   1.0000   1.0000   1.0000   0.0000   0.0000 |
        | 0.0000  0.0000  6.0000  1.0000   1.0000   1.0000   1.0000   1.0000   0.0000 |
        | 0.0000  0.0000  0.0000  7.0000   1.0000   1.0000   1.0000   1.0000   1.0000 |
A    =  | 0.0000  0.0000  0.0000  0.0000   8.0000   1.0000   1.0000   1.0000   1.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   9.0000   1.0000   1.0000   1.0000 |
        | 0.0000  0.0000  0.0000  0.0000   0.0000   0.0000  10.0000  11.0000  12.0000 |
        | 0.2500  0.1500  0.1000  0.0714   0.0536  -0.0694  -0.0306   0.1806   0.3111 |
        | 0.2500  0.1500  0.1000  0.0714  -0.0714  -0.0556  -0.0194   0.9385  -0.0031 |
        *                                                                             *

IPVT     =  (3, 4, 5, 6, 7, 8, 9, 8, 9)

Example 2

This example shows a factorization of a complex general matrix A of order 4.

Call Statement and Input

           A  LDA  N   IPVT
           |   |   |    |
CALL CGEF( A , 4 , 4 , IPVT )
 
        *                                             *
        | (1.0, 2.0) (1.0, 7.0) (2.0, 4.0) (3.0, 1.0) |
A    =  | (2.0, 0.0) (1.0, 3.0) (4.0, 4.0) (2.0, 3.0) |
        | (2.0, 1.0) (5.0, 0.0) (3.0, 6.0) (0.0, 0.0) |
        | (8.0, 5.0) (1.0, 9.0) (6.0, 6.0) (8.0, 1.0) |
        *                                             *

Output

        *                                                                          *
        |  (8.0000, 5.0000)   (1.0000, 9.0000)  (6.0000, 6.0000)  (8.0000, 1.0000) |
A    =  |  (0.2022, 0.1236)   (1.9101, 5.0562)  (1.5281, 2.0449) (1.5056, -0.1910) |
        | (0.2360, -0.0225) (-0.0654, -0.9269) (-0.3462, 6.2692) (-1.6346, 1.3269) |
        | (0.1798, -0.1124)   (0.2462, 0.1308) (0.4412, -0.3655)  (0.2900, 2.3864) |
        *                                                                          *

IPVT     =  (4, 4, 3, 4)