naginterfaces.library.lapackeig.zuncsd

naginterfaces.library.lapackeig.zuncsd(m, p, q, x11, x12, x21, x22, jobu1='Y', jobu2='Y', jobv1t='Y', jobv2t='Y', trans='N', signs='D')

zuncsd computes the CS decomposition of a complex $m\times m$ unitary matrix $X$, partitioned into a $2\times 2$ array of submatrices.

For full information please refer to the NAG Library document for f08rn

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08rnf.html

Parameters

mint

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

pint

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

qint

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

x11complex, array-like, shape $(:,:)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $trans=\text{'T'}$: $q$; otherwise: $p$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $trans=\text{'T'}$: $p$; otherwise: $q$.

The upper left partition of the unitary matrix $X$ whose CSD is desired.

x12complex, array-like, shape $(:,:)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $trans=\text{'T'}$: $m-q$; otherwise: $p$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $trans=\text{'T'}$: $p$; otherwise: $m-q$.

The upper right partition of the unitary matrix $X$ whose CSD is desired.

x21complex, array-like, shape $(:,:)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $trans=\text{'T'}$: $q$; otherwise: $m-p$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $trans=\text{'T'}$: $m-p$; otherwise: $q$.

The lower left partition of the unitary matrix $X$ whose CSD is desired.

x22complex, array-like, shape $(:,:)$

Note: the required extent for this argument in dimension 1 is determined as follows: if $trans=\text{'T'}$: $m-q$; otherwise: $m-p$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $trans=\text{'T'}$: $m-p$; otherwise: $m-q$.

The lower right partition of the unitary matrix $X$ CSD is desired.

jobu1str, length 1, optional

If $jobu1=\text{'Y'}$, $U_1$ is computed;

otherwise, $U_1$ is not computed.

jobu2str, length 1, optional

If $jobu2=\text{'Y'}$, $U_2$ is computed;

otherwise, $U_2$ is not computed.

jobv1tstr, length 1, optional

If $jobv1t=\text{'Y'}$, $V_1^T$ is computed;

otherwise, $V_1^T$ is not computed.

jobv2tstr, length 1, optional

If $jobv2t=\text{'Y'}$, $V_2^T$ is computed;

otherwise, $V_2^T$ is not computed.

transstr, length 1, optional

If $trans=\text{'T'}$, $X$, $U_1$, $U_2$, $V_1^T$ and $V_2^T$ are stored in row-major order;

otherwise, $X$, $U_1$, $U_2$, $V_1^T$ and $V_2^T$ are stored in column-major order.

signsstr, length 1, optional

If $signs=\text{'O'}$, the lower-left block is made nonpositive (the other convention);

otherwise, the upper-right block is made nonpositive (the default convention).

Returns

x11complex, ndarray, shape $(:,:)$

Contains details of the unitary matrix used in a simultaneous bidiagonalization process.

x12complex, ndarray, shape $(:,:)$

Contains details of the unitary matrix used in a simultaneous bidiagonalization process.

x21complex, ndarray, shape $(:,:)$

Contains details of the unitary matrix used in a simultaneous bidiagonalization process.

x22complex, ndarray, shape $(:,:)$

Contains details of the unitary matrix used in a simultaneous bidiagonalization process.

thetafloat, ndarray, shape $(min(p,m-p))$

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

$C=diag(\cos \left(theta\right[0\left]\right),\dots ,\cos \left(theta\right[r-1\left]\right))$ and

$S=diag(\sin \left(theta\right[0\left]\right),\dots ,\sin \left(theta\right[r-1\left]\right))$.

u1None or complex, ndarray, shape $(:,:)$

If $jobu1=\text{'Y'}$, $u1$ contains the $p\times p$ unitary matrix $U_1$.

u2None or complex, ndarray, shape $(:,:)$

If $jobu2=\text{'Y'}$, $u2$ contains the $m-p\times m-p$ unitary matrix $U_2$.

v1tNone or complex, ndarray, shape $(:,:)$

If $jobv1t=\text{'Y'}$, $v1t$ contains the $q\times q$ unitary matrix $V_1^H$.

v2tNone or complex, ndarray, shape $(:,:)$

If $jobv2t=\text{'Y'}$, $v2t$ contains the $m-q\times m-q$ unitary matrix $V_2^H$.

Raises

NagValueError

(errno $-7$)

On entry, error in parameter $m$.

Constraint: $m\ge 0$.

(errno $-8$)

On entry, error in parameter $p$.

Constraint: $0\le p\le m$.

(errno $-9$)

On entry, error in parameter $q$.

Constraint: $0\le q\le m$.

(errno $i>0$)

The Jacobi-type procedure failed to converge during an internal reduction to bidiagonal-block form. The process requires convergence to $min(p,m-p,q,m-q)$ values, the value of $\text{errno}$ gives the number of converged values.

Notes

The $m\times m$ unitary matrix $X$ is partitioned as

$$\begin{array}{c}X=\left(\begin{array}{cc}{X}_{11}& X_{12}\\ X_{21}& X_{22}\end{array}\right)\end{array}$$

where $X_{11}$ is a $p\times q$ submatrix and the dimensions of the other submatrices $X_{12}$, $X_{21}$ and $X_{22}$ are such that $X$ remains $m\times m$.

The CS decomposition of $X$ is $X=U{\Sigma }_p{V}^T$ where $U$, $V$ and ${\Sigma }_p$ are $m\times m$ matrices, such that

$$\begin{array}{c}U=\left(\begin{array}{cc}{U}_1& 0\\ 0& U_2\end{array}\right)\end{array}$$

is a unitary matrix containing the $p\times p$ unitary matrix $U_1$ and the $(m-p)\times (m-p)$ unitary matrix $U_2$;

$$\begin{array}{c}V=\left(\begin{array}{cc}{V}_1& 0\\ 0& V_2\end{array}\right)\end{array}$$

is a unitary matrix containing the $q\times q$ unitary matrix $V_1$ and the $(m-q)\times (m-q)$ unitary matrix $V_2$; and

$$\begin{array}{c}{\Sigma }_p=\left(\begin{array}{cccccc}{I}_{11}& & 0& & 0& 0\\ & C& 0& 0& -S& \\ 0& 0& & 0& & {-I}_{12}\\ & 0& 0& I_{22}& & 0\\ 0& S& & & C& 0\\ 0& & I_{21}& 0& 0& \end{array}\right)\end{array}$$

contains the $r\times r$ non-negative diagonal submatrices $C$ and $S$ satisfying $C^2+S^2=I$, where $r=min(p,m-p,q,m-q)$ and the top left partition is $p\times q$.

The identity matrix $I_{11}$ is of order $min(p,q)-r$ and vanishes if $min(p,q)=r$.

The identity matrix $I_{12}$ is of order $min(p,m-q)-r$ and vanishes if $min(p,m-q)=r$.

The identity matrix $I_{21}$ is of order $min(m-p,q)-r$ and vanishes if $min(m-p,q)=r$.

The identity matrix $I_{22}$ is of order $min(m-p,m-q)-r$ and vanishes if $min(m-p,m-q)=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}=\cos \left({\theta }_i\right)$ and $S_{ii}=\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.

References

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, https://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, https://dx.doi.org/10.1007/s11075-008-9215-6