Doc: fix xyyEQUB documentation

- fix description of purpose, parameters
- cite the paper "Scaling by Binormalization"

diff --git a/SRC/cheequb.f b/SRC/cheequb.f
index afa368f..7f8dc20 100644 (file)
--- a/SRC/cheequb.f
+++ b/SRC/cheequb.f
@@ -37,12 +37,11 @@
 *> \verbatim
 *>
 *> CHEEQUB computes row and column scalings intended to equilibrate a
-*> Hermitian matrix A and reduce its condition number
-*> (with respect to the two-norm).  S contains the scale factors,
-*> S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with
-*> elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal.  This
-*> choice of S puts the condition number of B within a factor N of the
-*> smallest possible condition number over all possible diagonal
+*> Hermitian matrix A (with respect to the Euclidean norm) and reduce
+*> its condition number. The scale factors S are computed by the BIN
+*> algorithm (see references) so that the scaled matrix B with elements
+*> B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of
+*> the smallest possible condition number over all possible diagonal
 *> scalings.
 *> \endverbatim
 *
@@ -52,28 +51,27 @@
 *> \param[in] UPLO
 *> \verbatim
 *>          UPLO is CHARACTER*1
-*>          = 'U':  Upper triangles of A and B are stored;
-*>          = 'L':  Lower triangles of A and B are stored.
+*>          = 'U':  Upper triangle of A is stored;
+*>          = 'L':  Lower triangle of A is stored.
 *> \endverbatim
 *>
 *> \param[in] N
 *> \verbatim
 *>          N is INTEGER
-*>          The order of the matrix A.  N >= 0.
+*>          The order of the matrix A. N >= 0.
 *> \endverbatim
 *>
 *> \param[in] A
 *> \verbatim
 *>          A is COMPLEX array, dimension (LDA,N)
-*>          The N-by-N Hermitian matrix whose scaling
-*>          factors are to be computed.  Only the diagonal elements of A
-*>          are referenced.
+*>          The N-by-N Hermitian matrix whose scaling factors are to be
+*>          computed.
 *> \endverbatim
 *>
 *> \param[in] LDA
 *> \verbatim
 *>          LDA is INTEGER
-*>          The leading dimension of the array A.  LDA >= max(1,N).
+*>          The leading dimension of the array A. LDA >= max(1,N).
 *> \endverbatim
 *>
 *> \param[out] S
@@ -86,16 +84,16 @@
 *> \verbatim
 *>          SCOND is REAL
 *>          If INFO = 0, S contains the ratio of the smallest S(i) to
-*>          the largest S(i).  If SCOND >= 0.1 and AMAX is neither too
+*>          the largest S(i). If SCOND >= 0.1 and AMAX is neither too
 *>          large nor too small, it is not worth scaling by S.
 *> \endverbatim
 *>
 *> \param[out] AMAX
 *> \verbatim
 *>          AMAX is REAL
-*>          Absolute value of largest matrix element.  If AMAX is very
-*>          close to overflow or very close to underflow, the matrix
-*>          should be scaled.
+*>          Largest absolute value of any matrix element. If AMAX is
+*>          very close to overflow or very close to underflow, the
+*>          matrix should be scaled.
 *> \endverbatim
 *>
 *> \param[out] WORK
@@ -123,6 +121,14 @@
 *
 *> \ingroup complexHEcomputational
 *
+*> \par References:
+*  ================
+*>
+*>  Livne, O.E. and Golub, G.H., "Scaling by Binormalization", \n
+*>  Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. \n
+*>  DOI 10.1023/B:NUMA.0000016606.32820.69 \n
+*>  Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679
+*>
 *  =====================================================================
       SUBROUTINE CHEEQUB( UPLO, N, A, LDA, S, SCOND, AMAX, WORK, INFO )
 *

diff --git a/SRC/csyequb.f b/SRC/csyequb.f
index d92ee47..5d54b5e 100644 (file)
--- a/SRC/csyequb.f
+++ b/SRC/csyequb.f
@@ -37,12 +37,11 @@
 *> \verbatim
 *>
 *> CSYEQUB computes row and column scalings intended to equilibrate a
-*> symmetric matrix A and reduce its condition number
-*> (with respect to the two-norm).  S contains the scale factors,
-*> S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with
-*> elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal.  This
-*> choice of S puts the condition number of B within a factor N of the
-*> smallest possible condition number over all possible diagonal
+*> symmetric matrix A (with respect to the Euclidean norm) and reduce
+*> its condition number. The scale factors S are computed by the BIN
+*> algorithm (see references) so that the scaled matrix B with elements
+*> B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of
+*> the smallest possible condition number over all possible diagonal
 *> scalings.
 *> \endverbatim
 *
