Integrating Doxygen in comments

1 files changed, 303 insertions, 189 deletions

diff --git a/SRC/sstevr.f b/SRC/sstevr.f
index 9e65739e..7cb4bf45 100644
--- a/SRC/sstevr.f
+++ b/SRC/sstevr.f
@@ -1,11 +1,312 @@
+*> \brief <b> SSTEVR computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices</b>
+*
+*  =========== DOCUMENTATION ===========
+*
+* Online html documentation available at 
+*            http://www.netlib.org/lapack/explore-html/ 
+*
+*  Definition
+*  ==========
+*
+*       SUBROUTINE SSTEVR( JOBZ, RANGE, N, D, E, VL, VU, IL, IU, ABSTOL,
+*                          M, W, Z, LDZ, ISUPPZ, WORK, LWORK, IWORK,
+*                          LIWORK, INFO )
+* 
+*       .. Scalar Arguments ..
+*       CHARACTER          JOBZ, RANGE
+*       INTEGER            IL, INFO, IU, LDZ, LIWORK, LWORK, M, N
+*       REAL               ABSTOL, VL, VU
+*       ..
+*       .. Array Arguments ..
+*       INTEGER            ISUPPZ( * ), IWORK( * )
+*       REAL               D( * ), E( * ), W( * ), WORK( * ), Z( LDZ, * )
+*       ..
+*  
+*  Purpose
+*  =======
+*
+*>\details \b Purpose:
+*>\verbatim
+*>
+*> SSTEVR computes selected eigenvalues and, optionally, eigenvectors
+*> of a real symmetric tridiagonal matrix T.  Eigenvalues and
+*> eigenvectors can be selected by specifying either a range of values
+*> or a range of indices for the desired eigenvalues.
+*>
+*> Whenever possible, SSTEVR calls SSTEMR to compute the
+*> eigenspectrum using Relatively Robust Representations.  SSTEMR
+*> computes eigenvalues by the dqds algorithm, while orthogonal
+*> eigenvectors are computed from various "good" L D L^T representations
+*> (also known as Relatively Robust Representations). Gram-Schmidt
+*> orthogonalization is avoided as far as possible. More specifically,
+*> the various steps of the algorithm are as follows. For the i-th
+*> unreduced block of T,
+*>    (a) Compute T - sigma_i = L_i D_i L_i^T, such that L_i D_i L_i^T
+*>         is a relatively robust representation,
+*>    (b) Compute the eigenvalues, lambda_j, of L_i D_i L_i^T to high
+*>        relative accuracy by the dqds algorithm,
+*>    (c) If there is a cluster of close eigenvalues, "choose" sigma_i
+*>        close to the cluster, and go to step (a),
+*>    (d) Given the approximate eigenvalue lambda_j of L_i D_i L_i^T,
+*>        compute the corresponding eigenvector by forming a
+*>        rank-revealing twisted factorization.
+*> The desired accuracy of the output can be specified by the input
+*> parameter ABSTOL.
+*>
+*> For more details, see "A new O(n^2) algorithm for the symmetric
+*> tridiagonal eigenvalue/eigenvector problem", by Inderjit Dhillon,
+*> Computer Science Division Technical Report No. UCB//CSD-97-971,
+*> UC Berkeley, May 1997.
+*>
+*>
+*> Note 1 : SSTEVR calls SSTEMR when the full spectrum is requested
+*> on machines which conform to the ieee-754 floating point standard.
+*> SSTEVR calls SSTEBZ and SSTEIN on non-ieee machines and
+*> when partial spectrum requests are made.
+*>
+*> Normal execution of SSTEMR may create NaNs and infinities and
+*> hence may abort due to a floating point exception in environments
+*> which do not handle NaNs and infinities in the ieee standard default
+*> manner.
+*>
+*>\endverbatim
+*
+*  Arguments
+*  =========
+*
+*> \param[in] JOBZ
+*> \verbatim
+*>          JOBZ is CHARACTER*1
+*>          = 'N':  Compute eigenvalues only;
+*>          = 'V':  Compute eigenvalues and eigenvectors.
+*> \endverbatim
+*>
+*> \param[in] RANGE
+*> \verbatim
+*>          RANGE is CHARACTER*1
+*>          = 'A': all eigenvalues will be found.
+*>          = 'V': all eigenvalues in the half-open interval (VL,VU]
+*>                 will be found.
+*>          = 'I': the IL-th through IU-th eigenvalues will be found.
+*>          For RANGE = 'V' or 'I' and IU - IL < N - 1, SSTEBZ and
+*>          SSTEIN are called
+*> \endverbatim
+*>
+*> \param[in] N
+*> \verbatim
+*>          N is INTEGER
+*>          The order of the matrix.  N >= 0.
+*> \endverbatim
+*>
+*> \param[in,out] D
+*> \verbatim
+*>          D is REAL array, dimension (N)
+*>          On entry, the n diagonal elements of the tridiagonal matrix
+*>          A.
+*>          On exit, D may be multiplied by a constant factor chosen
+*>          to avoid over/underflow in computing the eigenvalues.
+*> \endverbatim
+*>
+*> \param[in,out] E
+*> \verbatim
+*>          E is REAL array, dimension (max(1,N-1))
+*>          On entry, the (n-1) subdiagonal elements of the tridiagonal
+*>          matrix A in elements 1 to N-1 of E.
+*>          On exit, E may be multiplied by a constant factor chosen
+*>          to avoid over/underflow in computing the eigenvalues.
+*> \endverbatim
+*>
+*> \param[in] VL
+*> \verbatim
+*>          VL is REAL
+*> \endverbatim
+*>
+*> \param[in] VU
+*> \verbatim
+*>          VU is REAL
+*>          If RANGE='V', the lower and upper bounds of the interval to
+*>          be searched for eigenvalues. VL < VU.
+*>          Not referenced if RANGE = 'A' or 'I'.
+*> \endverbatim
+*>
+*> \param[in] IL
+*> \verbatim
+*>          IL is INTEGER
+*> \endverbatim
+*>
+*> \param[in] IU
+*> \verbatim
+*>          IU is INTEGER
+*>          If RANGE='I', the indices (in ascending order) of the
+*>          smallest and largest eigenvalues to be returned.
+*>          1 <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0.
+*>          Not referenced if RANGE = 'A' or 'V'.
+*> \endverbatim
+*>
+*> \param[in] ABSTOL
+*> \verbatim
+*>          ABSTOL is REAL
+*>          The absolute error tolerance for the eigenvalues.
+*>          An approximate eigenvalue is accepted as converged
+*>          when it is determined to lie in an interval [a,b]
+*>          of width less than or equal to
+*> \endverbatim
+*> \verbatim
+*>                  ABSTOL + EPS *   max( |a|,|b| ) ,
+*> \endverbatim
+*> \verbatim
+*>          where EPS is the machine precision.  If ABSTOL is less than
+*>          or equal to zero, then  EPS*|T|  will be used in its place,
+*>          where |T| is the 1-norm of the tridiagonal matrix obtained
+*>          by reducing A to tridiagonal form.
+*> \endverbatim
+*> \verbatim
+*>          See "Computing Small Singular Values of Bidiagonal Matrices
+*>          with Guaranteed High Relative Accuracy," by Demmel and
+*>          Kahan, LAPACK Working Note #3.
+*> \endverbatim
+*> \verbatim
+*>          If high relative accuracy is important, set ABSTOL to
+*>          SLAMCH( 'Safe minimum' ).  Doing so will guarantee that
+*>          eigenvalues are computed to high relative accuracy when
+*>          possible in future releases.  The current code does not
+*>          make any guarantees about high relative accuracy, but
+*>          future releases will. See J. Barlow and J. Demmel,
+*>          "Computing Accurate Eigensystems of Scaled Diagonally
+*>          Dominant Matrices", LAPACK Working Note #7, for a discussion
+*>          of which matrices define their eigenvalues to high relative
+*>          accuracy.
+*> \endverbatim
+*>
+*> \param[out] M
+*> \verbatim
+*>          M is INTEGER
+*>          The total number of eigenvalues found.  0 <= M <= N.
+*>          If RANGE = 'A', M = N, and if RANGE = 'I', M = IU-IL+1.
+*> \endverbatim
+*>
+*> \param[out] W
+*> \verbatim
+*>          W is REAL array, dimension (N)
+*>          The first M elements contain the selected eigenvalues in
+*>          ascending order.
+*> \endverbatim
+*>
+*> \param[out] Z
+*> \verbatim
+*>          Z is REAL array, dimension (LDZ, max(1,M) )
+*>          If JOBZ = 'V', then if INFO = 0, the first M columns of Z
+*>          contain the orthonormal eigenvectors of the matrix A
+*>          corresponding to the selected eigenvalues, with the i-th
+*>          column of Z holding the eigenvector associated with W(i).
+*>          Note: the user must ensure that at least max(1,M) columns are
+*>          supplied in the array Z; if RANGE = 'V', the exact value of M
+*>          is not known in advance and an upper bound must be used.
+*> \endverbatim
+*>
+*> \param[in] LDZ
+*> \verbatim
+*>          LDZ is INTEGER
+*>          The leading dimension of the array Z.  LDZ >= 1, and if
+*>          JOBZ = 'V', LDZ >= max(1,N).
+*> \endverbatim
+*>
+*> \param[out] ISUPPZ
+*> \verbatim
+*>          ISUPPZ is INTEGER array, dimension ( 2*max(1,M) )
+*>          The support of the eigenvectors in Z, i.e., the indices
+*>          indicating the nonzero elements in Z. The i-th eigenvector
+*>          is nonzero only in elements ISUPPZ( 2*i-1 ) through
+*>          ISUPPZ( 2*i ).
+*>          Implemented only for RANGE = 'A' or 'I' and IU - IL = N - 1
+*> \endverbatim
+*>
+*> \param[out] WORK
+*> \verbatim
+*>          WORK is REAL array, dimension (MAX(1,LWORK))
+*>          On exit, if INFO = 0, WORK(1) returns the optimal (and
+*>          minimal) LWORK.
+*> \endverbatim
+*>
+*> \param[in] LWORK
+*> \verbatim
+*>          LWORK is INTEGER
+*>          The dimension of the array WORK.  LWORK >= 20*N.
+*> \endverbatim
+*> \verbatim
+*>          If LWORK = -1, then a workspace query is assumed; the routine
+*>          only calculates the optimal sizes of the WORK and IWORK
+*>          arrays, returns these values as the first entries of the WORK
+*>          and IWORK arrays, and no error message related to LWORK or
+*>          LIWORK is issued by XERBLA.
+*> \endverbatim
+*>
+*> \param[out] IWORK
+*> \verbatim
+*>          IWORK is INTEGER array, dimension (MAX(1,LIWORK))
+*>          On exit, if INFO = 0, IWORK(1) returns the optimal (and
+*>          minimal) LIWORK.
+*> \endverbatim
+*>
+*> \param[in] LIWORK
+*> \verbatim
+*>          LIWORK is INTEGER
+*>          The dimension of the array IWORK.  LIWORK >= 10*N.
+*> \endverbatim
+*> \verbatim
+*>          If LIWORK = -1, then a workspace query is assumed; the
+*>          routine only calculates the optimal sizes of the WORK and
+*>          IWORK arrays, returns these values as the first entries of
+*>          the WORK and IWORK arrays, and no error message related to
+*>          LWORK or LIWORK is issued by XERBLA.
+*> \endverbatim
+*>
+*> \param[out] INFO
+*> \verbatim
+*>          INFO is INTEGER
+*>          = 0:  successful exit
+*>          < 0:  if INFO = -i, the i-th argument had an illegal value
+*>          > 0:  Internal error
+*> \endverbatim
+*>
+*
+*  Authors
+*  =======
+*
+*> \author Univ. of Tennessee 
+*> \author Univ. of California Berkeley 
+*> \author Univ. of Colorado Denver 
+*> \author NAG Ltd. 
+*
+*> \date November 2011
+*
+*> \ingroup realOTHEReigen
+*
+*
+*  Further Details
+*  ===============
+*>\details \b Further \b Details
+*> \verbatim
+*>
+*>  Based on contributions by
+*>     Inderjit Dhillon, IBM Almaden, USA
+*>     Osni Marques, LBNL/NERSC, USA
+*>     Ken Stanley, Computer Science Division, University of
+*>       California at Berkeley, USA
+*>     Jason Riedy, Computer Science Division, University of
+*>       California at Berkeley, USA
+*>
+*> \endverbatim
+*>
+*  =====================================================================
       SUBROUTINE SSTEVR( JOBZ, RANGE, N, D, E, VL, VU, IL, IU, ABSTOL,
      $                   M, W, Z, LDZ, ISUPPZ, WORK, LWORK, IWORK,
      $                   LIWORK, INFO )
 *
