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

STRSV, DTRSV, CTRSV, ZTRSV, STPSV, DTPSV, CTPSV, and ZTPSV--Solution of a Triangular System of Equations with a Single Right-Hand Side

STRSV, DTRSV, STPSV, and DTPSV perform one of the following solves for a triangular system of equations with a single right-hand side, using the vector x and triangular matrix A or its transpose:

CTRSV, ZTRSV, CTPSV, and ZTPSV perform one of the following solves for a triangular system of equations with a single right-hand side, using the vector x and and triangular matrix A, its transpose, or its conjugate transpose:

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

• For the _TRSV subroutines, it is stored in upper- or lower-triangular storage mode, respectively.
• For the _TPSV subroutines, it is stored in upper- or lower-triangular-packed storage mode, respectively.

Note:

The term b used in the systems of equations listed above represents the right-hand side of the system. It is important to note that in these subroutines the right-hand side of the equation is actually provided in the input-output argument x.

Table 102. Data Types

Syntax

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

transa

indicates the form of matrix A used in the system of equations, where:

If transa = 'N', A is used, resulting in solution 1.

If transa = 'T', A^T is used, resulting in solution 2.

If transa = 'C', A^H is used, resulting in solution 3.

Specified as: a single character. It must be 'N', 'T', or 'C'.

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

n

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

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

lda

is the leading dimension of the array 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 102.

x

is the vector x of length n, containing the right-hand side of the triangular system to be solved. Specified as: a one-dimensional array of (at least) length 1+(n-1)|incx|, containing numbers of the data type indicated in Table 102.

incx

is the stride for vector x. Specified as: a fullword integer; incx > 0 or incx < 0.

On Return

x

is the solution vector x of length n, containing the results of the computation. Returned as: a one-dimensional array, containing numbers of the data type indicated in Table 102.

Notes

1. These subroutines accept lowercase letters for the uplo, transa, and diag arguments.
2. For STRSV, DTRSV, STPSV, and DTPSV, if you specify 'C' for the transa argument, it is interpreted as though you specified 'T'.
3. Matrix A and vector x must have no common elements; otherwise, results are unpredictable.
4. ESSL assumes certain values in your array for parts of a triangular matrix. As a result, you do not have to set these values. For unit diagonal matrices, the elements of the diagonal are assumed to be 1.0 for real matrices and (1.0, 0.0) for complex matrices. When using upper- or lower-triangular storage, the unreferenced elements in the lower and upper triangular part, respectively, are assumed to be zero.
5. 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 solve a triangular system of equations with a single right-hand side. The solution x may be any of the following, where triangular matrix A, its transpose, or its conjugate transpose is used, and where A can be either upper- or lower-triangular:

1. x<--A^-1x
2. x<--A^-Tx
3. x<--A^-Hx (only for CTRSV, ZTRSV, CTPSV, and ZTPSV)

where:

x is a vector of length n.

A is an upper or lower triangular matrix of order n. For _TRSV, it is stored in upper- or lower-triangular storage mode, respectively. For _TPSV, it is stored in upper- or lower-triangular-packed storage mode, respectively.

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

Error Conditions

Computational Errors

None

Input-Argument Errors

1. uplo <> 'L' or 'U'
2. transa <> 'T', 'N', or 'C'
3. diag <> 'N' or 'U'
4. n < 0
5. lda <= 0
6. lda < n
7. incx = 0

Example 1

This example shows the solution x<--A^-1x. Matrix A is a real 4 by 4 lower unit triangular matrix, stored in lower-triangular storage mode. Vector x is a vector of length 4.

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 TRANSA DIAG  N   A  LDA  X  INCX
             |     |     |    |   |   |   |   |
CALL STRSV( 'L' , 'N' , 'U' , 4 , A , 4 , X , 1  )
 
        *                  *
        |  .    .    .   . |
        | 1.0   .    .   . |
A    =  | 2.0  3.0   .   . |
        | 3.0  4.0  3.0  . |
        *                  *
 
X        =  (1.0, 3.0, 11.0, 24.0)

Output

X        =  (1.0, 2.0, 3.0, 4.0)

Example 2

This example shows the solution x<--A^-Tx. Matrix A is a real 4 by 4 upper nonunit triangular matrix, stored in upper-triangular storage mode. Vector x is a vector of length 4.

Call Statement and Input

            UPLO TRANSA DIAG  N   A  LDA  X  INCX
             |     |     |    |   |   |   |   |
