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

STRI, DTRI, STPI, DTPI, STRTRI, DTRTRI, STPTRI, and DTPTRI--Triangular Matrix Inverse

These subroutines find the inverse of triangular matrix A:

A<--A^-1

Matrix A can be either upper or lower triangular, where:

|For STRI/STRTRI and DTRI/DTRTRI, it is stored in upper- or |lower-triangular storage |mode.
|For STPI/STPTRI and DTPI/DTPTRI, it is stored in upper- or |lower-triangular-packed storage |mode.

A	Subroutine
Short-precision real	STRI, STPI, STRTRI, and STPTRI
Long-precision real	DTRI, DTPI, DTRTRI, and DTPTRI

Syntax

Fortran

CALL STRI | DTRI (uplo, diag, a, lda, n)

CALL STPI | DTPI (uplo, diag, ap, n)

CALL STRTRI | DTRTRI (uplo, diag, n, a, lda, info)

CALL STPTRI | DTPTRI (uplo, diag, n, ap, info)

C and C++

stri | dtri (uplo, diag, a, lda, n);

stpi | dtpi (uplo, diag, ap, n);

strtri | dtrtri (uplo, diag, n, a, lda, info);

stptri | dtptri (uplo, diag, n, ap, info);

PL/I

CALL STRI | DTRI (uplo, diag, a, lda, n);

CALL STPI | DTPI (uplo, diag, ap, n);

CALL STRTRI | DTRTRI (uplo, diag, n, a, lda, info);

CALL STPTRI | DTPTRI (uplo, diag, n, ap, info);

On Entry

uplo

indicates whether matrix A is an upper or lower triangular matrix, where:

If uplo = 'U', A is an upper triangular matrix.

If uplo = 'L', A is a lower triangular matrix.

Specified as: a single character. It must be 'U' or 'L'.

diag

indicates the characteristics of the diagonal of matrix A, where:

If diag = 'U', A is a unit triangular matrix.

If diag = 'N', A is not a unit triangular matrix.

Specified as: a single character. It must be 'U' or 'N'.

a

is the upper or lower triangular matrix A of order n, stored in upper- or lower-triangular storage mode, respectively. Specified as: an lda by (at least) n array, containing numbers of the data type indicated in Table 104.

lda

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

ap

is the upper or lower triangular matrix A of order n, stored in upper- or lower-triangular-packed storage mode, respectively. Specified as: a one-dimensional array of (at least) length n(n+1)/2, containing numbers of the data type indicated in Table 104.

n

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

|info

|See On Return.

On Return

a

is the inverse of the upper or lower triangular matrix A of order n, stored in upper- or lower-triangular storage mode, respectively. Returned as: an lda by (at least) n array, containing numbers of the data type indicated in Table 104.

ap

is the inverse of the upper or lower triangular matrix A of order n, stored in upper- or lower-triangular-packed storage mode, respectively. Returned as: a one-dimensional array of (at least) length n(n+1)/2, containing numbers of the data type indicated in Table 104.

|info

|has the following meaning:

|If info = 0, the inverse completed successfully.

|If info > 0, info is set equal to the first |i, where |A_ii is zero. Matrix A is singular and |its inverse could not be computed.

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

Notes

|In C programs, the argument info must be passed by |reference.
These subroutines accept lowercase letters for the uplo and diag arguments.
If matrix A is upper triangular (uplo = 'U'), these subroutines refer to only the upper triangular portion of the matrix. If matrix A is lower triangular, (uplo = 'L'), these subroutines refer to only the lower triangular portion of the matrix. The unreferenced elements are assumed to be zero.
The elements of the diagonal of a unit triangular matrix are always one, so you do not need to set these values.
|The way _TRTRI and _TPTRI 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 a description of triangular matrices and how they are stored in upper- and lower-triangular storage mode and in upper- and lower-triangular-packed storage mode, see Triangular Matrix.

Function

These subroutines find the inverse of triangular matrix A, where A is either upper or lower triangular:

A<--A^-1

where:

A is the triangular matrix of order n.

A^-1 the inverse of the triangular matrix of order n.

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

Error Conditions

Resource Errors

Unable to allocate internal work area.

Computational Errors

Matrix A is singular.

For STRI/STPI and DTRI/DTPI

One or more of the diagonal elements of matrix A are zero. The first column, i, of matrix A, in which a zero diagonal element is found, 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 2145 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?.

|For STRTRI/STPTRI and DTRTRI/DTPTRI:

|One or more of the diagonal elements of matrix A are |zero. The first column, i, of matrix A, in which a |zero diagonal element is found, is identified in the computational error |message and returned in the argument info.
|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 2146 is set to be unlimited in the ESSL error |option table. |

Input-Argument Errors

uplo <> 'U' or 'L'
diag <> 'U' or 'N'
n < 0
lda <= 0
lda < n

Example 1

This example shows how the inverse of matrix A is computed, where A is a 5 by 5 upper triangular matrix that is not unit triangular and is stored in upper-triangular storage mode. Matrix A is:

                    *                                *
                    | 1.00  3.00  4.00   5.00   6.00 |
                    | 0.00  2.00  8.00   9.00   1.00 |
                    | 0.00  0.00  4.00   8.00   4.00 |
                    | 0.00  0.00  0.00  -2.00   6.00 |
                    | 0.00  0.00  0.00   0.00  -1.00 |
                    *                                *