-*  -- LAPACK driver routine (version 3.2) --
+*  -- LAPACK eigen 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          JOBZ, RANGE
@@ -17,193 +318,6 @@
       REAL               D( * ), E( * ), W( * ), WORK( * ), Z( LDZ, * )
 *     ..
 *
-*  Purpose
-*  =======
-*
-*  SSTEVR computes selected eigenvalues and, optionally, eigenvectors
-*  of a real symmetric tridiagonal matrix T.  Eigenvalues and
-*  eigenvectors can be selected by specifying either a range of values
-*  or a range of indices for the desired eigenvalues.
-*
-*  Whenever possible, SSTEVR calls SSTEMR to compute the
-*  eigenspectrum using Relatively Robust Representations.  SSTEMR
-*  computes eigenvalues by the dqds algorithm, while orthogonal
-*  eigenvectors are computed from various "good" L D L^T representations
-*  (also known as Relatively Robust Representations). Gram-Schmidt
-*  orthogonalization is avoided as far as possible. More specifically,
-*  the various steps of the algorithm are as follows. For the i-th
-*  unreduced block of T,
-*     (a) Compute T - sigma_i = L_i D_i L_i^T, such that L_i D_i L_i^T
-*          is a relatively robust representation,
-*     (b) Compute the eigenvalues, lambda_j, of L_i D_i L_i^T to high
-*         relative accuracy by the dqds algorithm,
-*     (c) If there is a cluster of close eigenvalues, "choose" sigma_i
-*         close to the cluster, and go to step (a),
-*     (d) Given the approximate eigenvalue lambda_j of L_i D_i L_i^T,
-*         compute the corresponding eigenvector by forming a
-*         rank-revealing twisted factorization.
-*  The desired accuracy of the output can be specified by the input
-*  parameter ABSTOL.
-*
-*  For more details, see "A new O(n^2) algorithm for the symmetric
-*  tridiagonal eigenvalue/eigenvector problem", by Inderjit Dhillon,
-*  Computer Science Division Technical Report No. UCB//CSD-97-971,
-*  UC Berkeley, May 1997.
-*
-*
-*  Note 1 : SSTEVR calls SSTEMR when the full spectrum is requested
-*  on machines which conform to the ieee-754 floating point standard.
-*  SSTEVR calls SSTEBZ and SSTEIN on non-ieee machines and
-*  when partial spectrum requests are made.
-*
-*  Normal execution of SSTEMR may create NaNs and infinities and
-*  hence may abort due to a floating point exception in environments
-*  which do not handle NaNs and infinities in the ieee standard default
-*  manner.
-*
-*  Arguments
-*  =========
-*
-*  JOBZ    (input) CHARACTER*1
-*          = 'N':  Compute eigenvalues only;
-*          = 'V':  Compute eigenvalues and eigenvectors.
-*
-*  RANGE   (input) CHARACTER*1
-*          = 'A': all eigenvalues will be found.
-*          = 'V': all eigenvalues in the half-open interval (VL,VU]
-*                 will be found.
-*          = 'I': the IL-th through IU-th eigenvalues will be found.
-*          For RANGE = 'V' or 'I' and IU - IL < N - 1, SSTEBZ and
-*          SSTEIN are called
-*
-*  N       (input) INTEGER
-*          The order of the matrix.  N >= 0.
-*
-*  D       (input/output) REAL array, dimension (N)
-*          On entry, the n diagonal elements of the tridiagonal matrix
-*          A.
-*          On exit, D may be multiplied by a constant factor chosen
-*          to avoid over/underflow in computing the eigenvalues.
-*
-*  E       (input/output) REAL array, dimension (max(1,N-1))
-*          On entry, the (n-1) subdiagonal elements of the tridiagonal
-*          matrix A in elements 1 to N-1 of E.
-*          On exit, E may be multiplied by a constant factor chosen
-*          to avoid over/underflow in computing the eigenvalues.
-*
-*  VL      (input) REAL
-*
-*  VU      (input) REAL
-*          If RANGE='V', the lower and upper bounds of the interval to
-*          be searched for eigenvalues. VL < VU.
-*          Not referenced if RANGE = 'A' or 'I'.
-*
-*  IL      (input) INTEGER
-*
-*  IU      (input) INTEGER
-*          If RANGE='I', the indices (in ascending order) of the
-*          smallest and largest eigenvalues to be returned.
-*          1 <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0.
-*          Not referenced if RANGE = 'A' or 'V'.
-*
-*  ABSTOL  (input) REAL
-*          The absolute error tolerance for the eigenvalues.
-*          An approximate eigenvalue is accepted as converged
-*          when it is determined to lie in an interval [a,b]
-*          of width less than or equal to
-*
-*                  ABSTOL + EPS *   max( |a|,|b| ) ,
-*
-*          where EPS is the machine precision.  If ABSTOL is less than
-*          or equal to zero, then  EPS*|T|  will be used in its place,
-*          where |T| is the 1-norm of the tridiagonal matrix obtained
-*          by reducing A to tridiagonal form.
-*
-*          See "Computing Small Singular Values of Bidiagonal Matrices
-*          with Guaranteed High Relative Accuracy," by Demmel and
-*          Kahan, LAPACK Working Note #3.
-*
-*          If high relative accuracy is important, set ABSTOL to
-*          SLAMCH( 'Safe minimum' ).  Doing so will guarantee that
-*          eigenvalues are computed to high relative accuracy when
-*          possible in future releases.  The current code does not
-*          make any guarantees about high relative accuracy, but
-*          future releases will. See J. Barlow and J. Demmel,
-*          "Computing Accurate Eigensystems of Scaled Diagonally
-*          Dominant Matrices", LAPACK Working Note #7, for a discussion
-*          of which matrices define their eigenvalues to high relative
-*          accuracy.
-*
-*  M       (output) INTEGER
-*          The total number of eigenvalues found.  0 <= M <= N.
-*          If RANGE = 'A', M = N, and if RANGE = 'I', M = IU-IL+1.
-*
-*  W       (output) REAL array, dimension (N)
-*          The first M elements contain the selected eigenvalues in
-*          ascending order.
-*
-*  Z       (output) REAL array, dimension (LDZ, max(1,M) )
-*          If JOBZ = 'V', then if INFO = 0, the first M columns of Z
-*          contain the orthonormal eigenvectors of the matrix A
-*          corresponding to the selected eigenvalues, with the i-th
-*          column of Z holding the eigenvector associated with W(i).
-*          Note: the user must ensure that at least max(1,M) columns are
-*          supplied in the array Z; if RANGE = 'V', the exact value of M
-*          is not known in advance and an upper bound must be used.
-*
-*  LDZ     (input) INTEGER
-*          The leading dimension of the array Z.  LDZ >= 1, and if
-*          JOBZ = 'V', LDZ >= max(1,N).
-*
-*  ISUPPZ  (output) INTEGER array, dimension ( 2*max(1,M) )
-*          The support of the eigenvectors in Z, i.e., the indices
-*          indicating the nonzero elements in Z. The i-th eigenvector
-*          is nonzero only in elements ISUPPZ( 2*i-1 ) through
-*          ISUPPZ( 2*i ).
-*          Implemented only for RANGE = 'A' or 'I' and IU - IL = N - 1
-*
-*  WORK    (workspace/output) REAL array, dimension (MAX(1,LWORK))
-*          On exit, if INFO = 0, WORK(1) returns the optimal (and
-*          minimal) LWORK.
-*
-*  LWORK   (input) INTEGER
-*          The dimension of the array WORK.  LWORK >= 20*N.
-*
-*          If LWORK = -1, then a workspace query is assumed; the routine
-*          only calculates the optimal sizes of the WORK and IWORK
-*          arrays, returns these values as the first entries of the WORK
-*          and IWORK arrays, and no error message related to LWORK or
-*          LIWORK is issued by XERBLA.
-*
-*  IWORK   (workspace/output) INTEGER array, dimension (MAX(1,LIWORK))
-*          On exit, if INFO = 0, IWORK(1) returns the optimal (and
-*          minimal) LIWORK.
-*
-*  LIWORK  (input) INTEGER
-*          The dimension of the array IWORK.  LIWORK >= 10*N.
-*
-*          If LIWORK = -1, then a workspace query is assumed; the
-*          routine only calculates the optimal sizes of the WORK and
-*          IWORK arrays, returns these values as the first entries of
-*          the WORK and IWORK arrays, and no error message related to
-*          LWORK or LIWORK is issued by XERBLA.
-*
-*  INFO    (output) INTEGER
-*          = 0:  successful exit
-*          < 0:  if INFO = -i, the i-th argument had an illegal value
-*          > 0:  Internal error
-*
-*  Further Details
-*  ===============
-*
-*  Based on contributions by
-*     Inderjit Dhillon, IBM Almaden, USA
-*     Osni Marques, LBNL/NERSC, USA
-*     Ken Stanley, Computer Science Division, University of
-*       California at Berkeley, USA
-*     Jason Riedy, Computer Science Division, University of
-*       California at Berkeley, USA
-*
 *  =====================================================================
 *
 *     .. Parameters ..