IBM Books

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

SGEMUL, DGEMUL, CGEMUL, and ZGEMUL--Matrix Multiplication for General Matrices, Their Transposes, or Conjugate Transposes

SGEMUL and DGEMUL can perform any one of the following matrix multiplications, using matrices A and B or their transposes, and matrix C:


C<--AB C<--ABT
C<--ATB C<--ATBT

CGEMUL and ZGEMUL can perform any one of the following matrix multiplications, using matrices A and B, their transposes or their conjugate transposes, and matrix C:

C<--AB C<--ABT C<--ABH
C<--ATB C<--ATBT C<--ATBH
C<--AHB C<--AHBT C<--AHBH

Table 74. Data Types

A, B, C Subroutine
Short-precision real SGEMUL
Long-precision real DGEMUL
Short-precision complex CGEMUL
Long-precision complex ZGEMUL

Syntax

Fortran CALL SGEMUL | DGEMUL | CGEMUL | ZGEMUL (a, lda, transa, b, ldb, transb, c, ldc, l, m, n)
C and C++ sgemul | dgemul | cgemul | zgemul (a, lda, transa, b, ldb, transb, c, ldc, l, m, n);
PL/I CALL SGEMUL | DGEMUL | CGEMUL | ZGEMUL (a, lda, transa, b, ldb, transb, c, ldc, l, m, n);
APL2 SGEMUL | DGEMUL | CGEMUL | ZGEMUL a lda transa b ldb transb 'c' ldc l m n

On Entry

a
is the matrix A, where:

If transa = 'N', A is used in the computation, and A has l rows and m columns.

If transa = 'T', AT is used in the computation, and A has m rows and l columns.

If transa = 'C', AH is used in the computation, and A has m rows and l columns.

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 74, where:

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

If transa = 'T' or 'C', its size must be lda by (at least) l.

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

If transa = 'N', lda >= l.

If transa = 'T' or 'C', lda >= m.

transa
indicates the form of matrix A to use in the computation, where:

If transa = 'N', A is used in the computation.

If transa = 'T', AT is used in the computation.

If transa = 'C', AH is used in the computation.

Specified as: a single character; transa = 'N' or 'T' for SGEMUL and DGEMUL; transa = 'N', 'T', or 'C' for CGEMUL and ZGEMUL.

b
is the matrix B, where:

If transb = 'N', B is used in the computation, and B has m rows and n columns.

If transb = 'T', BT is used in the computation, and B has n rows and m columns.

If transb = 'C', BH is used in the computation, and B has n rows and m columns.

Note:
No data should be moved to form BT or BH; that is, the matrix B should always be stored in its untransposed form.

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

If transb = 'N', its size must be ldb by (at least) n.

If transb = 'T' or 'C', its size must be ldb by (at least) m.

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

If transb = 'N', ldb >= m.

If transb = 'T' or 'C', ldb >= n.

transb
indicates the form of matrix B to use in the computation, where:

If transb = 'N', B is used in the computation.

If transb = 'T', BT is used in the computation.

If transb = 'C', BH is used in the computation.

Specified as: a single character; transb = 'N' or 'T' for SGEMUL and DGEMUL; transb = 'N', 'T', or 'C' for CGEMUL and ZGEMUL.

c
See On Return.

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

l
is the number of rows in matrix C. Specified as: a fullword integer; 0 <= l <= ldc.

m
has the following meaning, where:

If transa = 'N', it is the number of columns in matrix A.

If transa = 'T' or 'C', it is the number of rows in matrix A.

In addition:

If transb = 'N', it is the number of rows in matrix B.

If transb = 'T' or 'C', it is the number of columns in matrix B.

Specified as: a fullword integer; m >= 0.

n
is the number of columns in matrix C. Specified as: a fullword integer; n >= 0.

On Return

c
is the l by n matrix C, containing the results of the computation. Returned as: an ldc by (at least) n numbers of the data type indicated in Table 74.

Notes
  1. All subroutines accept lowercase letters for the transa and transb arguments.
  2. Matrix C must have no common elements with matrices A or B; otherwise, results are unpredictable. See Concepts.

Function

The matrix multiplication is expressed as follows, where aik, bkj, and cij are elements of matrices A, B, and C, respectively:




Matrix Multiplication Graphic

See reference [38]. If l or n is 0, no computation is performed. If l and n are greater than 0, and m is 0, an l by n matrix of zeros is returned.

Special Usage

