IBM Books

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

SSYMM, DSYMM, CSYMM, ZSYMM, CHEMM, and ZHEMM--Matrix-Matrix Product Where One Matrix is Real or Complex Symmetric or Complex Hermitian

These subroutines compute one of the following matrix-matrix products, using the scalars alpha and beta and matrices A, B, and C:

1. C<--alphaAB+betaC
2. C<--alphaBA+betaC

where matrix A is stored in either upper or lower storage mode, and:


Table 77. Data Types

alpha, A, B, beta, C Subprogram
Short-precision real SSYMM
Long-precision real DSYMM
Short-precision complex CSYMM and CHEMM
Long-precision complex ZSYMM and ZHEMM

Syntax

Fortran CALL SSYMM | DSYMM | CSYMM | ZSYMM | CHEMM | ZHEMM (side, uplo, m, n, alpha, a, lda, b, ldb, beta, c, ldc)
C and C++ ssymm | dsymm | csymm | zsymm | chemm | zhemm (side, uplo, m, n, alpha, a, lda, b, ldb, beta, c, ldc);
PL/I CALL SSYMM | DSYMM | CSYMM | ZSYMM | CHEMM | ZHEMM (side, uplo, m, n, alpha, a, lda, b, ldb, beta, c, ldc);

On Entry

side
indicates whether 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, resulting in equation 1.

If side = 'R', A is to the right of B, resulting in equation 2.

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

uplo
indicates the storage mode used for matrix A, where:

If uplo = 'U', A is stored in upper storage mode.

If uplo = 'L', A is stored in lower storage mode.

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

m
is the number of rows in rectangular matrices B and C, and:

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

Specified as: a fullword integer; 0 <= m <= ldb, m <= ldc, and:

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

n
is the number of columns in rectangular matrices B and C, and:

If side = 'R', n is the order of 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 77.

a
is the real symmetric, complex symmetric, or complex Hermitian matrix A, where:

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

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

and where it is stored as follows:

If uplo = 'U', A is stored in upper storage mode.

If uplo = 'L', A is stored in lower storage mode.

Specified as: a two-dimensional array, containing numbers of the data type indicated in Table 77, 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 77.

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

beta
is the scalar beta. Specified as: a number of the data type indicated in Table 77.

c
is the m by n rectangular matrix C. Specified as: an ldc by (at least) n array, containing numbers of the data type indicated in Table 77.

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

On Return

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

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

Notes
  1. These subroutines accept lowercase letters for the side and uplo arguments.
  2. Matrices A, B, and C must have no common elements; otherwise, results are unpredictable.
  3. If matrix A is upper triangular (uplo = 'U'), these subroutines use only the data in the upper triangular portion of the array. If matrix A is lower triangular, (uplo = 'L'), these subroutines use only the data in the lower triangular portion of the array. In each case, the other portion of the array is altered during the computation, but restored before exit.
  4. The imaginary parts of the diagonal elements of a complex Hermitian matrix A are assumed to be zero, so you do not have to set these values.
  5. For a description of how symmetric matrices are stored in upper and lower storage mode, see Symmetric Matrix. For a description of how complex Hermitian matrices are stored in upper and lower storage mode, see Complex Hermitian Matrix.

Function

These subroutines can perform the following matrix-matrix product computations using matrix A, which is real symmetric for SSYMM and DSYMM, complex symmetric for CSYMM and ZSYMM, and complex Hermitian for CHEMM and ZHEMM:

  1. C<--alphaAB+betaC
  2. C<--alphaBA+betaC

    where:

    alpha and beta are scalars.
    A is a matrix of the type indicated above, stored in upper or lower storage mode. It is order m for equation 1 and order n for equation 2.
    B and C are m by n rectangular matrices.

See references [32] and [38]. In the following two cases, no computation is performed:

Error Conditions

Resource Errors

Unable to allocate internal work area.

Computational Errors

None

Input-Argument Errors
  1. m < 0
  2. m > ldb
  3. m > ldc
  4. n < 0
  5. lda, ldb, ldc <= 0
  6. side <> 'L' or 'R'
  7. uplo <> 'L' or 'U'
  8. side = 'L' and m > lda
  9. side = 'R' and n > lda

Example 1

This example shows the computation C<--alphaAB+betaC, where A is a real symmetric matrix of order 5, stored in upper storage mode, and B and C are 5 by 4 rectangular matrices.

Call Statement and Input
            SIDE  UPLO  M   N   ALPHA   A  LDA  B  LDB  BETA  C  LDC
             |     |    |   |     |     |   |   |   |    |    |   |
CALL SSYMM( 'L' , 'U' , 5 , 4 ,  2.0  , A , 8 , B , 6 , 1.0 , C , 5 )

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

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

        *                        *
        | 23.0  12.0  -6.0   2.0 |
        | -4.0  -5.0   1.0   3.0 |
C    =  |  5.0   6.0  -1.0  -4.0 |
        | -4.0   1.0   0.0  -5.0 |
        |  8.0  -4.0  -2.0  13.0 |
        *                        *

Output
        *                            *
        |  69.0   36.0  -18.0    6.0 |
        | -12.0  -15.0    3.0    9.0 |
C    =  |  15.0   18.0   -3.0  -12.0 |
        | -12.0    3.0    0.0  -15.0 |
        |   8.0  -20.0   -2.0   35.0 |
        *                            *

Example 2

This example shows the computation C<--alphaAB+betaC, where A is a real symmetric matrix of order 3, stored in lower storage mode, and B and C are 3 by 6 rectangular matrices.

Call Statement and Input
            SIDE  UPLO  M   N   ALPHA   A  LDA  B  LDB  BETA  C  LDC
             |     |    |   |     |     |   |   |   |    |    |   |
