IBM Books

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

SGETRF, DGETRF, CGETRF and ZGETRF--General Matrix Factorization

These subroutines factor 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 SGETRS, DGETRS CGETRS, or ZGETRS, respectively. To compute the inverse of |real matrix A, follow the call to these subroutines with a call to |SGETRI or DGETRI.

Table 90. Data Types

A Subroutine
Short-precision real SGETRF
Long-precision real DGETRF
Short-precision complex CGETRF
Long-precision complex ZGETRF
Note:
The output from these factorization subroutines should be used only as input to the following subroutines for performing a solve or inverse: SGETRS, DGETRS, CGETRS, ZGETRS, |SGETRI, or DGETRI, respectively.

Syntax

Fortran CALL SGETRF | DGETRF | CGETRF | ZGETRF (m, n, a, lda, ipvt, info)
C and C++ sgetrf | dgetrf | cgetrf | zgetrf (m, n, a, lda, ipvt, info);
PL/I CALL SGETRF | DGETRF | CGETRF | ZGETRF (m, n, a, lda, ipvt, info);

On Entry

m
the number of rows in general matrix A used in the computation. Specified as: a fullword integer; 0 <= m <= lda.

n
the number of columns in general matrix A used in the computation. Specified as: a fullword integer; n >= 0.

a
is the m 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 90.

lda
is the leading dimension of matrix A. Specified as: a fullword integer; lda > 0 and lda >= m.

ipvt
See On Return.

info
See On Return.

On Return

a
is the m 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 90.

ipvt
is the integer vector ipvt of length min(m,n), containing the pivot indices. Returned as: a one-dimensional array of (at least) length min(m,n), containing fullword integers,where 1 <= ipvt(i) <= m.

info
has the following meaning:

If info = 0, the factorization of general matrix A completed successfully.

If info > 0, info is set equal to the first i, where Uii is singular and its inverse could not be computed.

Specified as: a fullword integer; info >= 0.

Notes
  1. In your C program, argument info must be passed by reference.
  2. The matrix A and vector ipvt must have no common elements; otherwise results are unpredictable.
  3. The way these subroutines handle singularity differs from LAPACK. These subroutines |use the info argument to provide information about the singularity of A, like LAPACK, but also provide an error message.
  4. 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 (if m >= n) or upper trapezoid (if m < n) and L in the strict lower triangle (if m <= n) or lower trapezoid (if m > n). ipvt contains the pivots representing permutation P, such that A = PLU.

If m or n is 0, no computation is performed and the subroutine returns after doing some parameter checking. See references [|8][36] and [62].

Error Conditions

Resource Errors

Unable to allocate internal work area.

Computational Errors

Matrix A is singular.

Input-Argument Errors
  1. m < 0
  2. n < 0
  3. m > lda
  4. lda <= 0

Example 1

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

Call Statement and Input
             M   N   A  LDA  IPVT  INFO
             |   |   |   |     |     |
CALL DGETRF( 9 , 9 , A,  9 , IPVT, INFO )

        *                                             *
        | 1.0  1.2  1.4  1.6  1.8  2.0  2.2  2.4  2.6 |
        | 1.2  1.0  1.2  1.4  1.6  1.8  2.0  2.2  2.4 |
        | 1.4  1.2  1.0  1.2  1.4  1.6  1.8  2.0  2.2 |
        | 1.6  1.4  1.2  1.0  1.2  1.4  1.6  1.8  2.0 |
A    =  | 1.8  1.6  1.4  1.2  1.0  1.2  1.4  1.6  1.8 |
        | 2.0  1.8  1.6  1.4  1.2  1.0  1.2  1.4  1.6 |
        | 2.2  2.0  1.8  1.6  1.4  1.2  1.0  1.2  1.4 |
        | 2.4  2.2  2.0  1.8  1.6  1.4  1.2  1.0  1.2 |
        | 2.6  2.4  2.2  2.0  1.8  1.6  1.4  1.2  1.0 |
        *                                             *

Output
        *                                              *
        | 2.6   2.4  2.2  2.0  1.8  1.6  1.4  1.2  1.0 |
        | 0.4   0.3  0.6  0.8  1.1  1.4  1.7  1.9  2.2 |
        | 0.5  -0.4  0.4  0.8  1.2  1.6  2.0  2.4  2.8 |
        | 0.5  -0.3  0.0  0.4  0.8  1.2  1.6  2.0  2.4 |
A    =  | 0.6  -0.3  0.0  0.0  0.4  0.8  1.2  1.6  2.0 |
        | 0.7  -0.2  0.0  0.0  0.0  0.4  0.8  1.2  1.6 |
        | 0.8  -0.2  0.0  0.0  0.0  0.0  0.4  0.8  1.2 |
        | 0.8  -0.1  0.0  0.0  0.0  0.0  0.0  0.4  0.8 |
        | 0.9  -0.1  0.0  0.0  0.0  0.0  0.0  0.0  0.4 |
        *                                              *

IPVT     =  (9, 9, 9, 9, 9, 9, 9, 9, 9)
INFO     =  0

