NAG Library Routine Document

F08VSF (ZGGSVP)

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     JOBU – CHARACTER(1)Input

On entry: if $\mathbf{JOBU}=\text{'U'}$, the unitary matrix $U$ is computed.

If $\mathbf{JOBU}=\text{'N'}$, $U$ is not computed.

Constraint: $\mathbf{JOBU}=\text{'U'}$ or $\text{'N'}$.

2:     JOBV – CHARACTER(1)Input

On entry: if $\mathbf{JOBV}=\text{'V'}$, the unitary matrix $V$ is computed.

If $\mathbf{JOBV}=\text{'N'}$, $V$ is not computed.

Constraint: $\mathbf{JOBV}=\text{'V'}$ or $\text{'N'}$.

3:     JOBQ – CHARACTER(1)Input

On entry: if $\mathbf{JOBQ}=\text{'Q'}$, the unitary matrix $Q$ is computed.

If $\mathbf{JOBQ}=\text{'N'}$, $Q$ is not computed.

Constraint: $\mathbf{JOBQ}=\text{'Q'}$ or $\text{'N'}$.

4:     M – INTEGERInput

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

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

5:     P – INTEGERInput

On entry: $p$, the number of rows of the matrix $B$.

Constraint: $\mathbf{P}\ge 0$.

6:     N – INTEGERInput

On entry: $n$, the number of columns of the matrices $A$ and $B$.

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

7:     A(LDA,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array A must be at least $\max \left(1,\mathbf{N}\right)$.

On entry: the $m$ by $n$ matrix $A$.

On exit: contains the triangular (or trapezoidal) matrix described in Section 3.

8:     LDA – INTEGERInput

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

Constraint: $\mathbf{LDA}\ge \max \left(1,\mathbf{M}\right)$.

9:     B(LDB,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array B must be at least $\max \left(1,\mathbf{N}\right)$.

On entry: the $p$ by $n$ matrix $B$.

On exit: contains the triangular matrix described in Section 3.

10:   LDB – INTEGERInput

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

Constraint: $\mathbf{LDB}\ge \max \left(1,\mathbf{P}\right)$.

11:   TOLA – REAL (KIND=nag_wp)Input

12:   TOLB – REAL (KIND=nag_wp)Input

On entry: TOLA and TOLB are the thresholds to determine the effective numerical rank of matrix $B$ and a subblock of $A$. Generally, they are set to

$$\begin{array}{c}\mathbf{TOLA}=\max \left(\mathbf{M},\mathbf{N}\right)‖A‖\epsilon \text{,}\\ \mathbf{TOLB}=\max \left(\mathbf{P},\mathbf{N}\right)‖B‖\epsilon \text{,}\end{array}$$

where $\epsilon$ is the machine precision.

The size of TOLA and TOLB may affect the size of backward errors of the decomposition.

13:   K – INTEGEROutput

14:   L – INTEGEROutput

On exit: K and L specify the dimension of the subblocks $k$ and $l$ as described in Section 3; $\left(k+l\right)$ is the effective numerical rank of ${\left(\begin{array}{cc}{\mathbf{A}}^{\mathrm{T}}& {\mathbf{B}}^{\mathrm{T}}\end{array}\right)}^{\mathrm{T}}$.

15:   U(LDU,$*$) – COMPLEX (KIND=nag_wp) arrayOutput

Note: the second dimension of the array U must be at least $\max \left(1,\mathbf{M}\right)$ if $\mathbf{JOBU}=\text{'U'}$, and at least $1$ otherwise.

On exit: if $\mathbf{JOBU}=\text{'U'}$, U contains the unitary matrix $U$.

If $\mathbf{JOBU}=\text{'N'}$, U is not referenced.

16:   LDU – INTEGERInput

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

Constraints:

• if $\mathbf{JOBU}=\text{'U'}$, $\mathbf{LDU}\ge \max \left(1,\mathbf{M}\right)$;
• otherwise $\mathbf{LDU}\ge 1$.

17:   V(LDV,$*$) – COMPLEX (KIND=nag_wp) arrayOutput

Note: the second dimension of the array V must be at least $\max \left(1,\mathbf{P}\right)$ if $\mathbf{JOBV}=\text{'V'}$, and at least $1$ otherwise.

On exit: if $\mathbf{JOBV}=\text{'V'}$, V contains the unitary matrix $V$.

If $\mathbf{JOBV}=\text{'N'}$, V is not referenced.

18:   LDV – INTEGERInput

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

Constraints:

• if $\mathbf{JOBV}=\text{'V'}$, $\mathbf{LDV}\ge \max \left(1,\mathbf{P}\right)$;
• otherwise $\mathbf{LDV}\ge 1$.

19:   Q(LDQ,$*$) – COMPLEX (KIND=nag_wp) arrayOutput

Note: the second dimension of the array Q must be at least $\max \left(1,\mathbf{N}\right)$ if $\mathbf{JOBQ}=\text{'Q'}$, and at least $1$ otherwise.

On exit: if $\mathbf{JOBQ}=\text{'Q'}$, Q contains the unitary matrix $Q$.

If $\mathbf{JOBQ}=\text{'N'}$, Q is not referenced.

20:   LDQ – INTEGERInput

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

Constraints:

• if $\mathbf{JOBQ}=\text{'Q'}$, $\mathbf{LDQ}\ge \max \left(1,\mathbf{N}\right)$;
• otherwise $\mathbf{LDQ}\ge 1$.

21:   IWORK(N) – INTEGER arrayWorkspace

22:   RWORK($2\times \mathbf{N}$) – REAL (KIND=nag_wp) arrayWorkspace

23:   TAU(N) – COMPLEX (KIND=nag_wp) arrayWorkspace

24:   WORK($\max \left(3\times \mathbf{N},\mathbf{M},\mathbf{P}\right)$) – COMPLEX (KIND=nag_wp) arrayWorkspace

25:   INFO – INTEGEROutput

On exit: $\mathbf{INFO}=0$ unless the routine detects an error (see Section 6).

6  Error Indicators and Warnings

$\mathbf{INFO}<0$

If $\mathbf{INFO}=-i$, argument $i$ had an illegal value. An explanatory message is output, and execution of the program is terminated.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (f08vsfe.f90)

9.2  Program Data

Program Data (f08vsfe.d)

9.3  Program Results

Program Results (f08vsfe.r)