NAG Library Routine Document

F08YSF (ZTGSJA)

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     JOBU – CHARACTER(1)Input

On entry: if $\mathbf{JOBU}=\text{'U'}$, U must contain a unitary matrix $U_1$ on entry, and the product $U_{1}U$ is returned.

If $\mathbf{JOBU}=\text{'I'}$, U is initialized to the unit matrix, and the unitary matrix $U$ is returned.

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

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

2:     JOBV – CHARACTER(1)Input

On entry: if $\mathbf{JOBV}=\text{'V'}$, V must contain a unitary matrix $V_1$ on entry, and the product $V_{1}V$ is returned.

If $\mathbf{JOBV}=\text{'I'}$, V is initialized to the unit matrix, and the unitary matrix $V$ is returned.

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

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

3:     JOBQ – CHARACTER(1)Input

On entry: if $\mathbf{JOBQ}=\text{'Q'}$, Q must contain a unitary matrix $Q_1$ on entry, and the product $Q_{1}Q$ is returned.

If $\mathbf{JOBQ}=\text{'I'}$, Q is initialized to the unit matrix, and the unitary matrix $Q$ is returned.

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

Constraint: $\mathbf{JOBQ}=\text{'Q'}$, $\text{'I'}$ 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:     K – INTEGERInput

8:     L – INTEGERInput

On entry: K and L specify the sizes, $k$ and $l$, of the subblocks of $A$ and $B$, whose GSVD is to be computed by F08YSF (ZTGSJA).

9:     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: if $m-k-l\ge 0$, $\mathbf{A}\left(1:k+l,n-k-l+1:n\right)$ contains the $\left(k+l\right)$ by $\left(k+l\right)$ upper triangular matrix $R$.

If $m-k-l<0$, $\mathbf{A}\left(1:m,n-k-l+1:n\right)$ contains the first $m$ rows of the $\left(k+l\right)$ by $\left(k+l\right)$ upper triangular matrix $R$, and the submatrix $R_{33}$ is returned in $\mathbf{B}\left(m-k+1:l,n+m-k-l+1:n\right)$.

10:   LDA – INTEGERInput

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

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

11:   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: if $m-k-l<0$, $\mathbf{B}\left(m-k+1:l,n+m-k-l+1:n\right)$ contains the submatrix $R_{33}$ of $R$.

12:   LDB – INTEGERInput

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

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

13:   TOLA – REAL (KIND=nag_wp)Input

14:   TOLB – REAL (KIND=nag_wp)Input

On entry: TOLA and TOLB are the convergence criteria for the Jacobi–Kogbetliantz iteration procedure. Generally, they should be the same as used in the preprocessing step performed by F08VSF (ZGGSVP), say

$$\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.

15:   ALPHA(N) – REAL (KIND=nag_wp) arrayOutput

On exit: see the description of BETA.

16:   BETA(N) – REAL (KIND=nag_wp) arrayOutput

On exit: ALPHA and BETA contain the generalized singular value pairs of $A$ and $B$;

• $\mathbf{ALPHA}\left(\mathit{i}\right)=1$, $\mathbf{BETA}\left(\mathit{i}\right)=0$, for $\mathit{i}=1,2,\dots ,k$, and
• if $m-k-l\ge 0$, $\mathbf{ALPHA}\left(\mathit{i}\right)={\alpha }_{\mathit{i}}$, $\mathbf{BETA}\left(\mathit{i}\right)={\beta }_{\mathit{i}}$, for $\mathit{i}=k+1,\dots ,k+l$, or
• if $m-k-l<0$, $\mathbf{ALPHA}\left(\mathit{i}\right)={\alpha }_{\mathit{i}}$, $\mathbf{BETA}\left(\mathit{i}\right)={\beta }_{\mathit{i}}$, for $\mathit{i}=k+1,\dots ,m$ and $\mathbf{ALPHA}\left(\mathit{i}\right)=0$, $\mathbf{BETA}\left(\mathit{i}\right)=1$, for $\mathit{i}=m+1,\dots ,k+l$.

Furthermore, if $k+l<n$, $\mathbf{ALPHA}\left(\mathit{i}\right)=\mathbf{BETA}\left(\mathit{i}\right)=0$, for $\mathit{i}=k+l+1,\dots ,n$.

17:   U(LDU,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output

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

On entry: if $\mathbf{JOBU}=\text{'U'}$, U must contain an $m$ by $m$ matrix $U_1$ (usually the unitary matrix returned by F08VSF (ZGGSVP)).

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

If $\mathbf{JOBU}=\text{'U'}$, U contains the product $U_{1}U$.

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

18:   LDU – INTEGERInput

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

Constraints:

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

19:   V(LDV,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output

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

On entry: if $\mathbf{JOBV}=\text{'V'}$, V must contain an $p$ by $p$ matrix $V_1$ (usually the unitary matrix returned by F08VSF (ZGGSVP)).

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

If $\mathbf{JOBV}=\text{'V'}$, V contains the product $V_{1}V$.

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

20:   LDV – INTEGERInput

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

Constraints:

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

21:   Q(LDQ,$*$) – COMPLEX (KIND=nag_wp) arrayInput/Output

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

On entry: if $\mathbf{JOBQ}=\text{'Q'}$, Q must contain an $n$ by $n$ matrix $Q_1$ (usually the unitary matrix returned by F08VSF (ZGGSVP)).

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

If $\mathbf{JOBQ}=\text{'Q'}$, Q contains the product $Q_{1}Q$.

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

22:   LDQ – INTEGERInput

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

Constraints:

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

23:   WORK($2\times \mathbf{N}$) – COMPLEX (KIND=nag_wp) arrayWorkspace

24:   NCYCLE – INTEGEROutput

On exit: the number of cycles required for convergence.

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.

$\mathbf{INFO}=1$

The procedure does not converge after $40$ cycles.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (f08ysfe.f90)

9.2  Program Data

Program Data (f08ysfe.d)

9.3  Program Results

Program Results (f08ysfe.r)