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

|DGELS--Linear Least Squares Solution for a General Matrix

|This subroutine computes the linear least squares solution for a general |matrix A or its transpose using a QR factorization |without column pivoting, where A is assumed to have full |rank.

|The following options are provided: |

• |If transa = 'N' and |m >= n: find the least squares solution of |an overdetermined system; that is, solve the least squares problem: |minimize ||B - AX||
• |If transa = 'N' and |m < n: find the minimum norm solution of an |underdetermined system; that is, the problem is: |AX = B
• |If transa = 'T' and |m >= n: find the minimum norm solution of an |underdetermined system; that is, the problem is |A^TX = B
• |If transa = 'T' and |m < n: find the least squares solution of |an overdetermined system; that is, solve the least squares problem: |minimize |||B - A^TX|| |

|Table 120. Data Types

|Syntax

|On Entry

| transa

|indicate the form of matrix A to use in the computation, |where:

|If transa = 'N', matrix A is |used.

|If transa = 'T', matrix A^T |is used.

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

| m

|is the number of rows in matrix A used in the |computation.

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

| n

|is the number of columns in matrix A used in the |computation.

|Specified as: a fullword integer; |n >= 0.

| nrhs

|is the number of right-hand sides; that is, the number of columns in |matrix B used in the computation.

|Specified as: a fullword integer; |nrhs >= 0.

| a

|is the m by n coefficient matrix A.

|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: an lda by (at least) n array, |containing numbers of the data type indicated in Table 120.

| lda

|is the leading dimension of the array specified for a.

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

| b

|is the matrix B of right-hand side vectors.

|If transa = 'N', matrix B has |m rows and nrhs columns.

|If transa = 'T', matrix B has |n rows and nrhs columns.

|Specified as: the ldb by (at least) nrhs array, |containing numbers of the data type indicated in Table 120.

| ldb

|is the leading dimension of the array specified for b.

|Specified as: a fullword integer; ldb > 0 |and ldb >= max(m,n).

| work

|has the following meaning:

|If lwork = 0, work is ignored.

|If lwork <> 0, work is the work area used by |this subroutine, where: |

• |If lwork <> -1, its size is (at least) of length |lwork.
• |If lwork = -1, its size is (at least) of length |1. |

|Specified as: an area of storage containing numbers of data type |indicated in Table 120.

| lwork

|is the number of elements in array work.

|Specified as: a fullword integer; where: |

• |If lwork = 0, DGELS dynamically allocates the work area |used by this subroutine. The work area is deallocated before control is |returned to the calling program. This option is an extension to the |LAPACK standard.
• |If lwork = -1, DGELS performs a work area query and |returns the optimal size of work in work₁. |No computation is performed, and the subroutine returns after error checking |is complete.
• |Otherwise, it must be:

  |lwork >= max(1, |mn + max(mn, nrhs))

  |where mn = min(m, n). |

|info

|See On Return. |

|On Return

| a

|is the updated general matrix A. The matrix A |is overwritten; that is, the original input is not preserved.

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

| b

|is the updated general matrix B, containing the results of the |computation. B is overwritten by the solution vectors, |stored columnwise: |

• |If transa = 'N' and |m >= n, rows 1 to n of B |contain the least squares solution vectors;the residual sum of squares |for the solution in each column is given by the sum of squares of elements |n+1 to m in that column.
• |If transa = 'N' and |m < n, rows 1 to n of B |contain the minimum norm solution vectors.
• |If transa = 'T' and |m >= n, rows 1 to m of B |contain the minimum norm solution vectors.
• |If transa = 'T' and |m < n, rows 1 to m of B |contain the least squares solution vectors; the residual sum of squares |for the solution in each column is given by the sum of squares of elements |m+1 to n in that column. |

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

| work

|is the work area used by this subroutine if lwork <> 0, |where:

|If lwork <> 0 and lwork <> -1, |its size is (at least) of length lwork.

|If lwork = -1, its size is (at least) of length |1.

|Returned as: an area of storage, where:

|If lwork >= 1 or lwork = -1, then |work₁ is set to the optimal lwork value and |contains numbers of the data type indicated in Table 120. Except for work₁, the contents |of work are overwritten on return.

| info

|indicates that a successful computation occurred.

|Returned as: a fullword integer; |info = 0. |

|Notes and Coding Rules

