NAG Library Routine Document

F02XEF

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

F02XEF returns all, or part, of the singular value decomposition of a general complex matrix.

2 Specification

SUBROUTINE F02XEF (	M, N, A, LDA, NCOLB, B, LDB, WANTQ, Q, LDQ, SV, WANTP, PH, LDPH, RWORK, CWORK, IFAIL)
INTEGER	M, N, LDA, NCOLB, LDB, LDQ, LDPH, IFAIL
*double precision*	SV(min(M,N)), RWORK(*)
**complex16***	A(LDA,), B(LDB,), Q(LDQ,), PH(LDPH,), CWORK(*)
LOGICAL	WANTQ, WANTP

3 Description

The m by n matrix A is factorized as

A=QDPH,

where

D = S 0 , m>n, D=S, m=n, D= S 0 , m<n,

Q is an m by m unitary matrix, P is an n by n unitary matrix and S is a minm,n by minm,n diagonal matrix with real non-negative diagonal elements, sv1,sv2,…,svminm,n, ordered such that

sv1≥sv2≥⋯≥svminm,n≥0.

The first minm,n columns of Q are the left-hand singular vectors of A, the diagonal elements of S are the singular values of A and the first minm,n columns of P are the right-hand singular vectors of A.

Either or both of the left-hand and right-hand singular vectors of A may be requested and the matrix C given by

C=QHB,

where B is an m by ncolb given matrix, may also be requested.

The routine obtains the singular value decomposition by first reducing A to upper triangular form by means of Householder transformations, from the left when m≥n and from the right when m<n. The upper triangular form is then reduced to bidiagonal form by Givens plane rotations and finally the QR algorithm is used to obtain the singular value decomposition of the bidiagonal form.

Good background descriptions to the singular value decomposition are given in Dongarra et al. (1979), Hammarling (1985) and Wilkinson (1978). Note that this routine is not based on the LINPACK routine CSVDC/ZSVDC.

Note that if K is any unitary diagonal matrix so that

KKH=I,

then

A=QKDPKH

is also a singular value decomposition of A.

4 References

Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) LINPACK Users' Guide SIAM, Philadelphia

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: M – INTEGERInput

On entry: m, the number of rows of the matrix A.

Constraint: M≥0.

If M=0, an immediate return is effected.

2: N – INTEGERInput

On entry: n, the number of columns of the matrix A.

Constraint: N≥0.

If N=0, an immediate return is effected.

3: A(LDA,*) – complex*16 arrayInput/Output

Note: the second dimension of the array A must be at least max1,N.

On entry: the leading m by n part of the array A must contain the matrix A whose singular value decomposition is required.

On exit: if M≥N and WANTQ=.TRUE., the leading m by n part of A will contain the first n columns of the unitary matrix Q.

If M<N and WANTP=.TRUE., the leading m by n part of A will contain the first m rows of the unitary matrix PH.

If M≥N and WANTQ=.FALSE. and WANTP=.TRUE., the leading n by n part of A will contain the first n rows of the unitary matrix PH.

Otherwise the leading m by n part of A is used as internal workspace.

4: LDA – INTEGERInput

On entry: the first dimension of the array A as declared in the (sub)program from which F02XEF is called.

Constraint: LDA≥max1,M.

5: 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.

6: B(LDB,*) – complex*16 arrayInput/Output

Note: the second dimension of the array B must be at least max1,NCOLB.

On entry: if NCOLB>0, the leading m by ncolb part of the array B must contain the matrix to be transformed.

On exit: is overwritten by the m by ncolb matrix QHB.

7: LDB – INTEGERInput

On entry: the first dimension of the array B as declared in the (sub)program from which F02XEF is called.

Constraints:

if NCOLB>0, LDB≥max1,M;
otherwise LDB≥1.

8: WANTQ – LOGICALInput

On entry: must be .TRUE. if the left-hand singular vectors are required.

If WANTQ=.FALSE., the array Q is not referenced.

9: Q(LDQ,*) – complex*16 arrayOutput

Note: the second dimension of the array Q must be at least max1,M if M<N and WANTQ=.TRUE.,, and at least 1 otherwise.

