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

SGESUB, DGESUB, CGESUB, and ZGESUB--Matrix Subtraction for General Matrices or Their Transposes

These subroutines can perform any one of the following matrix subtractions, using matrices A and B or their transposes, and matrix C:

C<--A-B

C<--A^T-B

C<--A-B^T

C<--A^T-B^T

Table 73. Data Types

Syntax

On Entry

a

is the matrix A, where:

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

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

Note:

No data should be moved to form A^T; 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 73, where:

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

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

lda

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

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

If transa = 'T', lda >= n.

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', A^T is used in the computation.

Specified as: a single character; transa = 'N' or 'T'.

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', B^T is used in the computation, and B has n rows and m columns.

Note:

No data should be moved to form B^T; 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 72, where:

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

If transb = 'T', 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', 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', B^T is used in the computation.

Specified as: a single character; transb = 'N' or 'T'.

c

See On Return.

ldc

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

m

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

n

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

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

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. However, C may (exactly) coincide with A if transa = 'N', and C may (exactly) coincide with B if transb = 'N'. Otherwise, results are unpredictable. See Concepts.

Function

The matrix subtraction is expressed as follows, where a_ij, b_ij, and c_ij are elements of matrices A, B, and C, respectively:

c_ij = a_ij-b_ij    for C<--A-B

c_ij = a_ij-b_ji    for C<--A-B^T

c_ij = a_ji-b_ij    for C<--A^T-B

c_ij = a_ji-b_ji    for C<--A^T-B^T

   for i = 1, m and j = 1, n

If m or n is 0, no computation is performed.

Special Usage

You can compute the transpose C^T of each of the four computations listed under Function by using the following matrix identities:

(A-B)^T = A^T-B^T

(A-B^T)^T = A^T-B

(A^T-B)^T = A-B^T

(A^T-B^T)^T = A-B

Be careful that your output array receiving C^T has dimensions large enough to hold the transposed matrix. See Example 5.

Error Conditions

Computational Errors

None

Input-Argument Errors

1. lda, ldb, ldc <= 0
2. m, n < 0
3. m > ldc
4. transa, transb <>  'N' or 'T'
5. transa = 'N' and m > lda
6. transa = 'T' and n > lda
7. transb = 'N' and m > ldb
8. transb = 'T' and n > ldb

Example 1

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

Call Statement and Input

             A  LDA TRANSA  B  LDB TRANSB  C  LDC  M   N
             |   |    |     |   |    |     |   |   |   |
CALL SGESUB( A , 6 , 'N'  , B , 4 , 'N'  , C , 5 , 4 , 3 )

        *                              *
        | 110000.0  120000.0  130000.0 |
        | 210000.0  220000.0  230000.0 |
A    =  | 310000.0  320000.0  330000.0 |
        | 410000.0  420000.0  430000.0 |
        |       .         .         .  |
        |       .         .         .  |
        *                              *

        *                     *
        | -11.0  -12.0  -13.0 |
B    =  | -21.0  -22.0  -23.0 |
        | -31.0  -32.0  -33.0 |
        | -41.0  -42.0  -43.0 |
        *                     *

Output

        *                              *
        | 110011.0  120012.0  130013.0 |
        | 210021.0  220022.0  230023.0 |
C    =  | 310031.0  320032.0  330033.0 |
        | 410041.0  420042.0  430043.0 |
        |       .         .         .  |
        *                              *

Example 2

This example shows the computation C<--A^T-B, where A, B, and C are the same size as arrays A, B, and C, in which they are contained.

Call Statement and Input

             A  LDA TRANSA  B  LDB TRANSB  C  LDC  M   N
             |   |    |     |   |    |     |   |   |   |
CALL SGESUB( A , 3 , 'T'  , B , 4 , 'N'  , C , 4 , 4 , 3 )

        *                                        *
        | 110000.0  120000.0  130000.0  140000.0 |
A    =  | 210000.0  220000.0  230000.0  240000.0 |
        | 310000.0  320000.0  330000.0  340000.0 |
        *                                        *

        *                     *
        | -11.0  -12.0  -13.0 |
B    =  | -21.0  -22.0  -23.0 |
        | -31.0  -32.0  -33.0 |
        | -41.0  -42.0  -43.0 |
        *                     *