@@ -52,30 +51,27 @@
 *> \param[in] UPLO
 *> \verbatim
 *>          UPLO is CHARACTER*1
-*>          Specifies whether the details of the factorization are stored
-*>          as an upper or lower triangular matrix.
-*>          = 'U':  Upper triangular, form is A = U*D*U**T;
-*>          = 'L':  Lower triangular, form is A = L*D*L**T.
+*>          = 'U':  Upper triangle of A is stored;
+*>          = 'L':  Lower triangle of A is stored.
 *> \endverbatim
 *>
 *> \param[in] N
 *> \verbatim
 *>          N is INTEGER
-*>          The order of the matrix A.  N >= 0.
+*>          The order of the matrix A. N >= 0.
 *> \endverbatim
 *>
 *> \param[in] A
 *> \verbatim
 *>          A is COMPLEX array, dimension (LDA,N)
-*>          The N-by-N symmetric matrix whose scaling
-*>          factors are to be computed.  Only the diagonal elements of A
-*>          are referenced.
+*>          The N-by-N symmetric matrix whose scaling factors are to be
+*>          computed.
 *> \endverbatim
 *>
 *> \param[in] LDA
 *> \verbatim
 *>          LDA is INTEGER
-*>          The leading dimension of the array A.  LDA >= max(1,N).
+*>          The leading dimension of the array A. LDA >= max(1,N).
 *> \endverbatim
 *>
 *> \param[out] S
@@ -88,16 +84,16 @@
 *> \verbatim
 *>          SCOND is REAL
 *>          If INFO = 0, S contains the ratio of the smallest S(i) to
-*>          the largest S(i).  If SCOND >= 0.1 and AMAX is neither too
+*>          the largest S(i). If SCOND >= 0.1 and AMAX is neither too
 *>          large nor too small, it is not worth scaling by S.
 *> \endverbatim
 *>
 *> \param[out] AMAX
 *> \verbatim
 *>          AMAX is REAL
-*>          Absolute value of largest matrix element.  If AMAX is very
-*>          close to overflow or very close to underflow, the matrix
-*>          should be scaled.
+*>          Largest absolute value of any matrix element. If AMAX is
+*>          very close to overflow or very close to underflow, the
+*>          matrix should be scaled.
 *> \endverbatim
 *>
 *> \param[out] WORK
@@ -131,7 +127,7 @@
 *>  Livne, O.E. and Golub, G.H., "Scaling by Binormalization", \n
 *>  Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. \n
 *>  DOI 10.1023/B:NUMA.0000016606.32820.69 \n
-*>  Tech report version: http://ruready.utah.edu/archive/papers/bin.pdf
+*>  Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679
 *>
 *  =====================================================================
       SUBROUTINE CSYEQUB( UPLO, N, A, LDA, S, SCOND, AMAX, WORK, INFO )

diff --git a/SRC/dsyequb.f b/SRC/dsyequb.f
index c9d8886..3c15cad 100644 (file)
--- a/SRC/dsyequb.f
+++ b/SRC/dsyequb.f
@@ -36,12 +36,11 @@
 *> \verbatim
 *>
 *> DSYEQUB computes row and column scalings intended to equilibrate a
-*> symmetric matrix A and reduce its condition number
-*> (with respect to the two-norm).  S contains the scale factors,
-*> S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with
-*> elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal.  This
-*> choice of S puts the condition number of B within a factor N of the
-*> smallest possible condition number over all possible diagonal
+*> symmetric matrix A (with respect to the Euclidean norm) and reduce
+*> its condition number. The scale factors S are computed by the BIN
+*> algorithm (see references) so that the scaled matrix B with elements
+*> B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of
+*> the smallest possible condition number over all possible diagonal
 *> scalings.
 *> \endverbatim
 *
@@ -51,30 +50,27 @@
 *> \param[in] UPLO
 *> \verbatim
 *>          UPLO is CHARACTER*1
-*>          Specifies whether the details of the factorization are stored
-*>          as an upper or lower triangular matrix.
-*>          = 'U':  Upper triangular, form is A = U*D*U**T;
-*>          = 'L':  Lower triangular, form is A = L*D*L**T.
+*>          = 'U':  Upper triangle of A is stored;
+*>          = 'L':  Lower triangle of A is stored.
 *> \endverbatim
 *>
 *> \param[in] N
 *> \verbatim
 *>          N is INTEGER
