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

STRSM, DTRSM, CTRSM, and ZTRSM--Solution of Triangular Systems of Equations with Multiple Right-Hand Sides

STRSM and DTRSM perform one of the following solves for a triangular system of equations with multiple right-hand sides, using scalar alpha, rectangular matrix B, and triangular matrix A or its transpose:

CTRSM and ZTRSM perform one of the following solves for a triangular system of equations with multiple right-hand sides, using scalar alpha, rectangular matrix B, and triangular matrix A, its transpose, or its conjugate transpose:

Note:

The term X used in the systems of equations listed above represents the output solution matrix. It is important to note that in these subroutines the solution matrix is actually returned in the input-output argument b.

Table 103. Data Types

Syntax

On Entry

side

indicates whether the triangular matrix A is located to the left or right of rectangular matrix B in the system of equations, where:

If side = 'L', A is to the left of B, resulting in solution 1, 2, or 5.

If side = 'R', A is to the right of B, resulting in solution 3, 4, or 6.

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

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 or 3.

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

If transa = 'C', A^H is used, resulting in solution 5 or 6.

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

m

is the number of rows in rectangular matrix B, and:

If side = 'L', m is the order of triangular matrix A.

Specified as: a fullword integer, where:

If side = 'L', 0 <= m <= lda and m <= ldb.

If side = 'R', 0 <= m <= ldb.

n

is the number of columns in rectangular matrix B, and:

If side = 'R', n is the order of triangular matrix A.

Specified as: a fullword integer; n >= 0, and:

If side = 'R', n <= lda.

alpha

is the scalar alpha. Specified as: a number of the data type indicated in Table 103.

a

is the triangular matrix A, of which only the upper or lower triangular portion is used, where:

If side = 'L', A is order m.

If side = 'R', A is order n.

Specified as: a two-dimensional array, containing numbers of the data type indicated in Table 103, where:

If side = 'L', its size must be lda by (at least) m.

If side = 'R', it size must be lda by (at least) n.

lda

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

If side = 'L', lda >= m.

If side = 'R', lda >= n.

b

is the m by n rectangular matrix B, which contains the right-hand sides of the triangular system to be solved. Specified as: an ldb by (at least) n array, containing numbers of the data type indicated in Table 103.

ldb

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

On Return

b

is the m by n matrix B, containing the results of the computation.

Returned as: an ldb by (at least) n array, containing numbers of the data type indicated in Table 103.

Notes

1. These subroutines accept lowercase letters for the transa, side, diag, and uplo arguments.
2. For STRSM and DTRSM, if you specify 'C' for the transa argument, it is interpreted as though you specified 'T'.
3. Matrices A and B must have no common elements or results are unpredictable.
4. 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.
5. The elements of the diagonal of a unit triangular matrix are always one, so you do not need to set these values. The ESSL subroutines always assume that the values in these positions are 1.0 for STRSM and DTRSM and (1.0, 0.0) for CTRSM and ZTRSM.
6. For a description of triangular matrices and how they are stored, see Triangular Matrix.

Function

These subroutines solve a triangular system of equations with multiple right-hand sides. The solution B may be any of the following, where A is a triangular matrix and B is a rectangular matrix:

1. B<--alpha(A^-1)B

2. B<--alpha(A^-T)B

3. B<--alphaB(A^-1)

4. B<--alphaB(A^-T)

5. B<--alpha(A^-H)B (only for CTRSM and ZTRSM)

6. B<--alphaB(A^-H) (only for CTRSM and ZTRSM)

where:

alpha is a scalar.

B is an m by n rectangular matrix.

A is an upper or lower triangular matrix, where:

If side = 'L', it has order m, and equation 1, 2, or 5 is performed.

If side = 'R', it has order n, and equation 3, 4, or 6 is performed.

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

Error Conditions

Resource Errors

Unable to allocate internal work area.

Computational Errors

None

Note:

If the triangular matrix A is singular, the results returned by this subroutine are unpredictable, and there may be a divide-by-zero program exception message.

Input-Argument Errors

1. m < 0
2. n < 0
3. lda, ldb <= 0
4. side <> 'L' or 'R'
5. uplo <> 'L' or 'U'
6. transa <> 'T', 'N', or 'C'
7. diag <> 'N' or 'U'
8. side = 'L' and m > lda
9. m > ldb
10. side = 'R' and n > lda

Example 1

This example shows the solution B<--alpha(A^-1)B, where A is a real 5 by 5 upper triangular matrix that is not unit triangular, and B is a real 5 by 3 rectangular matrix.

