Merge pull request Reference-LAPACK#998 from christoph-conrads/997-xS…

…YEVR-clarify-use-of-multiple-algorithms

xSY/HEEVR: clarify use of multiple algorithms

SRC/cheevr.f

@@ -41,9 +41,16 @@
 *> \verbatim
 *>
 *> CHEEVR computes selected eigenvalues and, optionally, eigenvectors
-*> of a complex Hermitian matrix A.  Eigenvalues and eigenvectors can
-*> be selected by specifying either a range of values or a range of
-*> indices for the desired eigenvalues.
+*> of a complex Hermitian matrix A. Eigenvalues and eigenvectors can be
+*> selected by specifying either a range of values or a range of indices
+*> for the desired eigenvalues. Invocations with different choices for
+*> these parameters may result in the computation of slightly different
+*> eigenvalues and/or eigenvectors for the same matrix. The reason for
+*> this behavior is that there exists a variety of algorithms (each
+*> performing best for a particular set of options) with CHEEVR
+*> attempting to select the best based on the various parameters. In all
+*> cases, the computed values are accurate within the limits of finite
+*> precision arithmetic.
 *>
 *> CHEEVR first reduces the matrix A to tridiagonal form T with a call
 *> to CHETRD.  Then, whenever possible, CHEEVR calls CSTEMR to compute
@@ -107,6 +114,9 @@
 *>          JOBZ is CHARACTER*1
 *>          = 'N':  Compute eigenvalues only;
 *>          = 'V':  Compute eigenvalues and eigenvectors.
+*>
+*>          This parameter influences the choice of the algorithm and
+*>          may alter the computed values.
 *> \endverbatim
 *>
 *> \param[in] RANGE
@@ -118,6 +128,9 @@
 *>          = 'I': the IL-th through IU-th eigenvalues will be found.
 *>          For RANGE = 'V' or 'I' and IU - IL < N - 1, SSTEBZ and
 *>          CSTEIN are called
+*>
+*>          This parameter influences the choice of the algorithm and
+*>          may alter the computed values.
 *> \endverbatim
 *>
 *> \param[in] UPLO
@@ -242,6 +255,7 @@
 *>          Note: the user must ensure that at least max(1,M) columns are
 *>          supplied in the array Z; if RANGE = 'V', the exact value of M
 *>          is not known in advance and an upper bound must be used.
+*>          Supplying N columns is always safe.
 *> \endverbatim
 *>
 *> \param[in] LDZ

SRC/dsyevr.f

@@ -39,9 +39,16 @@
 *> \verbatim
 *>
 *> DSYEVR computes selected eigenvalues and, optionally, eigenvectors
-*> of a real symmetric matrix A.  Eigenvalues and eigenvectors can be
-*> selected by specifying either a range of values or a range of
-*> indices for the desired eigenvalues.
+*> of a real symmetric matrix A. Eigenvalues and eigenvectors can be
+*> selected by specifying either a range of values or a range of indices
+*> for the desired eigenvalues. Invocations with different choices for
+*> these parameters may result in the computation of slightly different
+*> eigenvalues and/or eigenvectors for the same matrix. The reason for
+*> this behavior is that there exists a variety of algorithms (each
+*> performing best for a particular set of options) with DSYEVR
+*> attempting to select the best based on the various parameters. In all
+*> cases, the computed values are accurate within the limits of finite
+*> precision arithmetic.
 *>
 *> DSYEVR first reduces the matrix A to tridiagonal form T with a call
 *> to DSYTRD.  Then, whenever possible, DSYEVR calls DSTEMR to compute
@@ -105,6 +112,9 @@
 *>          JOBZ is CHARACTER*1
 *>          = 'N':  Compute eigenvalues only;
 *>          = 'V':  Compute eigenvalues and eigenvectors.
+*>
+*>          This parameter influences the choice of the algorithm and
+*>          may alter the computed values.
 *> \endverbatim
 *>
 *> \param[in] RANGE
@@ -116,6 +126,9 @@
 *>          = 'I': the IL-th through IU-th eigenvalues will be found.
 *>          For RANGE = 'V' or 'I' and IU - IL < N - 1, DSTEBZ and
 *>          DSTEIN are called