Output

        *                              *
        | 110011.0  210012.0  310013.0 |
C    =  | 120021.0  220022.0  320023.0 |
        | 130031.0  230032.0  330033.0 |
        | 140041.0  240042.0  340043.0 |
        *                              *

Example 3

This example shows computation C<--A-B^T, where A is contained in a larger array A, and B and C are the same size as arrays B and C, in which they are contained.

Call Statement and Input

             A  LDA TRANSA  B  LDB TRANSB  C  LDC  M   N
             |   |    |     |   |    |     |   |   |   |
CALL SGESUB( A , 5 , 'N'  , B , 3 , 'T'  , C , 4 , 4 , 3 )

        *                              *
        | 110000.0  120000.0  130000.0 |
        | 210000.0  220000.0  230000.0 |
A    =  | 310000.0  320000.0  330000.0 |
        | 410000.0  420000.0  430000.0 |
        |       .         .         .  |
        *                              *

        *                            *
        | -11.0  -12.0  -13.0  -14.0 |
B    =  | -21.0  -22.0  -23.0  -24.0 |
        | -31.0  -32.0  -33.0  -34.0 |
        *                            *

Output

        *                              *
        | 110011.0  120021.0  130031.0 |
C    =  | 210012.0  220022.0  230032.0 |
        | 310013.0  320023.0  330033.0 |
        | 410014.0  420024.0  430034.0 |
        *                              *

Example 4

This example shows the computation C<--A^T-B^T, where A, B, and C are the same size as the arrays A, B, and C, in which they are contained.

Call Statement and Input

             A  LDA TRANSA  B  LDB TRANSB  C  LDC  M   N
             |   |    |     |   |    |     |   |   |   |
CALL SGESUB( A , 3 , 'T'  , B , 3 , 'T'  , C , 4 , 4 , 3 )

        *                                        *
        | 110000.0  120000.0  130000.0  140000.0 |
A    =  | 210000.0  220000.0  230000.0  240000.0 |
        | 310000.0  320000.0  330000.0  340000.0 |
        *                                        *

        *                            *
        | -11.0  -12.0  -13.0  -14.0 |
B    =  | -21.0  -22.0  -23.0  -24.0 |
        | -31.0  -32.0  -33.0  -34.0 |
        *                            *

Output

        *                              *
        | 110011.0  210021.0  310031.0 |
C    =  | 120012.0  220022.0  320032.0 |
        | 130013.0  230023.0  330033.0 |
        | 140014.0  240024.0  340034.0 |
        *                              *

Example 5

This example shows how to produce the transpose of the result of the computation performed in Example 4, C<--A^T-B^T, which uses the calling sequence:

      CALL SGESUB( A , 3 , 'T' , B , 3 , 'T' , C , 4 , 4 , 3 )

You instead code a calling sequence for C^T<--A-B, as shown below, where the resulting matrix C^T in the output array CT is the transpose of the matrix in the output array C in Example 4. 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  M   N
             |   |    |     |   |    |     |    |   |   |
CALL SGESUB( A , 3 , 'N'  , B , 3 , 'N'  , CT , 3 , 3 , 4 )

        *                                        *
        | 110000.0  120000.0  130000.0  140000.0 |
A    =  | 210000.0  220000.0  230000.0  240000.0 |
        | 310000.0  320000.0  330000.0  340000.0 |
        *                                        *

        *                            *
        | -11.0  -12.0  -13.0  -14.0 |
B    =  | -21.0  -22.0  -23.0  -24.0 |
        | -31.0  -32.0  -33.0  -34.0 |
        *                            *

Output

        *                                        *
        | 110011.0  120012.0  130013.0  140014.0 |
CT   =  | 210021.0  220022.0  230023.0  240024.0 |
        | 310031.0  320032.0  330033.0  340034.0 |
        *                                        *

Example 6

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

Call Statement and Input

             A  LDA TRANSA  B  LDB TRANSB  C  LDC  M   N
             |   |    |     |   |    |     |   |   |   |
CALL CGESUB( A , 6 , 'N'  , B , 5 , 'N'  , C , 5 , 4 , 3 )

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

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

Output

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