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/cgeesx.f | |
parent | 5fe0466a14e395641f4f8a300ecc9dcb8058081b (diff) | |
download | lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.gz lapack-e1d39294aee16fa6db9ba079b14442358217db71.tar.bz2 lapack-e1d39294aee16fa6db9ba079b14442358217db71.zip |
Integrating Doxygen in comments
Diffstat (limited to 'SRC/cgeesx.f')
-rw-r--r-- | SRC/cgeesx.f | 361 |
1 files changed, 232 insertions, 129 deletions
diff --git a/SRC/cgeesx.f b/SRC/cgeesx.f index e49e5251..a6983984 100644 --- a/SRC/cgeesx.f +++ b/SRC/cgeesx.f @@ -1,11 +1,241 @@ +*> \brief <b> CGEESX computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices</b> +* +* =========== DOCUMENTATION =========== +* +* Online html documentation available at +* http://www.netlib.org/lapack/explore-html/ +* +* Definition +* ========== +* +* SUBROUTINE CGEESX( JOBVS, SORT, SELECT, SENSE, N, A, LDA, SDIM, W, +* VS, LDVS, RCONDE, RCONDV, WORK, LWORK, RWORK, +* BWORK, INFO ) +* +* .. Scalar Arguments .. +* CHARACTER JOBVS, SENSE, SORT +* INTEGER INFO, LDA, LDVS, LWORK, N, SDIM +* REAL RCONDE, RCONDV +* .. +* .. Array Arguments .. +* LOGICAL BWORK( * ) +* REAL RWORK( * ) +* COMPLEX A( LDA, * ), VS( LDVS, * ), W( * ), WORK( * ) +* .. +* .. Function Arguments .. +* LOGICAL SELECT +* EXTERNAL SELECT +* .. +* +* Purpose +* ======= +* +*>\details \b Purpose: +*>\verbatim +*> +*> CGEESX computes for an N-by-N complex nonsymmetric matrix A, the +*> eigenvalues, the Schur form T, and, optionally, the matrix of Schur +*> vectors Z. This gives the Schur factorization A = Z*T*(Z**H). +*> +*> Optionally, it also orders the eigenvalues on the diagonal of the +*> Schur form so that selected eigenvalues are at the top left; +*> computes a reciprocal condition number for the average of the +*> selected eigenvalues (RCONDE); and computes a reciprocal condition +*> number for the right invariant subspace corresponding to the +*> selected eigenvalues (RCONDV). The leading columns of Z form an +*> orthonormal basis for this invariant subspace. +*> +*> For further explanation of the reciprocal condition numbers RCONDE +*> and RCONDV, see Section 4.10 of the LAPACK Users' Guide (where +*> these quantities are called s and sep respectively). +*> +*> A complex matrix is in Schur form if it is upper triangular. +*> +*>\endverbatim +* +* Arguments +* ========= +* +*> \param[in] JOBVS +*> \verbatim +*> JOBVS is CHARACTER*1 +*> = 'N': Schur vectors are not computed; +*> = 'V': Schur vectors are computed. +*> \endverbatim +*> +*> \param[in] SORT +*> \verbatim +*> SORT is CHARACTER*1 +*> Specifies whether or not to order the eigenvalues on the +*> diagonal of the Schur form. +*> = 'N': Eigenvalues are not ordered; +*> = 'S': Eigenvalues are ordered (see SELECT). +*> \endverbatim +*> +*> \param[in] SELECT +*> \verbatim +*> SELECT is procedure) LOGICAL FUNCTION of one COMPLEX argument +*> SELECT must be declared EXTERNAL in the calling subroutine. +*> If SORT = 'S', SELECT is used to select eigenvalues to order +*> to the top left of the Schur form. +*> If SORT = 'N', SELECT is not referenced. +*> An eigenvalue W(j) is selected if SELECT(W(j)) is true. +*> \endverbatim +*> +*> \param[in] SENSE +*> \verbatim +*> SENSE is CHARACTER*1 +*> Determines which reciprocal condition numbers are computed. +*> = 'N': None are computed; +*> = 'E': Computed for average of selected eigenvalues only; +*> = 'V': Computed for selected right invariant subspace only; +*> = 'B': Computed for both. +*> If SENSE = 'E', 'V' or 'B', SORT must equal 'S'. +*> \endverbatim +*> +*> \param[in] N +*> \verbatim +*> N is INTEGER +*> The order of the matrix A. N >= 0. +*> \endverbatim +*> +*> \param[in,out] A +*> \verbatim +*> A is COMPLEX array, dimension (LDA, N) +*> On entry, the N-by-N matrix A. +*> On exit, A is overwritten by its Schur form T. +*> \endverbatim +*> +*> \param[in] LDA +*> \verbatim +*> LDA is INTEGER +*> The leading dimension of the array A. LDA >= max(1,N). +*> \endverbatim +*> +*> \param[out] SDIM +*> \verbatim +*> SDIM is INTEGER +*> If SORT = 'N', SDIM = 0. +*> If SORT = 'S', SDIM = number of eigenvalues for which +*> SELECT is true. +*> \endverbatim +*> +*> \param[out] W +*> \verbatim +*> W is COMPLEX array, dimension (N) +*> W contains the computed eigenvalues, in the same order +*> that they appear on the diagonal of the output Schur form T. +*> \endverbatim +*> +*> \param[out] VS +*> \verbatim +*> VS is COMPLEX array, dimension (LDVS,N) +*> If JOBVS = 'V', VS contains the unitary matrix Z of Schur +*> vectors. +*> If JOBVS = 'N', VS is not referenced. +*> \endverbatim +*> +*> \param[in] LDVS +*> \verbatim +*> LDVS is INTEGER +*> The leading dimension of the array VS. LDVS >= 1, and if +*> JOBVS = 'V', LDVS >= N. +*> \endverbatim +*> +*> \param[out] RCONDE +*> \verbatim +*> RCONDE is REAL +*> If SENSE = 'E' or 'B', RCONDE contains the reciprocal +*> condition number for the average of the selected eigenvalues. +*> Not referenced if SENSE = 'N' or 'V'. +*> \endverbatim +*> +*> \param[out] RCONDV +*> \verbatim +*> RCONDV is REAL +*> If SENSE = 'V' or 'B', RCONDV contains the reciprocal +*> condition number for the selected right invariant subspace. +*> Not referenced if SENSE = 'N' or 'E'. +*> \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. LWORK >= max(1,2*N). +*> Also, if SENSE = 'E' or 'V' or 'B', LWORK >= 2*SDIM*(N-SDIM), +*> where SDIM is the number of selected eigenvalues computed by +*> this routine. Note that 2*SDIM*(N-SDIM) <= N*N/2. Note also +*> that an error is only returned if LWORK < max(1,2*N), but if +*> SENSE = 'E' or 'V' or 'B' this may not be large enough. +*> For good performance, LWORK must generally be larger. +*> \endverbatim +*> \verbatim +*> If LWORK = -1, then a workspace query is assumed; the routine +*> only calculates upper bound on the optimal size of the +*> array WORK, 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 (N) +*> \endverbatim +*> +*> \param[out] BWORK +*> \verbatim +*> BWORK is LOGICAL array, dimension (N) +*> Not referenced if SORT = 'N'. +*> \endverbatim +*> +*> \param[out] INFO +*> \verbatim +*> INFO is INTEGER +*> = 0: successful exit +*> < 0: if INFO = -i, the i-th argument had an illegal value. +*> > 0: if INFO = i, and i is +*> <= N: the QR algorithm failed to compute all the +*> eigenvalues; elements 1:ILO-1 and i+1:N of W +*> contain those eigenvalues which have converged; if +*> JOBVS = 'V', VS contains the transformation which +*> reduces A to its partially converged Schur form. +*> = N+1: the eigenvalues could not be reordered because some +*> eigenvalues were too close to separate (the problem +*> is very ill-conditioned); +*> = N+2: after reordering, roundoff changed values of some +*> complex eigenvalues so that leading eigenvalues in +*> the Schur form no longer satisfy SELECT=.TRUE. This +*> could also be caused by underflow due to scaling. +*> \endverbatim +*> +* +* Authors +* ======= +* +*> \author Univ. of Tennessee +*> \author Univ. of California Berkeley +*> \author Univ. of Colorado Denver +*> \author NAG Ltd. +* +*> \date November 2011 +* +*> \ingroup complexGEeigen +* +* ===================================================================== SUBROUTINE CGEESX( JOBVS, SORT, SELECT, SENSE, N, A, LDA, SDIM, W, $ VS, LDVS, RCONDE, RCONDV, WORK, LWORK, RWORK, $ BWORK, INFO ) * -* -- LAPACK driver routine (version 3.2.2) -- +* -- LAPACK eigen routine (version 3.2.2) -- * -- LAPACK is a software package provided by Univ. of Tennessee, -- * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..-- -* June 2010 +* November 2011 * * .. Scalar Arguments .. CHARACTER JOBVS, SENSE, SORT @@ -22,133 +252,6 @@ EXTERNAL SELECT * .. * -* Purpose -* ======= -* -* CGEESX computes for an N-by-N complex nonsymmetric matrix A, the -* eigenvalues, the Schur form T, and, optionally, the matrix of Schur -* vectors Z. This gives the Schur factorization A = Z*T*(Z**H). -* -* Optionally, it also orders the eigenvalues on the diagonal of the -* Schur form so that selected eigenvalues are at the top left; -* computes a reciprocal condition number for the average of the -* selected eigenvalues (RCONDE); and computes a reciprocal condition -* number for the right invariant subspace corresponding to the -* selected eigenvalues (RCONDV). The leading columns of Z form an -* orthonormal basis for this invariant subspace. -* -* For further explanation of the reciprocal condition numbers RCONDE -* and RCONDV, see Section 4.10 of the LAPACK Users' Guide (where -* these quantities are called s and sep respectively). -* -* A complex matrix is in Schur form if it is upper triangular. -* -* Arguments -* ========= -* -* JOBVS (input) CHARACTER*1 -* = 'N': Schur vectors are not computed; -* = 'V': Schur vectors are computed. -* -* SORT (input) CHARACTER*1 -* Specifies whether or not to order the eigenvalues on the -* diagonal of the Schur form. -* = 'N': Eigenvalues are not ordered; -* = 'S': Eigenvalues are ordered (see SELECT). -* -* SELECT (external procedure) LOGICAL FUNCTION of one COMPLEX argument -* SELECT must be declared EXTERNAL in the calling subroutine. -* If SORT = 'S', SELECT is used to select eigenvalues to order -* to the top left of the Schur form. -* If SORT = 'N', SELECT is not referenced. -* An eigenvalue W(j) is selected if SELECT(W(j)) is true. -* -* SENSE (input) CHARACTER*1 -* Determines which reciprocal condition numbers are computed. -* = 'N': None are computed; -* = 'E': Computed for average of selected eigenvalues only; -* = 'V': Computed for selected right invariant subspace only; -* = 'B': Computed for both. -* If SENSE = 'E', 'V' or 'B', SORT must equal 'S'. -* -* N (input) INTEGER -* The order of the matrix A. N >= 0. -* -* A (input/output) COMPLEX array, dimension (LDA, N) -* On entry, the N-by-N matrix A. -* On exit, A is overwritten by its Schur form T. -* -* LDA (input) INTEGER -* The leading dimension of the array A. LDA >= max(1,N). -* -* SDIM (output) INTEGER -* If SORT = 'N', SDIM = 0. -* If SORT = 'S', SDIM = number of eigenvalues for which -* SELECT is true. -* -* W (output) COMPLEX array, dimension (N) -* W contains the computed eigenvalues, in the same order -* that they appear on the diagonal of the output Schur form T. -* -* VS (output) COMPLEX array, dimension (LDVS,N) -* If JOBVS = 'V', VS contains the unitary matrix Z of Schur -* vectors. -* If JOBVS = 'N', VS is not referenced. -* -* LDVS (input) INTEGER -* The leading dimension of the array VS. LDVS >= 1, and if -* JOBVS = 'V', LDVS >= N. -* -* RCONDE (output) REAL -* If SENSE = 'E' or 'B', RCONDE contains the reciprocal -* condition number for the average of the selected eigenvalues. -* Not referenced if SENSE = 'N' or 'V'. -* -* RCONDV (output) REAL -* If SENSE = 'V' or 'B', RCONDV contains the reciprocal -* condition number for the selected right invariant subspace. -* Not referenced if SENSE = 'N' or 'E'. -* -* WORK (workspace/output) 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. LWORK >= max(1,2*N). -* Also, if SENSE = 'E' or 'V' or 'B', LWORK >= 2*SDIM*(N-SDIM), -* where SDIM is the number of selected eigenvalues computed by -* this routine. Note that 2*SDIM*(N-SDIM) <= N*N/2. Note also -* that an error is only returned if LWORK < max(1,2*N), but if -* SENSE = 'E' or 'V' or 'B' this may not be large enough. -* For good performance, LWORK must generally be larger. -* -* If LWORK = -1, then a workspace query is assumed; the routine -* only calculates upper bound on the optimal size of the -* array WORK, 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 (N) -* -* BWORK (workspace) LOGICAL array, dimension (N) -* Not referenced if SORT = 'N'. -* -* INFO (output) INTEGER -* = 0: successful exit -* < 0: if INFO = -i, the i-th argument had an illegal value. -* > 0: if INFO = i, and i is -* <= N: the QR algorithm failed to compute all the -* eigenvalues; elements 1:ILO-1 and i+1:N of W -* contain those eigenvalues which have converged; if -* JOBVS = 'V', VS contains the transformation which -* reduces A to its partially converged Schur form. -* = N+1: the eigenvalues could not be reordered because some -* eigenvalues were too close to separate (the problem -* is very ill-conditioned); -* = N+2: after reordering, roundoff changed values of some -* complex eigenvalues so that leading eigenvalues in -* the Schur form no longer satisfy SELECT=.TRUE. This -* could also be caused by underflow due to scaling. -* * ===================================================================== * * .. Parameters .. |