Integrating Doxygen in comments

1 files changed, 300 insertions, 160 deletions

diff --git a/TESTING/EIG/zdrgvx.f b/TESTING/EIG/zdrgvx.f
index 7a6e2097..86e32712 100644
--- a/TESTING/EIG/zdrgvx.f
+++ b/TESTING/EIG/zdrgvx.f
@@ -1,11 +1,309 @@
+*> \brief \b ZDRGVX
+*
+*  =========== DOCUMENTATION ===========
+*
+* Online html documentation available at 
+*            http://www.netlib.org/lapack/explore-html/ 
+*
+*  Definition
+*  ==========
+*
+*       SUBROUTINE ZDRGVX( NSIZE, THRESH, NIN, NOUT, A, LDA, B, AI, BI,
+*                          ALPHA, BETA, VL, VR, ILO, IHI, LSCALE, RSCALE,
+*                          S, DTRU, DIF, DIFTRU, WORK, LWORK, RWORK,
+*                          IWORK, LIWORK, RESULT, BWORK, INFO )
+* 
+*       .. Scalar Arguments ..
+*       INTEGER            IHI, ILO, INFO, LDA, LIWORK, LWORK, NIN, NOUT,
+*      $                   NSIZE
+*       DOUBLE PRECISION   THRESH
+*       ..
+*       .. Array Arguments ..
+*       LOGICAL            BWORK( * )
+*       INTEGER            IWORK( * )
+*       DOUBLE PRECISION   DIF( * ), DIFTRU( * ), DTRU( * ), LSCALE( * ),
+*      $                   RESULT( 4 ), RSCALE( * ), RWORK( * ), S( * )
+*       COMPLEX*16         A( LDA, * ), AI( LDA, * ), ALPHA( * ),
+*      $                   B( LDA, * ), BETA( * ), BI( LDA, * ),
+*      $                   VL( LDA, * ), VR( LDA, * ), WORK( * )
+*       ..
+*  
+*  Purpose
+*  =======
+*
+*>\details \b Purpose:
+*>\verbatim
+*>
+*> ZDRGVX checks the nonsymmetric generalized eigenvalue problem
+*> expert driver ZGGEVX.
+*>
+*> ZGGEVX computes the generalized eigenvalues, (optionally) the left
+*> and/or right eigenvectors, (optionally) computes a balancing
+*> transformation to improve the conditioning, and (optionally)
+*> reciprocal condition numbers for the eigenvalues and eigenvectors.
+*>
+*> When ZDRGVX is called with NSIZE > 0, two types of test matrix pairs
+*> are generated by the subroutine DLATM6 and test the driver ZGGEVX.
+*> The test matrices have the known exact condition numbers for
+*> eigenvalues. For the condition numbers of the eigenvectors
+*> corresponding the first and last eigenvalues are also know
+*> ``exactly'' (see ZLATM6).
+*> For each matrix pair, the following tests will be performed and
+*> compared with the threshhold THRESH.
+*>
+*> (1) max over all left eigenvalue/-vector pairs (beta/alpha,l) of
+*>
+*>    | l**H * (beta A - alpha B) | / ( ulp max( |beta A|, |alpha B| ) )
+*>
+*>     where l**H is the conjugate tranpose of l.
+*>
+*> (2) max over all right eigenvalue/-vector pairs (beta/alpha,r) of
+*>
+*>       | (beta A - alpha B) r | / ( ulp max( |beta A|, |alpha B| ) )
+*>
+*> (3) The condition number S(i) of eigenvalues computed by ZGGEVX
+*>     differs less than a factor THRESH from the exact S(i) (see
+*>     ZLATM6).
+*>
+*> (4) DIF(i) computed by ZTGSNA differs less than a factor 10*THRESH
+*>     from the exact value (for the 1st and 5th vectors only).
+*>
+*> Test Matrices
+*> =============
+*>
+*> Two kinds of test matrix pairs
+*>          (A, B) = inverse(YH) * (Da, Db) * inverse(X)
+*> are used in the tests:
+*>
+*> 1: Da = 1+a   0    0    0    0    Db = 1   0   0   0   0
+*>          0   2+a   0    0    0         0   1   0   0   0
+*>          0    0   3+a   0    0         0   0   1   0   0
+*>          0    0    0   4+a   0         0   0   0   1   0
+*>          0    0    0    0   5+a ,      0   0   0   0   1 , and
+*>
+*> 2: Da =  1   -1    0    0    0    Db = 1   0   0   0   0
+*>          1    1    0    0    0         0   1   0   0   0
+*>          0    0    1    0    0         0   0   1   0   0
+*>          0    0    0   1+a  1+b        0   0   0   1   0
+*>          0    0    0  -1-b  1+a ,      0   0   0   0   1 .
+*>
+*> In both cases the same inverse(YH) and inverse(X) are used to compute
+*> (A, B), giving the exact eigenvectors to (A,B) as (YH, X):
+*>
+*> YH:  =  1    0   -y    y   -y    X =  1   0  -x  -x   x
+*>         0    1   -y    y   -y         0   1   x  -x  -x
+*>         0    0    1    0    0         0   0   1   0   0
+*>         0    0    0    1    0         0   0   0   1   0
+*>         0    0    0    0    1,        0   0   0   0   1 , where
+*>
+*> a, b, x and y will have all values independently of each other from
+*> { sqrt(sqrt(ULP)),  0.1,  1,  10,  1/sqrt(sqrt(ULP)) }.
+*>
+*>\endverbatim
+*
+*  Arguments
+*  =========
+*
+*> \param[in] NSIZE
+*> \verbatim
+*>          NSIZE is INTEGER
+*>          The number of sizes of matrices to use.  NSIZE must be at
+*>          least zero. If it is zero, no randomly generated matrices
+*>          are tested, but any test matrices read from NIN will be
+*>          tested.  If it is not zero, then N = 5.
+*> \endverbatim
+*>
+*> \param[in] THRESH
+*> \verbatim
+*>          THRESH is DOUBLE PRECISION
+*>          A test will count as "failed" if the "error", computed as
+*>          described above, exceeds THRESH.  Note that the error
+*>          is scaled to be O(1), so THRESH should be a reasonably
+*>          small multiple of 1, e.g., 10 or 100.  In particular,
+*>          it should not depend on the precision (single vs. double)
+*>          or the size of the matrix.  It must be at least zero.
+*> \endverbatim
+*>
+*> \param[in] NIN
+*> \verbatim
+*>          NIN is INTEGER
+*>          The FORTRAN unit number for reading in the data file of
+*>          problems to solve.
+*> \endverbatim
+*>
+*> \param[in] NOUT
+*> \verbatim
+*>          NOUT is INTEGER
+*>          The FORTRAN unit number for printing out error messages
+*>          (e.g., if a routine returns IINFO not equal to 0.)
+*> \endverbatim
+*>
+*> \param[out] A
+*> \verbatim
+*>          A is COMPLEX*16 array, dimension (LDA, NSIZE)
+*>          Used to hold the matrix whose eigenvalues are to be
+*>          computed.  On exit, A contains the last matrix actually used.
+*> \endverbatim
+*>
+*> \param[in] LDA
+*> \verbatim
+*>          LDA is INTEGER
+*>          The leading dimension of A, B, AI, BI, Ao, and Bo.
+*>          It must be at least 1 and at least NSIZE.
+*> \endverbatim
+*>
+*> \param[out] B
+*> \verbatim
+*>          B is COMPLEX*16 array, dimension (LDA, NSIZE)
+*>          Used to hold the matrix whose eigenvalues are to be
+*>          computed.  On exit, B contains the last matrix actually used.
+*> \endverbatim
+*>
+*> \param[out] AI
+*> \verbatim
+*>          AI is COMPLEX*16 array, dimension (LDA, NSIZE)
+*>          Copy of A, modified by ZGGEVX.
+*> \endverbatim
+*>
+*> \param[out] BI
+*> \verbatim
+*>          BI is COMPLEX*16 array, dimension (LDA, NSIZE)
+*>          Copy of B, modified by ZGGEVX.
+*> \endverbatim
+*>
+*> \param[out] ALPHA
+*> \verbatim
+*>          ALPHA is COMPLEX*16 array, dimension (NSIZE)
+*> \endverbatim
+*>
+*> \param[out] BETA
+*> \verbatim
+*>          BETA is COMPLEX*16 array, dimension (NSIZE)
+*> \endverbatim
+*> \verbatim
+*>          On exit, ALPHA/BETA are the eigenvalues.
+*> \endverbatim
+*>
+*> \param[out] VL
+*> \verbatim
+*>          VL is COMPLEX*16 array, dimension (LDA, NSIZE)
+*>          VL holds the left eigenvectors computed by ZGGEVX.
+*> \endverbatim
+*>
+*> \param[out] VR
+*> \verbatim
+*>          VR is COMPLEX*16 array, dimension (LDA, NSIZE)
+*>          VR holds the right eigenvectors computed by ZGGEVX.
+*> \endverbatim
+*>
+*> \param[out] ILO
+*> \verbatim
+*>  		ILO is INTEGER
+*> \endverbatim
+*>
+*> \param[out] IHI
+*> \verbatim
+*>  		IHI is INTEGER
+*> \endverbatim
+*>
+*> \param[out] LSCALE	
+*> \verbatim
+*>  		LSCALE is DOUBLE PRECISION array, dimension (N)
+*> \endverbatim
+*>
+*> \param[out] RSCALE	
+*> \verbatim
+*>  		RSCALE is DOUBLE PRECISION array, dimension (N)
+*> \endverbatim
+*>
+*> \param[out] S	
+*> \verbatim
+*>  		S is DOUBLE PRECISION array, dimension (N)
+*> \endverbatim
+*>
+*> \param[out] DTRU	
+*> \verbatim
+*>  		DTRU is DOUBLE PRECISION array, dimension (N)
+*> \endverbatim
+*>
+*> \param[out] DIF		
+*> \verbatim
+*>  		DIF is DOUBLE PRECISION array, dimension (N)
+*> \endverbatim
+*>
+*> \param[out] DIFTRU		
+*> \verbatim
+*>  		DIFTRU is DOUBLE PRECISION array, dimension (N)
+*> \endverbatim
+*>
+*> \param[out] WORK
+*> \verbatim
+*>          WORK is COMPLEX*16 array, dimension (LWORK)
+*> \endverbatim
+*>
+*> \param[in] LWORK
+*> \verbatim
+*>          LWORK is INTEGER
+*>          Leading dimension of WORK.  LWORK >= 2*N*N + 2*N
+*> \endverbatim
+*>
+*> \param[out] RWORK
+*> \verbatim
+*>          RWORK is DOUBLE PRECISION array, dimension (6*N)
+*> \endverbatim
+*>
+*> \param[out] IWORK
+*> \verbatim
+*>          IWORK is INTEGER array, dimension (LIWORK)
+*> \endverbatim
+*>
+*> \param[in] LIWORK
+*> \verbatim
+*>          LIWORK is INTEGER
+*>          Leading dimension of IWORK.  LIWORK >= N+2.
+*> \endverbatim
+*> \verbatim
+*>
+*> \param[out] RESULT	
+*>  		RESULT is DOUBLE PRECISION array, dimension (4)
+*> \endverbatim
+*>
+*> \param[out] BWORK
+*> \verbatim
+*>          BWORK is LOGICAL array, dimension (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:  A routine returned an error code.
+*> \endverbatim
+*>
+*
+*  Authors
+*  =======
+*
+*> \author Univ. of Tennessee 
+*> \author Univ. of California Berkeley 
+*> \author Univ. of Colorado Denver 
+*> \author NAG Ltd. 
+*
+*> \date November 2011
+*
+*> \ingroup complex16_eig
+*
+*  =====================================================================
       SUBROUTINE ZDRGVX( NSIZE, THRESH, NIN, NOUT, A, LDA, B, AI, BI,
      $                   ALPHA, BETA, VL, VR, ILO, IHI, LSCALE, RSCALE,
      $                   S, DTRU, DIF, DIFTRU, WORK, LWORK, RWORK,
      $                   IWORK, LIWORK, RESULT, BWORK, INFO )
 *
 *  -- LAPACK test routine (version 3.1) --
-*     Univ. of Tennessee, Univ. of California Berkeley and NAG Ltd..
-*     November 2006
+*  -- 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, LDA, LIWORK, LWORK, NIN, NOUT,
@@ -22,164 +320,6 @@
      $                   VL( LDA, * ), VR( LDA, * ), WORK( * )
 *     ..
 *
-*  Purpose
-*  =======
-*
-*  ZDRGVX checks the nonsymmetric generalized eigenvalue problem
-*  expert driver ZGGEVX.
-*
-*  ZGGEVX computes the generalized eigenvalues, (optionally) the left
-*  and/or right eigenvectors, (optionally) computes a balancing
-*  transformation to improve the conditioning, and (optionally)
-*  reciprocal condition numbers for the eigenvalues and eigenvectors.
-*
-*  When ZDRGVX is called with NSIZE > 0, two types of test matrix pairs
-*  are generated by the subroutine DLATM6 and test the driver ZGGEVX.
-*  The test matrices have the known exact condition numbers for
-*  eigenvalues. For the condition numbers of the eigenvectors
-*  corresponding the first and last eigenvalues are also know
-*  ``exactly'' (see ZLATM6).
-*  For each matrix pair, the following tests will be performed and
-*  compared with the threshhold THRESH.
-*
-*  (1) max over all left eigenvalue/-vector pairs (beta/alpha,l) of
-*
-*     | l**H * (beta A - alpha B) | / ( ulp max( |beta A|, |alpha B| ) )
-*
-*      where l**H is the conjugate tranpose of l.
-*
-*  (2) max over all right eigenvalue/-vector pairs (beta/alpha,r) of
-*
-*        | (beta A - alpha B) r | / ( ulp max( |beta A|, |alpha B| ) )
-*
-*  (3) The condition number S(i) of eigenvalues computed by ZGGEVX
-*      differs less than a factor THRESH from the exact S(i) (see
-*      ZLATM6).
-*
-*  (4) DIF(i) computed by ZTGSNA differs less than a factor 10*THRESH
-*      from the exact value (for the 1st and 5th vectors only).
-*
-*  Test Matrices
-*  =============
-*
-*  Two kinds of test matrix pairs
-*           (A, B) = inverse(YH) * (Da, Db) * inverse(X)
-*  are used in the tests:
-*
-*  1: Da = 1+a   0    0    0    0    Db = 1   0   0   0   0
-*           0   2+a   0    0    0         0   1   0   0   0
-*           0    0   3+a   0    0         0   0   1   0   0
-*           0    0    0   4+a   0         0   0   0   1   0
-*           0    0    0    0   5+a ,      0   0   0   0   1 , and
-*
-*  2: Da =  1   -1    0    0    0    Db = 1   0   0   0   0
-*           1    1    0    0    0         0   1   0   0   0
-*           0    0    1    0    0         0   0   1   0   0
-*           0    0    0   1+a  1+b        0   0   0   1   0
-*           0    0    0  -1-b  1+a ,      0   0   0   0   1 .
-*
-*  In both cases the same inverse(YH) and inverse(X) are used to compute
-*  (A, B), giving the exact eigenvectors to (A,B) as (YH, X):
-*
-*  YH:  =  1    0   -y    y   -y    X =  1   0  -x  -x   x
-*          0    1   -y    y   -y         0   1   x  -x  -x
-*          0    0    1    0    0         0   0   1   0   0
-*          0    0    0    1    0         0   0   0   1   0
-*          0    0    0    0    1,        0   0   0   0   1 , where
-*
-*  a, b, x and y will have all values independently of each other from
-*  { sqrt(sqrt(ULP)),  0.1,  1,  10,  1/sqrt(sqrt(ULP)) }.
-*
-*  Arguments
-*  =========
-*
-*  NSIZE   (input) INTEGER
-*          The number of sizes of matrices to use.  NSIZE must be at
-*          least zero. If it is zero, no randomly generated matrices
-*          are tested, but any test matrices read from NIN will be
-*          tested.  If it is not zero, then N = 5.
-*
-*  THRESH  (input) DOUBLE PRECISION
-*          A test will count as "failed" if the "error", computed as
-*          described above, exceeds THRESH.  Note that the error
-*          is scaled to be O(1), so THRESH should be a reasonably
-*          small multiple of 1, e.g., 10 or 100.  In particular,
-*          it should not depend on the precision (single vs. double)
-*          or the size of the matrix.  It must be at least zero.
-*
-*  NIN     (input) INTEGER
-*          The FORTRAN unit number for reading in the data file of
-*          problems to solve.
-*
-*  NOUT    (input) INTEGER
-*          The FORTRAN unit number for printing out error messages
-*          (e.g., if a routine returns IINFO not equal to 0.)
-*
-*  A       (workspace) COMPLEX*16 array, dimension (LDA, NSIZE)
-*          Used to hold the matrix whose eigenvalues are to be
-*          computed.  On exit, A contains the last matrix actually used.
-*
-*  LDA     (input) INTEGER
-*          The leading dimension of A, B, AI, BI, Ao, and Bo.
-*          It must be at least 1 and at least NSIZE.
-*
-*  B       (workspace) COMPLEX*16 array, dimension (LDA, NSIZE)
-*          Used to hold the matrix whose eigenvalues are to be
-*          computed.  On exit, B contains the last matrix actually used.
-*
-*  AI      (workspace) COMPLEX*16 array, dimension (LDA, NSIZE)
-*          Copy of A, modified by ZGGEVX.
-*
-*  BI      (workspace) COMPLEX*16 array, dimension (LDA, NSIZE)
-*          Copy of B, modified by ZGGEVX.
-*
-*  ALPHA   (workspace) COMPLEX*16 array, dimension (NSIZE)
-*  BETA    (workspace) COMPLEX*16 array, dimension (NSIZE)
-*          On exit, ALPHA/BETA are the eigenvalues.
-*
-*  VL      (workspace) COMPLEX*16 array, dimension (LDA, NSIZE)
-*          VL holds the left eigenvectors computed by ZGGEVX.
-*
-*  VR      (workspace) COMPLEX*16 array, dimension (LDA, NSIZE)
-*          VR holds the right eigenvectors computed by ZGGEVX.
-*
-*  ILO     (output/workspace) INTEGER
-*
-*  IHI     (output/workspace) INTEGER
-*
-*  LSCALE  (output/workspace) DOUBLE PRECISION array, dimension (N)
-*
-*  RSCALE  (output/workspace) DOUBLE PRECISION array, dimension (N)
-*
-*  S       (output/workspace) DOUBLE PRECISION array, dimension (N)
-*
-*  DTRU    (output/workspace) DOUBLE PRECISION array, dimension (N)
-*
-*  DIF     (output/workspace) DOUBLE PRECISION array, dimension (N)
-*
-*  DIFTRU  (output/workspace) DOUBLE PRECISION array, dimension (N)
-*
-*  WORK    (workspace) COMPLEX*16 array, dimension (LWORK)
-*
-*  LWORK   (input) INTEGER
-*          Leading dimension of WORK.  LWORK >= 2*N*N + 2*N
-*
-*  RWORK   (workspace) DOUBLE PRECISION array, dimension (6*N)
-*
-*  IWORK   (workspace) INTEGER array, dimension (LIWORK)
-*
-*  LIWORK  (input) INTEGER
-*          Leading dimension of IWORK.  LIWORK >= N+2.
-*
-*  RESULT  (output/workspace) DOUBLE PRECISION array, dimension (4)
-*
-*  BWORK   (workspace) LOGICAL array, dimension (N)
-*
-*  INFO    (output) INTEGER
-*          = 0:  successful exit
-*          < 0:  if INFO = -i, the i-th argument had an illegal value.
-*          > 0:  A routine returned an error code.
-*
 *  =====================================================================
 *
 *     .. Parameters ..