Integrating Doxygen in comments

1 files changed, 243 insertions, 148 deletions

diff --git a/SRC/dhseqr.f b/SRC/dhseqr.f
index 08447dc1..bb94d2a3 100644
--- a/SRC/dhseqr.f
+++ b/SRC/dhseqr.f
@@ -1,9 +1,250 @@
+*> \brief \b DHSEQR
+*
+*  =========== DOCUMENTATION ===========
+*
+* Online html documentation available at 
+*            http://www.netlib.org/lapack/explore-html/ 
+*
+*  Definition
+*  ==========
+*
+*       SUBROUTINE DHSEQR( JOB, COMPZ, N, ILO, IHI, H, LDH, WR, WI, Z,
+*                          LDZ, WORK, LWORK, INFO )
+* 
+*       .. Scalar Arguments ..
+*       INTEGER            IHI, ILO, INFO, LDH, LDZ, LWORK, N
+*       CHARACTER          COMPZ, JOB
+*       ..
+*       .. Array Arguments ..
+*       DOUBLE PRECISION   H( LDH, * ), WI( * ), WORK( * ), WR( * ),
+*      $                   Z( LDZ, * )
+*       ..
+*  Purpose
+*  =======
+*
+*>\details \b Purpose:
+*>\verbatim
+*> Purpose
+*>    =======
+*>
+*>    DHSEQR computes the eigenvalues of a Hessenberg matrix H
+*>    and, optionally, the matrices T and Z from the Schur decomposition
+*>    H = Z T Z**T, where T is an upper quasi-triangular matrix (the
+*>    Schur form), and Z is the orthogonal matrix of Schur vectors.
+*>
+*>    Optionally Z may be postmultiplied into an input orthogonal
+*>    matrix Q so that this routine can give the Schur factorization
+*>    of a matrix A which has been reduced to the Hessenberg form H
+*>    by the orthogonal matrix Q:  A = Q*H*Q**T = (QZ)*T*(QZ)**T.
+*>
+*>\endverbatim
+*
+*  Arguments
+*  =========
+*
+*> \param[in] JOB
+*> \verbatim
+*>          JOB is CHARACTER*1
+*>           = 'E':  compute eigenvalues only;
+*>           = 'S':  compute eigenvalues and the Schur form T.
+*> \endverbatim
+*>
+*> \param[in] COMPZ
+*> \verbatim
+*>          COMPZ is CHARACTER*1
+*>           = 'N':  no Schur vectors are computed;
+*>           = 'I':  Z is initialized to the unit matrix and the matrix Z
+*>                   of Schur vectors of H is returned;
+*>           = 'V':  Z must contain an orthogonal matrix Q on entry, and
+*>                   the product Q*Z is returned.
+*> \endverbatim
+*>
+*> \param[in] N
+*> \verbatim
+*>          N is INTEGER
+*>           The order of the matrix H.  N .GE. 0.
+*> \endverbatim
+*>
+*> \param[in] ILO
+*> \verbatim
+*>          ILO is INTEGER
+*> \param[in] IHI
+*> \verbatim
+*>          IHI is INTEGER
+*>           It is assumed that H is already upper triangular in rows
+*>           and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally
+*>           set by a previous call to DGEBAL, and then passed to DGEHRD
+*>           when the matrix output by DGEBAL is reduced to Hessenberg
+*>           form. Otherwise ILO and IHI should be set to 1 and N
+*>           respectively.  If N.GT.0, then 1.LE.ILO.LE.IHI.LE.N.
+*>           If N = 0, then ILO = 1 and IHI = 0.
+*> \endverbatim
+*> \endverbatim
+*>
+*> \param[in,out] H
+*> \verbatim
+*>          H is DOUBLE PRECISION array, dimension (LDH,N)
+*>           On entry, the upper Hessenberg matrix H.
+*>           On exit, if INFO = 0 and JOB = 'S', then H contains the
+*>           upper quasi-triangular matrix T from the Schur decomposition
+*>           (the Schur form); 2-by-2 diagonal blocks (corresponding to
+*>           complex conjugate pairs of eigenvalues) are returned in
+*>           standard form, with H(i,i) = H(i+1,i+1) and
+*>           H(i+1,i)*H(i,i+1).LT.0. If INFO = 0 and JOB = 'E', the
+*>           contents of H are unspecified on exit.  (The output value of
+*>           H when INFO.GT.0 is given under the description of INFO
+*>           below.)
+*> \endverbatim
+*> \verbatim
+*>           Unlike earlier versions of DHSEQR, this subroutine may
+*>           explicitly H(i,j) = 0 for i.GT.j and j = 1, 2, ... ILO-1
+*>           or j = IHI+1, IHI+2, ... N.
+*> \endverbatim
+*>
+*> \param[in] LDH
+*> \verbatim
+*>          LDH is INTEGER
+*>           The leading dimension of the array H. LDH .GE. max(1,N).
+*> \endverbatim
+*>
+*> \param[out] WR
+*> \verbatim
+*>          WR is DOUBLE PRECISION array, dimension (N)
+*> \param[out] WI
+*> \verbatim
+*>          WI is DOUBLE PRECISION array, dimension (N)
+*>           The real and imaginary parts, respectively, of the computed
+*>           eigenvalues. If two eigenvalues are computed as a complex
+*>           conjugate pair, they are stored in consecutive elements of
+*>           WR and WI, say the i-th and (i+1)th, with WI(i) .GT. 0 and
+*>           WI(i+1) .LT. 0. If JOB = 'S', the eigenvalues are stored in
+*>           the same order as on the diagonal of the Schur form returned
+*>           in H, with WR(i) = H(i,i) and, if H(i:i+1,i:i+1) is a 2-by-2
+*>           diagonal block, WI(i) = sqrt(-H(i+1,i)*H(i,i+1)) and
+*>           WI(i+1) = -WI(i).
+*> \endverbatim
+*> \endverbatim
+*>
+*> \param[in,out] Z
+*> \verbatim
+*>          Z is DOUBLE PRECISION array, dimension (LDZ,N)
+*>           If COMPZ = 'N', Z is not referenced.
+*>           If COMPZ = 'I', on entry Z need not be set and on exit,
+*>           if INFO = 0, Z contains the orthogonal matrix Z of the Schur
+*>           vectors of H.  If COMPZ = 'V', on entry Z must contain an
+*>           N-by-N matrix Q, which is assumed to be equal to the unit
+*>           matrix except for the submatrix Z(ILO:IHI,ILO:IHI). On exit,
+*>           if INFO = 0, Z contains Q*Z.
+*>           Normally Q is the orthogonal matrix generated by DORGHR
+*>           after the call to DGEHRD which formed the Hessenberg matrix
+*>           H. (The output value of Z when INFO.GT.0 is given under
+*>           the description of INFO below.)
+*> \endverbatim
+*>
+*> \param[in] LDZ
+*> \verbatim
+*>          LDZ is INTEGER
+*>           The leading dimension of the array Z.  if COMPZ = 'I' or
+*>           COMPZ = 'V', then LDZ.GE.MAX(1,N).  Otherwize, LDZ.GE.1.
+*> \endverbatim
+*>
+*> \param[out] WORK
+*> \verbatim
+*>          WORK is DOUBLE PRECISION array, dimension (LWORK)
+*>           On exit, if INFO = 0, WORK(1) returns an estimate of
+*>           the optimal value for LWORK.
+*> \endverbatim
+*>
+*> \param[in] LWORK
+*> \verbatim
+*>          LWORK is INTEGER
+*>           The dimension of the array WORK.  LWORK .GE. max(1,N)
+*>           is sufficient and delivers very good and sometimes
+*>           optimal performance.  However, LWORK as large as 11*N
+*>           may be required for optimal performance.  A workspace
+*>           query is recommended to determine the optimal workspace
+*>           size.
+*> \endverbatim
+*> \verbatim
+*>           If LWORK = -1, then DHSEQR does a workspace query.
+*>           In this case, DHSEQR checks the input parameters and
+*>           estimates the optimal workspace size for the given
+*>           values of N, ILO and IHI.  The estimate is returned
+*>           in WORK(1).  No error message related to LWORK is
+*>           issued by XERBLA.  Neither H nor Z are accessed.
+*> \endverbatim
+*>
+*> \param[out] INFO
+*> \verbatim
+*>          INFO is INTEGER
+*>             =  0:  successful exit
+*>           .LT. 0:  if INFO = -i, the i-th argument had an illegal
+*>                    value
+*>           .GT. 0:  if INFO = i, DHSEQR failed to compute all of
+*>                the eigenvalues.  Elements 1:ilo-1 and i+1:n of WR
+*>                and WI contain those eigenvalues which have been
+*>                successfully computed.  (Failures are rare.)
+*> \endverbatim
+*> \verbatim
+*>                If INFO .GT. 0 and JOB = 'E', then on exit, the
+*>                remaining unconverged eigenvalues are the eigen-
+*>                values of the upper Hessenberg matrix rows and
+*>                columns ILO through INFO of the final, output
+*>                value of H.
+*> \endverbatim
+*> \verbatim
+*>                If INFO .GT. 0 and JOB   = 'S', then on exit
+*> \endverbatim
+*> \verbatim
+*>           (*)  (initial value of H)*U  = U*(final value of H)
+*> \endverbatim
+*> \verbatim
+*>                where U is an orthogonal matrix.  The final
+*>                value of H is upper Hessenberg and quasi-triangular
+*>                in rows and columns INFO+1 through IHI.
+*> \endverbatim
+*> \verbatim
+*>                If INFO .GT. 0 and COMPZ = 'V', then on exit
+*> \endverbatim
+*> \verbatim
+*>                  (final value of Z)  =  (initial value of Z)*U
+*> \endverbatim
+*> \verbatim
+*>                where U is the orthogonal matrix in (*) (regard-
+*>                less of the value of JOB.)
+*> \endverbatim
+*> \verbatim
+*>                If INFO .GT. 0 and COMPZ = 'I', then on exit
+*>                      (final value of Z)  = U
+*>                where U is the orthogonal matrix in (*) (regard-
+*>                less of the value of JOB.)
+*> \endverbatim
+*> \verbatim
+*>                If INFO .GT. 0 and COMPZ = 'N', then Z is not
+*>                accessed.
+*> \endverbatim
+*>
+*
+*  Authors
+*  =======
+*
+*> \author Univ. of Tennessee 
+*> \author Univ. of California Berkeley 
+*> \author Univ. of Colorado Denver 
+*> \author NAG Ltd. 
+*
+*> \date November 2011
+*
+*> \ingroup doubleOTHERcomputational
+*
+*  =====================================================================
       SUBROUTINE DHSEQR( JOB, COMPZ, N, ILO, IHI, H, LDH, WR, WI, Z,
      $                   LDZ, WORK, LWORK, INFO )
 *
 *  -- LAPACK computational routine (version 3.2.2) --
