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

SGEICD, DGEICD, SGETRI and DGETRI--General Matrix Inverse

|These subroutines find the inverse of general matrix |A.

|Subroutines SGEICD and DGEICD also find the reciprocal of the condition number and the determinant of |general matrix A.

Table 100. Data Types

A, `aux`, `rcond`, *det, work*	Subroutine
Short-precision real	SGEICD and SGETRI
Long-precision real	DGEICD and DGETRI

Note:: If you call |subroutines SGEICD and DGEICD with iopt = 4, the input must be the output from the factorization subroutines SGEF/SGEFCD/SGETRF or DGEF/DGEFCD/DGEFP/DGETRF, respectively.
|The input to SGETRI and DGETRI must be the output from the |factorization subroutines SGETRF and DGETRF, respectively.

Syntax

Fortran	CALL SGEICD \| DGEICD (`a`, `lda`, `n`, `iopt`, `rcond`, `det`, `aux`, `naux`) CALL SGETRI \| DGETRI (`n`, `a`, `lda`, `ipvt`, `work`, `lwork`, `info`)
C and C++	sgeicd \| dgeicd (`a`, `lda`, `n`, `iopt`, `rcond`, `det`, `aux`, `naux`); sgetri \| dgetri (`n`, `a`, `lda`, `ipvt`, `work`, `lwork`, `info`);
PL/I	CALL SGEICD \| DGEICD (`a`, `lda`, `n`, `iopt`, `rcond`, `det`, `aux`, `naux`); CALL SGETRI \| DGETRI (`n`, `a`, `lda`, `ipvt`, `work`, `lwork`, `info`);

On Entry

a

has the following meaning, where:

|For subroutines SGEICD and DGEICD:

If iopt = 0, 1, 2, or 3, it is matrix A of order n, whose inverse, reciprocal of condition number, and determinant are computed.

If iopt = 4, it is the transformed matrix A of order n, resulting from the factorization performed in a previous call to SGEF/SGEFCD or DGEF/DGEFCD/DGEFP, respectively, whose inverse is computed. |

|For subroutines SGETRI and DGETRI:

|It is the transformed matrix A of order n, resulting |from the factorization performed in a previous call to SGETRF or DGETRF, |respectively, whose inverse is computed.

Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 100.

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.

iopt

indicates the type of computation to be performed, where:

If iopt = 0, the inverse is computed for matrix A.

If iopt = 1, the inverse and the reciprocal of the condition number are computed for matrix A.

If iopt = 2, the inverse and the determinant are computed for matrix A.

If iopt = 3, the inverse, the reciprocal of the condition number, and the determinant are computed for matrix A.

If iopt = 4, the inverse is computed using the factored matrix A.

Specified as: a fullword integer; iopt = 0, 1, 2, 3, 4.

rcond

See On Return.

det

See On Return.

aux

has the following meaning, and its size is specified by naux:

If iopt = 0, 1, 2, or 3, then if naux = 0 and error 2015 is unrecoverable, aux is ignored. Otherwise, it is the storage work area used by this subroutine.

If iopt = 4, aux has the following meaning:

For SGEICD, the first n locations in aux must contain the ipvt integer vector of length n, resulting from a previous call to SGEF, SGETRF, or SGEFCD.
For DGEICD, the first ceiling(n/2) locations in aux must contain the ipvt integer vector of length n, resulting from a previous call to DGEF, DGETRF, DGEFCD, or DGEFP.

Specified as: an area of storage, containing numbers of the data type indicated in Table 100.

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 iopt <> 4, then if naux = 0 and error 2015 is unrecoverable, SGEICD and DGEICD dynamically allocate the work area used by the subroutine. The work area is deallocated before control is returned to the calling program.

Otherwise naux must have the following value:

For the |POWER, POWER3, |POWER4, or PowerPC processors, naux >= 100n.

For the |POWER2 processors, naux >= 200n.

Note:: naux values specified for releases prior to ESSL Version 2 Release 2 will still work, but you may not achieve optimal performance.

|ipvt

|is the integer vector ipvt of length n, containing |the pivot indices resulting from a previous call to SGETRF or DGETRF. |Specified as: a one-dimensional array of (at least) length n, |containing fullword integers, where |1 <= ipvt(i) <= n.

|work

|has the following meaning:

|If lwork = 0, work is ignored.

|If lwork <> 0, work is the work area used by |this subroutine, where: |

|If lwork <> -1, its size is (at least) of length |lwork.
|If lwork = -1, its size is (at least) of length |1. |

|Specified as: an area of storage containing numbers of data type |indicated in Table 100.

|lwork

|is the number of elements in array WORK.

