LAPACK  3.4.1
LAPACK: Linear Algebra PACKage
spbequ.f
Go to the documentation of this file.
00001 *> \brief \b SPBEQU
00002 *
00003 *  =========== DOCUMENTATION ===========
00004 *
00005 * Online html documentation available at 
00006 *            http://www.netlib.org/lapack/explore-html/ 
00007 *
00008 *> \htmlonly
00009 *> Download SPBEQU + dependencies 
00010 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/spbequ.f"> 
00011 *> [TGZ]</a> 
00012 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/spbequ.f"> 
00013 *> [ZIP]</a> 
00014 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/spbequ.f"> 
00015 *> [TXT]</a>
00016 *> \endhtmlonly 
00017 *
00018 *  Definition:
00019 *  ===========
00020 *
00021 *       SUBROUTINE SPBEQU( UPLO, N, KD, AB, LDAB, S, SCOND, AMAX, INFO )
00022 * 
00023 *       .. Scalar Arguments ..
00024 *       CHARACTER          UPLO
00025 *       INTEGER            INFO, KD, LDAB, N
00026 *       REAL               AMAX, SCOND
00027 *       ..
00028 *       .. Array Arguments ..
00029 *       REAL               AB( LDAB, * ), S( * )
00030 *       ..
00031 *  
00032 *
00033 *> \par Purpose:
00034 *  =============
00035 *>
00036 *> \verbatim
00037 *>
00038 *> SPBEQU computes row and column scalings intended to equilibrate a
00039 *> symmetric positive definite band matrix A and reduce its condition
00040 *> number (with respect to the two-norm).  S contains the scale factors,
00041 *> S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with
00042 *> elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal.  This
00043 *> choice of S puts the condition number of B within a factor N of the
00044 *> smallest possible condition number over all possible diagonal
00045 *> scalings.
00046 *> \endverbatim
00047 *
00048 *  Arguments:
00049 *  ==========
00050 *
00051 *> \param[in] UPLO
00052 *> \verbatim
00053 *>          UPLO is CHARACTER*1
00054 *>          = 'U':  Upper triangular of A is stored;
00055 *>          = 'L':  Lower triangular of A is stored.
00056 *> \endverbatim
00057 *>
00058 *> \param[in] N
00059 *> \verbatim
00060 *>          N is INTEGER
00061 *>          The order of the matrix A.  N >= 0.
00062 *> \endverbatim
00063 *>
00064 *> \param[in] KD
00065 *> \verbatim
00066 *>          KD is INTEGER
00067 *>          The number of superdiagonals of the matrix A if UPLO = 'U',
00068 *>          or the number of subdiagonals if UPLO = 'L'.  KD >= 0.
00069 *> \endverbatim
00070 *>
00071 *> \param[in] AB
00072 *> \verbatim
00073 *>          AB is REAL array, dimension (LDAB,N)
00074 *>          The upper or lower triangle of the symmetric band matrix A,
00075 *>          stored in the first KD+1 rows of the array.  The j-th column
00076 *>          of A is stored in the j-th column of the array AB as follows:
00077 *>          if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
00078 *>          if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).
00079 *> \endverbatim
00080 *>
00081 *> \param[in] LDAB
00082 *> \verbatim
00083 *>          LDAB is INTEGER
00084 *>          The leading dimension of the array A.  LDAB >= KD+1.
00085 *> \endverbatim
00086 *>
00087 *> \param[out] S
00088 *> \verbatim
00089 *>          S is REAL array, dimension (N)
00090 *>          If INFO = 0, S contains the scale factors for A.
00091 *> \endverbatim
00092 *>
00093 *> \param[out] SCOND
00094 *> \verbatim
00095 *>          SCOND is REAL
00096 *>          If INFO = 0, S contains the ratio of the smallest S(i) to
00097 *>          the largest S(i).  If SCOND >= 0.1 and AMAX is neither too
00098 *>          large nor too small, it is not worth scaling by S.
00099 *> \endverbatim
00100 *>
00101 *> \param[out] AMAX
00102 *> \verbatim
00103 *>          AMAX is REAL
00104 *>          Absolute value of largest matrix element.  If AMAX is very
00105 *>          close to overflow or very close to underflow, the matrix
00106 *>          should be scaled.
00107 *> \endverbatim
00108 *>
00109 *> \param[out] INFO
00110 *> \verbatim
00111 *>          INFO is INTEGER
00112 *>          = 0:  successful exit
00113 *>          < 0:  if INFO = -i, the i-th argument had an illegal value.
00114 *>          > 0:  if INFO = i, the i-th diagonal element is nonpositive.
00115 *> \endverbatim
00116 *
00117 *  Authors:
00118 *  ========
00119 *
00120 *> \author Univ. of Tennessee 
00121 *> \author Univ. of California Berkeley 
00122 *> \author Univ. of Colorado Denver 
00123 *> \author NAG Ltd. 
00124 *
00125 *> \date November 2011
00126 *
00127 *> \ingroup realOTHERcomputational
00128 *
00129 *  =====================================================================
00130       SUBROUTINE SPBEQU( UPLO, N, KD, AB, LDAB, S, SCOND, AMAX, INFO )
00131 *
00132 *  -- LAPACK computational routine (version 3.4.0) --
00133 *  -- LAPACK is a software package provided by Univ. of Tennessee,    --
00134 *  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
00135 *     November 2011
00136 *
00137 *     .. Scalar Arguments ..
00138       CHARACTER          UPLO
00139       INTEGER            INFO, KD, LDAB, N
00140       REAL               AMAX, SCOND
00141 *     ..
00142 *     .. Array Arguments ..
00143       REAL               AB( LDAB, * ), S( * )
00144 *     ..
00145 *
00146 *  =====================================================================
00147 *
00148 *     .. Parameters ..
00149       REAL               ZERO, ONE
00150       PARAMETER          ( ZERO = 0.0E+0, ONE = 1.0E+0 )
00151 *     ..
00152 *     .. Local Scalars ..
00153       LOGICAL            UPPER
00154       INTEGER            I, J
00155       REAL               SMIN
00156 *     ..
00157 *     .. External Functions ..
00158       LOGICAL            LSAME
00159       EXTERNAL           LSAME
00160 *     ..
00161 *     .. External Subroutines ..
00162       EXTERNAL           XERBLA
00163 *     ..
00164 *     .. Intrinsic Functions ..
00165       INTRINSIC          MAX, MIN, SQRT
00166 *     ..
00167 *     .. Executable Statements ..
00168 *
00169 *     Test the input parameters.
00170 *
00171       INFO = 0
00172       UPPER = LSAME( UPLO, 'U' )
00173       IF( .NOT.UPPER .AND. .NOT.LSAME( UPLO, 'L' ) ) THEN
00174          INFO = -1
00175       ELSE IF( N.LT.0 ) THEN
00176          INFO = -2
00177       ELSE IF( KD.LT.0 ) THEN
00178          INFO = -3
00179       ELSE IF( LDAB.LT.KD+1 ) THEN
00180          INFO = -5
00181       END IF
00182       IF( INFO.NE.0 ) THEN
00183          CALL XERBLA( 'SPBEQU', -INFO )
00184          RETURN
00185       END IF
00186 *
00187 *     Quick return if possible
00188 *
00189       IF( N.EQ.0 ) THEN
00190          SCOND = ONE
00191          AMAX = ZERO
00192          RETURN
00193       END IF
00194 *
00195       IF( UPPER ) THEN
00196          J = KD + 1
00197       ELSE
00198          J = 1
00199       END IF
00200 *
00201 *     Initialize SMIN and AMAX.
00202 *
00203       S( 1 ) = AB( J, 1 )
00204       SMIN = S( 1 )
00205       AMAX = S( 1 )
00206 *
00207 *     Find the minimum and maximum diagonal elements.
00208 *
00209       DO 10 I = 2, N
00210          S( I ) = AB( J, I )
00211          SMIN = MIN( SMIN, S( I ) )
00212          AMAX = MAX( AMAX, S( I ) )
00213    10 CONTINUE
00214 *
00215       IF( SMIN.LE.ZERO ) THEN
00216 *
00217 *        Find the first non-positive diagonal element and return.
00218 *
00219          DO 20 I = 1, N
00220             IF( S( I ).LE.ZERO ) THEN
00221                INFO = I
00222                RETURN
00223             END IF
00224    20    CONTINUE
00225       ELSE
00226 *
00227 *        Set the scale factors to the reciprocals
00228 *        of the diagonal elements.
00229 *
00230          DO 30 I = 1, N
00231             S( I ) = ONE / SQRT( S( I ) )
00232    30    CONTINUE
00233 *
00234 *        Compute SCOND = min(S(I)) / max(S(I))
00235 *
00236          SCOND = SQRT( SMIN ) / SQRT( AMAX )
00237       END IF
00238       RETURN
00239 *
00240 *     End of SPBEQU
00241 *
00242       END
 All Files Functions