and where the following inverse matrix is computed. Matrix A^-1 is:

                  *                                   *
                  | 1.00  -1.50   2.00   3.75   35.00 |
                  | 0.00   0.50  -1.00  -1.75  -14.00 |
                  | 0.00   0.00   0.25   1.00    7.00 |
                  | 0.00   0.00   0.00  -0.50   -3.00 |
                  | 0.00   0.00   0.00   0.00   -1.00 |
                  *                                   *

Call Statement and Input

           UPLO  DIAG  A  LDA  N
            |     |    |   |   |
CALL STRI( 'U' , 'N' , A , 5 , 5)

|or

|             UPLO  DIAG  N   A  LDA  INFO 
|              |     |    |   |   |    |
|CALL STRTRI( 'U' , 'N' , 5 , A,  5,  INFO )

        *                                *
        | 1.00  3.00  4.00   5.00   6.00 |
        |  .    2.00  8.00   9.00   1.00 |
A    =  |  .     .    4.00   8.00   4.00 |
        |  .     .     .    -2.00   6.00 |
        |  .     .     .      .    -1.00 |
        *                                *

Output

        *                                   *
        | 1.00  -1.50   2.00   3.75   35.00 |
        |  .     0.50  -1.00  -1.75  -14.00 |
A    =  |  .      .     0.25   1.00    7.00 |
        |  .      .      .    -0.50   -3.00 |
        |  .      .      .      .     -1.00 |
        *                                   *

|INFO =    0

Example 2

This example shows how the inverse of matrix A is computed, where A is a 5 by 5 lower triangular matrix that is unit triangular and is stored in lower-triangular storage mode. Matrix A is:

                       *                         *
                       | 1.0  0.0  0.0  0.0  0.0 |
                       | 3.0  1.0  0.0  0.0  0.0 |
                       | 4.0  8.0  1.0  0.0  0.0 |
                       | 5.0  9.0  8.0  1.0  0.0 |
                       | 6.0  1.0  4.0  6.0  1.0 |
                       *                         *

and where the following inverse matrix is computed. Matrix A^-1 is:

                   *                                 *
                   |    1.0     0.0   0.0   0.0  0.0 |
                   |   -3.0     1.0   0.0   0.0  0.0 |
                   |   20.0    -8.0   1.0   0.0  0.0 |
                   | -138.0    55.0  -8.0   1.0  0.0 |
                   |  745.0  -299.0  44.0  -6.0  1.0 |
                   *                                 *

Note:: Because matrix A is unit triangular, the diagonal elements are not referenced. ESSL assumes a value of 1.0 for the diagonal elements.

Call Statement and Input

           UPLO  DIAG  A  LDA  N
            |     |    |   |   |
CALL STRI( 'L' , 'U' , A , 5 , 5)

|or

|             UPLO  DIAG  N   A  LDA  INFO 
|              |     |    |   |   |    |
|CALL STRTRI( 'L' , 'U' , 5 , A,  5,  INFO )

        *                       *
        |  .    .    .    .   . |
        | 3.0   .    .    .   . |
A    =  | 4.0  8.0   .    .   . |
        | 5.0  9.0  8.0   .   . |
        | 6.0  1.0  4.0  6.0  . |
        *                       *

Output

        *                               *
        |     .       .     .     .   . |
        |   -3.0      .     .     .   . |
A    =  |   20.0    -8.0    .     .   . |
        | -138.0    55.0  -8.0    .   . |
        |  745.0  -299.0  44.0  -6.0  . |
        *                               *

|INFO =    0

Example 3

This example shows how the inverse of matrix A is computed, where A is the same matrix shown in Example 1 and is stored in upper-triangular-packed storage mode. The inverse matrix computed here is the same as the inverse matrix shown in Example 1 and is stored in upper-triangular-packed storage mode.

Call Statement and Input

           UPLO  DIAG  AP   N
            |     |    |    |
CALL STPI( 'U' , 'N' , AP , 5)

|or

|             UPLO  DIAG  N   A   INFO 
|              |     |    |   |    |
|CALL STPTRI( 'U' , 'N' , 5 , AP, INFO )

AP   =  (1.00, 3.00, 2.00, 4.00, 8.00, 4.00, 5.00, 9.00, 8.00,
         -2.00, 6.00, 1.00, 4.00, 6.00, -1.00)

Output

AP   =  (1.00, -1.50, 0.50, 2.00, -1.00, 0.25, 3.75, -1.75, 1.00,
         -0.50, 35.00, -14.00, 7.00, -3.00, -1.00)

|INFO =   0

Example 4

This example shows how the inverse of matrix A is computed, where A is the same matrix shown in Example 2 and is stored in lower-triangular-packed storage mode. The inverse matrix computed here is the same as the inverse matrix shown in Example 2 and is stored in lower-triangular-packed storage mode.

Note:: Because matrix A is unit triangular, the diagonal elements are not referenced. ESSL assumes a value of 1.0 for the diagonal elements.

Call Statement and Input

           UPLO  DIAG  AP   N
            |     |    |    |
CALL STPI( 'L' , 'U' , AP , 5)

|or

|             UPLO  DIAG  N   A   INFO 
|              |     |    |   |    |
|CALL STPTRI( 'L' , 'U' , N , AP, INFO )

AP   =  ( . , 3.0, 4.0, 5.0, 6.0, . , 8.0, 9.0, 1.0, . , 8.0, 4.0,
         . , 6.0, . )

Output

AP   =  ( . , -3.0, 20.0, -138.0, 745.0, . , -8.0, 55.0, -299.0,
          . , -8.0, 44.0, . , -6.0, . )

INFO = 0

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