NAG Library Routine Document

f08vsf  (zggsvp)

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 f08vsf (zggsvp) 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 f08vsf (zggsvp) 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 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:   $\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 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:   $\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 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:   $\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(3\times \mathbf{n},\mathbf{m},\mathbf{p}\right)\right)$ – Complex (Kind=nag_wp) arrayWorkspace

25:   $\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 (f08vsfe.f90)

10.2

Program Data

Program Data (f08vsfe.d)

10.3

Program Results

Program Results (f08vsfe.r)