-*>          The order of the matrix A.  N >= 0.
+*>          The order of the matrix A. N >= 0.
 *> \endverbatim
 *>
 *> \param[in] A
 *> \verbatim
 *>          A is DOUBLE PRECISION array, dimension (LDA,N)
-*>          The N-by-N symmetric matrix whose scaling
-*>          factors are to be computed.  Only the diagonal elements of A
-*>          are referenced.
+*>          The N-by-N symmetric matrix whose scaling factors are to be
+*>          computed.
 *> \endverbatim
 *>
 *> \param[in] LDA
 *> \verbatim
 *>          LDA is INTEGER
-*>          The leading dimension of the array A.  LDA >= max(1,N).
+*>          The leading dimension of the array A. LDA >= max(1,N).
 *> \endverbatim
 *>
 *> \param[out] S
@@ -87,16 +83,16 @@
 *> \verbatim
 *>          SCOND is DOUBLE PRECISION
 *>          If INFO = 0, S contains the ratio of the smallest S(i) to
-*>          the largest S(i).  If SCOND >= 0.1 and AMAX is neither too
+*>          the largest S(i). If SCOND >= 0.1 and AMAX is neither too
 *>          large nor too small, it is not worth scaling by S.
 *> \endverbatim
 *>
 *> \param[out] AMAX
 *> \verbatim
 *>          AMAX is DOUBLE PRECISION
-*>          Absolute value of largest matrix element.  If AMAX is very
-*>          close to overflow or very close to underflow, the matrix
-*>          should be scaled.
+*>          Largest absolute value of any matrix element. If AMAX is
+*>          very close to overflow or very close to underflow, the
+*>          matrix should be scaled.
 *> \endverbatim
 *>
 *> \param[out] WORK
@@ -130,7 +126,7 @@
 *>  Livne, O.E. and Golub, G.H., "Scaling by Binormalization", \n
 *>  Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. \n
 *>  DOI 10.1023/B:NUMA.0000016606.32820.69 \n
-*>  Tech report version: http://ruready.utah.edu/archive/papers/bin.pdf
+*>  Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679
 *>
 *  =====================================================================
       SUBROUTINE DSYEQUB( UPLO, N, A, LDA, S, SCOND, AMAX, WORK, INFO )

diff --git a/SRC/ssyequb.f b/SRC/ssyequb.f
index 15aaf03..eb14390 100644 (file)
--- a/SRC/ssyequb.f
+++ b/SRC/ssyequb.f
@@ -36,12 +36,11 @@
 *> \verbatim
 *>
 *> SSYEQUB computes row and column scalings intended to equilibrate a
-*> symmetric matrix A and reduce its condition number
-*> (with respect to the two-norm).  S contains the scale factors,
-*> S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with
-*> elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal.  This
-*> choice of S puts the condition number of B within a factor N of the
-*> smallest possible condition number over all possible diagonal
+*> symmetric matrix A (with respect to the Euclidean norm) and reduce
+*> its condition number. The scale factors S are computed by the BIN
+*> algorithm (see references) so that the scaled matrix B with elements
+*> B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of
+*> the smallest possible condition number over all possible diagonal
 *> scalings.
 *> \endverbatim
 *
@@ -51,30 +50,27 @@
 *> \param[in] UPLO
 *> \verbatim
 *>          UPLO is CHARACTER*1
-*>          Specifies whether the details of the factorization are stored
-*>          as an upper or lower triangular matrix.
-*>          = 'U':  Upper triangular, form is A = U*D*U**T;
-*>          = 'L':  Lower triangular, form is A = L*D*L**T.
+*>          = 'U':  Upper triangle of A is stored;
+*>          = 'L':  Lower triangle of A is stored.
 *> \endverbatim
 *>
 *> \param[in] N
 *> \verbatim
 *>          N is INTEGER
-*>          The order of the matrix A.  N >= 0.
+*>          The order of the matrix A. N >= 0.
 *> \endverbatim
 *>
 *> \param[in] A
 *> \verbatim
 *>          A is REAL array, dimension (LDA,N)
-*>          The N-by-N symmetric matrix whose scaling
-*>          factors are to be computed.  Only the diagonal elements of A
-*>          are referenced.
+*>          The N-by-N symmetric matrix whose scaling factors are to be
+*>          computed.
 *> \endverbatim
 *>
 *> \param[in] LDA
 *> \verbatim
 *>          LDA is INTEGER
