Integrating Doxygen in comments

1 files changed, 227 insertions, 113 deletions

diff --git a/SRC/dlar1v.f b/SRC/dlar1v.f
index adc13085..7912c74e 100644
--- a/SRC/dlar1v.f
+++ b/SRC/dlar1v.f
@@ -1,3 +1,229 @@
+*> \brief \b DLAR1V
+*
+*  =========== DOCUMENTATION ===========
+*
+* Online html documentation available at 
+*            http://www.netlib.org/lapack/explore-html/ 
+*
+*  Definition
+*  ==========
+*
+*       SUBROUTINE DLAR1V( N, B1, BN, LAMBDA, D, L, LD, LLD,
+*                  PIVMIN, GAPTOL, Z, WANTNC, NEGCNT, ZTZ, MINGMA,
+*                  R, ISUPPZ, NRMINV, RESID, RQCORR, WORK )
+* 
+*       .. Scalar Arguments ..
+*       LOGICAL            WANTNC
+*       INTEGER   B1, BN, N, NEGCNT, R
+*       DOUBLE PRECISION   GAPTOL, LAMBDA, MINGMA, NRMINV, PIVMIN, RESID,
+*      $                   RQCORR, ZTZ
+*       ..
+*       .. Array Arguments ..
+*       INTEGER            ISUPPZ( * )
+*       DOUBLE PRECISION   D( * ), L( * ), LD( * ), LLD( * ),
+*      $                  WORK( * )
+*       DOUBLE PRECISION Z( * )
+*       ..
+*  
+*  Purpose
+*  =======
+*
+*>\details \b Purpose:
+*>\verbatim
+*>
+*> DLAR1V computes the (scaled) r-th column of the inverse of
+*> the sumbmatrix in rows B1 through BN of the tridiagonal matrix
+*> L D L**T - sigma I. When sigma is close to an eigenvalue, the
+*> computed vector is an accurate eigenvector. Usually, r corresponds
+*> to the index where the eigenvector is largest in magnitude.
+*> The following steps accomplish this computation :
+*> (a) Stationary qd transform,  L D L**T - sigma I = L(+) D(+) L(+)**T,
+*> (b) Progressive qd transform, L D L**T - sigma I = U(-) D(-) U(-)**T,
+*> (c) Computation of the diagonal elements of the inverse of
+*>     L D L**T - sigma I by combining the above transforms, and choosing
+*>     r as the index where the diagonal of the inverse is (one of the)
+*>     largest in magnitude.
+*> (d) Computation of the (scaled) r-th column of the inverse using the
+*>     twisted factorization obtained by combining the top part of the
+*>     the stationary and the bottom part of the progressive transform.
+*>
+*>\endverbatim
+*
+*  Arguments
+*  =========
+*
+*> \param[in] N
+*> \verbatim
+*>          N is INTEGER
+*>           The order of the matrix L D L**T.
+*> \endverbatim
+*>
+*> \param[in] B1
+*> \verbatim
+*>          B1 is INTEGER
+*>           First index of the submatrix of L D L**T.
+*> \endverbatim
+*>
+*> \param[in] BN
+*> \verbatim
+*>          BN is INTEGER
+*>           Last index of the submatrix of L D L**T.
+*> \endverbatim
+*>
+*> \param[in] LAMBDA
+*> \verbatim
+*>          LAMBDA is DOUBLE PRECISION
+*>           The shift. In order to compute an accurate eigenvector,
+*>           LAMBDA should be a good approximation to an eigenvalue
+*>           of L D L**T.
+*> \endverbatim
+*>
+*> \param[in] L
+*> \verbatim
+*>          L is DOUBLE PRECISION array, dimension (N-1)
+*>           The (n-1) subdiagonal elements of the unit bidiagonal matrix
+*>           L, in elements 1 to N-1.
+*> \endverbatim
+*>
+*> \param[in] D
+*> \verbatim
+*>          D is DOUBLE PRECISION array, dimension (N)
+*>           The n diagonal elements of the diagonal matrix D.
+*> \endverbatim
+*>
+*> \param[in] LD
+*> \verbatim
+*>          LD is DOUBLE PRECISION array, dimension (N-1)
+*>           The n-1 elements L(i)*D(i).
+*> \endverbatim
+*>
+*> \param[in] LLD
+*> \verbatim
+*>          LLD is DOUBLE PRECISION array, dimension (N-1)
+*>           The n-1 elements L(i)*L(i)*D(i).
+*> \endverbatim
+*>
+*> \param[in] PIVMIN
+*> \verbatim
+*>          PIVMIN is DOUBLE PRECISION
+*>           The minimum pivot in the Sturm sequence.
+*> \endverbatim
+*>
+*> \param[in] GAPTOL
+*> \verbatim
+*>          GAPTOL is DOUBLE PRECISION
+*>           Tolerance that indicates when eigenvector entries are negligible
+*>           w.r.t. their contribution to the residual.
+*> \endverbatim
+*>
+*> \param[in,out] Z
+*> \verbatim
+*>          Z is DOUBLE PRECISION array, dimension (N)
+*>           On input, all entries of Z must be set to 0.
+*>           On output, Z contains the (scaled) r-th column of the
+*>           inverse. The scaling is such that Z(R) equals 1.
+*> \endverbatim
+*>
+*> \param[in] WANTNC
+*> \verbatim
+*>          WANTNC is LOGICAL
+*>           Specifies whether NEGCNT has to be computed.
+*> \endverbatim
+*>
+*> \param[out] NEGCNT
+*> \verbatim
+*>          NEGCNT is INTEGER
+*>           If WANTNC is .TRUE. then NEGCNT = the number of pivots < pivmin
+*>           in the  matrix factorization L D L**T, and NEGCNT = -1 otherwise.
+*> \endverbatim
+*>
+*> \param[out] ZTZ
+*> \verbatim
+*>          ZTZ is DOUBLE PRECISION
+*>           The square of the 2-norm of Z.
+*> \endverbatim
+*>
+*> \param[out] MINGMA
+*> \verbatim
+*>          MINGMA is DOUBLE PRECISION
+*>           The reciprocal of the largest (in magnitude) diagonal
+*>           element of the inverse of L D L**T - sigma I.
+*> \endverbatim
+*>
+*> \param[in,out] R
+*> \verbatim
+*>          R is INTEGER
+*>           The twist index for the twisted factorization used to
+*>           compute Z.
+*>           On input, 0 <= R <= N. If R is input as 0, R is set to
+*>           the index where (L D L**T - sigma I)^{-1} is largest
+*>           in magnitude. If 1 <= R <= N, R is unchanged.
+*>           On output, R contains the twist index used to compute Z.
+*>           Ideally, R designates the position of the maximum entry in the
+*>           eigenvector.
+*> \endverbatim
+*>
+*> \param[out] ISUPPZ
+*> \verbatim
+*>          ISUPPZ is INTEGER array, dimension (2)
+*>           The support of the vector in Z, i.e., the vector Z is
+*>           nonzero only in elements ISUPPZ(1) through ISUPPZ( 2 ).
+*> \endverbatim
+*>
+*> \param[out] NRMINV
+*> \verbatim
+*>          NRMINV is DOUBLE PRECISION
+*>           NRMINV = 1/SQRT( ZTZ )
+*> \endverbatim
+*>
+*> \param[out] RESID
+*> \verbatim
+*>          RESID is DOUBLE PRECISION
+*>           The residual of the FP vector.
+*>           RESID = ABS( MINGMA )/SQRT( ZTZ )
+*> \endverbatim
+*>
+*> \param[out] RQCORR
+*> \verbatim
+*>          RQCORR is DOUBLE PRECISION
+*>           The Rayleigh Quotient correction to LAMBDA.
+*>           RQCORR = MINGMA*TMP
+*> \endverbatim
+*>
+*> \param[out] WORK
+*> \verbatim
+*>          WORK is DOUBLE PRECISION array, dimension (4*N)
+*> \endverbatim
+*>
+*
+*  Authors
+*  =======
+*
+*> \author Univ. of Tennessee 
+*> \author Univ. of California Berkeley 
+*> \author Univ. of Colorado Denver 
+*> \author NAG Ltd. 
+*
+*> \date November 2011
+*
+*> \ingroup doubleOTHERauxiliary
+*
+*
+*  Further Details
+*  ===============
+*>\details \b Further \b Details
+*> \verbatim
+*>
+*>  Based on contributions by
+*>     Beresford Parlett, University of California, Berkeley, USA
+*>     Jim Demmel, University of California, Berkeley, USA
+*>     Inderjit Dhillon, University of Texas, Austin, USA
+*>     Osni Marques, LBNL/NERSC, USA
+*>     Christof Voemel, University of California, Berkeley, USA
+*>
+*> \endverbatim
+*>
+*  =====================================================================
       SUBROUTINE DLAR1V( N, B1, BN, LAMBDA, D, L, LD, LLD,
      $           PIVMIN, GAPTOL, Z, WANTNC, NEGCNT, ZTZ, MINGMA,
      $           R, ISUPPZ, NRMINV, RESID, RQCORR, WORK )
