NAG Library Routine Document

F02WDF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     M – INTEGERInput

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

Constraint: $\mathbf{M}\ge \mathbf{N}$.

2:     N – INTEGERInput

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

Constraint: $1\le \mathbf{N}\le \mathbf{M}$.

3:     A(LDA,N) – 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 8.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: $\mathbf{LDA}\ge \mathbf{M}$.

5:     WANTB – LOGICALInput

On entry: must be .TRUE. if $Q^{\mathrm{T}}b$ or $Q_1^{\mathrm{T}}b$ is required.

If on entry $\mathbf{WANTB}=\mathrm{.FALSE.}$, B is not referenced.

6:     B(M) – 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 $Q_1^{\mathrm{T}}b$ if SVD is returned as .TRUE. and $Q^{\mathrm{T}}b$ 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\times {10}^{-4}$. See Section 8.3 for a description of how TOL is used to determine rank.

If TOL is outside the range $\left(\epsilon ,1.0\right)$, where $\epsilon$ is the machine precision, the value $\epsilon$ 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, $\mathbf{SVD}=\mathrm{.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:   Z(N) – REAL (KIND=nag_wp) arrayOutput

On exit: the $n$-element vector Z contains some details of the Householder transformations. See Section 8.4 for further information.

11:   SV(N) – 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 $\mathbf{WANTR}=\mathrm{.FALSE.}$, R is not referenced.

13:   R(LDR,N) – REAL (KIND=nag_wp) arrayOutput

Note: the second dimension of the array R must be at least $\mathbf{N}$ if $\mathbf{WANTR}=\mathrm{.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 $\mathbf{WANTR}=\mathrm{.TRUE.}$, $\mathbf{LDR}\ge \mathbf{N}$;
• otherwise $1$.

15:   WANTPT – LOGICALInput

On entry: must be .TRUE. if the orthogonal matrix $P^{\mathrm{T}}$ 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:   PT(LDPT,N) – 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 $P^{\mathrm{T}}$.

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: $\mathbf{LDPT}\ge \mathbf{N}$.

18:   WORK(LWORK) – REAL (KIND=nag_wp) arrayOutput

On exit: if SVD is returned as .FALSE., $\mathbf{WORK}\left(1\right)$ contains the condition number ${‖U‖}_E{‖U^{-1}‖}_E$ of the upper triangular matrix $U$.

If SVD is returned as .TRUE., $\mathbf{WORK}\left(1\right)$ 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: $\mathbf{LWORK}\ge 3\times \mathbf{N}$.

20:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ 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\text{ 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 $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

On entry,	$\mathbf{N}<1$,
or	$\mathbf{M}<\mathbf{N}$,
or	$\mathbf{LDA}<\mathbf{M}$,
or	$\mathbf{LDR}<\mathbf{N}$ when $\mathbf{WANTR}=\mathrm{.TRUE.}$,
or	$\mathbf{LDPT}<\mathbf{N}$
or	$\mathbf{LWORK}<3\times \mathbf{N}$.

(The routine only checks LDR if WANTR is supplied as .TRUE..)

$\mathbf{IFAIL}>1$

The $QR$ algorithm has failed to converge to the singular values in $50\times \mathbf{N}$ iterations. In this case $\mathbf{SV}\left(1\right),\mathbf{SV}\left(2\right),\dots ,\mathbf{SV}\left(\mathbf{IFAIL}-1\right)$ 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=Q_{1}C{P}^{\mathrm{T}}$, where $C$ is an upper bidiagonal matrix with $\mathbf{SV}\left(1\right),\mathbf{SV}\left(2\right),\dots ,\mathbf{SV}\left(n\right)$ as its diagonal elements and $\mathbf{WORK}\left(2\right),\mathbf{WORK}\left(3\right),\dots ,\mathbf{WORK}\left(n\right)$ as its superdiagonal elements.

This failure cannot occur if SVD is returned as .FALSE. and in any case is extremely rare.

7  Accuracy

8  Further Comments

8.1  Timing

8.2  General Remarks

8.3  Determining the Rank of $A$

8.4  Storage Details of the $QU$ Factorization

9  Example

9.1  Program Text

Program Text (f02wdfe.f90)

9.2  Program Data

Program Data (f02wdfe.d)

9.3  Program Results

Program Results (f02wdfe.r)