+*>
+*>          This parameter influences the choice of the algorithm and
+*>          may alter the computed values.
 *> \endverbatim
 *>
 *> \param[in] UPLO

SRC/ssyevr.f

@@ -39,9 +39,16 @@
 *> \verbatim
 *>
 *> SSYEVR computes selected eigenvalues and, optionally, eigenvectors
-*> of a real symmetric matrix A.  Eigenvalues and eigenvectors can be
-*> selected by specifying either a range of values or a range of
-*> indices for the desired eigenvalues.
+*> of a real symmetric matrix A. Eigenvalues and eigenvectors can be
+*> selected by specifying either a range of values or a range of indices
+*> for the desired eigenvalues. Invocations with different choices for
+*> these parameters may result in the computation of slightly different
+*> eigenvalues and/or eigenvectors for the same matrix. The reason for
+*> this behavior is that there exists a variety of algorithms (each
+*> performing best for a particular set of options) with SSYEVR
+*> attempting to select the best based on the various parameters. In all
+*> cases, the computed values are accurate within the limits of finite
+*> precision arithmetic.
 *>
 *> SSYEVR first reduces the matrix A to tridiagonal form T with a call
 *> to SSYTRD.  Then, whenever possible, SSYEVR calls SSTEMR to compute
@@ -105,6 +112,9 @@
 *>          JOBZ is CHARACTER*1
 *>          = 'N':  Compute eigenvalues only;
 *>          = 'V':  Compute eigenvalues and eigenvectors.
+*>
+*>          This parameter influences the choice of the algorithm and
+*>          may alter the computed values.
 *> \endverbatim
 *>
 *> \param[in] RANGE
@@ -116,6 +126,9 @@
 *>          = 'I': the IL-th through IU-th eigenvalues will be found.
 *>          For RANGE = 'V' or 'I' and IU - IL < N - 1, SSTEBZ and
 *>          SSTEIN are called
+*>
+*>          This parameter influences the choice of the algorithm and
+*>          may alter the computed values.
 *> \endverbatim
 *>
 *> \param[in] UPLO

SRC/zheevr.f

@@ -41,9 +41,16 @@
 *> \verbatim
 *>
 *> ZHEEVR computes selected eigenvalues and, optionally, eigenvectors
-*> of a complex Hermitian matrix A.  Eigenvalues and eigenvectors can
-*> be selected by specifying either a range of values or a range of
-*> indices for the desired eigenvalues.
+*> of a complex Hermitian matrix A. Eigenvalues and eigenvectors can be
+*> selected by specifying either a range of values or a range of indices
+*> for the desired eigenvalues. Invocations with different choices for
+*> these parameters may result in the computation of slightly different
+*> eigenvalues and/or eigenvectors for the same matrix. The reason for
+*> this behavior is that there exists a variety of algorithms (each
+*> performing best for a particular set of options) with ZHEEVR
+*> attempting to select the best based on the various parameters. In all
+*> cases, the computed values are accurate within the limits of finite
+*> precision arithmetic.
 *>
 *> ZHEEVR first reduces the matrix A to tridiagonal form T with a call
 *> to ZHETRD.  Then, whenever possible, ZHEEVR calls ZSTEMR to compute
@@ -107,6 +114,9 @@
 *>          JOBZ is CHARACTER*1
 *>          = 'N':  Compute eigenvalues only;
 *>          = 'V':  Compute eigenvalues and eigenvectors.
+*>
+*>          This parameter influences the choice of the algorithm and
+*>          may alter the computed values.
 *> \endverbatim
 *>
 *> \param[in] RANGE
@@ -118,6 +128,9 @@
 *>          = 'I': the IL-th through IU-th eigenvalues will be found.
 *>          For RANGE = 'V' or 'I' and IU - IL < N - 1, DSTEBZ and
 *>          ZSTEIN are called
+*>
+*>          This parameter influences the choice of the algorithm and
+*>          may alter the computed values.
 *> \endverbatim
 *>
 *> \param[in] UPLO
@@ -242,6 +255,7 @@
 *>          Note: the user must ensure that at least max(1,M) columns are
 *>          supplied in the array Z; if RANGE = 'V', the exact value of M
 *>          is not known in advance and an upper bound must be used.
+*>          Supplying N columns is always safe.
 *> \endverbatim
 *>
 *> \param[in] LDZ