IBM Books

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

STRMM, DTRMM, CTRMM, and ZTRMM--Triangular Matrix-Matrix Product

STRMM and DTRMM compute one of the following matrix-matrix products, using the scalar alpha, rectangular matrix B, and triangular matrix A or its transpose:

1. B<--alphaAB 3. B<--alphaBA
2. B<--alphaATB 4. B<--alphaBAT

CTRMM and ZTRMM compute one of the following matrix-matrix products, using the scalar alpha, rectangular matrix B, and triangular matrix A, its transpose, or its conjugate transpose:

1. B<--alphaAB 3. B<--alphaBA 5. B<--alphaAHB
2. B<--alphaATB 4. B<--alphaBAT 6. B<--alphaBAH

Table 78. Data Types

A, B, alpha Subroutine
Short-precision real STRMM
Long-precision real DTRMM
Short-precision complex CTRMM
Long-precision complex ZTRMM

Syntax

Fortran CALL STRMM | DTRMM | CTRMM | ZTRMM (side, uplo, transa, diag, m, n, alpha, a, lda, b, ldb)
C and C++ strmm | dtrmm | ctrmm | ztrmm (side, uplo, transa, diag, m, n, alpha, a, lda, b, ldb);
PL/I CALL STRMM | DTRMM | CTRMM | ZTRMM (side, uplo, transa, diag, m, n, alpha, a, lda, b, ldb);

On Entry

side
indicates whether the triangular matrix A is located to the left or right of rectangular matrix B in the equation used for this computation, where:

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

If side = 'R', A is to the right of B in the equation, resulting in either equation 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 to use in the computation, where:

If transa = 'N', A is used in the computation, resulting in either equation 1 or 3.

If transa = 'T', AT is used in the computation, resulting in either equation 2 or 4.

If transa = 'C', AH is used in the computation, resulting in either equation 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 78.

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.

Note:
No data should be moved to form AT or AH; that is, the matrix A should always be stored in its untransposed form.

Specified as: a two-dimensional array, containing numbers of the data type indicated in Table 78, 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. Specified as: an ldb by (at least) n array, containing numbers of the data type indicated in Table 78.

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

Notes
  1. These subroutines accept lowercase letters for the side, uplo, transa, and diag arguments.
  2. For STRMM and DTRMM, 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; 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 triangular 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, see Triangular Matrix.

Function

These subroutines can perform the following matrix-matrix product computations, using the triangular matrix A, its transpose, or its conjugate transpose, where A can be either upper- or lower-triangular:

  1. B<--alphaAB
  2. B<--alphaATB
  3. B<--alphaAHB (for CTRMM and ZTRMM only)

    where:

    alpha is a scalar.
    A is a triangular matrix of order m.
    B is an m by n rectangular matrix.
  4. B<--alphaBA
  5. B<--alphaBAT
  6. B<--alphaBAH (for CTRMM and ZTRMM only)

    where:

    alpha is a scalar.
    A is a triangular matrix of order n.
    B is an m by n rectangular matrix.

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

Error Conditions

Resource Errors

Unable to allocate internal work area.

Computational Errors

None

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 computation B<--alphaAB, where A is a 5 by 5 upper triangular matrix that is not unit triangular, and B is a 5 by 3 rectangular matrix.

Call Statement and Input
            SIDE  UPLO TRANSA  DIAG  M   N   ALPHA   A  LDA  B  LDB
             |     |     |      |    |   |     |     |   |   |   |
CALL STRMM( '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 |
        |  .     .     .     .     .  |
        |  .     .     .     .     .  |
        *                             *

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

Output
        *                    *
        |   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 |
        |    .     .      .  |
        *                    *

Example 2

This example shows the computation B<--alphaATB, where A is a 5 by 5 upper triangular matrix that is not unit triangular, and B is a 5 by 4 rectangular matrix.

Call Statement and Input
            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA  A  LDA  B  LDB
             |     |     |      |    |   |     |     |   |   |   |
CALL STRMM( '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 |
        |  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 |
        |   .     .     .     .  |
        *                        *

Output
        *                          *
        | -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 |
        |   .     .      .      .  |
        *                          *

Example 3

This example shows the computation B<--alphaBA, where A is a 5 by 5 lower triangular matrix that is not unit triangular, and B is a 3 by 5 rectangular matrix.

Call Statement and Input
            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA  A  LDA  B  LDB
             |     |     |      |    |   |     |     |   |   |   |
CALL STRMM( '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 |
        |  .    .     .     .     .  |
        |  .    .     .     .     .  |
        *                            *

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

Output
        *                             *
        | 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 |
        |   .     .     .    .     .  |
        *                             *

Example 4

This example shows the computation B<--alphaBA, where A is a 6 by 6 upper triangular matrix that is unit triangular, and B is a 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 elements.

Call Statement and Input
            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA  A  LDA  B  LDB
             |     |     |      |    |   |     |     |   |   |   |
CALL STRMM( '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  2.0  1.0  3.0  -1.0  -2.0 |
        |  .    .    .    .     .     .  |
        *                                *

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

Example 5

This example shows the computation B<--alphaAHB, where A is a 5 by 5 upper triangular matrix that is not unit triangular, and B is a 5 by 1 rectangular matrix.

Call Statement and Input
            SIDE  UPLO TRANSA  DIAG  M   N    ALPHA   A  LDA  B  LDB
             |     |     |      |    |   |      |     |   |   |   |
CALL CTRMM( '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) |
        |      .           .             .            .             .       |
        *                                                                   *

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

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

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