NAG Library Function Document

1Purpose

nag_zuncsd (f08rnc) computes the CS decomposition of a complex $m$ by $m$ unitary matrix $X$, partitioned into a $2$ by $2$ array of submatrices.

2Specification

 #include #include
 void nag_zuncsd (Nag_OrderType order, Nag_ComputeUType jobu1, Nag_ComputeUType jobu2, Nag_ComputeVTType jobv1t, Nag_ComputeVTType jobv2t, Nag_SignsType signs, Integer m, Integer p, Integer q, Complex x11[], Integer pdx11, Complex x12[], Integer pdx12, Complex x21[], Integer pdx21, Complex x22[], Integer pdx22, double theta[], Complex u1[], Integer pdu1, Complex u2[], Integer pdu2, Complex v1t[], Integer pdv1t, Complex v2t[], Integer pdv2t, NagError *fail)

3Description

The $m$ by $m$ unitary matrix $X$ is partitioned as
 $X= X11 X12 X21 X22$
where ${X}_{11}$ is a $p$ by $q$ submatrix and the dimensions of the other submatrices ${X}_{12}$, ${X}_{21}$ and ${X}_{22}$ are such that $X$ remains $m$ by $m$.
The CS decomposition of $X$ is $X=U{\Sigma }_{p}{V}^{\mathrm{T}}$ where $U$, $V$ and ${\Sigma }_{p}$ are $m$ by $m$ matrices, such that
 $U= U1 0 0 U2$
is a unitary matrix containing the $p$ by $p$ unitary matrix ${U}_{1}$ and the $\left(m-p\right)$ by $\left(m-p\right)$ unitary matrix ${U}_{2}$;
 $V= V1 0 0 V2$
is a unitary matrix containing the $q$ by $q$ unitary matrix ${V}_{1}$ and the $\left(m-q\right)$ by $\left(m-q\right)$ unitary matrix ${V}_{2}$; and
 $Σp= I11 0 0 0 C 0 0 -S 0 0 0 -I12 0 0 I22 0 0 S C 0 0 I21 0 0$
contains the $r$ by $r$ non-negative diagonal submatrices $C$ and $S$ satisfying ${C}^{2}+{S}^{2}=I$, where $r=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(p,m-p,q,m-q\right)$ and the top left partition is $p$ by $q$.
The identity matrix ${I}_{11}$ is of order $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(p,q\right)-r$ and vanishes if $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(p,q\right)=r$.
The identity matrix ${I}_{12}$ is of order $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(p,m-q\right)-r$ and vanishes if $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(p,m-q\right)=r$.
The identity matrix ${I}_{21}$ is of order $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m-p,q\right)-r$ and vanishes if $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m-p,q\right)=r$.
The identity matrix ${I}_{22}$ is of order $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m-p,m-q\right)-r$ and vanishes if $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(m-p,m-q\right)=r$.
In each of the four cases $r=p,q,m-p,m-q$ at least two of the identity matrices vanish.
The indicated zeros represent augmentations by additional rows or columns (but not both) to the square diagonal matrices formed by ${I}_{ij}$ and $C$ or $S$.
${\Sigma }_{p}$ does not need to be stored in full; it is sufficient to return only the values ${\theta }_{i}$ for $i=1,2,\dots ,r$ where ${C}_{ii}=\mathrm{cos}\left({\theta }_{i}\right)$ and ${S}_{ii}=\mathrm{sin}\left({\theta }_{i}\right)$.
The algorithm used to perform the complete $CS$ decomposition is described fully in Sutton (2009) including discussions of the stability and accuracy of the algorithm.
Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (2012) Matrix Computations (4th Edition) Johns Hopkins University Press, Baltimore
Sutton B D (2009) Computing the complete $CS$ decomposition Numerical Algorithms (Volume 50) 1017–1398 Springer US 33–65 http://dx.doi.org/10.1007/s11075-008-9215-6

5Arguments