|Specified as: a fullword integer; where: |

|If lwork = 0, SGETRI/DGETRI dynamically allocates the |work area used by this subroutine. The work area is deallocated before |control is returned to the calling program. This option is an extension |to the LAPACK standard.
|If lwork = -1, SGETRI/DGETRI performs a work area |query and returns the optimal size of work in |work₁. No computation is performed and the |subroutine returns after error checking is complete.
|Otherwise, it must be:
|lwork >= max(1, n)
|For optimal performance, lwork >=100*n. |

|info

|See On Return.

On Return

a

is the resulting inverse of matrix A of order n. Returned as: an lda by (at least) n array, containing numbers of the data type indicated in Table 100.

rcond

is the reciprocal of the condition number, rcond, of matrix A. Returned as: a real number of the data type indicated in Table 100; rcond >= 0.

det

is the vector det, containing the two components det₁ and det₂ of the determinant of matrix A. The determinant is:

Determinant Graphic

where 1 <= det₁ < 10. Returned as: an array of length 2, containing numbers of the data type indicated in Table 100.

|work

|is the work area used by this subroutine if lwork <> 0, |where:

|If lwork <> 0 and lwork <> -1, |its size is (at least) of length lwork.

|If lwork = -1, its size is (at least) of length |1.

|Returned as: an area of storage, where:

|If lwork >= 1 or lwork = -1, then |work₁ is set to the optimal lwork value and |contains numbers of the data type indicated in Table 100. Except for work₁, the contents |of work are overwritten on return.

|info

|has the following meaning:

|If info = 0, the inverse completed successfully.

|If info > 0, info is set equal to the |first i, where U_ii is exactly zero. The |matrix is singular, and its inverse could not be computed.

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

Notes

In your C program, arguments rcond and |info must be passed by reference.
|If iopt = 4, the input scalar arguments for SGEICD |and DGEICD must be set to the same values as the corresponding input arguments |in the previous call to SGEF/SGEFCD or DGEF/DGEFCD/DGEFP, respectively.

|The input scalar arguments for SGETRI and DGETRI must be set to the same |values as the corresponding input arguments in the previous call to SGETRF or |DGETRF, respectively.
You have the option of having the value for naux dynamically returned to your program. For details, see Using Auxiliary Storage in ESSL.
|The way _GETRI subroutines handle computational errors differs from |LAPACK. These subroutines use the info argument to provide |information about the computational error, like LAPACK, but also provide an |error message.
|On both input and output, matrix A conforms to LAPACK |format.
|For best performance, specify |lwork = 0.

Function

|For subroutines SGEICD and DGEICD, the inverse, the reciprocal of the condition number, and the determinant of a general square matrix A are computed using partial pivoting to preserve accuracy, where:

A^-1 is the inverse of matrix A, where AA^-1 = A^-1A = I, and I is the identity matrix.
1/(||A||₁)(||A^-1||₁) is the reciprocal of the condition number, where ||A||₁ is the one-norm of matrix A.
|A| is the determinant of matrix A, where |A| is expressed as:

The iopt argument is used to determine the combination of output items produced by this subroutine: the inverse, the reciprocal of the condition number, and the determinant.

|For subroutines SGETRI and DGETRI, the inverse of general square |matrix A is computed.

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

Error Conditions

Resource Errors

If iopt = 0, 1, 2, or 3, then error 2015 is unrecoverable, naux = 0, and unable to allocate work area.

Computational Errors

|Matrix A is singular or nearly singular (for SGEICD and |DGEICD). |
- |The index i of the first pivot element having a value equal to 0, |is identified in the computational error message.
- |These subroutines return 0 for rcond and det, if you |requested them.
- |The return code is set to 2.
- |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?. |
|Matrix A is singular or nearly singular (for SGETRI and |DGETRI). |
- |The index i of the first pivot element having a value equal to 0, |is identified in the computational error message.
- |The computational error message may occur multiple times with processing |continuing after each error, because the default for the number of allowable |errors for error code 2149 is set to be unlimited in the ESSL error option |table. |

Input-Argument Errors

lda <= 0
n < 0
n > lda
iopt <> 0, 1, 2, 3, or 4
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 computes the inverse, the reciprocal of the condition number, and the determinant of matrix A. The values used to compute the reciprocal of the condition number in this example are obtained with the following values:

||A||₁ = max(6.0, 8.0, 10.0, 12.0, 13.0, 14.0, 15.0, 15.0, 15.0) = 15.0

||A^-1||₁ = 1226.33

On output, the value in det, |A|, is equal to 336.

Call Statement and Input

             A  LDA  N  IOPT  RCOND   DET   AUX   NAUX
             |   |   |   |      |      |     |     |
