Integrating Doxygen in comments

1 files changed, 206 insertions, 121 deletions

diff --git a/SRC/sgesvd.f b/SRC/sgesvd.f
index 1f0f0537..8b2ad01f 100644
--- a/SRC/sgesvd.f
+++ b/SRC/sgesvd.f
@@ -1,10 +1,214 @@
+*> \brief <b> SGESVD computes the singular value decomposition (SVD) for GE matrices</b>
+*
+*  =========== DOCUMENTATION ===========
+*
+* Online html documentation available at 
+*            http://www.netlib.org/lapack/explore-html/ 
+*
+*  Definition
+*  ==========
+*
+*       SUBROUTINE SGESVD( JOBU, JOBVT, M, N, A, LDA, S, U, LDU, VT, LDVT,
+*                          WORK, LWORK, INFO )
+* 
+*       .. Scalar Arguments ..
+*       CHARACTER          JOBU, JOBVT
+*       INTEGER            INFO, LDA, LDU, LDVT, LWORK, M, N
+*       ..
+*       .. Array Arguments ..
+*       REAL               A( LDA, * ), S( * ), U( LDU, * ),
+*      $                   VT( LDVT, * ), WORK( * )
+*       ..
+*  
+*  Purpose
+*  =======
+*
+*>\details \b Purpose:
+*>\verbatim
+*>
+*> SGESVD computes the singular value decomposition (SVD) of a real
+*> M-by-N matrix A, optionally computing the left and/or right singular
+*> vectors. The SVD is written
+*>
+*>      A = U * SIGMA * transpose(V)
+*>
+*> where SIGMA is an M-by-N matrix which is zero except for its
+*> min(m,n) diagonal elements, U is an M-by-M orthogonal matrix, and
+*> V is an N-by-N orthogonal matrix.  The diagonal elements of SIGMA
+*> are the singular values of A; they are real and non-negative, and
+*> are returned in descending order.  The first min(m,n) columns of
+*> U and V are the left and right singular vectors of A.
+*>
+*> Note that the routine returns V**T, not V.
+*>
+*>\endverbatim
+*
+*  Arguments
+*  =========
+*
+*> \param[in] JOBU
+*> \verbatim
+*>          JOBU is CHARACTER*1
+*>          Specifies options for computing all or part of the matrix U:
+*>          = 'A':  all M columns of U are returned in array U:
+*>          = 'S':  the first min(m,n) columns of U (the left singular
+*>                  vectors) are returned in the array U;
+*>          = 'O':  the first min(m,n) columns of U (the left singular
+*>                  vectors) are overwritten on the array A;
+*>          = 'N':  no columns of U (no left singular vectors) are
+*>                  computed.
+*> \endverbatim
+*>
+*> \param[in] JOBVT
+*> \verbatim
+*>          JOBVT is CHARACTER*1
+*>          Specifies options for computing all or part of the matrix
+*>          V**T:
+*>          = 'A':  all N rows of V**T are returned in the array VT;
+*>          = 'S':  the first min(m,n) rows of V**T (the right singular
+*>                  vectors) are returned in the array VT;
+*>          = 'O':  the first min(m,n) rows of V**T (the right singular
+*>                  vectors) are overwritten on the array A;
+*>          = 'N':  no rows of V**T (no right singular vectors) are
+*>                  computed.
+*> \endverbatim
+*> \verbatim
+*>          JOBVT and JOBU cannot both be 'O'.
+*> \endverbatim
+*>
+*> \param[in] M
+*> \verbatim
+*>          M is INTEGER
+*>          The number of rows of the input matrix A.  M >= 0.
+*> \endverbatim
+*>
+*> \param[in] N
+*> \verbatim
+*>          N is INTEGER
+*>          The number of columns of the input matrix A.  N >= 0.
+*> \endverbatim
+*>
+*> \param[in,out] A
+*> \verbatim
+*>          A is REAL array, dimension (LDA,N)
+*>          On entry, the M-by-N matrix A.
+*>          On exit,
+*>          if JOBU = 'O',  A is overwritten with the first min(m,n)
+*>                          columns of U (the left singular vectors,
+*>                          stored columnwise);
+*>          if JOBVT = 'O', A is overwritten with the first min(m,n)
+*>                          rows of V**T (the right singular vectors,
+*>                          stored rowwise);
+*>          if JOBU .ne. 'O' and JOBVT .ne. 'O', the contents of A
+*>                          are destroyed.
+*> \endverbatim
+*>
+*> \param[in] LDA
+*> \verbatim
+*>          LDA is INTEGER
+*>          The leading dimension of the array A.  LDA >= max(1,M).
+*> \endverbatim
+*>
+*> \param[out] S
+*> \verbatim
+*>          S is REAL array, dimension (min(M,N))
+*>          The singular values of A, sorted so that S(i) >= S(i+1).
+*> \endverbatim
+*>
+*> \param[out] U
+*> \verbatim
+*>          U is REAL array, dimension (LDU,UCOL)
+*>          (LDU,M) if JOBU = 'A' or (LDU,min(M,N)) if JOBU = 'S'.
+*>          If JOBU = 'A', U contains the M-by-M orthogonal matrix U;
+*>          if JOBU = 'S', U contains the first min(m,n) columns of U
+*>          (the left singular vectors, stored columnwise);
+*>          if JOBU = 'N' or 'O', U is not referenced.
+*> \endverbatim
+*>
+*> \param[in] LDU
+*> \verbatim
+*>          LDU is INTEGER
+*>          The leading dimension of the array U.  LDU >= 1; if
+*>          JOBU = 'S' or 'A', LDU >= M.
+*> \endverbatim
+*>
+*> \param[out] VT
+*> \verbatim
+*>          VT is REAL array, dimension (LDVT,N)
+*>          If JOBVT = 'A', VT contains the N-by-N orthogonal matrix
+*>          V**T;
+*>          if JOBVT = 'S', VT contains the first min(m,n) rows of
+*>          V**T (the right singular vectors, stored rowwise);
+*>          if JOBVT = 'N' or 'O', VT is not referenced.
+*> \endverbatim
+*>
+*> \param[in] LDVT
+*> \verbatim
+*>          LDVT is INTEGER
+*>          The leading dimension of the array VT.  LDVT >= 1; if
+*>          JOBVT = 'A', LDVT >= N; if JOBVT = 'S', LDVT >= min(M,N).
+*> \endverbatim
+*>
+*> \param[out] WORK
+*> \verbatim
+*>          WORK is REAL array, dimension (MAX(1,LWORK))
+*>          On exit, if INFO = 0, WORK(1) returns the optimal LWORK;
+*>          if INFO > 0, WORK(2:MIN(M,N)) contains the unconverged
+*>          superdiagonal elements of an upper bidiagonal matrix B
+*>          whose diagonal is in S (not necessarily sorted). B
+*>          satisfies A = U * B * VT, so it has the same singular values
+*>          as A, and singular vectors related by U and VT.
+*> \endverbatim
+*>
+*> \param[in] LWORK
+*> \verbatim
+*>          LWORK is INTEGER
+*>          The dimension of the array WORK.
+*>          LWORK >= MAX(1,5*MIN(M,N)) for the paths (see comments inside code):
+*>             - PATH 1  (M much larger than N, JOBU='N') 
+*>             - PATH 1t (N much larger than M, JOBVT='N')
+*>          LWORK >= MAX(1,3*MIN(M,N)+MAX(M,N),5*MIN(M,N)) for the other paths
+*>          For good performance, LWORK should generally be larger.
+*> \endverbatim
+*> \verbatim
+*>          If LWORK = -1, then a workspace query is assumed; the routine
+*>          only calculates the optimal size of the WORK array, returns
+*>          this value as the first entry of the WORK array, and no error
+*>          message related to LWORK 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:  if SBDSQR did not converge, INFO specifies how many
+*>                superdiagonals of an intermediate bidiagonal form B
+*>                did not converge to zero. See the description of WORK
+*>                above for details.
+*> \endverbatim
+*>
+*
+*  Authors
+*  =======
+*
+*> \author Univ. of Tennessee 
+*> \author Univ. of California Berkeley 
+*> \author Univ. of Colorado Denver 
+*> \author NAG Ltd. 
+*
+*> \date November 2011
+*
+*> \ingroup realGEsing
+*
+*  =====================================================================
       SUBROUTINE SGESVD( JOBU, JOBVT, M, N, A, LDA, S, U, LDU, VT, LDVT,
      $                   WORK, LWORK, INFO )
 *
