NAG Library Routine Document

F08RNF (ZUNCSD)

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     $\mathrm{JOBU1}$ – CHARACTER(1)Input

On entry:

• if $\mathbf{JOBU1}=\text{'Y'}$, $U_1$ is computed;
• otherwise, $U_1$ is not computed.

2:     $\mathrm{JOBU2}$ – CHARACTER(1)Input

On entry:

• if $\mathbf{JOBU2}=\text{'Y'}$, $U_2$ is computed;
• otherwise, $U_2$ is not computed.

3:     $\mathrm{JOBV1T}$ – CHARACTER(1)Input

On entry:

• if $\mathbf{JOBV1T}=\text{'Y'}$, $V_1^{\mathrm{T}}$ is computed;
• otherwise, $V_1^{\mathrm{T}}$ is not computed.

4:     $\mathrm{JOBV2T}$ – CHARACTER(1)Input

On entry:

• if $\mathbf{JOBV2T}=\text{'Y'}$, $V_2^{\mathrm{T}}$ is computed;
• otherwise, $V_2^{\mathrm{T}}$ is not computed.

5:     $\mathrm{TRANS}$ – CHARACTER(1)Input

On entry:

• if $\mathbf{TRANS}=\text{'T'}$, $X$, $U_1$, $U_2$, $V_1^{\mathrm{T}}$ and $V_2^{\mathrm{T}}$ are stored in row-major order;
• otherwise, $X$, $U_1$, $U_2$, $V_1^{\mathrm{T}}$ and $V_2^{\mathrm{T}}$ are stored in column-major order.

6:     $\mathrm{SIGNS}$ – CHARACTER(1)Input

On entry:

• if $\mathbf{SIGNS}=\text{'O'}$, the lower-left block is made nonpositive (the other convention);
• otherwise, the upper-right block is made nonpositive (the default convention).

7:     $\mathrm{M}$ – INTEGERInput

On entry: $m$, the number of rows and columns in the unitary matrix $X$.

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

8:     $\mathrm{P}$ – INTEGERInput

On entry: $p$, the number of rows in $X_{11}$ and $X_{12}$.

Constraint: $0\le \mathbf{P}\le \mathbf{M}$.

9:     $\mathrm{Q}$ – INTEGERInput

On entry: $q$, the number of columns in $X_{11}$ and $X_{21}$.

Constraint: $0\le \mathbf{Q}\le \mathbf{M}$.

10:   $\mathrm{X11}\left(\mathbf{LDX11},*\right)$ – COMPLEX (KIND=nag_wp) arrayInput/Output

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

On entry: the upper left partition of the unitary matrix $X$ whose CSD is desired.

On exit: contains details of the unitary matrix used in a simultaneous bidiagonalization process.

11:   $\mathrm{LDX11}$ – INTEGERInput

On entry: the first dimension of the array X11 as declared in the (sub)program from which F08RNF (ZUNCSD) is called.

Constraints:

• if $\mathbf{TRANS}=\text{'T'}$, $\mathbf{LDX11}\ge \max \left(1,\mathbf{Q}\right)$;
• otherwise $\mathbf{LDX11}\ge \max \left(1,\mathbf{P}\right)$.

12:   $\mathrm{X12}\left(\mathbf{LDX12},*\right)$ – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array X12 must be at least $\max \left(1,\mathbf{P}\right)$ if $\mathbf{TRANS}=\text{'T'}$, and at least $\mathbf{M}-\mathbf{Q}$ otherwise.

On entry: the upper right partition of the unitary matrix $X$ whose CSD is desired.

On exit: contains details of the unitary matrix used in a simultaneous bidiagonalization process.

13:   $\mathrm{LDX12}$ – INTEGERInput

On entry: the first dimension of the array X12 as declared in the (sub)program from which F08RNF (ZUNCSD) is called.

Constraints:

• if $\mathbf{TRANS}=\text{'T'}$, $\mathbf{LDX12}\ge \max \left(1,\mathbf{M}-\mathbf{Q}\right)$;
• otherwise $\mathbf{LDX12}\ge \max \left(1,\mathbf{P}\right)$.

14:   $\mathrm{X21}\left(\mathbf{LDX21},*\right)$ – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array X21 must be at least $\max \left(1,\mathbf{M}-\mathbf{P}\right)$ if $\mathbf{TRANS}=\text{'T'}$, and at least $\mathbf{Q}$ otherwise.

On entry: the lower left partition of the unitary matrix $X$ whose CSD is desired.