-*>          The leading dimension of the array A.  LDA >= max(1,N).
+*>          The leading dimension of the array A. LDA >= max(1,N).
 *> \endverbatim
 *>
 *> \param[out] S
@@ -87,16 +83,16 @@
 *> \verbatim
 *>          SCOND is REAL
 *>          If INFO = 0, S contains the ratio of the smallest S(i) to
-*>          the largest S(i).  If SCOND >= 0.1 and AMAX is neither too
+*>          the largest S(i). If SCOND >= 0.1 and AMAX is neither too
 *>          large nor too small, it is not worth scaling by S.
 *> \endverbatim
 *>
 *> \param[out] AMAX
 *> \verbatim
 *>          AMAX is REAL
-*>          Absolute value of largest matrix element.  If AMAX is very
-*>          close to overflow or very close to underflow, the matrix
-*>          should be scaled.
+*>          Largest absolute value of any matrix element. If AMAX is
+*>          very close to overflow or very close to underflow, the
+*>          matrix should be scaled.
 *> \endverbatim
 *>
 *> \param[out] WORK
@@ -130,7 +126,7 @@
 *>  Livne, O.E. and Golub, G.H., "Scaling by Binormalization", \n
 *>  Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. \n
 *>  DOI 10.1023/B:NUMA.0000016606.32820.69 \n
-*>  Tech report version: http://ruready.utah.edu/archive/papers/bin.pdf
+*>  Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679
 *>
 *  =====================================================================
       SUBROUTINE SSYEQUB( UPLO, N, A, LDA, S, SCOND, AMAX, WORK, INFO )

diff --git a/SRC/zheequb.f b/SRC/zheequb.f
index ac1251b..341b7d2 100644 (file)
--- a/SRC/zheequb.f
+++ b/SRC/zheequb.f
@@ -37,12 +37,11 @@
 *> \verbatim
 *>
 *> ZHEEQUB computes row and column scalings intended to equilibrate a
-*> Hermitian matrix A and reduce its condition number
-*> (with respect to the two-norm).  S contains the scale factors,
-*> S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with
-*> elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal.  This
-*> choice of S puts the condition number of B within a factor N of the
-*> smallest possible condition number over all possible diagonal
+*> Hermitian matrix A (with respect to the Euclidean norm) and reduce
+*> its condition number. The scale factors S are computed by the BIN
+*> algorithm (see references) so that the scaled matrix B with elements
+*> B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of
+*> the smallest possible condition number over all possible diagonal
 *> scalings.
 *> \endverbatim
 *
@@ -52,28 +51,27 @@
 *> \param[in] UPLO
 *> \verbatim
 *>          UPLO is CHARACTER*1
-*>          = 'U':  Upper triangles of A and B are stored;
-*>          = 'L':  Lower triangles of A and B are stored.
+*>          = 'U':  Upper triangle of A is stored;
+*>          = 'L':  Lower triangle of A is stored.
 *> \endverbatim
 *>
 *> \param[in] N
 *> \verbatim
 *>          N is INTEGER
-*>          The order of the matrix A.  N >= 0.
+*>          The order of the matrix A. N >= 0.
 *> \endverbatim
 *>
 *> \param[in] A
 *> \verbatim
 *>          A is COMPLEX*16 array, dimension (LDA,N)
-*>          The N-by-N Hermitian matrix whose scaling
-*>          factors are to be computed.  Only the diagonal elements of A
-*>          are referenced.
+*>          The N-by-N Hermitian matrix whose scaling factors are to be
+*>          computed.
 *> \endverbatim
 *>
 *> \param[in] LDA
 *> \verbatim
 *>          LDA is INTEGER
-*>          The leading dimension of the array A.  LDA >= max(1,N).
+*>          The leading dimension of the array A. LDA >= max(1,N).
 *> \endverbatim
 *>
 *> \param[out] S
@@ -86,16 +84,16 @@
 *> \verbatim
 *>          SCOND is DOUBLE PRECISION
 *>          If INFO = 0, S contains the ratio of the smallest S(i) to
-*>          the largest S(i).  If SCOND >= 0.1 and AMAX is neither too
+*>          the largest S(i). If SCOND >= 0.1 and AMAX is neither too
 *>          large nor too small, it is not worth scaling by S.
 *> \endverbatim
 *>
 *> \param[out] AMAX
 *> \verbatim
 *>          AMAX is DOUBLE PRECISION