@@ -5,7 +231,7 @@
 *  -- LAPACK auxiliary 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..--
-*  -- April 2011                                                      --
+*     November 2011
 *
 *     .. Scalar Arguments ..
       LOGICAL            WANTNC
@@ -20,118 +246,6 @@
       DOUBLE PRECISION Z( * )
 *     ..
 *
-*  Purpose
-*  =======
-*
-*  DLAR1V computes the (scaled) r-th column of the inverse of
-*  the sumbmatrix in rows B1 through BN of the tridiagonal matrix
-*  L D L**T - sigma I. When sigma is close to an eigenvalue, the
-*  computed vector is an accurate eigenvector. Usually, r corresponds
-*  to the index where the eigenvector is largest in magnitude.
-*  The following steps accomplish this computation :
-*  (a) Stationary qd transform,  L D L**T - sigma I = L(+) D(+) L(+)**T,
-*  (b) Progressive qd transform, L D L**T - sigma I = U(-) D(-) U(-)**T,
-*  (c) Computation of the diagonal elements of the inverse of
-*      L D L**T - sigma I by combining the above transforms, and choosing
-*      r as the index where the diagonal of the inverse is (one of the)
-*      largest in magnitude.
-*  (d) Computation of the (scaled) r-th column of the inverse using the
-*      twisted factorization obtained by combining the top part of the
-*      the stationary and the bottom part of the progressive transform.
-*
-*  Arguments
-*  =========
-*
-*  N        (input) INTEGER
-*           The order of the matrix L D L**T.
-*
-*  B1       (input) INTEGER
-*           First index of the submatrix of L D L**T.
-*
-*  BN       (input) INTEGER
-*           Last index of the submatrix of L D L**T.
-*
-*  LAMBDA    (input) DOUBLE PRECISION
-*           The shift. In order to compute an accurate eigenvector,
-*           LAMBDA should be a good approximation to an eigenvalue
-*           of L D L**T.
-*
-*  L        (input) DOUBLE PRECISION array, dimension (N-1)
-*           The (n-1) subdiagonal elements of the unit bidiagonal matrix
-*           L, in elements 1 to N-1.
-*
-*  D        (input) DOUBLE PRECISION array, dimension (N)
-*           The n diagonal elements of the diagonal matrix D.
-*
-*  LD       (input) DOUBLE PRECISION array, dimension (N-1)
-*           The n-1 elements L(i)*D(i).
-*
-*  LLD      (input) DOUBLE PRECISION array, dimension (N-1)
-*           The n-1 elements L(i)*L(i)*D(i).
-*
-*  PIVMIN   (input) DOUBLE PRECISION
-*           The minimum pivot in the Sturm sequence.
-*
-*  GAPTOL   (input) DOUBLE PRECISION
-*           Tolerance that indicates when eigenvector entries are negligible
-*           w.r.t. their contribution to the residual.
-*
-*  Z        (input/output) DOUBLE PRECISION array, dimension (N)
-*           On input, all entries of Z must be set to 0.
-*           On output, Z contains the (scaled) r-th column of the
-*           inverse. The scaling is such that Z(R) equals 1.
-*
-*  WANTNC   (input) LOGICAL
-*           Specifies whether NEGCNT has to be computed.
-*
-*  NEGCNT   (output) INTEGER
-*           If WANTNC is .TRUE. then NEGCNT = the number of pivots < pivmin
-*           in the  matrix factorization L D L**T, and NEGCNT = -1 otherwise.
-*
-*  ZTZ      (output) DOUBLE PRECISION
-*           The square of the 2-norm of Z.
-*
-*  MINGMA   (output) DOUBLE PRECISION
-*           The reciprocal of the largest (in magnitude) diagonal
-*           element of the inverse of L D L**T - sigma I.
-*
-*  R        (input/output) INTEGER
-*           The twist index for the twisted factorization used to
-*           compute Z.
-*           On input, 0 <= R <= N. If R is input as 0, R is set to
-*           the index where (L D L**T - sigma I)^{-1} is largest
-*           in magnitude. If 1 <= R <= N, R is unchanged.
-*           On output, R contains the twist index used to compute Z.
-*           Ideally, R designates the position of the maximum entry in the
-*           eigenvector.
-*
-*  ISUPPZ   (output) INTEGER array, dimension (2)
-*           The support of the vector in Z, i.e., the vector Z is
-*           nonzero only in elements ISUPPZ(1) through ISUPPZ( 2 ).
-*
-*  NRMINV   (output) DOUBLE PRECISION
-*           NRMINV = 1/SQRT( ZTZ )
-*
-*  RESID    (output) DOUBLE PRECISION
-*           The residual of the FP vector.
-*           RESID = ABS( MINGMA )/SQRT( ZTZ )
-*
-*  RQCORR   (output) DOUBLE PRECISION
-*           The Rayleigh Quotient correction to LAMBDA.
-*           RQCORR = MINGMA*TMP
-*
-*  WORK     (workspace) DOUBLE PRECISION array, dimension (4*N)
-*
-*  Further Details
-*  ===============
-*
-*  Based on contributions by
-*     Beresford Parlett, University of California, Berkeley, USA
-*     Jim Demmel, University of California, Berkeley, USA
-*     Inderjit Dhillon, University of Texas, Austin, USA
-*     Osni Marques, LBNL/NERSC, USA
-*     Christof Voemel, University of California, Berkeley, USA
-*
 *  =====================================================================
 *
 *     .. Parameters ..