On exit: contains details of the unitary matrix used in a simultaneous bidiagonalization process.

15:   $\mathrm{LDX21}$ – INTEGERInput

On entry: the first dimension of the array X21 as declared in the (sub)program from which F08RNF (ZUNCSD) is called.

Constraints:

• if $\mathbf{TRANS}=\text{'T'}$, $\mathbf{LDX21}\ge \max \left(1,\mathbf{Q}\right)$;
• otherwise $\mathbf{LDX21}\ge \max \left(1,\mathbf{M}-\mathbf{P}\right)$.

16:   $\mathrm{X22}\left(\mathbf{LDX22},*\right)$ – COMPLEX (KIND=nag_wp) arrayInput/Output

Note: the second dimension of the array X22 must be at least $\max \left(1,\mathbf{M}-\mathbf{P}\right)$ if $\mathbf{TRANS}=\text{'T'}$, and at least $\mathbf{M}-\mathbf{Q}$ otherwise.

On entry: the lower right partition of the unitary matrix $X$ CSD is desired.

On exit: contains details of the unitary matrix used in a simultaneous bidiagonalization process.

17:   $\mathrm{LDX22}$ – INTEGERInput

On entry: the first dimension of the array X22 as declared in the (sub)program from which F08RNF (ZUNCSD) is called.

Constraints:

• if $\mathbf{TRANS}=\text{'T'}$, $\mathbf{LDX22}\ge \max \left(1,\mathbf{M}-\mathbf{Q}\right)$;
• otherwise $\mathbf{LDX22}\ge \max \left(1,\mathbf{M}-\mathbf{P}\right)$.