Call Statement and Input

            SIDE  UPLO TRANSA  DIAG  M   N   ALPHA   A  LDA  B  LDB
             |     |     |      |    |   |     |     |   |   |   |
CALL STRSM( 'L' , 'U' , 'N'  , 'N' , 5 , 3 ,  1.0  , A , 7 , B , 6 )

        *                             *
        | 3.0  -1.0   2.0   2.0   1.0 |
        |  .   -2.0   4.0  -1.0   3.0 |
        |  .     .   -3.0   0.0   2.0 |
A    =  |  .     .     .    4.0  -2.0 |
        |  .     .     .     .    1.0 |
        |  .     .     .     .     .  |
        |  .     .     .     .     .  |
        *                             *

        *                    *
        |   6.0  10.0   -2.0 |
        | -16.0  -1.0    6.0 |
B    =  |  -2.0   1.0   -4.0 |
        |  14.0   0.0  -14.0 |
        |  -1.0   2.0    1.0 |
        |    .     .      .  |
        *                    *

Output

        *                 *
        |  2.0  3.0   1.0 |
        |  5.0  5.0   4.0 |
B    =  |  0.0  1.0   2.0 |
        |  3.0  1.0  -3.0 |
        | -1.0  2.0   1.0 |
        |   .    .     .  |
        *                 *

Example 2

This example shows the solution B<--alpha(A^-T)B, where A is a real 5 by 5 upper triangular matrix that is not unit triangular, and B is a real 5 by 4 rectangular matrix.

Call Statement and Input

            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA  A  LDA  B  LDB
             |     |     |      |    |   |     |     |   |   |   |
CALL STRSM( 'L' , 'U' , 'T'  , 'N' , 5 , 4 ,  1.0  , A , 7 , B , 6 )

        *                              *
        | -1.0  -4.0  -2.0   2.0   3.0 |
        |   .   -2.0   2.0   2.0   2.0 |
        |   .     .   -3.0  -1.0   4.0 |
A    =  |   .     .     .    1.0   0.0 |
        |   .     .     .     .   -2.0 |
        |   .     .     .     .     .  |
        |   .     .     .     .     .  |
        *                              *

        *                          *
        | -1.0  -2.0   -3.0   -4.0 |
        |  2.0  -2.0  -14.0  -12.0 |
B    =  | 10.0   5.0   -8.0   -7.0 |
        | 14.0  15.0    1.0    8.0 |
        | -3.0   4.0    3.0   16.0 |
        |   .     .      .      .  |
        *                          *

Output

        *                        *
        |  1.0   2.0   3.0   4.0 |
        |  3.0   3.0  -1.0   2.0 |
B    =  | -2.0  -1.0   0.0   1.0 |
        |  4.0   4.0  -3.0  -3.0 |
        |  2.0   2.0   2.0   2.0 |
        |   .     .     .     .  |
        *                        *

Example 3

This example shows the solution B<--alphaB(A^-1), where A is a real 5 by 5 lower triangular matrix that is not unit triangular, and B is a real 3 by 5 rectangular matrix.

Call Statement and Input

            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA  A  LDA  B  LDB
             |     |     |      |    |   |     |     |   |   |   |
CALL STRSM( 'R' , 'L' , 'N'  , 'N' , 3 , 5 ,  1.0  , A , 7 , B , 4 )

        *                            *
        | 2.0   .     .     .     .  |
        | 2.0  3.0    .     .     .  |
        | 2.0  1.0   1.0    .     .  |
A    =  | 0.0  3.0   0.0  -2.0    .  |
        | 2.0  4.0  -1.0   2.0  -1.0 |
        |  .    .     .     .     .  |
        |  .    .     .     .     .  |
        *                            *

        *                             *
        | 10.0   4.0   0.0  0.0   1.0 |
B    =  | 10.0  14.0  -4.0  6.0  -3.0 |
        | -8.0   2.0  -5.0  4.0  -2.0 |
        |   .     .     .    .     .  |
        *                             *

Output

        *                              *
        |  3.0   4.0  -1.0  -1.0  -1.0 |
B    =  |  2.0   1.0  -1.0   0.0   3.0 |
        | -2.0  -1.0  -3.0   0.0   2.0 |
        |   .     .     .     .     .  |
        *                              *

Example 4

This example shows the solution B<--alphaB(A^-1), where A is a real 6 by 6 upper triangular matrix that is unit triangular, and B is a real 1 by 6 rectangular matrix.

Note:

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

Call Statement and Input

            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA  A  LDA  B  LDB
             |     |     |      |    |   |     |     |   |   |   |