Example 2

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

Call Statement and Input
             M   N   A  LDA  IPVT  INFO
             |   |   |   |     |     |
CALL ZGETRF( 9 , 9 , A,  9 , IPVT, INFO )




         *                                                                                                     *
        | (2.0, 1.0) (2.4,-1.0) (2.8,-1.0) (3.2,-1.0)  (3.6,-1.0) (4.0,-1.0) (4.4,-1.0) (4.8,-1.0) (5.2,-1.0) |
        | (2.4, 1.0) (2.0, 1.0) (2.4,-1.0) (2.8,-1.0)  (3.2,-1.0) (3.6,-1.0) (4.0,-1.0) (4.4,-1.0) (4.8,-1.0) |
        | (2.8, 1.0) (2.4, 1.0) (2.0, 1.0) (2.4,-1.0)  (2.8,-1.0) (3.2,-1.0) (3.6,-1.0) (4.0,-1.0) (4.4,-1.0) |
        | (3.2, 1.0) (2.8, 1.0) (2.4, 1.0) (2.0, 1.0)  (2.4,-1.0) (2.8,-1.0) (3.2,-1.0) (3.6,-1.0) (4.0,-1.0) |
A    =  | (3.6, 1.0) (3.2, 1.0) (2.8, 1.0) (2.4, 1.0)  (2.0, 1.0) (2.4,-1.0) (2.8,-1.0) (3.2,-1.0) (3.6,-1.0) |
        | (4.0, 1.0) (3.6, 1.0) (3.2, 1.0) (2.8, 1.0)  (2.4, 1.0) (2.0, 1.0) (2.4,-1.0) (2.8,-1.0) (3.2,-1.0) |
        | (4.4, 1.0) (4.0, 1.0) (3.6, 1.0) (3.2, 1.0)  (2.8, 1.0) (2.4, 1.0) (2.0, 1.0) (2.4,-1.0) (2.8,-1.0) |
        | (4.8, 1.0) (4.4, 1.0) (4.0, 1.0) (3.6, 1.0)  (3.2, 1.0) (2.8, 1.0) (2.4, 1.0) (2.0, 1.0) (2.4,-1.0) |
        | (5.2, 1.0) (4.8, 1.0) (4.4, 1.0) (4.0, 1.0)  (3.6, 1.0) (3.2, 1.0) (2.8, 1.0) (2.4, 1.0) (2.0, 1.0) |
        *                                                                                                     *

Output



        *                                                                                                         *
        | (5.2, 1.0) (4.8, 1.0) (4.4, 1.0)   (4.0, 1.0)   (3.6, 1.0)  (3.2, 1.0) (2.8, 1.0) (2.4, 1.0) (2.0, 1.0) |
        | (0.4, 0.1) (0.6,-2.0) (1.1,-1.9)   (1.7,-1.9)   (2.3,-1.8)  (2.8,-1.8) (3.4,-1.7) (3.9,-1.7) (4.5,-1.6) |
        | (0.5, 0.1) (0.0,-0.1) (0.6,-1.9)   (1.2,-1.8)   (1.8,-1.7)  (2.5,-1.6) (3.1,-1.5) (3.7,-1.4) (4.3,-1.3) |
        | (0.6, 0.1) (0.0,-0.1) (-0.1,-0.1)  (0.7,-1.9)   (1.3,-1.7)  (2.0,-1.6) (2.7,-1.5) (3.4,-1.4) (4.0,-1.2) |
A    =  | (0.6, 0.1) (0.0,-0.1) (-0.1,-0.1) (-0.1, 0.0)   (0.7,-1.9)  (1.5,-1.7) (2.2,-1.6) (2.9,-1.5) (3.7,-1.3) |
        | (0.7, 0.1) (0.0,-0.1)  (0.0, 0.0) (-0.1, 0.0)  (-0.1, 0.0)  (0.8,-1.9) (1.6,-1.8) (2.4,-1.6) (3.2,-1.5) |
        | (0.8, 0.0) (0.0, 0.0)  (0.0, 0.0)  (0.0, 0.0)   (0.0, 0.0)  (0.0, 0.0) (0.8,-1.9) (1.7,-1.8) (2.5,-1.8) |
        | (0.9, 0.0) (0.0, 0.0)  (0.0, 0.0)  (0.0, 0.0)   (0.0, 0.0)  (0.0, 0.0) (0.0, 0.0) (0.8,-2.0) (1.7,-1.9) |
        | (0.9, 0.0) (0.0, 0.0)  (0.0, 0.0)  (0.0, 0.0)   (0.0, 0.0)  (0.0, 0.0) (0.0, 0.0) (0.0, 0.0) (0.8,-2.0) |
        *                                                                                                         *

IPVT     =  (9, 9, 9, 9, 9, 9, 9, 9, 9)
INFO     =  0

|Example 3

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

|Call Statement and Input
|             M   N   A  LDA  IPVT  INFO
|             |   |   |   |     |     |
|CALL SGETRF( 9 , 9 , A,  9 , IPVT, INFO )
|        *                                                *
|        | 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)

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]