1:    $\mathbf{order}$Nag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.3.1.3 in How to Use the NAG Library and its Documentation for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or $\mathrm{Nag_ColMajor}$.
2:    $\mathbf{jobu1}$Nag_ComputeUTypeInput
On entry:
• if ${\mathbf{jobu1}}=\mathrm{Nag_AllU}$, ${U}_{1}$ is computed;
• if ${\mathbf{jobu1}}=\mathrm{Nag_NotU}$, ${U}_{1}$ is not computed.
Constraint: ${\mathbf{jobu1}}=\mathrm{Nag_AllU}$ or $\mathrm{Nag_NotU}$.
3:    $\mathbf{jobu2}$Nag_ComputeUTypeInput
On entry:
• if ${\mathbf{jobu2}}=\mathrm{Nag_AllU}$, ${U}_{2}$ is computed;
• if ${\mathbf{jobu2}}=\mathrm{Nag_NotU}$, ${U}_{2}$ is not computed.
Constraint: ${\mathbf{jobu2}}=\mathrm{Nag_AllU}$ or $\mathrm{Nag_NotU}$.
4:    $\mathbf{jobv1t}$Nag_ComputeVTTypeInput
On entry:
• if ${\mathbf{jobv1t}}=\mathrm{Nag_AllVT}$, ${V}_{1}^{\mathrm{T}}$ is computed;
• if ${\mathbf{jobv1t}}=\mathrm{Nag_NotVT}$, ${V}_{1}^{\mathrm{T}}$ is not computed.
Constraint: ${\mathbf{jobv1t}}=\mathrm{Nag_AllVT}$ or $\mathrm{Nag_NotVT}$.
5:    $\mathbf{jobv2t}$Nag_ComputeVTTypeInput
On entry:
• if ${\mathbf{jobv2t}}=\mathrm{Nag_AllVT}$, ${V}_{2}^{\mathrm{T}}$ is computed;
• if ${\mathbf{jobv2t}}=\mathrm{Nag_NotVT}$, ${V}_{2}^{\mathrm{T}}$ is not computed.
Constraint: ${\mathbf{jobv2t}}=\mathrm{Nag_AllVT}$ or $\mathrm{Nag_NotVT}$.
6:    $\mathbf{signs}$Nag_SignsTypeInput
On entry:
• if ${\mathbf{signs}}=\mathrm{Nag_LowerMinus}$, the lower-left block is made nonpositive (the other convention);
• if ${\mathbf{signs}}=\mathrm{Nag_UpperMinus}$, the upper-right block is made nonpositive (the default convention).
Constraint: ${\mathbf{signs}}=\mathrm{Nag_LowerMinus}$ or $\mathrm{Nag_UpperMinus}$.
7:    $\mathbf{m}$IntegerInput
On entry: $m$, the number of rows and columns in the unitary matrix $X$.
Constraint: ${\mathbf{m}}\ge 0$.
8:    $\mathbf{p}$IntegerInput
On entry: $p$, the number of rows in ${X}_{11}$ and ${X}_{12}$.
Constraint: $0\le {\mathbf{p}}\le {\mathbf{m}}$.
9:    $\mathbf{q}$IntegerInput
On entry: $q$, the number of columns in ${X}_{11}$ and ${X}_{21}$.
Constraint: $0\le {\mathbf{q}}\le {\mathbf{m}}$.
10:  $\mathbf{x11}\left[\mathit{dim}\right]$ComplexInput/Output
Note: the dimension, dim, of the array x11 must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx11}}×{\mathbf{p}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx11}}×{\mathbf{q}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{x11}}\left[\left(j-1\right)×{\mathbf{pdx11}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{x11}}\left[\left(i-1\right)×{\mathbf{pdx11}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
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:  $\mathbf{pdx11}$IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array x11.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx11}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{q}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx11}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$.
12:  $\mathbf{x12}\left[\mathit{dim}\right]$ComplexInput/Output
Note: the dimension, dim, of the array x12 must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx12}}×{\mathbf{p}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx12}}×\left({\mathbf{m}}-{\mathbf{q}}\right)\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{x12}}\left[\left(j-1\right)×{\mathbf{pdx12}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{x12}}\left[\left(i-1\right)×{\mathbf{pdx12}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
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:  $\mathbf{pdx12}$IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array x12.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx12}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{q}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx12}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$.
14:  $\mathbf{x21}\left[\mathit{dim}\right]$ComplexInput/Output
Note: the dimension, dim, of the array x21 must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx21}}×\left({\mathbf{m}}-{\mathbf{p}}\right)\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx21}}×{\mathbf{q}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{x21}}\left[\left(j-1\right)×{\mathbf{pdx21}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{x21}}\left[\left(i-1\right)×{\mathbf{pdx21}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
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:  $\mathbf{pdx21}$IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array x21.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx21}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{q}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx21}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{p}}\right)$.
16:  $\mathbf{x22}\left[\mathit{dim}\right]$ComplexInput/Output
Note: the dimension, dim, of the array x22 must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx22}}×\left({\mathbf{m}}-{\mathbf{p}}\right)\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx22}}×\left({\mathbf{m}}-{\mathbf{q}}\right)\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{x22}}\left[\left(j-1\right)×{\mathbf{pdx22}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{x22}}\left[\left(i-1\right)×{\mathbf{pdx22}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
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:  $\mathbf{pdx22}$IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array x22.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx22}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{q}}\right)$;
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx22}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{p}}\right)$.
18:  $\mathbf{theta}\left[\mathit{dim}\right]$doubleOutput
Note: the dimension, dim, of the array theta must be at least $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{p}},{\mathbf{m}}-{\mathbf{p}},{\mathbf{q}},{\mathbf{m}}-{\mathbf{q}}\right)$.
On exit: the values ${\theta }_{i}$ for $i=1,2,\dots ,r$ where $r=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\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(\mathrm{cos}\left({\mathbf{theta}}\left[0\right]\right),\dots ,\mathrm{cos}\left({\mathbf{theta}}\left[r-1\right]\right)\right)$ and
• $S=\mathrm{diag}\left(\mathrm{sin}\left({\mathbf{theta}}\left[0\right]\right),\dots ,\mathrm{sin}\left({\mathbf{theta}}\left[r-1\right]\right)\right)$.
19:  $\mathbf{u1}\left[\mathit{dim}\right]$ComplexOutput
Note: the dimension, dim, of the array u1 must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdu1}}×{\mathbf{p}}\right)$ when ${\mathbf{jobu1}}=\mathrm{Nag_AllU}$;
• otherwise u1 may be NULL.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{u1}}\left[\left(j-1\right)×{\mathbf{pdu1}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{u1}}\left[\left(i-1\right)×{\mathbf{pdu1}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{jobu1}}=\mathrm{Nag_AllU}$, u1 contains the $p$ by $p$ unitary matrix ${U}_{1}$.
20:  $\mathbf{pdu1}$IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array u1.
Constraint: if ${\mathbf{jobu1}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu1}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$
21:  $\mathbf{u2}\left[\mathit{dim}\right]$ComplexOutput
Note: the dimension, dim, of the array u2 must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdu2}}×\left({\mathbf{m}}-{\mathbf{p}}\right)\right)$ when ${\mathbf{jobu2}}=\mathrm{Nag_AllU}$;
• otherwise u2 may be NULL.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{u2}}\left[\left(j-1\right)×{\mathbf{pdu2}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{u2}}\left[\left(i-1\right)×{\mathbf{pdu2}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{jobu2}}=\mathrm{Nag_AllU}$, u2 contains the $m-p$ by $m-p$ unitary matrix ${U}_{2}$.
22:  $\mathbf{pdu2}$IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array u2.
Constraint: if ${\mathbf{jobu2}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu2}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{p}}\right)$
23:  $\mathbf{v1t}\left[\mathit{dim}\right]$ComplexOutput
Note: the dimension, dim, of the array v1t must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdv1t}}×{\mathbf{q}}\right)$ when ${\mathbf{jobv1t}}=\mathrm{Nag_AllVT}$;
• otherwise v1t may be NULL.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{v1t}}\left[\left(j-1\right)×{\mathbf{pdv1t}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{v1t}}\left[\left(i-1\right)×{\mathbf{pdv1t}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{jobv1t}}=\mathrm{Nag_AllVT}$, v1t contains the $q$ by $q$ unitary matrix ${{V}_{1}}^{\mathrm{H}}$.
24:  $\mathbf{pdv1t}$IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array v1t.
Constraint: if ${\mathbf{jobv1t}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdv1t}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{q}}\right)$
25:  $\mathbf{v2t}\left[\mathit{dim}\right]$ComplexOutput
Note: the dimension, dim, of the array v2t must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdv2t}}×\left({\mathbf{m}}-{\mathbf{q}}\right)\right)$ when ${\mathbf{jobv2t}}=\mathrm{Nag_AllVT}$;
• otherwise v2t may be NULL.
The $\left(i,j\right)$th element of the matrix is stored in
• ${\mathbf{v2t}}\left[\left(j-1\right)×{\mathbf{pdv2t}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{v2t}}\left[\left(i-1\right)×{\mathbf{pdv2t}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: if ${\mathbf{jobv2t}}=\mathrm{Nag_AllVT}$, v2t contains the $m-q$ by $m-q$ unitary matrix ${{V}_{2}}^{\mathrm{H}}$.
26:  $\mathbf{pdv2t}$IntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array v2t.
Constraint: if ${\mathbf{jobv2t}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdv2t}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{q}}\right)$
27:  $\mathbf{fail}$NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_CONVERGENCE
The Jacobi-type procedure failed to converge during an internal reduction to bidiagonal-block form. The process requires convergence to $\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{p}},{\mathbf{m}}-{\mathbf{p}},{\mathbf{q}},{\mathbf{m}}-{\mathbf{q}}\right)$ values, the value of ${\mathbf{fail}}\mathbf{.}\mathbf{errnum}$ gives the number of converged values.
NE_ENUM_INT_2
On entry, ${\mathbf{jobu1}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdu1}}=〈\mathit{\text{value}}〉$ and ${\mathbf{p}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobu1}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu1}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$.
On entry, ${\mathbf{jobu1}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdu1}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobu1}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu1}}\ge {\mathbf{p}}$.
On entry, ${\mathbf{jobv1t}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdv1t}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobv1t}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdv1t}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{q}}\right)$.
On entry, ${\mathbf{jobv1t}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdv1t}}=〈\mathit{\text{value}}〉$, ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobv1t}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdv1t}}\ge {\mathbf{q}}$.
NE_ENUM_INT_3
On entry, ${\mathbf{jobu2}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdu2}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ and ${\mathbf{p}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobu2}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu2}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{p}}\right)$.
On entry, ${\mathbf{jobu2}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdu2}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ and ${\mathbf{p}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobu2}}=\mathrm{Nag_AllU}$, ${\mathbf{pdu2}}\ge {\mathbf{m}}-{\mathbf{p}}$.
On entry, ${\mathbf{jobv2t}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdv2t}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobv2t}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdv2t}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{q}}\right)$.
On entry, ${\mathbf{jobv2t}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdv2t}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{jobv2t}}=\mathrm{Nag_AllVT}$, ${\mathbf{pdv2t}}\ge {\mathbf{m}}-{\mathbf{q}}$.
On entry, ${\mathbf{order}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdx11}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx11}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$;
if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx11}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{q}}\right)$.
On entry, ${\mathbf{order}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdx11}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx11}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{q}}\right)$;
if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx11}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$.
NE_ENUM_INT_4
On entry, ${\mathbf{order}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdx12}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx12}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{q}}\right)$;
if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx12}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$.
On entry, ${\mathbf{order}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdx12}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx12}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{p}}\right)$;
if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx12}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{q}}\right)$.
On entry, ${\mathbf{order}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdx21}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx21}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{p}}\right)$;
if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx21}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{q}}\right)$.
On entry, ${\mathbf{order}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdx21}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx21}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{q}}\right)$;
if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx21}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{p}}\right)$.
On entry, ${\mathbf{order}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdx22}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx22}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{p}}\right)$;
if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx22}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{q}}\right)$.
On entry, ${\mathbf{order}}=〈\mathit{\text{value}}〉$, ${\mathbf{pdx22}}=〈\mathit{\text{value}}〉$, ${\mathbf{m}}=〈\mathit{\text{value}}〉$, ${\mathbf{p}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx22}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{q}}\right)$;
if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx22}}\ge \mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{m}}-{\mathbf{p}}\right)$.
NE_INT
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{m}}\ge 0$.
NE_INT_2
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ and ${\mathbf{p}}=〈\mathit{\text{value}}〉$.
Constraint: $0\le {\mathbf{p}}\le {\mathbf{m}}$.
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$ and ${\mathbf{q}}=〈\mathit{\text{value}}〉$.
Constraint: $0\le {\mathbf{q}}\le {\mathbf{m}}$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

7Accuracy

The computed $CS$ decomposition is nearly the exact $CS$ decomposition for the nearby matrix $\left(X+E\right)$, where
 $E2 = Oε ,$
and $\epsilon$ is the machine precision.

8Parallelism and Performance

nag_zuncsd (f08rnc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_zuncsd (f08rnc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the x06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

The total number of floating-point operations required to perform the full $CS$ decomposition is approximately $2{m}^{3}$.
The real analogue of this function is nag_dorcsd (f08rac).

10Example

This example finds the full CS decomposition of a unitary $6$ by $6$ matrix $X$ (see Section 10.2) partitioned so that the top left block is $2$ by $3$.
The decomposition is performed both on submatrices of the unitary matrix $X$ and on separated partition matrices. Code is also provided to perform a recombining check if required.

10.1Program Text

Program Text (f08rnce.c)

10.2Program Data

Program Data (f08rnce.d)

10.3Program Results

Program Results (f08rnce.r)

© The Numerical Algorithms Group Ltd, Oxford, UK. 2017