On exit: if M<N and WANTQ=.TRUE., the leading m by m part of the array Q will contain the unitary matrix Q. Otherwise the array Q is not referenced.

10: LDQ – INTEGERInput

On entry: the first dimension of the array Q as declared in the (sub)program from which F02XEF is called.

Constraints:

if M<N and WANTQ=.TRUE., LDQ≥max1,M;
otherwise LDQ≥1.

11: SV(minM,N) – double precision arrayOutput

On exit: the minm,n diagonal elements of the matrix S.

12: WANTP – LOGICALInput

On entry: must be .TRUE. if the right-hand singular vectors are required.

If WANTP=.FALSE., the array PH is not referenced.

13: PH(LDPH,*) – complex*16 arrayOutput

Note: the second dimension of the array PH must be at least max1,N if M≥N and WANTQ=.TRUE. and WANTP=.TRUE., and at least 1 otherwise.

On exit: if M≥N and WANTQ and WANTP are .TRUE., the leading n by n part of the array PH will contain the unitary matrix PH. Otherwise the array PH is not referenced.

14: LDPH – INTEGERInput

On entry: the first dimension of the array PH as declared in the (sub)program from which F02XEF is called.

Constraints:

if M≥N and WANTQ=.TRUE. and WANTP=.TRUE., LDPH≥max1,N;
otherwise LDPH≥1.

15: RWORK(*) – double precision arrayOutput

Note: the dimension of the array RWORK must be at least max1,lrwork, where lrwork must satisfy:

lrwork=2×minM,N-1, when NCOLB=0 and WANTQ and WANTP are .FALSE.,
lrwork=3×minM,N-1, when either NCOLB=0 and WANTQ=.FALSE. and WANTP=.TRUE., or WANTP=.FALSE. and one or both of NCOLB>0 and WANTQ=.TRUE.,
lrwork=5×minM,N-1, otherwise.

On exit: RWORK minM,N contains the total number of iterations taken by the QR algorithm.

The rest of the array is used as workspace.

16: CWORK(*) – complex*16 arrayWorkspace

Note: the dimension of the array CWORK must be at least max1,lcwork, where lcwork must satisfy:

lcwork=N+maxN2,NCOLB, when M≥N and WANTQ and WANTP are both .TRUE.,
lcwork=N+maxN2+N,NCOLB, when M≥N and WANTQ=.TRUE., but WANTP=.FALSE.,
lcwork=N+maxN,NCOLB, when M≥N and WANTQ=.FALSE.,
lcwork=M2+M+max1,M-1, when M<N and WANTP=.TRUE.,
lcwork=M, when M<N and WANTP=.FALSE..

17: 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.

On exit: IFAIL=0 unless the routine detects an error (see Section 6).

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.

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: One or more of the following conditions hold:

M<0;

N<0;

LDA<M;

NCOLB<0;

LDB<M and NCOLB>0;

LDQ<M and M<N and WANTQ=.TRUE.;

LDPH<N and M≥N and WANTQ=.TRUE. and WANTP=.TRUE..

IFAIL>0: The QR algorithm has failed to converge in 50×minm,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 A will nevertheless have been factorized as A=QEPH where the leading minm,n by minm,n part of E is a bidiagonal matrix with SV1 , SV2 , … , SV minm,n as the diagonal elements and RWORK1 , RWORK2 , … , RWORK minm,n - 1 as the superdiagonal elements.

This failure is not likely to occur.

7 Accuracy

The computed factors Q, D and P satisfy the relation

QDPH=A+E,

where

E≤cε A,

ε is the machine precision, c is a modest function of m and n and . denotes the spectral (two) norm. Note that A=sv1.

8 Further Comments

Following the use of this routine the rank of A may be estimated by a call to the INTEGER FUNCTION F06KLF. The statement:

IRANK = F06KLF(MIN(M,N),SV,1,TOL)

returns the value k-1 in IRANK, where k is the smallest integer for which SVk<tol×SV1, where tol is the tolerance supplied in TOL, so that IRANK is an estimate of the rank of S and thus also of A. If TOL is supplied as negative then the machine precision is used in place of TOL.