NAG Library Routine Document
F02WUF
1 Purpose
F02WUF returns all, or part, of the singular value decomposition of a real upper triangular matrix.
2 Specification
SUBROUTINE F02WUF ( |
N, A, LDA, NCOLB, B, LDB, WANTQ, Q, LDQ, SV, WANTP, WORK, IFAIL) |
INTEGER |
N, LDA, NCOLB, LDB, LDQ, IFAIL |
REAL (KIND=nag_wp) |
A(LDA,*), B(LDB,*), Q(LDQ,*), SV(N), WORK(*) |
LOGICAL |
WANTQ, WANTP |
|
3 Description
The
n by
n upper triangular matrix
R is factorized as
where
Q and
P are
n by
n orthogonal matrices and
S is an
n by
n diagonal matrix with non-negative diagonal elements,
σ1,σ2,…,σn, ordered such that
The columns of
Q are the left-hand singular vectors of
R, the diagonal elements of
S are the singular values of
R and the columns of
P are the right-hand singular vectors of
R.
Either or both of
Q and
PT may be requested and the matrix
C given by
where
B is an
n by
ncolb given matrix, may also be requested.
The routine obtains the singular value decomposition by first reducing R to bidiagonal form by means of Givens plane rotations and then using the QR algorithm to obtain the singular value decomposition of the bidiagonal form.
Note that if
K is any orthogonal diagonal matrix so that
(that is the diagonal elements of
K are
+1 or
-1) then
is also a singular value decomposition of
A.
4 References
Chan T F (1982) An improved algorithm for computing the singular value decomposition
ACM Trans. Math. Software 8 72–83
Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979)
LINPACK Users' Guide SIAM, Philadelphia
Golub G H and Van Loan C F (1996)
Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics
SIGNUM Newsl. 20(3) 2–25
Wilkinson J H (1978) Singular Value Decomposition – Basic Aspects
Numerical Software – Needs and Availability (ed D A H Jacobs) Academic Press
5 Parameters
- 1: N – INTEGERInput
On entry:
n, the order of the matrix
R.
If N=0, an immediate return is effected.
Constraint:
N≥0.
- 2: A(LDA,*) – REAL (KIND=nag_wp) arrayInput/Output
-
Note: the second dimension of the array
A
must be at least
max1,N.
On entry: the leading
n by
n upper triangular part of the array
A must contain the upper triangular matrix
R.
On exit: if
WANTP=.TRUE., the
n by
n part of
A will contain the
n by
n orthogonal matrix
PT, otherwise the
n by
n upper triangular part of
A is used as internal workspace, but the strictly lower triangular part of
A is not referenced.
- 3: LDA – INTEGERInput
On entry: the first dimension of the array
A as declared in the (sub)program from which F02WUF is called.
Constraint:
LDA≥max1,N.
- 4: NCOLB – INTEGERInput
On entry:
ncolb, the number of columns of the matrix
B.
If
NCOLB=0, the array
B is not referenced.
Constraint:
NCOLB≥0.
- 5: B(LDB,*) – REAL (KIND=nag_wp) arrayInput/Output
-
Note: the second dimension of the array
B
must be at least
max1,NCOLB.
On entry: with
NCOLB>0, the leading
n by
ncolb part of the array
B must contain the matrix to be transformed.
On exit: the leading
n by
ncolb part of the array
B is overwritten by the matrix
QTB.
- 6: LDB – INTEGERInput
On entry: the first dimension of the array
B as declared in the (sub)program from which F02WUF is called.
Constraints:
- if NCOLB>0, LDB≥max1,N;
- otherwise LDB≥1.
- 7: WANTQ – LOGICALInput
On entry: must be .TRUE. if the matrix
Q is required.
If
WANTQ=.FALSE., the array
Q is not referenced.
- 8: Q(LDQ,*) – REAL (KIND=nag_wp) arrayOutput
-
Note: the second dimension of the array
Q
must be at least
max1,N if
WANTQ=.TRUE., and at least
1 otherwise.
On exit: with
WANTQ=.TRUE., the leading
n by
n part of the array
Q will contain the orthogonal matrix
Q. Otherwise the array
Q is not referenced.
- 9: LDQ – INTEGERInput
On entry: the first dimension of the array
Q as declared in the (sub)program from which F02WUF is called.
Constraints:
- if WANTQ=.TRUE., LDQ≥max1,N;
- otherwise LDQ≥1.
- 10: SV(N) – REAL (KIND=nag_wp) arrayOutput
On exit: the array
SV will contain the
n diagonal elements of the matrix
S.
- 11: WANTP – LOGICALInput
On entry: must be .TRUE. if the matrix
PT is required, in which case
PT is overwritten on the array
A, otherwise
WANTP must be .FALSE..
- 12: WORK(*) – REAL (KIND=nag_wp) arrayOutput
-
Note: the dimension of the array
WORK
must be at least
max1,2×N-1 if
NCOLB=0 and
WANTQ=.FALSE. and
WANTP=.FALSE.,
max1,3×N-1 if (
NCOLB=0 and
WANTQ=.FALSE. and
WANTP=.TRUE.) or (
WANTP=.FALSE. and (
NCOLB>0 or
WANTQ=.TRUE.)), and at least
max1,5×N-1 otherwise.
On exit:
WORKN contains the total number of iterations taken by the
QR algorithm.
The rest of the array is used as internal workspace.
- 13: IFAIL – INTEGERInput/Output
-
On entry:
IFAIL must be set to
0,
-1 or 1. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
-1 or 1 is recommended. If the output of error messages is undesirable, then the value
1 is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is
0.
When the value -1 or 1 is used it is essential to test the value of IFAIL on exit.
On exit:
IFAIL=0 unless the routine detects an error or a warning has been flagged (see
Section 6).
6 Error Indicators and Warnings
If on entry
IFAIL=0 or
-1, explanatory error messages are output on the current error message unit (as defined by
X04AAF).
Errors or warnings detected by the routine:
- IFAIL=-1
On entry, | N<0, |
or | LDA<N, |
or | NCOLB<0, |
or | LDB<N and NCOLB>0, |
or | LDQ<N and WANTQ=.TRUE.. |
- IFAIL>0
The QR algorithm has failed to converge in 50×N iterations. In this case SV1,SV2,…,SVIFAIL may not have been found correctly and the remaining singular values may not be the smallest. The matrix R will nevertheless have been factorized as R=QEPT, where E is a bidiagonal matrix with SV1,SV2,…,SVn as the diagonal elements and WORK1,WORK2,…,WORKn-1 as the superdiagonal elements.
This failure is not likely to occur.
7 Accuracy
The computed factors
Q,
S and
P satisfy the relation
where
ε is the
machine precision,
c is a modest function of
n and
. denotes the spectral (two) norm. Note that
A=SV1.
A similar result holds for the computed matrix QTB.
The computed matrix
Q satisfies the relation
where
T is exactly orthogonal and
where
d is a modest function of
n. A similar result holds for
P.
8 Further Comments
For given values of
NCOLB,
WANTQ and
WANTP, the number of floating point operations required is approximately proportional to
n3.
Following the use of this routine the rank of
R may be estimated by a call to the INTEGER FUNCTION
F06KLF. The statement
IRANK = F06KLF(N,SV,1,TOL)
returns the value
k-1 in
IRANK, where
k is the smallest integer for which
SVk<tol×SV1, and
tol is the tolerance supplied in
TOL, so that
IRANK is an estimate of the rank of
S and thus also of
R. If
TOL is supplied as negative then the
machine precision is used in place of
TOL .
9 Example
This example finds the singular value decomposition of the
3 by
3 upper triangular matrix
together with the vector
QTb for the vector
9.1 Program Text
Program Text (f02wufe.f90)
9.2 Program Data
Program Data (f02wufe.d)
9.3 Program Results
Program Results (f02wufe.r)