18:   $\mathrm{THETA}\left(\min \left(\mathbf{P},\mathbf{M}-\mathbf{P},\mathbf{Q},\mathbf{M}-\mathbf{Q}\right)\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit: the values ${\theta }_i$ for $i=1,2,\dots ,r$ where $r=\min \left(p,m-p,q,m-q\right)$. The diagonal submatrices $C$ and $S$ of ${\Sigma }_p$ are constructed from these values as

• $C=\mathrm{diag}\left(\cos \left(\mathbf{THETA}\left(1\right)\right),\dots ,\cos \left(\mathbf{THETA}\left(r\right)\right)\right)$ and
• $S=\mathrm{diag}\left(\sin \left(\mathbf{THETA}\left(1\right)\right),\dots ,\sin \left(\mathbf{THETA}\left(r\right)\right)\right)$.

19:   $\mathrm{U1}\left(\mathbf{LDU1},*\right)$ – COMPLEX (KIND=nag_wp) arrayOutput

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

On exit: if $\mathbf{JOBU1}=\text{'Y'}$, U1 contains the $p$ by $p$ unitary matrix $U_1$.

20:   $\mathrm{LDU1}$ – INTEGERInput

On entry: the first dimension of the array U1 as declared in the (sub)program from which F08RNF (ZUNCSD) is called.

Constraint: if $\mathbf{JOBU1}=\text{'Y'}$, $\mathbf{LDU1}\ge \max \left(1,\mathbf{P}\right)$.

21:   $\mathrm{U2}\left(\mathbf{LDU2},*\right)$ – COMPLEX (KIND=nag_wp) arrayOutput

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

On exit: if $\mathbf{JOBU2}=\text{'Y'}$, U2 contains the $m-p$ by $m-p$ unitary matrix $U_2$.

22:   $\mathrm{LDU2}$ – INTEGERInput

On entry: the first dimension of the array U2 as declared in the (sub)program from which F08RNF (ZUNCSD) is called.

Constraint: if $\mathbf{JOBU2}=\text{'Y'}$, $\mathbf{LDU2}\ge \max \left(1,\mathbf{M}-\mathbf{P}\right)$.

23:   $\mathrm{V1T}\left(\mathbf{LDV1T},*\right)$ – COMPLEX (KIND=nag_wp) arrayOutput

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

On exit: if $\mathbf{JOBV1T}=\text{'Y'}$, V1T contains the $q$ by $q$ unitary matrix ${V_1}^{\mathrm{H}}$.

24:   $\mathrm{LDV1T}$ – INTEGERInput

On entry: the first dimension of the array V1T as declared in the (sub)program from which F08RNF (ZUNCSD) is called.

Constraint: if $\mathbf{JOBV1T}=\text{'Y'}$, $\mathbf{LDV1T}\ge \max \left(1,\mathbf{Q}\right)$.

25:   $\mathrm{V2T}\left(\mathbf{LDV2T},*\right)$ – COMPLEX (KIND=nag_wp) arrayOutput

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

On exit: if $\mathbf{JOBV2T}=\text{'Y'}$, V2T contains the $m-q$ by $m-q$ unitary matrix ${V_2}^{\mathrm{H}}$.

26:   $\mathrm{LDV2T}$ – INTEGERInput

On entry: the first dimension of the array V2T as declared in the (sub)program from which F08RNF (ZUNCSD) is called.

Constraint: if $\mathbf{JOBV2T}=\text{'Y'}$, $\mathbf{LDV2T}\ge \max \left(1,\mathbf{M}-\mathbf{Q}\right)$.

27:   $\mathrm{WORK}\left(\max \left(1,\mathbf{LWORK}\right)\right)$ – COMPLEX (KIND=nag_wp) arrayWorkspace

On exit: if $\mathbf{INFO}=\mathbf{0}$, $\mathbf{WORK}\left(1\right)$ returns the optimal LWORK.

If $\mathbf{INFO}>\mathbf{0}$ on exit, $\mathbf{WORK}\left(2:\mathit{r}\right)$ contains the values $\mathrm{PHI}\left(1\right),\dots \mathrm{PHI}\left(\mathit{r}-1\right)$ that, together with ${\mathrm{xref}}^{\arg }\left(1\right),\dots {\mathrm{xref}}^{\arg }\left(\mathit{r}\right)$, define the matrix in intermediate bidiagonal-block form remaining after nonconvergence. INFO specifies the number of nonzero PHI's.

28:   $\mathrm{LWORK}$ – INTEGERInput

On entry:

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.

The minimum workspace required is $$\begin{gathered} \max \left(1,\mathbf{P}\right)+\max \left(1,\mathbf{M}-\mathbf{P}\right)+\max \left(1,\mathbf{Q}\right)+ \\ \max \left(1,\mathbf{M}-\mathbf{Q}\right)+\max \left(1,\mathbf{P},\mathbf{M}-\mathbf{P},\mathbf{Q},\mathbf{M}-\mathbf{Q}\right)+1 \end{gathered}$$; the optimal amount of workspace depends on internal block sizes and the relative problem dimensions.

Constraint:
$\mathbf{LWORK}=-1$ or $$\begin{gathered} \mathbf{LWORK}\ge \max \left(1,\mathbf{P}\right)+\max \left(1,\mathbf{M}-\mathbf{P}\right)+\max \left(1,\mathbf{Q}\right)+ \\ \max \left(1,\mathbf{M}-\mathbf{Q}\right)+\max \left(1,\mathbf{P},\mathbf{M}-\mathbf{P},\mathbf{Q},\mathbf{M}-\mathbf{Q}\right)+1 \end{gathered}$$.

29:   $\mathrm{RWORK}\left(\max \left(1,\mathbf{LRWORK}\right)\right)$ – REAL (KIND=nag_wp) arrayWorkspace

30:   $\mathrm{LRWORK}$ – INTEGERInput

On entry:

If $\mathbf{LRWORK}=-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 LRWORK is issued. Otherwise the required workspace is $5\times \max \left(1,\mathbf{Q}-1\right)+4\times \max \left(1,\mathbf{Q}\right)+\max \left(1,8\times \mathbf{Q}\right)+1$ which equates to $11$ for $\mathbf{Q}=0$, $18$ for $\mathbf{Q}=1$ and $17\times \mathbf{Q}-4$ when $\mathbf{Q}>1$.

Constraint:
$\mathbf{LRWORK}=-1\text{ or }\mathbf{LRWORK}\ge 5\times \max \left(1,\mathbf{Q}-1\right)+4\times \max \left(1,\mathbf{Q}\right)+\max \left(1,8\times \mathbf{Q}\right)+1$.

31:   $\mathrm{IWORK}\left(\mathbf{M}-\min \left(\mathbf{P},\mathbf{M}-\mathbf{P},\mathbf{Q},\mathbf{M}-\mathbf{Q}\right)\right)$ – INTEGER arrayWorkspace

32:   $\mathrm{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}>0$

The Jacobi-type procedure failed to converge during an internal reduction to bidiagonal-block form. The process requires convergence to $\min \left(\mathbf{P},\mathbf{M}-\mathbf{P},\mathbf{Q},\mathbf{M}-\mathbf{Q}\right)$ values, the value of INFO gives the number of converged values.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f08rnfe.f90)

10.2  Program Data

Program Data (f08rnfe.d)

10.3  Program Results

Program Results (f08rnfe.r)