Equivalence Rules

By using the following equivalence rules, you can compute the transpose CT or the conjugate transpose CH of some of the computations performed by these subroutines:

Transpose Conjugate Transpose
(AB)T = BTAT (AB)H = BHAH
(ATB)T = BTA (AHB)H = BHA
(ABT)T = BAT (ABH)H = BAH
(ATBT)T = BA (AHBH)H = BA

When coding the calling sequences for these cases, be careful to code your matrix arguments and dimension arguments in the order indicated by the rule. Also, be careful that your output array, receiving CT or CH, has dimensions large enough to hold the resulting transposed or conjugate transposed matrix. See Example 2 and Example 4.

Error Conditions

Resource Errors

Unable to allocate internal work area (CGEMUL and ZGEMUL only).

Computational Errors

None

Input-Argument Errors
  1. lda, ldb, ldc <= 0
  2. l, m, n < 0
  3. l > ldc
  4. transa, transb <>  'N' or 'T' for SGEMUL and DGEMUL
  5. transa, transb <>  'N', 'T', or 'C' for CGEMUL and ZGEMUL
  6. transa = 'N' and l > lda
  7. transa = 'T' or 'C' and m > lda
  8. transb = 'N' and m > ldb
  9. transb = 'T' or 'C' and n > ldb

Example 1

This example shows the computation C<--AB, where A, B, and C are contained in larger arrays A, B, and C, respectively.

Call Statement and Input
             A  LDA TRANSA  B  LDB TRANSB  C  LDC  L   M   N
             |   |    |     |   |    |     |   |   |   |   |
CALL SGEMUL( A , 8 , 'N'  , B , 6 , 'N'  , C , 7 , 6 , 5 , 4 )

        *                              *
        |  1.0   2.0  -1.0  -1.0   4.0 |
        |  2.0   0.0   1.0   1.0  -1.0 |
        |  1.0  -1.0  -1.0   1.0   2.0 |
A    =  | -3.0   2.0   2.0   2.0   0.0 |
        |  4.0   0.0  -2.0   1.0  -1.0 |
        | -1.0  -1.0   1.0  -3.0   2.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 |
        |   .     .     .     .  |
        *                        *

Output
        *                         *
        | 23.0  12.0  -6.0    2.0 |
        | -4.0  -5.0   1.0    3.0 |
        |  3.0   0.0   1.0    4.0 |
C    =  | -3.0   5.0  -2.0  -10.0 |
        | -5.0  -7.0   4.0    4.0 |
        | 15.0   6.0  -5.0    6.0 |
        |   .     .     .      .  |
        *                         *

Example 2

This example shows how to produce the transpose of the result of the computation performed in Example 1, C<--AB, which uses the calling sequence: 

      CALL  SGEMUL (A,8,'N',B,6,'N',C,7,6,5,4)

You instead code a calling sequence for CT<--BTAT, as shown below, where the resulting matrix CT in the output array CT is the transpose of the matrix in the output array C in Example 1. Note that the array CT has dimensions large enough to receive the transposed matrix. For a description of all the matrix identities, see Special Usage.

Call Statement and Input
             A  LDA TRANSA  B  LDB TRANSB  C   LDC  L   M   N
             |   |    |     |   |    |     |    |   |   |   |
CALL SGEMUL( B , 6 , 'T'  , A , 8 , 'T'  , CT , 5 , 4 , 5 , 6 )

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

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

Output
        *                                    *
        | 23.0  -4.0  3.0   -3.0  -5.0  15.0 |
        | 12.0  -5.0  0.0    5.0  -7.0   6.0 |
CT   =  | -6.0   1.0  1.0   -2.0   4.0  -5.0 |
        |  2.0   3.0  4.0  -10.0   4.0   6.0 |
        |   .     .    .      .     .     .  |
        *                                    *

Example 3

This example shows the computation C<--ATB, where A and C are contained in larger arrays A and C, respectively, and B is the same size as the

Call Statement and Input
             A  LDA TRANSA  B  LDB TRANSB  C  LDC  L   M   N
             |   |    |     |   |    |     |   |   |   |   |
CALL SGEMUL( A , 4 , 'T'  , B , 3 , 'N'  , C , 5 , 3 , 3 , 6 )

        *                 *
        | 1.0  -3.0   2.0 |
A    =  | 2.0   4.0   0.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 |
        *                                   *

