F02WDF (PDF version)
F02 Chapter Contents
F02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

F02WDF

Note:  before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

F02WDF returns the Householder QU factorization of a real rectangular m by n mn matrix A. Further, on request or if A is not of full rank, part or all of the singular value decomposition of A is returned.

2  Specification

SUBROUTINE F02WDF ( M, N, A, LDA, WANTB, B, TOL, SVD, IRANK, Z, SV, WANTR, R, LDR, WANTPT, PT, LDPT, WORK, LWORK, IFAIL)
INTEGER  M, N, LDA, IRANK, LDR, LDPT, LWORK, IFAIL
REAL (KIND=nag_wp)  A(LDA,N), B(M), TOL, Z(N), SV(N), R(LDR,N), PT(LDPT,N), WORK(LWORK)
LOGICAL  WANTB, SVD, WANTR, WANTPT

3  Description

The real m by n mn matrix A is first factorized as
A=Q U 0 ,  
where Q is an m by m orthogonal matrix and U is an n by n upper triangular matrix.
If either U is singular or SVD is supplied as .TRUE., then the singular value decomposition (SVD) of U is obtained so that U is factorized as
U=RDPT,  
where R and P are n by n orthogonal matrices and D is the n by n diagonal matrix
D=diagsv1,sv2,,svn,  
with sv1sv2svn0.
Note that the SVD of A is then given by
A=Q1 D 0 PT  where  Q1=Q R 0 0 I ,  
the diagonal elements of D being the singular values of A.
The option to form a vector QTb, or if appropriate Q1T b, is also provided.
The rank of the matrix A, based upon a user-supplied parameter TOL, is also returned.
The QU factorization of A is obtained by Householder transformations. To obtain the SVD of U the matrix is first reduced to bidiagonal form by means of plane rotations and then the QR algorithm is used to obtain the SVD of the bidiagonal form.

4  References

Wilkinson J H (1978) Singular Value Decomposition – Basic Aspects Numerical Software – Needs and Availability (ed D A H Jacobs) Academic Press

5  Parameters

1:     M – INTEGERInput
On entry: m, the number of rows of the matrix A.
Constraint: MN.
2:     N – INTEGERInput
On entry: n, the number of columns of the matrix A.
Constraint: 1NM.
3:     ALDAN – REAL (KIND=nag_wp) arrayInput/Output
On entry: the leading m by n part of A must contain the matrix to be factorized.
On exit: the leading m by n part of A, together with the n-element vector Z, contains details of the Householder QU factorization.
Details of the storage of the QU factorization are given in Section 9.4.
4:     LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which F02WDF is called.
Constraint: LDAM.
5:     WANTB – LOGICALInput
On entry: must be .TRUE. if QTb or Q1Tb is required.
If on entry WANTB=.FALSE., B is not referenced.
6:     BM – REAL (KIND=nag_wp) arrayInput/Output
On entry: if WANTB is supplied as .TRUE., B must contain the m element vector b. Otherwise, B is not referenced.
On exit: contains Q1Tb if SVD is returned as .TRUE. and QTb if SVD is returned as .FALSE..
7:     TOL – REAL (KIND=nag_wp)Input
On entry: must specify a relative tolerance to be used to determine the rank of A. TOL should be chosen as approximately the largest relative error in the elements of A. For example, if the elements of A are correct to about 4 significant figures, TOL should be set to about 5×10-4. See Section 9.3 for a description of how TOL is used to determine rank.
If TOL is outside the range ε,1.0, where ε is the machine precision, the value ε is used in place of TOL. For most problems this is unreasonably small.
8:     SVD – LOGICALInput/Output
On entry: must be .TRUE. if the singular values are to be found even if A is of full rank.
If before entry, SVD=.FALSE. and A is determined to be of full rank, only the QU factorization of A is computed.
On exit: is returned as .FALSE. if only the QU factorization of A has been obtained and is returned as .TRUE. if the singular values of A have been obtained.
9:     IRANK – INTEGEROutput
On exit: returns the rank of the matrix A. (It should be noted that it is possible for IRANK to be returned as n and SVD to be returned as .TRUE., even if SVD was supplied as .FALSE.. This means that the matrix U only just failed the test for nonsingularity.)
10:   ZN – REAL (KIND=nag_wp) arrayOutput
On exit: the n-element vector Z contains some details of the Householder transformations. See Section 9.4 for further information.
11:   SVN – REAL (KIND=nag_wp) arrayOutput
On exit: if SVD is returned as .TRUE., SV contains the n singular values of A arranged in descending order.
12:   WANTR – LOGICALInput
On entry: must be .TRUE. if the orthogonal matrix R is required when the singular values are computed.
If on entry WANTR=.FALSE., R is not referenced.
13:   RLDRN – REAL (KIND=nag_wp) arrayOutput
Note: the second dimension of the array R must be at least N if WANTR=.TRUE., and at least 1 otherwise.
On exit: if SVD is returned as .TRUE. and WANTR was supplied as .TRUE., the leading n by n part of R will contain the left-hand orthogonal matrix of the SVD of U.
14:   LDR – INTEGERInput
On entry: the first dimension of the array R as declared in the (sub)program from which F02WDF is called.
Constraints:
  • if WANTR=.TRUE., LDRN;
  • otherwise LDR1.
