NAG Library Routine Document
F08BNF (ZGELSY)
1 Purpose
F08BNF (ZGELSY) computes the minimum norm solution to a real linear least squares problem
using a complete orthogonal factorization of
A.
A is an
m by
n matrix which may be rank-deficient. Several right-hand side vectors
b and solution vectors
x can be handled in a single call.
2 Specification
| SUBROUTINE F08BNF ( |
M, N, NRHS, A, LDA, B, LDB, JPVT, RCOND, RANK, WORK, LWORK, RWORK, INFO) |
| INTEGER |
M, N, NRHS, LDA, LDB, JPVT(*), RANK, LWORK, INFO |
| REAL (KIND=nag_wp) |
RCOND, RWORK(*) |
| COMPLEX (KIND=nag_wp) |
A(LDA,*), B(LDB,*), WORK(max(1,LWORK)) |
|
The routine may be called by its
LAPACK
name zgelsy.
3 Description
The right-hand side vectors are stored as the columns of the m by r matrix B and the solution vectors in the n by r matrix X.
F08BNF (ZGELSY) first computes a
QR factorization with column pivoting
with
R11 defined as the largest leading sub-matrix whose estimated condition number is less than
1/RCOND. The order of
R11,
RANK, is the effective rank of
A.
Then,
R22 is considered to be negligible, and
R12 is annihilated by orthogonal transformations from the right, arriving at the complete orthogonal factorization
The minimum norm solution is then
where
Q1 consists of the first
RANK columns of
Q.
4 References
Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999)
LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia
http://www.netlib.org/lapack/lugGolub G H and Van Loan C F (1996)
Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
5 Parameters
- 1: M – INTEGERInput
-
On entry:
m, the number of rows of the matrix A.
Constraint:
M≥0.
- 2: N – INTEGERInput
-
On entry:
n, the number of columns of the matrix A.
Constraint:
N≥0.
- 3: NRHS – INTEGERInput
-
On entry: r, the number of right-hand sides, i.e., the number of columns of the matrices B and X.
Constraint:
NRHS≥0.
- 4: A(LDA,*) – COMPLEX (KIND=nag_wp) arrayInput/Output
-
Note: the second dimension of the array
A
must be at least
max1,N.
On entry: the m by n matrix A.
On exit:
A has been overwritten by details of its complete orthogonal factorization.
- 5: LDA – INTEGERInput
-
On entry: the first dimension of the array
A as declared in the (sub)program from which F08BNF (ZGELSY) is called.
Constraint:
LDA≥max1,M.
- 6: B(LDB,*) – COMPLEX (KIND=nag_wp) arrayInput/Output
-
Note: the second dimension of the array
B
must be at least
max1,NRHS.
On entry: the m by r right-hand side matrix B.
On exit:
the n by r solution matrix X.
- 7: LDB – INTEGERInput
-
On entry: the first dimension of the array
B as declared in the (sub)program from which F08BNF (ZGELSY) is called.
Constraint:
LDB≥
max1,M,N
.
- 8: JPVT(*) – INTEGER arrayInput/Output
-
Note: the dimension of the array
JPVT
must be at least
max1,N.
On entry: if JPVTi≠0, the ith column of A is permuted to the front of AP, otherwise column i is a free column.
On exit: if JPVTi=k, then the ith column of AP was the kth column of A.
- 9: RCOND – REAL (KIND=nag_wp)Input
-
On entry: used to determine the effective rank of A, which is defined as the order of the largest leading triangular sub-matrix R11 in the QR factorization of A, whose estimated condition number is <1/RCOND.
- 10: RANK – INTEGEROutput
-
On exit: the effective rank of A, i.e., the order of the sub-matrix R11. This is the same as the order of the sub-matrix T11 in the complete orthogonal factorization of A.
- 11: WORK(max1,LWORK) – COMPLEX (KIND=nag_wp) arrayWorkspace
On exit: if
INFO=0, the real part of
WORK1 contains the minimum value of
LWORK required for optimal performance.
- 12: LWORK – INTEGERInput
-
On entry:
the dimension of the array
WORK as declared in the (sub)program from which F08BNF (ZGELSY) is called.
If
LWORK=-1, a workspace query is assumed; the routine only calculates the optimal size of the
WORK array, returns this value as the first entry of the
WORK array, and no error message related to
LWORK is issued.
Suggested value:
for optimal performance,
where
k
=
minM,N
and
nb
is the optimal
block size.
Constraint:
LWORK
≥
k
+
max2×k,N+1,k+NRHS
, where
k
=
minM,N
or
LWORK=-1.
- 13: RWORK(*) – REAL (KIND=nag_wp) arrayWorkspace
-
Note: the dimension of the array
RWORK
must be at least
max1,2×N.
- 14: INFO – INTEGEROutput
On exit:
INFO=0 unless the routine detects an error (see
Section 6).
6 Error Indicators and Warnings
Errors or warnings detected by the routine:
- INFO<0
If INFO=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
7 Accuracy
See Section 4.5 of
Anderson et al. (1999) for details of error bounds.
8 Further Comments
The real analogue of this routine is
F08BAF (DGELSY).
9 Example
This example solves the linear least squares problem
for the solution,
x, of minimum norm, where
and
A tolerance of 0.01 is used to determine the effective rank of A.
Note that the block size (NB) of 64 assumed in this example is not realistic for such a small problem, but should be suitable for large problems.
9.1 Program Text
Program Text (f08bnfe.f90)
9.2 Program Data
Program Data (f08bnfe.d)
9.3 Program Results
Program Results (f08bnfe.r)