CALL STRSM( 'R' , 'U' , 'N'  , 'U' , 1 , 6 ,  1.0  , A , 7 , B , 2 )

        *                               *
        | .  2.0  -3.0  1.0   2.0   4.0 |
        | .   .    0.0  1.0   1.0  -2.0 |
        | .   .     .   4.0  -1.0   1.0 |
A    =  | .   .     .    .    0.0  -1.0 |
        | .   .     .    .     .    2.0 |
        | .   .     .    .     .     .  |
        | .   .     .    .     .     .  |
        *                               *

        *                                 *
B    =  | 1.0  4.0  -2.0  10.0  2.0  -6.0 |
        |  .    .     .     .    .     .  |
        *                                 *

Output

        *                                *
B    =  | 1.0  2.0  1.0  3.0  -1.0  -2.0 |
        |  .    .    .    .     .     .  |
        *                                *

Example 5

This example shows the solution B<--alphaB(A^-1), where A is a complex 5 by 5 lower triangular matrix that is not unit triangular, and B is a complex 3 by 5 rectangular matrix.

Call Statement and Input

            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA   A  LDA  B  LDB
             |     |     |      |    |   |      |     |   |   |   |
CALL CTRSM( 'R' , 'L' , 'N'  , 'N' , 3 , 5 ,  ALPHA , A , 7 , B , 4 )
 
ALPHA    =  (1.0, 0.0)

        *                                                                *
        | (2.0, -3.0)     .            .            .            .       |
        | (2.0, -4.0) (3.0, -1.0)      .            .            .       |
        | (2.0,  2.0) (1.0,  2.0)  (1.0,  1.0)      .            .       |
A    =  | (0.0,  0.0) (3.0, -1.0)  (0.0, -1.0) (-2.0,  1.0)      .       |
        | (2.0,  2.0) (4.0,  0.0) (-1.0,  2.0)  (2.0, -4.0) (-1.0, -4.0) |
        |     .           .            .            .            .       |
        |     .           .            .            .            .       |
        *                                                                *

        *                                                                      *
        | (22.0, -41.0)  (7.0, -26.0)  (9.0, 0.0)  (-15.0, -3.0)  (-15.0, 8.0) |
B    =  | (29.0, -18.0) (24.0, -10.0)  (9.0, 6.0) (-12.0, -24.0) (-19.0, -8.0) |
        |  (-15.0, 2.0) (-3.0, -21.0) (-2.0, 4.0)  (-4.0, -12.0) (-10.0, -6.0) |
        |        .           .             .            .            .         |
        *                                                                      *

Output

        *                                                                 *
        |  (3.0, 0.0)   (4.0, 0.0) (-1.0, -2.0) (-1.0, -1.0) (-1.0, -4.0) |
B    =  | (2.0, -1.0)   (1.0, 2.0) (-1.0, -3.0)   (0.0, 2.0)  (3.0, -4.0) |
        | (-2.0, 1.0) (-1.0, -3.0)  (-3.0, 1.0)   (0.0, 0.0)  (2.0, -2.0) |
        |     .            .            .             .             .     |
        *                                                                 *

Example 6

This example shows the solution B<--alpha(A^-H)B, where A is a complex 5 by 5 upper triangular matrix that is not unit triangular, and B is a complex 5 by 1 rectangular matrix.

Call Statement and Input

            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA   A  LDA  B  LDB
             |     |     |      |    |   |      |     |   |   |   |
CALL CTRSM( 'L' , 'U' , 'C'  , 'N' , 5 , 1 ,  ALPHA , A , 6 , B , 6 )
 
ALPHA    =  (1.0, 0.0)

        *                                                                *
        | (-4.0, 1.0) (4.0, -3.0)  (-1.0, 3.0)   (0.0, 0.0)  (-1.0, 0.0) |
        |      .      (-2.0, 0.0) (-3.0, -1.0) (-2.0, -1.0)   (4.0, 3.0) |
A    =  |      .           .       (-5.0, 3.0) (-3.0, -3.0) (-5.0, -5.0) |
        |      .           .            .       (4.0, -4.0)   (2.0, 0.0) |
        |      .           .            .           .        (2.0, -1.0) |
        |      .           .            .           .             .      |
        *                                                                *

        *               *
        | (-8.0, -19.0) |
        |  (8.0,  21.0) |
B    =  | (44.0,  -8.0) |
        | (13.0,  -7.0) |
        | (19.0,   2.0) |
        |      .        |
        *               *

Output

        *             *
        |  (3.0, 4.0) |
        | (-4.0, 2.0) |
B    =  | (-5.0, 0.0) |
        |  (1.0, 3.0) |
        |  (3.0, 1.0) |
        |      .      |
        *             *