diff options
author | julie <julielangou@users.noreply.github.com> | 2011-10-06 06:53:11 +0000 |
---|---|---|
committer | julie <julielangou@users.noreply.github.com> | 2011-10-06 06:53:11 +0000 |
commit | e1d39294aee16fa6db9ba079b14442358217db71 (patch) | |
tree | 30e5aa04c1f6596991fda5334f63dfb9b8027849 /SRC/cuncsd.f | |
parent | 5fe0466a14e395641f4f8a300ecc9dcb8058081b (diff) | |
download | lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.gz lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.bz2 lapack-e1d39294aee16fa6db9ba079b14442358217db71.zip |
Integrating Doxygen in comments
Diffstat (limited to 'SRC/cuncsd.f')
-rw-r--r-- | SRC/cuncsd.f | 429 |
1 files changed, 278 insertions, 151 deletions
diff --git a/SRC/cuncsd.f b/SRC/cuncsd.f index 808daa2d..5d3a883c 100644 --- a/SRC/cuncsd.f +++ b/SRC/cuncsd.f @@ -1,20 +1,289 @@ +*> \brief \b CUNCSD +* +* =========== DOCUMENTATION =========== +* +* Online html documentation available at +* http://www.netlib.org/lapack/explore-html/ +* +* Definition +* ========== +* +* RECURSIVE SUBROUTINE CUNCSD( JOBU1, JOBU2, JOBV1T, JOBV2T, TRANS, +* SIGNS, M, P, Q, X11, LDX11, X12, +* LDX12, X21, LDX21, X22, LDX22, THETA, +* U1, LDU1, U2, LDU2, V1T, LDV1T, V2T, +* LDV2T, WORK, LWORK, RWORK, LRWORK, +* IWORK, INFO ) +* +* .. Scalar Arguments .. +* CHARACTER JOBU1, JOBU2, JOBV1T, JOBV2T, SIGNS, TRANS +* INTEGER INFO, LDU1, LDU2, LDV1T, LDV2T, LDX11, LDX12, +* $ LDX21, LDX22, LRWORK, LWORK, M, P, Q +* .. +* .. Array Arguments .. +* INTEGER IWORK( * ) +* REAL THETA( * ) +* REAL RWORK( * ) +* COMPLEX U1( LDU1, * ), U2( LDU2, * ), V1T( LDV1T, * ), +* $ V2T( LDV2T, * ), WORK( * ), X11( LDX11, * ), +* $ X12( LDX12, * ), X21( LDX21, * ), X22( LDX22, +* $ * ) +* .. +* +* Purpose +* ======= +* +*>\details \b Purpose: +*>\verbatim +*> +*> CUNCSD computes the CS decomposition of an M-by-M partitioned +*> unitary matrix X: +*> +*> [ I 0 0 | 0 0 0 ] +*> [ 0 C 0 | 0 -S 0 ] +*> [ X11 | X12 ] [ U1 | ] [ 0 0 0 | 0 0 -I ] [ V1 | ]**H +*> X = [-----------] = [---------] [---------------------] [---------] . +*> [ X21 | X22 ] [ | U2 ] [ 0 0 0 | I 0 0 ] [ | V2 ] +*> [ 0 S 0 | 0 C 0 ] +*> [ 0 0 I | 0 0 0 ] +*> +*> X11 is P-by-Q. The unitary matrices U1, U2, V1, and V2 are P-by-P, +*> (M-P)-by-(M-P), Q-by-Q, and (M-Q)-by-(M-Q), respectively. C and S are +*> R-by-R nonnegative diagonal matrices satisfying C^2 + S^2 = I, in +*> which R = MIN(P,M-P,Q,M-Q). +*> +*>\endverbatim +* +* Arguments +* ========= +* +*> \param[in] JOBU1 +*> \verbatim +*> JOBU1 is CHARACTER +*> = 'Y': U1 is computed; +*> otherwise: U1 is not computed. +*> \endverbatim +*> +*> \param[in] JOBU2 +*> \verbatim +*> JOBU2 is CHARACTER +*> = 'Y': U2 is computed; +*> otherwise: U2 is not computed. +*> \endverbatim +*> +*> \param[in] JOBV1T +*> \verbatim +*> JOBV1T is CHARACTER +*> = 'Y': V1T is computed; +*> otherwise: V1T is not computed. +*> \endverbatim +*> +*> \param[in] JOBV2T +*> \verbatim +*> JOBV2T is CHARACTER +*> = 'Y': V2T is computed; +*> otherwise: V2T is not computed. +*> \endverbatim +*> +*> \param[in] TRANS +*> \verbatim +*> TRANS is CHARACTER +*> = 'T': X, U1, U2, V1T, and V2T are stored in row-major +*> order; +*> otherwise: X, U1, U2, V1T, and V2T are stored in column- +*> major order. +*> \endverbatim +*> +*> \param[in] SIGNS +*> \verbatim +*> SIGNS is CHARACTER +*> = 'O': The lower-left block is made nonpositive (the +*> "other" convention); +*> otherwise: The upper-right block is made nonpositive (the +*> "default" convention). +*> \endverbatim +*> +*> \param[in] M +*> \verbatim +*> M is INTEGER +*> The number of rows and columns in X. +*> \endverbatim +*> +*> \param[in] P +*> \verbatim +*> P is INTEGER +*> The number of rows in X11 and X12. 0 <= P <= M. +*> \endverbatim +*> +*> \param[in] Q +*> \verbatim +*> Q is INTEGER +*> The number of columns in X11 and X21. 0 <= Q <= M. +*> \endverbatim +*> +*> \param[in,out] X +*> \verbatim +*> X is COMPLEX array, dimension (LDX,M) +*> On entry, the unitary matrix whose CSD is desired. +*> \endverbatim +*> +*> \param[in] LDX +*> \verbatim +*> LDX is INTEGER +*> The leading dimension of X. LDX >= MAX(1,M). +*> \endverbatim +*> +*> \param[out] THETA +*> \verbatim +*> THETA is REAL array, dimension (R), in which R = +*> MIN(P,M-P,Q,M-Q). +*> C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) ) and +*> S = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ). +*> \endverbatim +*> +*> \param[out] U1 +*> \verbatim +*> U1 is COMPLEX array, dimension (P) +*> If JOBU1 = 'Y', U1 contains the P-by-P unitary matrix U1. +*> \endverbatim +*> +*> \param[in] LDU1 +*> \verbatim +*> LDU1 is INTEGER +*> The leading dimension of U1. If JOBU1 = 'Y', LDU1 >= +*> MAX(1,P). +*> \endverbatim +*> +*> \param[out] U2 +*> \verbatim +*> U2 is COMPLEX array, dimension (M-P) +*> If JOBU2 = 'Y', U2 contains the (M-P)-by-(M-P) unitary +*> matrix U2. +*> \endverbatim +*> +*> \param[in] LDU2 +*> \verbatim +*> LDU2 is INTEGER +*> The leading dimension of U2. If JOBU2 = 'Y', LDU2 >= +*> MAX(1,M-P). +*> \endverbatim +*> +*> \param[out] V1T +*> \verbatim +*> V1T is COMPLEX array, dimension (Q) +*> If JOBV1T = 'Y', V1T contains the Q-by-Q matrix unitary +*> matrix V1**H. +*> \endverbatim +*> +*> \param[in] LDV1T +*> \verbatim +*> LDV1T is INTEGER +*> The leading dimension of V1T. If JOBV1T = 'Y', LDV1T >= +*> MAX(1,Q). +*> \endverbatim +*> +*> \param[out] V2T +*> \verbatim +*> V2T is COMPLEX array, dimension (M-Q) +*> If JOBV2T = 'Y', V2T contains the (M-Q)-by-(M-Q) unitary +*> matrix V2**H. +*> \endverbatim +*> +*> \param[in] LDV2T +*> \verbatim +*> LDV2T is INTEGER +*> The leading dimension of V2T. If JOBV2T = 'Y', LDV2T >= +*> MAX(1,M-Q). +*> \endverbatim +*> +*> \param[out] WORK +*> \verbatim +*> WORK is COMPLEX array, dimension (MAX(1,LWORK)) +*> On exit, if INFO = 0, WORK(1) returns the optimal LWORK. +*> \endverbatim +*> +*> \param[in] LWORK +*> \verbatim +*> LWORK is INTEGER +*> The dimension of the array WORK. +*> \endverbatim +*> \verbatim +*> If LWORK = -1, then 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 by XERBLA. +*> \endverbatim +*> +*> \param[out] RWORK +*> \verbatim +*> RWORK is REAL array, dimension MAX(1,LRWORK) +*> On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. +*> If INFO > 0 on exit, RWORK(2:R) contains the values PHI(1), +*> ..., PHI(R-1) that, together with THETA(1), ..., THETA(R), +*> define the matrix in intermediate bidiagonal-block form +*> remaining after nonconvergence. INFO specifies the number +*> of nonzero PHI's. +*> \endverbatim +*> +*> \param[in] LRWORK +*> \verbatim +*> LRWORK is INTEGER +*> The dimension of the array RWORK. +*> \endverbatim +*> \verbatim +*> If LRWORK = -1, then a workspace query is assumed; the routine +*> only calculates the optimal size of the RWORK array, returns +*> this value as the first entry of the work array, and no error +*> message related to LRWORK is issued by XERBLA. +*> \endverbatim +*> +*> \param[out] IWORK +*> \verbatim +*> IWORK is INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q)) +*> \endverbatim +*> +*> \param[out] INFO +*> \verbatim +*> INFO is INTEGER +*> = 0: successful exit. +*> < 0: if INFO = -i, the i-th argument had an illegal value. +*> > 0: CBBCSD did not converge. See the description of RWORK +*> above for details. +*> \endverbatim +*> \verbatim +*> Reference +*> ========= +*> \endverbatim +*> \verbatim +*> [1] Brian D. Sutton. Computing the complete CS decomposition. Numer. +*> Algorithms, 50(1):33-65, 2009. +*> \endverbatim +*> +* +* Authors +* ======= +* +*> \author Univ. of Tennessee +*> \author Univ. of California Berkeley +*> \author Univ. of Colorado Denver +*> \author NAG Ltd. +* +*> \date November 2011 +* +*> \ingroup complexOTHERcomputational +* +* ===================================================================== RECURSIVE SUBROUTINE CUNCSD( JOBU1, JOBU2, JOBV1T, JOBV2T, TRANS, $ SIGNS, M, P, Q, X11, LDX11, X12, $ LDX12, X21, LDX21, X22, LDX22, THETA, $ U1, LDU1, U2, LDU2, V1T, LDV1T, V2T, $ LDV2T, WORK, LWORK, RWORK, LRWORK, $ IWORK, INFO ) - IMPLICIT NONE -* -* -- LAPACK routine (version 3.3.1) -- -* -* -- Contributed by Brian Sutton of the Randolph-Macon College -- -* -- November 2010 * +* -- LAPACK computational routine (version 3.3.1) -- * -- LAPACK is a software package provided by Univ. of Tennessee, -- -* -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..-- -* -* @generated c +* -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..-- +* November 2011 * * .. Scalar Arguments .. CHARACTER JOBU1, JOBU2, JOBV1T, JOBV2T, SIGNS, TRANS @@ -31,148 +300,6 @@ $ * ) * .. * -* Purpose -* ======= -* -* CUNCSD computes the CS decomposition of an M-by-M partitioned -* unitary matrix X: -* -* [ I 0 0 | 0 0 0 ] -* [ 0 C 0 | 0 -S 0 ] -* [ X11 | X12 ] [ U1 | ] [ 0 0 0 | 0 0 -I ] [ V1 | ]**H -* X = [-----------] = [---------] [---------------------] [---------] . -* [ X21 | X22 ] [ | U2 ] [ 0 0 0 | I 0 0 ] [ | V2 ] -* [ 0 S 0 | 0 C 0 ] -* [ 0 0 I | 0 0 0 ] -* -* X11 is P-by-Q. The unitary matrices U1, U2, V1, and V2 are P-by-P, -* (M-P)-by-(M-P), Q-by-Q, and (M-Q)-by-(M-Q), respectively. C and S are -* R-by-R nonnegative diagonal matrices satisfying C^2 + S^2 = I, in -* which R = MIN(P,M-P,Q,M-Q). -* -* Arguments -* ========= -* -* JOBU1 (input) CHARACTER -* = 'Y': U1 is computed; -* otherwise: U1 is not computed. -* -* JOBU2 (input) CHARACTER -* = 'Y': U2 is computed; -* otherwise: U2 is not computed. -* -* JOBV1T (input) CHARACTER -* = 'Y': V1T is computed; -* otherwise: V1T is not computed. -* -* JOBV2T (input) CHARACTER -* = 'Y': V2T is computed; -* otherwise: V2T is not computed. -* -* TRANS (input) CHARACTER -* = 'T': X, U1, U2, V1T, and V2T are stored in row-major -* order; -* otherwise: X, U1, U2, V1T, and V2T are stored in column- -* major order. -* -* SIGNS (input) CHARACTER -* = 'O': The lower-left block is made nonpositive (the -* "other" convention); -* otherwise: The upper-right block is made nonpositive (the -* "default" convention). -* -* M (input) INTEGER -* The number of rows and columns in X. -* -* P (input) INTEGER -* The number of rows in X11 and X12. 0 <= P <= M. -* -* Q (input) INTEGER -* The number of columns in X11 and X21. 0 <= Q <= M. -* -* X (input/workspace) COMPLEX array, dimension (LDX,M) -* On entry, the unitary matrix whose CSD is desired. -* -* LDX (input) INTEGER -* The leading dimension of X. LDX >= MAX(1,M). -* -* THETA (output) REAL array, dimension (R), in which R = -* MIN(P,M-P,Q,M-Q). -* C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) ) and -* S = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ). -* -* U1 (output) COMPLEX array, dimension (P) -* If JOBU1 = 'Y', U1 contains the P-by-P unitary matrix U1. -* -* LDU1 (input) INTEGER -* The leading dimension of U1. If JOBU1 = 'Y', LDU1 >= -* MAX(1,P). -* -* U2 (output) COMPLEX array, dimension (M-P) -* If JOBU2 = 'Y', U2 contains the (M-P)-by-(M-P) unitary -* matrix U2. -* -* LDU2 (input) INTEGER -* The leading dimension of U2. If JOBU2 = 'Y', LDU2 >= -* MAX(1,M-P). -* -* V1T (output) COMPLEX array, dimension (Q) -* If JOBV1T = 'Y', V1T contains the Q-by-Q matrix unitary -* matrix V1**H. -* -* LDV1T (input) INTEGER -* The leading dimension of V1T. If JOBV1T = 'Y', LDV1T >= -* MAX(1,Q). -* -* V2T (output) COMPLEX array, dimension (M-Q) -* If JOBV2T = 'Y', V2T contains the (M-Q)-by-(M-Q) unitary -* matrix V2**H. -* -* LDV2T (input) INTEGER -* The leading dimension of V2T. If JOBV2T = 'Y', LDV2T >= -* MAX(1,M-Q). -* -* WORK (workspace) COMPLEX array, dimension (MAX(1,LWORK)) -* On exit, if INFO = 0, WORK(1) returns the optimal LWORK. -* -* LWORK (input) INTEGER -* The dimension of the array WORK. -* -* If LWORK = -1, then 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 by XERBLA. -* -* RWORK (workspace) REAL array, dimension MAX(1,LRWORK) -* On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. -* If INFO > 0 on exit, RWORK(2:R) contains the values PHI(1), -* ..., PHI(R-1) that, together with THETA(1), ..., THETA(R), -* define the matrix in intermediate bidiagonal-block form -* remaining after nonconvergence. INFO specifies the number -* of nonzero PHI's. -* -* LRWORK (input) INTEGER -* The dimension of the array RWORK. -* -* If LRWORK = -1, then a workspace query is assumed; the routine -* only calculates the optimal size of the RWORK array, returns -* this value as the first entry of the work array, and no error -* message related to LRWORK is issued by XERBLA. -* -* IWORK (workspace) INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q)) -* -* INFO (output) INTEGER -* = 0: successful exit. -* < 0: if INFO = -i, the i-th argument had an illegal value. -* > 0: CBBCSD did not converge. See the description of RWORK -* above for details. -* -* Reference -* ========= -* -* [1] Brian D. Sutton. Computing the complete CS decomposition. Numer. -* Algorithms, 50(1):33-65, 2009. -* * =================================================================== * * .. Parameters .. |