15:   WANTPT – LOGICALInput
On entry: must be .TRUE. if the orthogonal matrix PT is required when the singular values are computed.
Note that if SVD is returned as .TRUE., PT is referenced even if WANTPT is supplied as .FALSE., but see parameter PT.
16:   PTLDPTN – REAL (KIND=nag_wp) arrayOutput
On exit: if SVD is returned as .TRUE. and WANTPT was supplied as .TRUE., the leading n by n part of PT contains the orthogonal matrix PT.
If SVD is returned as .TRUE., but WANTPT was supplied as .FALSE., the leading n by n part of PT is used for internal workspace.
17:   LDPT – INTEGERInput
On entry: the first dimension of the array PT as declared in the (sub)program from which F02WDF is called.
Constraint: LDPTN.
18:   WORKLWORK – REAL (KIND=nag_wp) arrayOutput
On exit: if SVD is returned as .FALSE., WORK1 contains the condition number UEU-1E of the upper triangular matrix U.
If SVD is returned as .TRUE., WORK1 will contain the total number of iterations taken by the QR algorithm.
The rest of the array is used as workspace and so contains no meaningful information.
19:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which F02WDF is called.
Constraint: LWORK3×N.
20:   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<1,
orM<N,
orLDA<M,
orLDR<N when WANTR=.TRUE.,
orLDPT<N 
orLWORK<3×N.
(The routine only checks LDR if WANTR is supplied as .TRUE..)
IFAIL>1
The QR algorithm has failed to converge to the singular values in 50×N iterations. In this case SV1,SV2,,SVIFAIL-1 may not have been correctly found and the remaining singular values may not be the smallest singular values. The matrix A has nevertheless been factorized as A=Q1CPT, where C is an upper bidiagonal matrix with SV1,SV2,,SVn as its diagonal elements and WORK2,WORK3,,WORKn as its superdiagonal elements.
This failure cannot occur if SVD is returned as .FALSE. and in any case is extremely rare.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.8 in the Essential Introduction for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.7 in the Essential Introduction for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

The computed factors Q, U, R, D and PT satisfy the relations
Q U 0 =A+E,  
Q R 0 0 I D 0 PT=A+F  
where E2c1ε A2, F2c2ε A2,
ε being the machine precision and c1 and c2 are modest functions of m and n. Note that A2=sv1.

8  Parallelism and Performance

F02WDF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
F02WDF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9  Further Comments

9.1  Timing

The time taken by F02WDF to obtain the Householder QU factorization is approximately proportional to n23m-n.
The additional time taken to obtain the singular value decomposition is approximately proportional to n3, where the constant of proportionality depends upon whether or not the orthogonal matrices R and PT are required.

9.2  General Remarks

Singular vectors associated with a zero or multiple singular value, are not uniquely determined, even in exact arithmetic, and very different results may be obtained if they are computed on different machines.
Unless otherwise stated in the Users' Note for your implementation, the routine may be called with the same array for parameters Z and SV, in which case, if SVD is returned as .TRUE., the singular values will overwrite the original contents of Z; also, if WANTPT=.FALSE., it may be called with the same array for parameters R and PT. However this is not standard Fortran, and may not work on all systems.
This routine is called by the least squares routine F04JGF.

9.3  Determining the Rank of A

Following the QU factorization of A, if SVD is supplied as .FALSE., then the condition number of U given by
CU=UF U-1F  
is found, where .F denotes the Frobenius norm, and if CU is such that
CU×TOL>1.0  
then U is regarded as singular and the singular values of A are computed. If this test is not satisfied, then the rank of A is set to n. Note that if SVD is supplied as .TRUE. then this test is omitted.
When the singular values are computed, then the rank of A, r, is returned as the largest integer such that
svr>TOL×sv1,  
unless sv1=0 in which case r is returned as zero. That is, singular values which satisfy sviTOL×sv1 are regarded as negligible because relative perturbations of order TOL can make such singular values zero.

9.4  Storage Details of the QU Factorization

The kth Householder transformation matrix, Tk, used in the QU factorization is chosen to introduce the zeros into the kth column and has the form
Tk=I-2 0 u 0 uT ,  uTu=1,  
where u is an m-k+1 element vector.
In place of u the routine actually computes the vector z given by
z=2u1u.  
The first element of z is stored in Zk and the remaining elements of z are overwritten on the subdiagonal elements of the kth column of A. The upper triangular matrix U is overwritten on the n by n upper triangular part of A.

10  Example

This example obtains the rank and the singular value decomposition of the 6 by 4 matrix A given by
A= 22.25 31.75 -38.25 65.50 20.00 26.75 28.50 -26.50 -15.25 24.25 27.75 18.50 27.25 10.00 3.00 2.00 -17.25 -30.75 11.25 7.50 17.25 30.75 -11.25 -7.50  
the value TOL to be taken as 5×10-4.

10.1  Program Text

Program Text (f02wdfe.f90)

10.2  Program Data

Program Data (f02wdfe.d)

10.3  Program Results

Program Results (f02wdfe.r)


F02WDF (PDF version)
F02 Chapter Contents
F02 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2015