Output
        *                                    *
        | 6.0   4.0   1.0   1.0   0.0   -1.0 |
        | 4.0  26.0  -5.0  -5.0   8.0  -15.0 |
C    =  | 1.0  -5.0   5.0   5.0  -1.0    3.0 |
        |  .     .     .     .     .      .  |
        |  .     .     .     .     .      .  |
        *                                    *

Example 4

This example shows how to produce the transpose of the result of the computation performed in Example 3, C<--ATB, which uses the calling sequence: 

      CALL  SGEMUL (A,4,'T',B,3,'N',C,5,3,3,6)

You instead code the calling sequence for CT<--BTA, as shown below, where the resulting matrix CT in the output array CT is the transpose of the matrix in the output array C in Example 3. Note that the array CT has dimensions large enough to receive the transposed matrix. For a description of all the matrix identities, see Special Usage.

Call Statement and Input
             A  LDA TRANSA  B  LDB TRANSB  C   LDC  L   M   N
             |   |    |     |   |    |     |    |   |   |   |
CALL SGEMUL( B , 3 , 'T'  , A , 4 , 'N'  , CT , 8 , 6 , 3 , 3 )

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

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

Output
        *                   *
        |  6.0    4.0   1.0 |
        |  4.0   26.0  -5.0 |
        |  1.0   -5.0   5.0 |
CT   =  |  1.0   -5.0   5.0 |
        |  0.0    8.0  -1.0 |
        | -1.0  -15.0   3.0 |
        |   .      .     .  |
        |   .      .     .  |
        *                   *

Example 5

This example shows the computation C<--ABT, where A and C are contained in larger arrays A and C, respectively, and B is the same size as the array B in which it is contained.

Call Statement and Input
             A  LDA TRANSA  B  LDB TRANSB  C  LDC  L   M   N
             |   |    |     |   |    |     |   |   |   |   |
CALL SGEMUL( A , 4 , 'N'  , B , 3 , 'T'  , C , 5 , 3 , 2 , 3 )

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

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

Output
        *                    *
        |  10.0  -10.0   4.0 |
        | -10.0   20.0  -2.0 |
C    =  |   4.0   -2.0   2.0 |
        |    .      .     .  |
        |    .      .     .  |
        *                    *

Example 6

This example shows the computation C<--ATBT, where A, B, and C are the same size as the arrays A, B, and C in which they are contained. (Based on the dimensions of the matrices, A is actually a column vector, and C is actually a row vector.)

Call Statement and Input
             A  LDA TRANSA  B  LDB TRANSB  C  LDC  L   M   N
             |   |    |     |   |    |     |   |   |   |   |
CALL SGEMUL( A , 3 , 'T'  , B , 3 , 'T'  , C , 1 , 1 , 3 , 3 )

        *     *
        | 1.0 |
A    =  | 2.0 |
        | 1.0 |
        *     *

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

Output
        *                  *
B    =  | -3.0  10.0  -2.0 |
        *                  *

Example 7

This example shows the computation C<--ATB using complex data, where A, B, and C are contained in larger arrays A, B, and C, respectively.

Call Statement and Input
             A  LDA TRANSA  B  LDB TRANSB  C  LDC  L   M   N
             |   |    |     |   |    |     |   |   |   |   |
CALL CGEMUL( A , 6 , 'T'  , B , 7 , 'N'  , C , 3 , 2 , 3 , 3 )

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

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

Output
        *                                             *
        | (-45.0, 85.0)  (20.0, 93.0)  (-13.0, 110.0) |
C    =  | (-50.0, 90.0)  (12.0, 79.0)    (3.0,  94.0) |
        |       .             .              .        |
        *                                             *

Example 8

This example shows the computation C<--ABH using complex data, where A and C are contained in larger arrays A and C, respectively, and B is the same size as the array B in which it is contained.

Call Statement and Input
             A  LDA TRANSA  B  LDB TRANSB  C  LDC  L   M   N
             |   |    |     |   |    |     |   |   |   |   |
CALL CGEMUL( A , 4 , 'N'  , B , 3 , 'C'  , C , 4 , 3 , 2 , 3 )

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

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

Output
        *                                            *
        | (20.0,  -1.0)  (12.0, 25.0)  (24.0,  26.0) |
C    =  | (18.0, -23.0)  (80.0, -2.0)  (49.0, -37.0) |
        | (26.0, -23.0)  (56.0, 37.0)  (76.0,   2.0) |
        |      .              .             .        |
        *                                            *

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