CALL DGEICD( A , 9 , 9 , 3  , RCOND , DET , AUX , 293 )
 
        *                                                *
        | 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

        *                                                                      *
        |    0.333   -0.667   0.333  0.000  0.000  0.000   0.042 -0.042  0.000 |
        |   56.833  -52.167  -1.167 -0.500 -0.500 -0.357   6.836 -0.479 -0.500 |
        |  -55.167   51.833   0.833  0.500  0.500  0.214  -6.735  0.521  0.500 |
        |   -1.000    1.000   0.000  0.000  0.000  0.143  -0.143  0.000  0.000 |
A    =  |   -1.000    1.000   0.000  0.000  0.000  0.000   0.000  0.000  0.000 |
        |   -1.000    1.000   0.000  0.000  0.000  0.000  -0.125  0.125  0.000 |
        | -226.000  206.000   5.000  3.000  2.000  1.429 -27.179  1.750  2.000 |
        |  560.000 -520.000 -10.000 -6.000 -4.000 -2.857  67.857 -5.000 -5.000 |
        | -325.000  305.000   5.000  3.000  2.000  1.429 -39.554  3.125  3.000 |
        *                                                                      *
 
RCOND    =  0.00005436
DET      =  (3.36, 2.00)

Example 2

|This example computes the inverse of matrix A, |where: iopt = 4; matrix A is the |transformed matrix factored by SGEF in Example 1; and the input contents of AUX are the same |as the output contents of IPVT in Example 1.

Call Statement and Input

             A  LDA  N  IOPT  RCOND   DET   AUX   NAUX
             |   |   |   |      |      |     |     |
CALL SGEICD( A , 9 , 9 , 4  , RCOND , DET , AUX , 300 )

A = (same as output A in Example 1)
|AUX = (same as output IPVT in Example 1)

Output:

        *                                                                      *
        |    0.333   -0.667   0.333  0.000  0.000  0.000   0.042 -0.042  0.000 |
        |   56.833  -52.167  -1.167 -0.500 -0.500 -0.357   6.836 -0.479 -0.500 |
        |  -55.167   51.833   0.833  0.500  0.500  0.214  -6.735  0.521  0.500 |
        |   -1.000    1.000   0.000  0.000  0.000  0.143  -0.143  0.000  0.000 |
A    =  |   -1.000    1.000   0.000  0.000  0.000  0.000   0.000  0.000  0.000 |
        |   -1.000    1.000   0.000  0.000  0.000  0.000  -0.125  0.125  0.000 |
        | -226.000  206.000   5.000  3.000  2.000  1.429 -27.179  1.750  2.000 |
        |  560.000 -520.000 -10.000 -6.000 -4.000 -2.857  67.857 -5.000 -5.000 |
        | -325.000  305.000   5.000  3.000  2.000  1.429 -39.554  3.125  3.000 |
        *                                                                      *

|Example 3

|This example computes the inverse of matrix A, where matrix |A is the transformed matrix factored by SGETRF in Example 3 and the input contents of IPVT are the same |as the output contents of IPVT in Example 3.

|Note:: |Because lwork is 0, SGETRI dynamically allocates the work |area used by this subroutine. |

|Call Statement and Input

|             N   A  LDA  IPVT   WORK  LWORK  INFO
|             |   |   |    |      |      |     |
|CALL SGETRI( 9 , A , 9 , IPVT , WORK ,  0  , INFO )
|

|A = (same as output A in Example 3)
|IPVT = (same as output IPVT in Example 3)

|Output:

|        *                                                                      *
|        |    0.333   -0.667   0.333  0.000  0.000  0.000   0.042 -0.042  0.000 |
|        |   56.833  -52.167  -1.167 -0.500 -0.500 -0.357   6.836 -0.479 -0.500 |
|        |  -55.167   51.833   0.833  0.500  0.500  0.214  -6.735  0.521  0.500 |
|        |   -1.000    1.000   0.000  0.000  0.000  0.143  -0.143  0.000  0.000 |
|A    =  |   -1.000    1.000   0.000  0.000  0.000  0.000   0.000  0.000  0.000 |
|        |   -1.000    1.000   0.000  0.000  0.000  0.000  -0.125  0.125  0.000 |
|        | -226.000  206.000   5.000  3.000  2.000  1.429 -27.179  1.750  2.000 |
|        |  560.000 -520.000 -10.000 -6.000 -4.000 -2.857  67.857 -5.000 -5.000 |
|        | -325.000  305.000   5.000  3.000  2.000  1.429 -39.554  3.125  3.000 |
|        *                                                                      *

|INFO =       0

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