1. |In your C program, argument info must be passed by |reference.
2. |All subroutines accept lowercase letters for the transa |argument.
3. |The vectors and matrices used in the computation must have no common |elements; otherwise, results are unpredictable.
4. |For best perfomance specify lwork = 0. |

|Function

|This subroutine computes the linear least squares solution for a general |matrix A or its transpose using a QR factorization |without column pivoting, where A is assumed to have full |rank.

|The following options are provided: |

• |If transa = 'N' and |m >= n: find the least squares solution of |an overdetermined system; that is, solve the least squares problem: |minimize ||B - AX||
• |If transa = 'N' and |m < n: find the minimum norm solution of an |underdetermined system; that is, the problem is: |AX = B
• |If transa = 'T' and |m >= n: find the minimum norm solution of an |underdetermined system; that is, the problem is |A^TX = B
• |If transa = 'T' and |m < n: find the least squares solution of |an overdetermined system; that is, solve the least squares problem: |minimize |||B - A^TX|| |

|If (m = 0 and n = 0) or |nrhs = 0, then no computation is performed and the subroutine |returns after doing some parameter checking.

|See reference [62].

|Error Conditions

|Resource Errors

|lwork = 0 and unable to allocate work space.

|Computational Errors

|None.

|Input-Argument Errors

1. |transa <> 'N' or 'T'
2. |m < 0
3. |n < 0
4. |nrhs < 0
5. |lda < m
6. |lda <= 0
7. |ldb < max(m, n)
8. |ldb <= 0
9. |lwork <> 0, lwork <> -1, and |lwork < max(1, mn + max(mn, |nrhs)) where mn = min(m, n) |

|Example 1

|This example finds the least squares solution of an overdetermined |system; that is, it solves the least squares problem: minimize |||B-AX||. Matrix |A is size 6 × 2 and matrix B is size |6 × 3.

|Note:

Because lwork = 0, DGELS dynamically allocates the work area |used by this subroutine. |

|Call Statements and Input

|           TRANSA   M   N   NRHS   A   LDA  B  LDB  WORK  LWORK  INFO
|              |     |   |     |    |    |   |   |     |     |      |
|CALL DGELS ( 'N' ,  6 , 2 ,   3 ,  A ,  6 , B,  6,  WORK,   0,   INFO )

|General matrix A of size 6 × 2:

|        *                           *
|        |   .000000000  2.000000000 |
|        |  2.000000000 -1.000000000 |
|A    =  |  2.000000000 -1.000000000 |
|        |   .000000000  1.500000000 |
|        |  2.000000000 -1.000000000 |
|        |  2.000000000 -1.000000000 |
|        *                           *

|General matrix B of size 6 × 3:

|        *                                        *
|        |  1.000000000  4.000000000  1.000000000 |
|        |  1.000000000  1.000000000  2.000000000 |
|B    =  |  1.000000000 -1.000000000  1.000000000 |
|        |  1.000000000  3.000000000  2.000000000 |
|        |  1.000000000  1.000000000  1.000000000 |
|        |  1.000000000 -1.000000000  1.000000000 |
|        *                                        *

|Output:

|General matrix A is overwritten.

|Solution matrix X overwrites B:

|        *                                        *
|        |   .780000000  1.000000000  1.025000000 |
|        |   .560000000  2.000000000   .800000000 |
|B    =  |   .042857143 -1.285714286  -.250000000 |
|        |   .185714286   .428571429  1.250000000 |
|        |   .042857143   .714285714  -.250000000 |
|        |   .042857143 -1.285714286  -.250000000 |
|        *                                        *

|INFO  =  0

|Example 2

|This example finds the minimum norm solution of an underdetermined system |A^TX = B. |Matrix A is size 6 × 2. On input, matrix |B is size 2 × 1, stored in array b with |leading dimension 6.

|Note:

Because lwork = 0, DGELS dynamically allocates the work area |used by this subroutine. |

|Call Statements and Input

|           TRANSA   M   N   NRHS   A   LDA  B  LDB  WORK  LWORK  INFO
|              |     |   |     |    |    |   |   |     |     |      |
|CALL DGELS ( 'T' ,  6 , 2 ,   1 ,  A ,  6 , B,  6,  WORK,   0,   INFO )

|General matrix A of size 6 × 2:

|        *                           *
|        |   .000000000  2.000000000 |
|        |  2.000000000 -1.000000000 |
|A    =  |  2.000000000 -1.000000000 |
|        |   .000000000  1.500000000 |
|        |  2.000000000 -1.000000000 |
|        |  2.000000000 -1.000000000 |
|        *                           *

|General matrix B of size 2 × 1:

|        *              *
|B    =  |  1.000000000 |
|        |  1.000000000 |
|        |       .      |
|        |       .      |
|        |       .      |
|        |       .      |
|        *              *

|Output:

|General matrix A is overwritten.

|Solution matrix X overwrites B:

|        *              *
|        |   .480000000 |
|        |   .125000000 |
|B    =  |   .125000000 |
|        |   .360000000 |
|        |   .125000000 |
|        |   .125000000 |
|        *              *

|INFO  =  0

|Example 3

|This example finds the minimum norm solution of an underdetermined system |AX = B. Matrix |A is size 3 × 4. On input, matrix B |is size 3 × 4, stored in array b with leading dimension |4.

|Note:

Because lwork = 0, DGELS dynamically allocates the work area |used by this subroutine. |

|Call Statements and Input

|           TRANSA   M   N   NRHS   A   LDA  B  LDB  WORK  LWORK  INFO
|              |     |   |     |    |    |   |   |     |     |      |
|CALL DGELS ( 'N' ,  3 , 4 ,   4 ,  A ,  3 , B,  4,  WORK,   0,   INFO )

|General matrix A of size 3 × 4:

|        *                                                      *
|        |   .500000000   .500000000    .500000000   .500000000 |
|A    =  |   .500000000 -1.500000000    .500000000 -1.500000000 |
|        |  1.000000000  1.000000000    .000000000  1.000000000 |
|        *                                                      *

|General matrix B of size 3 × 4:

|        *                                                      *
|        |  1.000000000  1.000000000   1.000000000   .000000000 |
|B    =  |  1.000000000 -1.000000000   2.500000000  1.000000000 |
|        |  1.000000000  1.000000000   3.000000000   .000000000 |
|        |        .            .             .            .     |
|        *                                                      *

|Output:

|General matrix A is overwritten.

|Solution matrix X overwrites B:

|        *                                                      *
|        |  1.000000000   .000000000   3.500000000   .500000000 |
|B    =  |   .000000000   .500000000   -.250000000  -.250000000 |
|        |  1.000000000  1.000000000  -1.000000000   .000000000 |
|        |   .000000000   .500000000   -.250000000  -.250000000 |
|        *                                                      *

|INFO  =  0

|Example 4

|This example finds the least squares solution of an overdetermined |system; that is, it solves the least squares problem: minimize |||B-A^TX||. |Matrix A is size 3 × 4. On input, matrix |B is size 4 × 4.

|Note:

Because lwork = 0, DGELS dynamically allocates the work area |used by this subroutine. |

|Call Statements and Input

|           TRANSA  M   N   NRHS  A  LDA  B  LDB  WORK  LWORK  INFO
|              |    |   |    |    |   |   |   |    |      |     |
|CALL DGELS ( 'T' , 3 , 4 ,  4 ,  A , 3 , B , 4 , WORK ,  0 ,  INFO )

|General matrix A of size 3 × 4:

|        *                                                      *
|        |   .500000000   .500000000    .500000000   .500000000 |
|A    =  |   .500000000 -1.500000000    .500000000 -1.500000000 |
|        |  1.207106781  -.500000000    .207106781  -.500000000 |
|        *                                                      *

|General matrix B of size 4 × 4:

|        *                                                      *
|        |  1.000000000  1.000000000   1.000000000   .000000000 |
|B    =  |  1.000000000 -1.000000000   2.000000000  2.414213562 |
|        |  1.000000000  1.000000000   3.000000000   .000000000 |
|        |  1.000000000 -1.000000000   4.000000000  -.414213562 |
|        *                                                      *

|Output:

|General matrix A is overwritten.

|Solution matrix X overwrites B:

|        *                                                      *
|        |  2.000000000  1.000000000   6.121320344   .500000000 |
|B    =  |   .000000000  1.000000000    .707106781  -.500000000 |
|        |   .000000000   .000000000  -2.000000000   .000000000 |
|        |   .000000000   .000000000   1.414213562 -2.000000000 |
|        *                                                      *

|INFO  =  0