NAG Library Routine Document

f08vuf  (zggsvp3)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{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:     $\mathbf{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:     $\mathbf{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:     $\mathbf{m}$ – IntegerInput

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

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

5:     $\mathbf{p}$ – IntegerInput

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

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

6:     $\mathbf{n}$ – IntegerInput

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

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

7:     $\mathbf{a}\left(\mathbf{lda},*\right)$ – 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:     $\mathbf{lda}$ – IntegerInput

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

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

9:     $\mathbf{b}\left(\mathbf{ldb},*\right)$ – 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:   $\mathbf{ldb}$ – IntegerInput

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

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

11:   $\mathbf{tola}$ – Real (Kind=nag_wp)Input

12:   $\mathbf{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:   $\mathbf{k}$ – IntegerOutput

14:   $\mathbf{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:   $\mathbf{u}\left(\mathbf{ldu},*\right)$ – 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:   $\mathbf{ldu}$ – IntegerInput

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

Constraints:

• if $\mathbf{jobu}=\text{'U'}$, $\mathbf{ldu}\ge \max \left(1,\mathbf{m}\right)$;
• otherwise $\mathbf{ldu}\ge 1$.

17:   $\mathbf{v}\left(\mathbf{ldv},*\right)$ – 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:   $\mathbf{ldv}$ – IntegerInput

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

Constraints:

• if $\mathbf{jobv}=\text{'V'}$, $\mathbf{ldv}\ge \max \left(1,\mathbf{p}\right)$;
• otherwise $\mathbf{ldv}\ge 1$.

19:   $\mathbf{q}\left(\mathbf{ldq},*\right)$ – 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:   $\mathbf{ldq}$ – IntegerInput

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

Constraints:

• if $\mathbf{jobq}=\text{'Q'}$, $\mathbf{ldq}\ge \max \left(1,\mathbf{n}\right)$;
• otherwise $\mathbf{ldq}\ge 1$.

21:   $\mathbf{iwork}\left(\mathbf{n}\right)$ – Integer arrayWorkspace

22:   $\mathbf{rwork}\left(2\times \mathbf{n}\right)$ – Real (Kind=nag_wp) arrayWorkspace

23:   $\mathbf{tau}\left(\mathbf{n}\right)$ – Complex (Kind=nag_wp) arrayWorkspace

24:   $\mathbf{work}\left(\max \left(1,\mathbf{lwork}\right)\right)$ – Complex (Kind=nag_wp) arrayWorkspace

On exit: if $\mathbf{info}=\mathbf{0}$, the real part of $\mathbf{work}\left(1\right)$ contains the minimum value of lwork required for optimal performance.

25:   $\mathbf{lwork}$ – IntegerInput

On entry: the dimension of the array work as declared in the (sub)program from which f08vuf (zggsvp3) is called.

If $\mathbf{lwork}=-1$, a workspace query is assumed; the routine only calculates the optimal size of the work array, returns this value as the first entry of the work array, and no error message related to lwork is issued.

Suggested value: for optimal performance, lwork must generally be larger than the minimum; increase workspace by, say, $\mathit{nb}\times \left(\mathbf{n}+1\right)$, where $\mathit{nb}$ is the optimal block size

Constraints:

• if $\mathbf{jobv}=\text{'V'}$, $\mathbf{lwork}=-1$ or $\mathbf{lwork}\ge \max \left(\mathbf{n}+1,\mathbf{p},\mathbf{m}\right)$;
• if $\mathbf{jobv}=\text{'N'}$, $\mathbf{lwork}=-1$ or $\mathbf{lwork}\ge \max \left(\mathbf{n}+1,\mathbf{m}\right)$.

26:   $\mathbf{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

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (f08vufe.f90)

10.2

Program Data

Program Data (f08vufe.d)

10.3

Program Results

Program Results (f08vufe.r)