CALL SSYMM( 'L' , 'L' , 3 , 6 ,  2.0  , A , 4 , B , 3 , 2.0 , C , 5 )

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

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

        *                                  *
        |  6.0   4.0  1.0  1.0   0.0  -1.0 |
        |  9.0  11.0  5.0  5.0   3.0  -5.0 |
C    =  | -2.0  -6.0  3.0  3.0  -1.0  32.0 |
        |   .     .    .    .     .     .  |
        |   .     .    .    .     .     .  |
        *                                  *

Output
        *                                      *
        | 24.0   16.0   4.0   4.0   0.0   -4.0 |
        | 36.0   44.0  20.0  20.0  12.0  -20.0 |
C    =  | -8.0  -24.0  12.0  12.0  -4.0   12.0 |
        |   .      .     .     .     .      .  |
        |   .      .     .     .     .      .  |
        *                                      *

Example 3

This example shows the computation C<--alphaBA+betaC, where A is a real symmetric matrix of order 3, stored in upper storage mode, and B and C are 2 by 3 rectangular matrices.

Call Statement and Input
            SIDE  UPLO  M   N   ALPHA   A  LDA  B  LDB  BETA  C  LDC
             |     |    |   |     |     |   |   |   |    |    |   |
CALL SSYMM( 'R' , 'U' , 2 , 3 ,  2.0  , A , 4 , B , 3 , 1.0 , C , 5 )

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

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

        *                    *
        |  13.0  -18.0  10.0 |
        | -11.0   11.0  -4.0 |
C    =  |    .      .     .  |
        |    .      .     .  |
        |    .      .     .  |
        *                    *

Output
        *                     *
        |  39.0  -54.0   30.0 |
        | -33.0   33.0  -12.0 |
C    =  |    .      .      .  |
        |    .      .      .  |
        |    .      .      .  |
        *                     *

Example 4

This example shows the computation C<--alphaBA+betaC, where A is a real symmetric matrix of order 3, stored in lower storage mode, and B and C are 3 by 3 square matrices.

Call Statement and Input
            SIDE  UPLO  M   N   ALPHA   A  LDA  B  LDB  BETA  C  LDC
             |     |    |   |     |     |   |   |   |    |    |   |
CALL SSYMM( 'R' , 'L' , 3 , 3 , -1.0  , A , 3 , B , 3 , 1.0 , C , 3 )

        *                *
        | 1.0    .    .  |
A    =  | 2.0  10.0   .  |
        | 1.0  11.0  4.0 |
        *                *

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

        *                  *
        |  1.0   5.0  -9.0 |
C    =  | -3.0  10.0  -2.0 |
        | -2.0   8.0   0.0 |
        *                  *

Output
        *                     *
        |   4.0   11.0   15.0 |
C    =  | -13.0  -34.0  -48.0 |
        |   0.0   27.0   14.0 |
        *                     *

Example 5

This example shows the computation C<--alphaBA+betaC, where A is a complex symmetric matrix of order 3, stored in upper storage mode, and B and C are 2 by 3 rectangular matrices.

Call Statement and Input
            SIDE  UPLO  M   N   ALPHA   A  LDA  B  LDB  BETA   C  LDC
             |     |    |   |     |     |   |   |   |    |     |   |
CALL CSYMM( 'R' , 'U' , 2 , 3 , ALPHA , A , 4 , B , 3 , BETA , C , 5 )

ALPHA    =  (2.0, 3.0)
 
BETA     =  (1.0, 6.0)

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

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

        *                                         *
        |  (13.0, 6.0)  (-18.0, 6.0)  (10.0, 7.0) |
        | (-11.0, 8.0)   (11.0, 1.0)  (-4.0, 2.0) |
C    =  |       .             .            .      |
        |       .             .            .      |
        |       .             .            .      |
        *                                         *

Output
        *                                                      *
        |  (-96.0,   72.0)  (-141.0, -226.0)  (-112.0,   38.0) |
        | (-230.0, -269.0)  (-133.0,  -23.0)  (-272.0, -198.0) |
C    =  |        .                 .                 .         |
        |        .                 .                 .         |
        |        .                 .                 .         |
        *                                                      *

Example 6

This example shows the computation C<--alphaBA+betaC, where A is a complex Hermitian matrix of order 3, stored in lower storage mode, and B and C are 3 by 3 square matrices.

Note:
The imaginary parts of the diagonal elements of a complex Hermitian matrix are assumed to be zero, so you do not have to set these values.

Call Statement and Input
            SIDE  UPLO  M   N   ALPHA   A  LDA  B  LDB  BETA   C  LDC
             |     |    |   |     |     |   |   |   |    |     |   |
CALL CHEMM( 'R' , 'L' , 2 , 3 , ALPHA , A , 4 , B , 3 , BETA , C , 5 )

ALPHA    =  (2.0, 3.0)
 
BETA     =  (1.0, 6.0)

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

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

        *                                         *
        |  (13.0, 6.0)  (-18.0, 6.0)  (10.0, 7.0) |
        | (-11.0, 8.0)   (11.0, 1.0)  (-4.0, 2.0) |
C    =  |       .             .            .      |
        |       .             .            .      |
        |       .             .            .      |
        *                                         *

Output
        *                                                   *
        | (-137.0,  17.0)  (-158.0, -102.0)  (-39.0, 141.0) |
        | (-154.0, -77.0)   (-63.0,  186.0)  (159.0, 104.0) |
C    =  |        .                .                .        |
        |        .                .                .        |
        |        .                .                .        |
        *                                                   *

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