-*  -- LAPACK driver routine (version 3.3.1) --
+*  -- LAPACK sing 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          JOBU, JOBVT
@@ -15,125 +219,6 @@
      $                   VT( LDVT, * ), WORK( * )
 *     ..
 *
-*  Purpose
-*  =======
-*
-*  SGESVD computes the singular value decomposition (SVD) of a real
-*  M-by-N matrix A, optionally computing the left and/or right singular
-*  vectors. The SVD is written
-*
-*       A = U * SIGMA * transpose(V)
-*
-*  where SIGMA is an M-by-N matrix which is zero except for its
-*  min(m,n) diagonal elements, U is an M-by-M orthogonal matrix, and
-*  V is an N-by-N orthogonal matrix.  The diagonal elements of SIGMA
-*  are the singular values of A; they are real and non-negative, and
-*  are returned in descending order.  The first min(m,n) columns of
-*  U and V are the left and right singular vectors of A.
-*
-*  Note that the routine returns V**T, not V.
-*
-*  Arguments
-*  =========
-*
-*  JOBU    (input) CHARACTER*1
-*          Specifies options for computing all or part of the matrix U:
-*          = 'A':  all M columns of U are returned in array U:
-*          = 'S':  the first min(m,n) columns of U (the left singular
-*                  vectors) are returned in the array U;
-*          = 'O':  the first min(m,n) columns of U (the left singular
-*                  vectors) are overwritten on the array A;
-*          = 'N':  no columns of U (no left singular vectors) are
-*                  computed.
-*
-*  JOBVT   (input) CHARACTER*1
-*          Specifies options for computing all or part of the matrix
-*          V**T:
-*          = 'A':  all N rows of V**T are returned in the array VT;
-*          = 'S':  the first min(m,n) rows of V**T (the right singular
-*                  vectors) are returned in the array VT;
-*          = 'O':  the first min(m,n) rows of V**T (the right singular
-*                  vectors) are overwritten on the array A;
-*          = 'N':  no rows of V**T (no right singular vectors) are
-*                  computed.
-*
-*          JOBVT and JOBU cannot both be 'O'.
-*
-*  M       (input) INTEGER
-*          The number of rows of the input matrix A.  M >= 0.
-*
-*  N       (input) INTEGER
-*          The number of columns of the input matrix A.  N >= 0.
-*
-*  A       (input/output) REAL array, dimension (LDA,N)
-*          On entry, the M-by-N matrix A.
-*          On exit,
-*          if JOBU = 'O',  A is overwritten with the first min(m,n)
-*                          columns of U (the left singular vectors,
-*                          stored columnwise);
-*          if JOBVT = 'O', A is overwritten with the first min(m,n)
-*                          rows of V**T (the right singular vectors,
-*                          stored rowwise);
-*          if JOBU .ne. 'O' and JOBVT .ne. 'O', the contents of A
-*                          are destroyed.
-*
-*  LDA     (input) INTEGER
-*          The leading dimension of the array A.  LDA >= max(1,M).
-*
-*  S       (output) REAL array, dimension (min(M,N))
-*          The singular values of A, sorted so that S(i) >= S(i+1).
-*
-*  U       (output) REAL array, dimension (LDU,UCOL)
-*          (LDU,M) if JOBU = 'A' or (LDU,min(M,N)) if JOBU = 'S'.
-*          If JOBU = 'A', U contains the M-by-M orthogonal matrix U;
-*          if JOBU = 'S', U contains the first min(m,n) columns of U
-*          (the left singular vectors, stored columnwise);
-*          if JOBU = 'N' or 'O', U is not referenced.
-*
-*  LDU     (input) INTEGER
-*          The leading dimension of the array U.  LDU >= 1; if
-*          JOBU = 'S' or 'A', LDU >= M.
-*
-*  VT      (output) REAL array, dimension (LDVT,N)
-*          If JOBVT = 'A', VT contains the N-by-N orthogonal matrix
-*          V**T;
-*          if JOBVT = 'S', VT contains the first min(m,n) rows of
-*          V**T (the right singular vectors, stored rowwise);
-*          if JOBVT = 'N' or 'O', VT is not referenced.
-*
-*  LDVT    (input) INTEGER
-*          The leading dimension of the array VT.  LDVT >= 1; if
-*          JOBVT = 'A', LDVT >= N; if JOBVT = 'S', LDVT >= min(M,N).
-*
-*  WORK    (workspace/output) REAL array, dimension (MAX(1,LWORK))
-*          On exit, if INFO = 0, WORK(1) returns the optimal LWORK;
-*          if INFO > 0, WORK(2:MIN(M,N)) contains the unconverged
-*          superdiagonal elements of an upper bidiagonal matrix B
-*          whose diagonal is in S (not necessarily sorted). B
-*          satisfies A = U * B * VT, so it has the same singular values
-*          as A, and singular vectors related by U and VT.
-*
-*  LWORK   (input) INTEGER
-*          The dimension of the array WORK.
-*          LWORK >= MAX(1,5*MIN(M,N)) for the paths (see comments inside code):
-*             - PATH 1  (M much larger than N, JOBU='N') 
-*             - PATH 1t (N much larger than M, JOBVT='N')
-*          LWORK >= MAX(1,3*MIN(M,N)+MAX(M,N),5*MIN(M,N)) for the other paths
-*          For good performance, LWORK should generally be larger.
-*
-*          If LWORK = -1, then a workspace query is assumed; the routine
-*          only calculates the optimal size of the WORK array, returns
-*          this value as the first entry of the WORK array, and no error
-*          message related to LWORK is issued by XERBLA.
-*
-*  INFO    (output) INTEGER
-*          = 0:  successful exit.
-*          < 0:  if INFO = -i, the i-th argument had an illegal value.
-*          > 0:  if SBDSQR did not converge, INFO specifies how many
-*                superdiagonals of an intermediate bidiagonal form B
-*                did not converge to zero. See the description of WORK
-*                above for details.
-*
 *  =====================================================================
 *
 *     .. Parameters ..