-*     Univ. of Tennessee, Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..
-*     June 2010
+*  -- LAPACK is a software package provided by Univ. of Tennessee,    --
+*  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
+*     November 2011
 *
 *     .. Scalar Arguments ..
       INTEGER            IHI, ILO, INFO, LDH, LDZ, LWORK, N
@@ -13,152 +254,6 @@
       DOUBLE PRECISION   H( LDH, * ), WI( * ), WORK( * ), WR( * ),
      $                   Z( LDZ, * )
 *     ..
-*  Purpose
-*     =======
-*
-*     DHSEQR computes the eigenvalues of a Hessenberg matrix H
-*     and, optionally, the matrices T and Z from the Schur decomposition
-*     H = Z T Z**T, where T is an upper quasi-triangular matrix (the
-*     Schur form), and Z is the orthogonal matrix of Schur vectors.
-*
-*     Optionally Z may be postmultiplied into an input orthogonal
-*     matrix Q so that this routine can give the Schur factorization
-*     of a matrix A which has been reduced to the Hessenberg form H
-*     by the orthogonal matrix Q:  A = Q*H*Q**T = (QZ)*T*(QZ)**T.
-*
-*  Arguments
-*  =========
-*
-*     JOB   (input) CHARACTER*1
-*           = 'E':  compute eigenvalues only;
-*           = 'S':  compute eigenvalues and the Schur form T.
-*
-*     COMPZ (input) CHARACTER*1
-*           = 'N':  no Schur vectors are computed;
-*           = 'I':  Z is initialized to the unit matrix and the matrix Z
-*                   of Schur vectors of H is returned;
-*           = 'V':  Z must contain an orthogonal matrix Q on entry, and
-*                   the product Q*Z is returned.
-*
-*     N     (input) INTEGER
-*           The order of the matrix H.  N .GE. 0.
-*
-*     ILO   (input) INTEGER
-*     IHI   (input) INTEGER
-*           It is assumed that H is already upper triangular in rows
-*           and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally
-*           set by a previous call to DGEBAL, and then passed to DGEHRD
-*           when the matrix output by DGEBAL is reduced to Hessenberg
-*           form. Otherwise ILO and IHI should be set to 1 and N
-*           respectively.  If N.GT.0, then 1.LE.ILO.LE.IHI.LE.N.
-*           If N = 0, then ILO = 1 and IHI = 0.
-*
-*     H     (input/output) DOUBLE PRECISION array, dimension (LDH,N)
-*           On entry, the upper Hessenberg matrix H.
-*           On exit, if INFO = 0 and JOB = 'S', then H contains the
-*           upper quasi-triangular matrix T from the Schur decomposition
-*           (the Schur form); 2-by-2 diagonal blocks (corresponding to
-*           complex conjugate pairs of eigenvalues) are returned in
-*           standard form, with H(i,i) = H(i+1,i+1) and
-*           H(i+1,i)*H(i,i+1).LT.0. If INFO = 0 and JOB = 'E', the
-*           contents of H are unspecified on exit.  (The output value of
-*           H when INFO.GT.0 is given under the description of INFO
-*           below.)
-*
-*           Unlike earlier versions of DHSEQR, this subroutine may
-*           explicitly H(i,j) = 0 for i.GT.j and j = 1, 2, ... ILO-1
-*           or j = IHI+1, IHI+2, ... N.
-*
-*     LDH   (input) INTEGER
-*           The leading dimension of the array H. LDH .GE. max(1,N).
-*
-*     WR    (output) DOUBLE PRECISION array, dimension (N)
-*     WI    (output) DOUBLE PRECISION array, dimension (N)
-*           The real and imaginary parts, respectively, of the computed
-*           eigenvalues. If two eigenvalues are computed as a complex
-*           conjugate pair, they are stored in consecutive elements of
-*           WR and WI, say the i-th and (i+1)th, with WI(i) .GT. 0 and
-*           WI(i+1) .LT. 0. If JOB = 'S', the eigenvalues are stored in
-*           the same order as on the diagonal of the Schur form returned
-*           in H, with WR(i) = H(i,i) and, if H(i:i+1,i:i+1) is a 2-by-2
-*           diagonal block, WI(i) = sqrt(-H(i+1,i)*H(i,i+1)) and
-*           WI(i+1) = -WI(i).
-*
-*     Z     (input/output) DOUBLE PRECISION array, dimension (LDZ,N)
-*           If COMPZ = 'N', Z is not referenced.
-*           If COMPZ = 'I', on entry Z need not be set and on exit,
-*           if INFO = 0, Z contains the orthogonal matrix Z of the Schur
-*           vectors of H.  If COMPZ = 'V', on entry Z must contain an
-*           N-by-N matrix Q, which is assumed to be equal to the unit
-*           matrix except for the submatrix Z(ILO:IHI,ILO:IHI). On exit,
-*           if INFO = 0, Z contains Q*Z.
-*           Normally Q is the orthogonal matrix generated by DORGHR
-*           after the call to DGEHRD which formed the Hessenberg matrix
-*           H. (The output value of Z when INFO.GT.0 is given under
-*           the description of INFO below.)
-*
-*     LDZ   (input) INTEGER
-*           The leading dimension of the array Z.  if COMPZ = 'I' or
-*           COMPZ = 'V', then LDZ.GE.MAX(1,N).  Otherwize, LDZ.GE.1.
-*
-*     WORK  (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
-*           On exit, if INFO = 0, WORK(1) returns an estimate of
-*           the optimal value for LWORK.
-*
-*     LWORK (input) INTEGER
-*           The dimension of the array WORK.  LWORK .GE. max(1,N)
-*           is sufficient and delivers very good and sometimes
-*           optimal performance.  However, LWORK as large as 11*N
-*           may be required for optimal performance.  A workspace
-*           query is recommended to determine the optimal workspace
-*           size.
-*
-*           If LWORK = -1, then DHSEQR does a workspace query.
-*           In this case, DHSEQR checks the input parameters and
-*           estimates the optimal workspace size for the given
-*           values of N, ILO and IHI.  The estimate is returned
-*           in WORK(1).  No error message related to LWORK is
-*           issued by XERBLA.  Neither H nor Z are accessed.
-*
-*
-*     INFO  (output) INTEGER
-*             =  0:  successful exit
-*           .LT. 0:  if INFO = -i, the i-th argument had an illegal
-*                    value
-*           .GT. 0:  if INFO = i, DHSEQR failed to compute all of
-*                the eigenvalues.  Elements 1:ilo-1 and i+1:n of WR
-*                and WI contain those eigenvalues which have been
-*                successfully computed.  (Failures are rare.)
-*
-*                If INFO .GT. 0 and JOB = 'E', then on exit, the
-*                remaining unconverged eigenvalues are the eigen-
-*                values of the upper Hessenberg matrix rows and
-*                columns ILO through INFO of the final, output
-*                value of H.
-*
-*                If INFO .GT. 0 and JOB   = 'S', then on exit
-*
-*           (*)  (initial value of H)*U  = U*(final value of H)
-*
-*                where U is an orthogonal matrix.  The final
-*                value of H is upper Hessenberg and quasi-triangular
-*                in rows and columns INFO+1 through IHI.
-*
-*                If INFO .GT. 0 and COMPZ = 'V', then on exit
-*
-*                  (final value of Z)  =  (initial value of Z)*U
-*
-*                where U is the orthogonal matrix in (*) (regard-
-*                less of the value of JOB.)
-*
-*                If INFO .GT. 0 and COMPZ = 'I', then on exit
-*                      (final value of Z)  = U
-*                where U is the orthogonal matrix in (*) (regard-
-*                less of the value of JOB.)
-*
-*                If INFO .GT. 0 and COMPZ = 'N', then Z is not
-*                accessed.
-*
 *  ================================================================
 *             Default values supplied by
 *             ILAENV(ISPEC,'DHSEQR',JOB(:1)//COMPZ(:1),N,ILO,IHI,LWORK).