CALL STRSV( 'U' , 'T' , 'N' , 4 , A , 4 , X , 1  )
 
        *                    *
        | 1.0  2.0  3.0  2.0 |
A    =  |  .   2.0  2.0  5.0 |
        |  .    .   3.0  3.0 |
        |  .    .    .   1.0 |
        *                    *
 
X        =  (5.0, 18.0, 32.0, 41.0)

Output

X        =  (5.0, 4.0, 3.0, 2.0)

Example 3

This example shows the solution x<--A^-Hx. Matrix A is a complex 4 by 4 upper unit triangular matrix, stored in upper-triangular storage mode. Vector x is a vector of length 4.

Note:

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

Call Statement and Input

            UPLO TRANSA DIAG  N   A  LDA  X  INCX
             |     |     |    |   |   |   |   |
CALL CTRSV( 'U' , 'C' , 'U' , 4 , A , 4 , X , 1  )
 
        *                                     *
        | . (2.0, 2.0) (3.0,  3.0) (2.0, 2.0) |
A    =  | .     .      (2.0,  2.0) (5.0, 5.0) |
        | .     .          .       (3.0, 3.0) |
        | .     .          .           .      |
        *                                     *
 
X        =  ((5.0, 5.0), (24.0, 4.0), (49.0, 3.0), (80.0, 2.0))

Output

X        =  ((5.0, 5.0), (4.0, 4.0), (3.0, 3.0), (2.0, 2.0))

Example 4

This example shows the solution x<--A^-1x. Matrix A is a real 4 by 4 lower unit triangular matrix, stored in lower-triangular-packed storage mode. Vector x is a vector of length 4. Matrix A is:

                          *                    *
                          | 1.0   .    .    .  |
                          | 1.0  1.0   .    .  |
                          | 2.0  3.0  1.0   .  |
                          | 3.0  4.0  3.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 TRANSA DIAG  N   AP   X  INCX
             |     |     |    |   |    |   |
CALL STPSV( 'L' , 'N' , 'U' , 4 , AP , X , 1  )
 
AP       =  ( . , 1.0, 2.0, 3.0, . , 3.0, 4.0, . , 3.0, . )
X        =  (1.0, 3.0, 11.0, 24.0)

Output

X        =  (1.0, 2.0, 3.0, 4.0)

Example 5

This example shows the solution x<--A^-Tx. Matrix A is a real 4 by 4 upper nonunit triangular matrix, stored in upper-triangular-packed storage mode. Vector x is a vector of length 4. Matrix A is:

                         *                    *
                         | 1.0  2.0  3.0  2.0 |
                         |  .   2.0  2.0  5.0 |
                         |  .    .   3.0  3.0 |
                         |  .    .    .   1.0 |
                         *                    *

Call Statement and Input

            UPLO TRANSA DIAG  N   AP   X  INCX
             |     |     |    |   |    |   |
CALL STPSV( 'U' , 'T' , 'N' , 4 , AP , X , 1  )
 
AP       =  (1.0, 2.0, 2.0, 3.0, 2.0, 3.0, 2.0, 5.0, 3.0, 1.0)
X        =  (5.0, 18.0, 32.0, 41.0)

Output

X        =  (5.0, 4.0, 3.0, 2.0)

Example 6

This example shows the solution x<--A^-Hx. Matrix A is a complex 4 by 4 upper unit triangular matrix, stored in upper-triangular-packed storage mode. Vector x is a vector of length 4. Matrix A is:

                *                                                *
                | (1.0, 0.0)  (2.0, 2.0)  (3.0, 3.0)  (2.0, 2.0) |
                |     .       (1.0, 0.0)  (2.0, 2.0)  (5.0, 5.0) |
                |     .           .       (1.0, 0.0)  (3.0, 3.0) |
                |     .           .           .       (1.0, 0.0) |
                *                                                *

Note:

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

Call Statement and Input

            UPLO TRANSA DIAG  N   AP   X  INCX
             |     |     |    |   |    |   |
CALL CTPSV( 'U' , 'C' , 'U' , 4 , AP , X , 1  )
 
AP       =  ( . , (2.0, 2.0), . , (3.0, 3.0), (2.0, 2.0), . ,
             (2.0, 2.0), (5.0, 5.0), (3.0, 3.0), . )
X        =  ((5.0, 5.0), (24.0, 4.0), (49.0, 3.0), (80.0, 2.0))

Output

X        =  ((5.0, 5.0), (4.0, 4.0), (3.0, 3.0), (2.0, 2.0))