-*>          Absolute value of largest matrix element.  If AMAX is very
-*>          close to overflow or very close to underflow, the matrix
-*>          should be scaled.
+*>          Largest absolute value of any matrix element. If AMAX is
+*>          very close to overflow or very close to underflow, the
+*>          matrix should be scaled.
 *> \endverbatim
 *>
 *> \param[out] WORK
@@ -123,6 +121,14 @@
 *
 *> \ingroup complex16HEcomputational
 *
+*> \par References:
+*  ================
+*>
+*>  Livne, O.E. and Golub, G.H., "Scaling by Binormalization", \n
+*>  Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. \n
+*>  DOI 10.1023/B:NUMA.0000016606.32820.69 \n
+*>  Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679
+*>
 *  =====================================================================
       SUBROUTINE ZHEEQUB( UPLO, N, A, LDA, S, SCOND, AMAX, WORK, INFO )
 *

diff --git a/SRC/zsyequb.f b/SRC/zsyequb.f
index 059676d..8514388 100644 (file)
--- a/SRC/zsyequb.f
+++ b/SRC/zsyequb.f
@@ -37,12 +37,11 @@
 *> \verbatim
 *>
 *> ZSYEQUB computes row and column scalings intended to equilibrate a
-*> symmetric matrix A and reduce its condition number
-*> (with respect to the two-norm).  S contains the scale factors,
-*> S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with
-*> elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal.  This
-*> choice of S puts the condition number of B within a factor N of the
-*> smallest possible condition number over all possible diagonal
+*> symmetric matrix A (with respect to the Euclidean norm) and reduce
+*> its condition number. The scale factors S are computed by the BIN
+*> algorithm (see references) so that the scaled matrix B with elements
+*> B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of
+*> the smallest possible condition number over all possible diagonal
 *> scalings.
 *> \endverbatim
 *
@@ -52,30 +51,27 @@
 *> \param[in] UPLO
 *> \verbatim
 *>          UPLO is CHARACTER*1
-*>          Specifies whether the details of the factorization are stored
-*>          as an upper or lower triangular matrix.
-*>          = 'U':  Upper triangular, form is A = U*D*U**T;
-*>          = 'L':  Lower triangular, form is A = L*D*L**T.
+*>          = 'U':  Upper triangle of A is stored;
+*>          = 'L':  Lower triangle of A is stored.
 *> \endverbatim
 *>
 *> \param[in] N
 *> \verbatim
 *>          N is INTEGER
-*>          The order of the matrix A.  N >= 0.
+*>          The order of the matrix A. N >= 0.
 *> \endverbatim
 *>
 *> \param[in] A
 *> \verbatim
 *>          A is COMPLEX*16 array, dimension (LDA,N)
-*>          The N-by-N symmetric matrix whose scaling
-*>          factors are to be computed.  Only the diagonal elements of A
-*>          are referenced.
+*>          The N-by-N symmetric matrix whose scaling factors are to be
+*>          computed.
 *> \endverbatim
 *>
 *> \param[in] LDA
 *> \verbatim
 *>          LDA is INTEGER
-*>          The leading dimension of the array A.  LDA >= max(1,N).
+*>          The leading dimension of the array A. LDA >= max(1,N).
 *> \endverbatim
 *>
 *> \param[out] S
@@ -88,16 +84,16 @@
 *> \verbatim
 *>          SCOND is DOUBLE PRECISION
 *>          If INFO = 0, S contains the ratio of the smallest S(i) to
-*>          the largest S(i).  If SCOND >= 0.1 and AMAX is neither too
+*>          the largest S(i). If SCOND >= 0.1 and AMAX is neither too
 *>          large nor too small, it is not worth scaling by S.
 *> \endverbatim
 *>
 *> \param[out] AMAX
 *> \verbatim
 *>          AMAX is DOUBLE PRECISION
-*>          Absolute value of largest matrix element.  If AMAX is very
-*>          close to overflow or very close to underflow, the matrix
-*>          should be scaled.
+*>          Largest absolute value of any matrix element. If AMAX is
+*>          very close to overflow or very close to underflow, the
+*>          matrix should be scaled.
 *> \endverbatim
 *>
 *> \param[out] WORK
@@ -131,7 +127,7 @@
 *>  Livne, O.E. and Golub, G.H., "Scaling by Binormalization", \n
 *>  Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. \n
 *>  DOI 10.1023/B:NUMA.0000016606.32820.69 \n
-*>  Tech report version: http://ruready.utah.edu/archive/papers/bin.pdf
+*>  Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679
 *>
 *  =====================================================================
       SUBROUTINE ZSYEQUB( UPLO, N, A, LDA, S, SCOND, AMAX, WORK, INFO )