Integrating Doxygen in comments

1 files changed, 300 insertions, 190 deletions

diff --git a/SRC/ztgsna.f b/SRC/ztgsna.f
index 46fdce5a..80b93a06 100644
--- a/SRC/ztgsna.f
+++ b/SRC/ztgsna.f
@@ -1,11 +1,309 @@
+*> \brief \b ZTGSNA
+*
+*  =========== DOCUMENTATION ===========
+*
+* Online html documentation available at 
+*            http://www.netlib.org/lapack/explore-html/ 
+*
+*  Definition
+*  ==========
+*
+*       SUBROUTINE ZTGSNA( JOB, HOWMNY, SELECT, N, A, LDA, B, LDB, VL,
+*                          LDVL, VR, LDVR, S, DIF, MM, M, WORK, LWORK,
+*                          IWORK, INFO )
+* 
+*       .. Scalar Arguments ..
+*       CHARACTER          HOWMNY, JOB
+*       INTEGER            INFO, LDA, LDB, LDVL, LDVR, LWORK, M, MM, N
+*       ..
+*       .. Array Arguments ..
+*       LOGICAL            SELECT( * )
+*       INTEGER            IWORK( * )
+*       DOUBLE PRECISION   DIF( * ), S( * )
+*       COMPLEX*16         A( LDA, * ), B( LDB, * ), VL( LDVL, * ),
+*      $                   VR( LDVR, * ), WORK( * )
+*       ..
+*  
+*  Purpose
+*  =======
+*
+*>\details \b Purpose:
+*>\verbatim
+*>
+*> ZTGSNA estimates reciprocal condition numbers for specified
+*> eigenvalues and/or eigenvectors of a matrix pair (A, B).
+*>
+*> (A, B) must be in generalized Schur canonical form, that is, A and
+*> B are both upper triangular.
+*>
+*>\endverbatim
+*
+*  Arguments
+*  =========
+*
+*> \param[in] JOB
+*> \verbatim
+*>          JOB is CHARACTER*1
+*>          Specifies whether condition numbers are required for
+*>          eigenvalues (S) or eigenvectors (DIF):
+*>          = 'E': for eigenvalues only (S);
+*>          = 'V': for eigenvectors only (DIF);
+*>          = 'B': for both eigenvalues and eigenvectors (S and DIF).
+*> \endverbatim
+*>
+*> \param[in] HOWMNY
+*> \verbatim
+*>          HOWMNY is CHARACTER*1
+*>          = 'A': compute condition numbers for all eigenpairs;
+*>          = 'S': compute condition numbers for selected eigenpairs
+*>                 specified by the array SELECT.
+*> \endverbatim
+*>
+*> \param[in] SELECT
+*> \verbatim
+*>          SELECT is LOGICAL array, dimension (N)
+*>          If HOWMNY = 'S', SELECT specifies the eigenpairs for which
+*>          condition numbers are required. To select condition numbers
+*>          for the corresponding j-th eigenvalue and/or eigenvector,
+*>          SELECT(j) must be set to .TRUE..
+*>          If HOWMNY = 'A', SELECT is not referenced.
+*> \endverbatim
+*>
+*> \param[in] N
+*> \verbatim
+*>          N is INTEGER
+*>          The order of the square matrix pair (A, B). N >= 0.
+*> \endverbatim
+*>
+*> \param[in] A
+*> \verbatim
+*>          A is COMPLEX*16 array, dimension (LDA,N)
+*>          The upper triangular matrix A in the pair (A,B).
+*> \endverbatim
+*>
+*> \param[in] LDA
+*> \verbatim
+*>          LDA is INTEGER
+*>          The leading dimension of the array A. LDA >= max(1,N).
+*> \endverbatim
+*>
+*> \param[in] B
+*> \verbatim
+*>          B is COMPLEX*16 array, dimension (LDB,N)
+*>          The upper triangular matrix B in the pair (A, B).
+*> \endverbatim
+*>
+*> \param[in] LDB
+*> \verbatim
+*>          LDB is INTEGER
+*>          The leading dimension of the array B. LDB >= max(1,N).
+*> \endverbatim
+*>
+*> \param[in] VL
+*> \verbatim
+*>          VL is COMPLEX*16 array, dimension (LDVL,M)
+*>          IF JOB = 'E' or 'B', VL must contain left eigenvectors of
+*>          (A, B), corresponding to the eigenpairs specified by HOWMNY
+*>          and SELECT.  The eigenvectors must be stored in consecutive
+*>          columns of VL, as returned by ZTGEVC.
+*>          If JOB = 'V', VL is not referenced.
+*> \endverbatim
+*>
+*> \param[in] LDVL
+*> \verbatim
+*>          LDVL is INTEGER
+*>          The leading dimension of the array VL. LDVL >= 1; and
+*>          If JOB = 'E' or 'B', LDVL >= N.
+*> \endverbatim
+*>
+*> \param[in] VR
+*> \verbatim
+*>          VR is COMPLEX*16 array, dimension (LDVR,M)
+*>          IF JOB = 'E' or 'B', VR must contain right eigenvectors of
+*>          (A, B), corresponding to the eigenpairs specified by HOWMNY
+*>          and SELECT.  The eigenvectors must be stored in consecutive
+*>          columns of VR, as returned by ZTGEVC.
+*>          If JOB = 'V', VR is not referenced.
+*> \endverbatim
+*>
+*> \param[in] LDVR
+*> \verbatim
+*>          LDVR is INTEGER
+*>          The leading dimension of the array VR. LDVR >= 1;
+*>          If JOB = 'E' or 'B', LDVR >= N.
+*> \endverbatim
+*>
+*> \param[out] S
+*> \verbatim
+*>          S is DOUBLE PRECISION array, dimension (MM)
+*>          If JOB = 'E' or 'B', the reciprocal condition numbers of the
+*>          selected eigenvalues, stored in consecutive elements of the
+*>          array.
+*>          If JOB = 'V', S is not referenced.
+*> \endverbatim
+*>
+*> \param[out] DIF
+*> \verbatim
+*>          DIF is DOUBLE PRECISION array, dimension (MM)
+*>          If JOB = 'V' or 'B', the estimated reciprocal condition
+*>          numbers of the selected eigenvectors, stored in consecutive
+*>          elements of the array.
+*>          If the eigenvalues cannot be reordered to compute DIF(j),
+*>          DIF(j) is set to 0; this can only occur when the true value
+*>          would be very small anyway.
+*>          For each eigenvalue/vector specified by SELECT, DIF stores
+*>          a Frobenius norm-based estimate of Difl.
+*>          If JOB = 'E', DIF is not referenced.
+*> \endverbatim
+*>
+*> \param[in] MM
+*> \verbatim
+*>          MM is INTEGER
+*>          The number of elements in the arrays S and DIF. MM >= M.
+*> \endverbatim
+*>
+*> \param[out] M
+*> \verbatim
+*>          M is INTEGER
+*>          The number of elements of the arrays S and DIF used to store
+*>          the specified condition numbers; for each selected eigenvalue
+*>          one element is used. If HOWMNY = 'A', M is set to N.
+*> \endverbatim
+*>
+*> \param[out] WORK
+*> \verbatim
+*>          WORK is COMPLEX*16 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,N).
+*>          If JOB = 'V' or 'B', LWORK >= max(1,2*N*N).
+*> \endverbatim
+*>
+*> \param[out] IWORK
+*> \verbatim
+*>          IWORK is INTEGER array, dimension (N+2)
+*>          If JOB = 'E', IWORK is not referenced.
+*> \endverbatim
+*>
+*> \param[out] INFO
+*> \verbatim
+*>          INFO is INTEGER
+*>          = 0: Successful exit
+*>          < 0: If INFO = -i, the i-th argument had an illegal value
+*> \endverbatim
+*>
+*
+*  Authors
+*  =======
+*
+*> \author Univ. of Tennessee 
+*> \author Univ. of California Berkeley 
+*> \author Univ. of Colorado Denver 
+*> \author NAG Ltd. 
+*
+*> \date November 2011
+*
+*> \ingroup complex16OTHERcomputational
+*
+*
+*  Further Details
+*  ===============
+*>\details \b Further \b Details
+*> \verbatim
+*>
+*>  The reciprocal of the condition number of the i-th generalized
+*>  eigenvalue w = (a, b) is defined as
+*>
+*>          S(I) = (|v**HAu|**2 + |v**HBu|**2)**(1/2) / (norm(u)*norm(v))
+*>
+*>  where u and v are the right and left eigenvectors of (A, B)
+*>  corresponding to w; |z| denotes the absolute value of the complex
+*>  number, and norm(u) denotes the 2-norm of the vector u. The pair
+*>  (a, b) corresponds to an eigenvalue w = a/b (= v**HAu/v**HBu) of the
+*>  matrix pair (A, B). If both a and b equal zero, then (A,B) is
+*>  singular and S(I) = -1 is returned.
+*>
+*>  An approximate error bound on the chordal distance between the i-th
+*>  computed generalized eigenvalue w and the corresponding exact
+*>  eigenvalue lambda is
+*>
+*>          chord(w, lambda) <=   EPS * norm(A, B) / S(I),
+*>
+*>  where EPS is the machine precision.
+*>
+*>  The reciprocal of the condition number of the right eigenvector u
+*>  and left eigenvector v corresponding to the generalized eigenvalue w
+*>  is defined as follows. Suppose
+*>
+*>                   (A, B) = ( a   *  ) ( b  *  )  1
+*>                            ( 0  A22 ),( 0 B22 )  n-1
+*>                              1  n-1     1 n-1
+*>
+*>  Then the reciprocal condition number DIF(I) is
+*>
+*>          Difl[(a, b), (A22, B22)]  = sigma-min( Zl )
+*>
+*>  where sigma-min(Zl) denotes the smallest singular value of
+*>
+*>         Zl = [ kron(a, In-1) -kron(1, A22) ]
+*>              [ kron(b, In-1) -kron(1, B22) ].
+*>
+*>  Here In-1 is the identity matrix of size n-1 and X**H is the conjugate
+*>  transpose of X. kron(X, Y) is the Kronecker product between the
+*>  matrices X and Y.
+*>
+*>  We approximate the smallest singular value of Zl with an upper
+*>  bound. This is done by ZLATDF.
+*>
+*>  An approximate error bound for a computed eigenvector VL(i) or
+*>  VR(i) is given by
+*>
+*>                      EPS * norm(A, B) / DIF(i).
+*>
+*>  See ref. [2-3] for more details and further references.
+*>
+*>  Based on contributions by
+*>     Bo Kagstrom and Peter Poromaa, Department of Computing Science,
+*>     Umea University, S-901 87 Umea, Sweden.
+*>
+*>  References
+*>  ==========
+*>
+*>  [1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the
+*>      Generalized Real Schur Form of a Regular Matrix Pair (A, B), in
+*>      M.S. Moonen et al (eds), Linear Algebra for Large Scale and
+*>      Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
+*>
+*>  [2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified
+*>      Eigenvalues of a Regular Matrix Pair (A, B) and Condition
+*>      Estimation: Theory, Algorithms and Software, Report
+*>      UMINF - 94.04, Department of Computing Science, Umea University,
+*>      S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87.
+*>      To appear in Numerical Algorithms, 1996.
+*>
+*>  [3] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software
+*>      for Solving the Generalized Sylvester Equation and Estimating the
+*>      Separation between Regular Matrix Pairs, Report UMINF - 93.23,
+*>      Department of Computing Science, Umea University, S-901 87 Umea,
+*>      Sweden, December 1993, Revised April 1994, Also as LAPACK Working
+*>      Note 75.
+*>      To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.
+*>
+*> \endverbatim
+*>
+*  =====================================================================
       SUBROUTINE ZTGSNA( JOB, HOWMNY, SELECT, N, A, LDA, B, LDB, VL,
      $                   LDVL, VR, LDVR, S, DIF, MM, M, WORK, LWORK,
      $                   IWORK, INFO )
 *
-*  -- LAPACK routine (version 3.3.1) --
+*  -- LAPACK computational 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 ..
       CHARACTER          HOWMNY, JOB
@@ -19,194 +317,6 @@
      $                   VR( LDVR, * ), WORK( * )
 *     ..
 *
-*  Purpose
-*  =======
-*
-*  ZTGSNA estimates reciprocal condition numbers for specified
-*  eigenvalues and/or eigenvectors of a matrix pair (A, B).
-*
-*  (A, B) must be in generalized Schur canonical form, that is, A and
-*  B are both upper triangular.
-*
-*  Arguments
-*  =========
-*
-*  JOB     (input) CHARACTER*1
-*          Specifies whether condition numbers are required for
-*          eigenvalues (S) or eigenvectors (DIF):
-*          = 'E': for eigenvalues only (S);
-*          = 'V': for eigenvectors only (DIF);
-*          = 'B': for both eigenvalues and eigenvectors (S and DIF).
-*
-*  HOWMNY  (input) CHARACTER*1
-*          = 'A': compute condition numbers for all eigenpairs;
-*          = 'S': compute condition numbers for selected eigenpairs
-*                 specified by the array SELECT.
-*
-*  SELECT  (input) LOGICAL array, dimension (N)
-*          If HOWMNY = 'S', SELECT specifies the eigenpairs for which
-*          condition numbers are required. To select condition numbers
-*          for the corresponding j-th eigenvalue and/or eigenvector,
-*          SELECT(j) must be set to .TRUE..
-*          If HOWMNY = 'A', SELECT is not referenced.
-*
-*  N       (input) INTEGER
-*          The order of the square matrix pair (A, B). N >= 0.
-*
-*  A       (input) COMPLEX*16 array, dimension (LDA,N)
-*          The upper triangular matrix A in the pair (A,B).
-*
-*  LDA     (input) INTEGER
-*          The leading dimension of the array A. LDA >= max(1,N).
-*
-*  B       (input) COMPLEX*16 array, dimension (LDB,N)
-*          The upper triangular matrix B in the pair (A, B).
-*
-*  LDB     (input) INTEGER
-*          The leading dimension of the array B. LDB >= max(1,N).
-*
-*  VL      (input) COMPLEX*16 array, dimension (LDVL,M)
-*          IF JOB = 'E' or 'B', VL must contain left eigenvectors of
-*          (A, B), corresponding to the eigenpairs specified by HOWMNY
-*          and SELECT.  The eigenvectors must be stored in consecutive
-*          columns of VL, as returned by ZTGEVC.
-*          If JOB = 'V', VL is not referenced.
-*
-*  LDVL    (input) INTEGER
-*          The leading dimension of the array VL. LDVL >= 1; and
-*          If JOB = 'E' or 'B', LDVL >= N.
-*
-*  VR      (input) COMPLEX*16 array, dimension (LDVR,M)
-*          IF JOB = 'E' or 'B', VR must contain right eigenvectors of
-*          (A, B), corresponding to the eigenpairs specified by HOWMNY
-*          and SELECT.  The eigenvectors must be stored in consecutive
-*          columns of VR, as returned by ZTGEVC.
-*          If JOB = 'V', VR is not referenced.
-*
-*  LDVR    (input) INTEGER
-*          The leading dimension of the array VR. LDVR >= 1;
-*          If JOB = 'E' or 'B', LDVR >= N.
-*
-*  S       (output) DOUBLE PRECISION array, dimension (MM)
-*          If JOB = 'E' or 'B', the reciprocal condition numbers of the
-*          selected eigenvalues, stored in consecutive elements of the
-*          array.
-*          If JOB = 'V', S is not referenced.
-*
-*  DIF     (output) DOUBLE PRECISION array, dimension (MM)
-*          If JOB = 'V' or 'B', the estimated reciprocal condition
-*          numbers of the selected eigenvectors, stored in consecutive
-*          elements of the array.
-*          If the eigenvalues cannot be reordered to compute DIF(j),
-*          DIF(j) is set to 0; this can only occur when the true value
-*          would be very small anyway.
-*          For each eigenvalue/vector specified by SELECT, DIF stores
-*          a Frobenius norm-based estimate of Difl.
-*          If JOB = 'E', DIF is not referenced.
-*
-*  MM      (input) INTEGER
-*          The number of elements in the arrays S and DIF. MM >= M.
-*
-*  M       (output) INTEGER
-*          The number of elements of the arrays S and DIF used to store
-*          the specified condition numbers; for each selected eigenvalue
-*          one element is used. If HOWMNY = 'A', M is set to N.
-*
-*  WORK    (workspace/output) COMPLEX*16 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,N).
-*          If JOB = 'V' or 'B', LWORK >= max(1,2*N*N).
-*
-*  IWORK   (workspace) INTEGER array, dimension (N+2)
-*          If JOB = 'E', IWORK is not referenced.
-*
-*  INFO    (output) INTEGER
-*          = 0: Successful exit
-*          < 0: If INFO = -i, the i-th argument had an illegal value
-*
-*  Further Details
-*  ===============
-*
-*  The reciprocal of the condition number of the i-th generalized
-*  eigenvalue w = (a, b) is defined as
-*
-*          S(I) = (|v**HAu|**2 + |v**HBu|**2)**(1/2) / (norm(u)*norm(v))
-*
-*  where u and v are the right and left eigenvectors of (A, B)
-*  corresponding to w; |z| denotes the absolute value of the complex
-*  number, and norm(u) denotes the 2-norm of the vector u. The pair
-*  (a, b) corresponds to an eigenvalue w = a/b (= v**HAu/v**HBu) of the
-*  matrix pair (A, B). If both a and b equal zero, then (A,B) is
-*  singular and S(I) = -1 is returned.
-*
-*  An approximate error bound on the chordal distance between the i-th
-*  computed generalized eigenvalue w and the corresponding exact
-*  eigenvalue lambda is
-*
-*          chord(w, lambda) <=   EPS * norm(A, B) / S(I),
-*
-*  where EPS is the machine precision.
-*
-*  The reciprocal of the condition number of the right eigenvector u
-*  and left eigenvector v corresponding to the generalized eigenvalue w
-*  is defined as follows. Suppose
-*
-*                   (A, B) = ( a   *  ) ( b  *  )  1
-*                            ( 0  A22 ),( 0 B22 )  n-1
-*                              1  n-1     1 n-1
-*
-*  Then the reciprocal condition number DIF(I) is
-*
-*          Difl[(a, b), (A22, B22)]  = sigma-min( Zl )
-*
-*  where sigma-min(Zl) denotes the smallest singular value of
-*
-*         Zl = [ kron(a, In-1) -kron(1, A22) ]
-*              [ kron(b, In-1) -kron(1, B22) ].
-*
-*  Here In-1 is the identity matrix of size n-1 and X**H is the conjugate
-*  transpose of X. kron(X, Y) is the Kronecker product between the
-*  matrices X and Y.
-*
-*  We approximate the smallest singular value of Zl with an upper
-*  bound. This is done by ZLATDF.
-*
-*  An approximate error bound for a computed eigenvector VL(i) or
-*  VR(i) is given by
-*
-*                      EPS * norm(A, B) / DIF(i).
-*
-*  See ref. [2-3] for more details and further references.
-*
-*  Based on contributions by
-*     Bo Kagstrom and Peter Poromaa, Department of Computing Science,
-*     Umea University, S-901 87 Umea, Sweden.
-*
-*  References
-*  ==========
-*
-*  [1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the
-*      Generalized Real Schur Form of a Regular Matrix Pair (A, B), in
-*      M.S. Moonen et al (eds), Linear Algebra for Large Scale and
-*      Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
-*
-*  [2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified
-*      Eigenvalues of a Regular Matrix Pair (A, B) and Condition
-*      Estimation: Theory, Algorithms and Software, Report
-*      UMINF - 94.04, Department of Computing Science, Umea University,
-*      S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87.
-*      To appear in Numerical Algorithms, 1996.
-*
-*  [3] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software
-*      for Solving the Generalized Sylvester Equation and Estimating the
-*      Separation between Regular Matrix Pairs, Report UMINF - 93.23,
-*      Department of Computing Science, Umea University, S-901 87 Umea,
-*      Sweden, December 1993, Revised April 1994, Also as LAPACK Working
-*      Note 75.
-*      To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.
-*
 *  =====================================================================
 *
 *     .. Parameters ..