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/cbdsqr.f | |
parent | 5fe0466a14e395641f4f8a300ecc9dcb8058081b (diff) | |
download | lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.gz lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.bz2 lapack-e1d39294aee16fa6db9ba079b14442358217db71.zip |
Integrating Doxygen in comments
Diffstat (limited to 'SRC/cbdsqr.f')
-rw-r--r-- | SRC/cbdsqr.f | 345 |
1 files changed, 217 insertions, 128 deletions
diff --git a/SRC/cbdsqr.f b/SRC/cbdsqr.f index 12cbb748..72ee31d4 100644 --- a/SRC/cbdsqr.f +++ b/SRC/cbdsqr.f @@ -1,10 +1,225 @@ +*> \brief \b CBDSQR +* +* =========== DOCUMENTATION =========== +* +* Online html documentation available at +* http://www.netlib.org/lapack/explore-html/ +* +* Definition +* ========== +* +* SUBROUTINE CBDSQR( UPLO, N, NCVT, NRU, NCC, D, E, VT, LDVT, U, +* LDU, C, LDC, RWORK, INFO ) +* +* .. Scalar Arguments .. +* CHARACTER UPLO +* INTEGER INFO, LDC, LDU, LDVT, N, NCC, NCVT, NRU +* .. +* .. Array Arguments .. +* REAL D( * ), E( * ), RWORK( * ) +* COMPLEX C( LDC, * ), U( LDU, * ), VT( LDVT, * ) +* .. +* +* Purpose +* ======= +* +*>\details \b Purpose: +*>\verbatim +*> +*> CBDSQR computes the singular values and, optionally, the right and/or +*> left singular vectors from the singular value decomposition (SVD) of +*> a real N-by-N (upper or lower) bidiagonal matrix B using the implicit +*> zero-shift QR algorithm. The SVD of B has the form +*> +*> B = Q * S * P**H +*> +*> where S is the diagonal matrix of singular values, Q is an orthogonal +*> matrix of left singular vectors, and P is an orthogonal matrix of +*> right singular vectors. If left singular vectors are requested, this +*> subroutine actually returns U*Q instead of Q, and, if right singular +*> vectors are requested, this subroutine returns P**H*VT instead of +*> P**H, for given complex input matrices U and VT. When U and VT are +*> the unitary matrices that reduce a general matrix A to bidiagonal +*> form: A = U*B*VT, as computed by CGEBRD, then +*> +*> A = (U*Q) * S * (P**H*VT) +*> +*> is the SVD of A. Optionally, the subroutine may also compute Q**H*C +*> for a given complex input matrix C. +*> +*> See "Computing Small Singular Values of Bidiagonal Matrices With +*> Guaranteed High Relative Accuracy," by J. Demmel and W. Kahan, +*> LAPACK Working Note #3 (or SIAM J. Sci. Statist. Comput. vol. 11, +*> no. 5, pp. 873-912, Sept 1990) and +*> "Accurate singular values and differential qd algorithms," by +*> B. Parlett and V. Fernando, Technical Report CPAM-554, Mathematics +*> Department, University of California at Berkeley, July 1992 +*> for a detailed description of the algorithm. +*> +*>\endverbatim +* +* Arguments +* ========= +* +*> \param[in] UPLO +*> \verbatim +*> UPLO is CHARACTER*1 +*> = 'U': B is upper bidiagonal; +*> = 'L': B is lower bidiagonal. +*> \endverbatim +*> +*> \param[in] N +*> \verbatim +*> N is INTEGER +*> The order of the matrix B. N >= 0. +*> \endverbatim +*> +*> \param[in] NCVT +*> \verbatim +*> NCVT is INTEGER +*> The number of columns of the matrix VT. NCVT >= 0. +*> \endverbatim +*> +*> \param[in] NRU +*> \verbatim +*> NRU is INTEGER +*> The number of rows of the matrix U. NRU >= 0. +*> \endverbatim +*> +*> \param[in] NCC +*> \verbatim +*> NCC is INTEGER +*> The number of columns of the matrix C. NCC >= 0. +*> \endverbatim +*> +*> \param[in,out] D +*> \verbatim +*> D is REAL array, dimension (N) +*> On entry, the n diagonal elements of the bidiagonal matrix B. +*> On exit, if INFO=0, the singular values of B in decreasing +*> order. +*> \endverbatim +*> +*> \param[in,out] E +*> \verbatim +*> E is REAL array, dimension (N-1) +*> On entry, the N-1 offdiagonal elements of the bidiagonal +*> matrix B. +*> On exit, if INFO = 0, E is destroyed; if INFO > 0, D and E +*> will contain the diagonal and superdiagonal elements of a +*> bidiagonal matrix orthogonally equivalent to the one given +*> as input. +*> \endverbatim +*> +*> \param[in,out] VT +*> \verbatim +*> VT is COMPLEX array, dimension (LDVT, NCVT) +*> On entry, an N-by-NCVT matrix VT. +*> On exit, VT is overwritten by P**H * VT. +*> Not referenced if NCVT = 0. +*> \endverbatim +*> +*> \param[in] LDVT +*> \verbatim +*> LDVT is INTEGER +*> The leading dimension of the array VT. +*> LDVT >= max(1,N) if NCVT > 0; LDVT >= 1 if NCVT = 0. +*> \endverbatim +*> +*> \param[in,out] U +*> \verbatim +*> U is COMPLEX array, dimension (LDU, N) +*> On entry, an NRU-by-N matrix U. +*> On exit, U is overwritten by U * Q. +*> Not referenced if NRU = 0. +*> \endverbatim +*> +*> \param[in] LDU +*> \verbatim +*> LDU is INTEGER +*> The leading dimension of the array U. LDU >= max(1,NRU). +*> \endverbatim +*> +*> \param[in,out] C +*> \verbatim +*> C is COMPLEX array, dimension (LDC, NCC) +*> On entry, an N-by-NCC matrix C. +*> On exit, C is overwritten by Q**H * C. +*> Not referenced if NCC = 0. +*> \endverbatim +*> +*> \param[in] LDC +*> \verbatim +*> LDC is INTEGER +*> The leading dimension of the array C. +*> LDC >= max(1,N) if NCC > 0; LDC >=1 if NCC = 0. +*> \endverbatim +*> +*> \param[out] RWORK +*> \verbatim +*> RWORK is REAL array, dimension (2*N) +*> if NCVT = NRU = NCC = 0, (max(1, 4*N-4)) otherwise +*> \endverbatim +*> +*> \param[out] INFO +*> \verbatim +*> INFO is INTEGER +*> = 0: successful exit +*> < 0: If INFO = -i, the i-th argument had an illegal value +*> > 0: the algorithm did not converge; D and E contain the +*> elements of a bidiagonal matrix which is orthogonally +*> similar to the input matrix B; if INFO = i, i +*> elements of E have not converged to zero. +*> \endverbatim +*> \verbatim +*> Internal Parameters +*> =================== +*> \endverbatim +*> \verbatim +*> TOLMUL REAL, default = max(10,min(100,EPS**(-1/8))) +*> TOLMUL controls the convergence criterion of the QR loop. +*> If it is positive, TOLMUL*EPS is the desired relative +*> precision in the computed singular values. +*> If it is negative, abs(TOLMUL*EPS*sigma_max) is the +*> desired absolute accuracy in the computed singular +*> values (corresponds to relative accuracy +*> abs(TOLMUL*EPS) in the largest singular value. +*> abs(TOLMUL) should be between 1 and 1/EPS, and preferably +*> between 10 (for fast convergence) and .1/EPS +*> (for there to be some accuracy in the results). +*> Default is to lose at either one eighth or 2 of the +*> available decimal digits in each computed singular value +*> (whichever is smaller). +*> \endverbatim +*> \verbatim +*> MAXITR INTEGER, default = 6 +*> MAXITR controls the maximum number of passes of the +*> algorithm through its inner loop. The algorithms stops +*> (and so fails to converge) if the number of passes +*> through the inner loop exceeds MAXITR*N**2. +*> \endverbatim +*> +* +* Authors +* ======= +* +*> \author Univ. of Tennessee +*> \author Univ. of California Berkeley +*> \author Univ. of Colorado Denver +*> \author NAG Ltd. +* +*> \date November 2011 +* +*> \ingroup complexOTHERcomputational +* +* ===================================================================== SUBROUTINE CBDSQR( UPLO, N, NCVT, NRU, NCC, D, E, VT, LDVT, U, $ LDU, C, LDC, RWORK, INFO ) * -* -- LAPACK routine (version 3.2) -- +* -- LAPACK computational routine (version 3.2) -- * -- LAPACK is a software package provided by Univ. of Tennessee, -- * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..-- -* November 2006 +* November 2011 * * .. Scalar Arguments .. CHARACTER UPLO @@ -15,132 +230,6 @@ COMPLEX C( LDC, * ), U( LDU, * ), VT( LDVT, * ) * .. * -* Purpose -* ======= -* -* CBDSQR computes the singular values and, optionally, the right and/or -* left singular vectors from the singular value decomposition (SVD) of -* a real N-by-N (upper or lower) bidiagonal matrix B using the implicit -* zero-shift QR algorithm. The SVD of B has the form -* -* B = Q * S * P**H -* -* where S is the diagonal matrix of singular values, Q is an orthogonal -* matrix of left singular vectors, and P is an orthogonal matrix of -* right singular vectors. If left singular vectors are requested, this -* subroutine actually returns U*Q instead of Q, and, if right singular -* vectors are requested, this subroutine returns P**H*VT instead of -* P**H, for given complex input matrices U and VT. When U and VT are -* the unitary matrices that reduce a general matrix A to bidiagonal -* form: A = U*B*VT, as computed by CGEBRD, then -* -* A = (U*Q) * S * (P**H*VT) -* -* is the SVD of A. Optionally, the subroutine may also compute Q**H*C -* for a given complex input matrix C. -* -* See "Computing Small Singular Values of Bidiagonal Matrices With -* Guaranteed High Relative Accuracy," by J. Demmel and W. Kahan, -* LAPACK Working Note #3 (or SIAM J. Sci. Statist. Comput. vol. 11, -* no. 5, pp. 873-912, Sept 1990) and -* "Accurate singular values and differential qd algorithms," by -* B. Parlett and V. Fernando, Technical Report CPAM-554, Mathematics -* Department, University of California at Berkeley, July 1992 -* for a detailed description of the algorithm. -* -* Arguments -* ========= -* -* UPLO (input) CHARACTER*1 -* = 'U': B is upper bidiagonal; -* = 'L': B is lower bidiagonal. -* -* N (input) INTEGER -* The order of the matrix B. N >= 0. -* -* NCVT (input) INTEGER -* The number of columns of the matrix VT. NCVT >= 0. -* -* NRU (input) INTEGER -* The number of rows of the matrix U. NRU >= 0. -* -* NCC (input) INTEGER -* The number of columns of the matrix C. NCC >= 0. -* -* D (input/output) REAL array, dimension (N) -* On entry, the n diagonal elements of the bidiagonal matrix B. -* On exit, if INFO=0, the singular values of B in decreasing -* order. -* -* E (input/output) REAL array, dimension (N-1) -* On entry, the N-1 offdiagonal elements of the bidiagonal -* matrix B. -* On exit, if INFO = 0, E is destroyed; if INFO > 0, D and E -* will contain the diagonal and superdiagonal elements of a -* bidiagonal matrix orthogonally equivalent to the one given -* as input. -* -* VT (input/output) COMPLEX array, dimension (LDVT, NCVT) -* On entry, an N-by-NCVT matrix VT. -* On exit, VT is overwritten by P**H * VT. -* Not referenced if NCVT = 0. -* -* LDVT (input) INTEGER -* The leading dimension of the array VT. -* LDVT >= max(1,N) if NCVT > 0; LDVT >= 1 if NCVT = 0. -* -* U (input/output) COMPLEX array, dimension (LDU, N) -* On entry, an NRU-by-N matrix U. -* On exit, U is overwritten by U * Q. -* Not referenced if NRU = 0. -* -* LDU (input) INTEGER -* The leading dimension of the array U. LDU >= max(1,NRU). -* -* C (input/output) COMPLEX array, dimension (LDC, NCC) -* On entry, an N-by-NCC matrix C. -* On exit, C is overwritten by Q**H * C. -* Not referenced if NCC = 0. -* -* LDC (input) INTEGER -* The leading dimension of the array C. -* LDC >= max(1,N) if NCC > 0; LDC >=1 if NCC = 0. -* -* RWORK (workspace) REAL array, dimension (2*N) -* if NCVT = NRU = NCC = 0, (max(1, 4*N-4)) otherwise -* -* INFO (output) INTEGER -* = 0: successful exit -* < 0: If INFO = -i, the i-th argument had an illegal value -* > 0: the algorithm did not converge; D and E contain the -* elements of a bidiagonal matrix which is orthogonally -* similar to the input matrix B; if INFO = i, i -* elements of E have not converged to zero. -* -* Internal Parameters -* =================== -* -* TOLMUL REAL, default = max(10,min(100,EPS**(-1/8))) -* TOLMUL controls the convergence criterion of the QR loop. -* If it is positive, TOLMUL*EPS is the desired relative -* precision in the computed singular values. -* If it is negative, abs(TOLMUL*EPS*sigma_max) is the -* desired absolute accuracy in the computed singular -* values (corresponds to relative accuracy -* abs(TOLMUL*EPS) in the largest singular value. -* abs(TOLMUL) should be between 1 and 1/EPS, and preferably -* between 10 (for fast convergence) and .1/EPS -* (for there to be some accuracy in the results). -* Default is to lose at either one eighth or 2 of the -* available decimal digits in each computed singular value -* (whichever is smaller). -* -* MAXITR INTEGER, default = 6 -* MAXITR controls the maximum number of passes of the -* algorithm through its inner loop. The algorithms stops -* (and so fails to converge) if the number of passes -* through the inner loop exceeds MAXITR*N**2. -* * ===================================================================== * * .. Parameters .. |