NAG Library Routine Document
F08BNF (ZGELSY)
1 Purpose
F08BNF (ZGELSY) computes the minimum norm solution to a complex linear least squares problem
using a complete orthogonal factorization of
.
is an
by
matrix which may be rank-deficient. Several right-hand side vectors
and solution vectors
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 by matrix and the solution vectors in the by matrix .
F08BNF (ZGELSY) first computes a
factorization with column pivoting
with
defined as the largest leading sub-matrix whose estimated condition number is less than
. The order of
,
RANK, is the effective rank of
.
Then,
is considered to be negligible, and
is annihilated by orthogonal transformations from the right, arriving at the complete orthogonal factorization
The minimum norm solution is then
where
consists of the first
RANK columns of
.
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/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
5 Parameters
- 1: M – INTEGERInput
On entry: , the number of rows of the matrix .
Constraint:
.
- 2: N – INTEGERInput
On entry: , the number of columns of the matrix .
Constraint:
.
- 3: NRHS – INTEGERInput
On entry: , the number of right-hand sides, i.e., the number of columns of the matrices and .
Constraint:
.
- 4: A(LDA,) – COMPLEX (KIND=nag_wp) arrayInput/Output
-
Note: the second dimension of the array
A
must be at least
.
On entry: the by matrix .
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:
.
- 6: B(LDB,) – COMPLEX (KIND=nag_wp) arrayInput/Output
-
Note: the second dimension of the array
B
must be at least
.
On entry: the by right-hand side matrix .
On exit: the by solution matrix .
- 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:
.
- 8: JPVT() – INTEGER arrayInput/Output
-
Note: the dimension of the array
JPVT
must be at least
.
On entry: if , the th column of is permuted to the front of , otherwise column is a free column.
On exit: if , then the th column of was the th column of .
- 9: RCOND – REAL (KIND=nag_wp)Input
On entry: used to determine the effective rank of , which is defined as the order of the largest leading triangular sub-matrix in the factorization of , whose estimated condition number is .
Suggested value:
if the condition number of
A is not known then
(where
is
machine precision, see
X02AJF) is a good choice. Negative values or values less than
machine precision should be avoided since this will cause
A to have an effective
that could be larger than its actual rank, leading to meaningless results.
- 10: RANK – INTEGEROutput
On exit: the effective rank of , i.e., the order of the sub-matrix . This is the same as the order of the sub-matrix in the complete orthogonal factorization of .
- 11: WORK() – COMPLEX (KIND=nag_wp) arrayWorkspace
On exit: if
, the real part of
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
, 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
and
is the optimal
block size.
Constraint:
or
.
- 13: RWORK() – REAL (KIND=nag_wp) arrayWorkspace
-
Note: the dimension of the array
RWORK
must be at least
.
- 14: INFO – INTEGEROutput
On exit:
unless the routine detects an error (see
Section 6).
6 Error Indicators and Warnings
Errors or warnings detected by the routine:
If , argument 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.
The real analogue of this routine is
F08BAF (DGELSY).
9 Example
This example solves the linear least squares problem
for the solution,
, of minimum norm, where
and
A tolerance of is used to determine the effective rank of .
Note that the block size (NB) of 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)