SRC/cpoequ.f

   1 *> \brief \b CPOEQU
   2 *
   3 *  =========== DOCUMENTATION ===========
   4 *
   5 * Online html documentation available at
   6 *            http://www.netlib.org/lapack/explore-html/
   7 *
   8 *> \htmlonly
   9 *> Download CPOEQU + dependencies
  10 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/cpoequ.f">
  11 *> [TGZ]</a>
  12 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/cpoequ.f">
  13 *> [ZIP]</a>
  14 *> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/cpoequ.f">
  15 *> [TXT]</a>
  16 *> \endhtmlonly
  17 *
  18 *  Definition:
  19 *  ===========
  20 *
  21 *       SUBROUTINE CPOEQU( N, A, LDA, S, SCOND, AMAX, INFO )
  22 *
  23 *       .. Scalar Arguments ..
  24 *       INTEGER            INFO, LDA, N
  25 *       REAL               AMAX, SCOND
  26 *       ..
  27 *       .. Array Arguments ..
  28 *       REAL               S( * )
  29 *       COMPLEX            A( LDA, * )
  30 *       ..
  31 *
  32 *
  33 *> \par Purpose:
  34 *  =============
  35 *>
  36 *> \verbatim
  37 *>
  38 *> CPOEQU computes row and column scalings intended to equilibrate a
  39 *> Hermitian positive definite matrix A and reduce its condition number
  40 *> (with respect to the two-norm).  S contains the scale factors,
  41 *> S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with
  42 *> elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal.  This
  43 *> choice of S puts the condition number of B within a factor N of the
  44 *> smallest possible condition number over all possible diagonal
  45 *> scalings.
  46 *> \endverbatim
  47 *
  48 *  Arguments:
  49 *  ==========
  50 *
  51 *> \param[in] N
  52 *> \verbatim
  53 *>          N is INTEGER
  54 *>          The order of the matrix A.  N >= 0.
  55 *> \endverbatim
  56 *>
  57 *> \param[in] A
  58 *> \verbatim
  59 *>          A is COMPLEX array, dimension (LDA,N)
  60 *>          The N-by-N Hermitian positive definite matrix whose scaling
  61 *>          factors are to be computed.  Only the diagonal elements of A
  62 *>          are referenced.
  63 *> \endverbatim
  64 *>
  65 *> \param[in] LDA
  66 *> \verbatim
  67 *>          LDA is INTEGER
  68 *>          The leading dimension of the array A.  LDA >= max(1,N).
  69 *> \endverbatim
  70 *>
  71 *> \param[out] S
  72 *> \verbatim
  73 *>          S is REAL array, dimension (N)
  74 *>          If INFO = 0, S contains the scale factors for A.
  75 *> \endverbatim
  76 *>
  77 *> \param[out] SCOND
  78 *> \verbatim
  79 *>          SCOND is REAL
  80 *>          If INFO = 0, S contains the ratio of the smallest S(i) to
  81 *>          the largest S(i).  If SCOND >= 0.1 and AMAX is neither too
  82 *>          large nor too small, it is not worth scaling by S.
  83 *> \endverbatim
  84 *>
  85 *> \param[out] AMAX
  86 *> \verbatim
  87 *>          AMAX is REAL
  88 *>          Absolute value of largest matrix element.  If AMAX is very
  89 *>          close to overflow or very close to underflow, the matrix
  90 *>          should be scaled.
  91 *> \endverbatim
  92 *>
  93 *> \param[out] INFO
  94 *> \verbatim
  95 *>          INFO is INTEGER
  96 *>          = 0:  successful exit
  97 *>          < 0:  if INFO = -i, the i-th argument had an illegal value
  98 *>          > 0:  if INFO = i, the i-th diagonal element is nonpositive.
  99 *> \endverbatim
 100 *
 101 *  Authors:
 102 *  ========
 103 *
 104 *> \author Univ. of Tennessee
 105 *> \author Univ. of California Berkeley
 106 *> \author Univ. of Colorado Denver
 107 *> \author NAG Ltd.
 108 *
 109 *> \date November 2011
 110 *
 111 *> \ingroup complexPOcomputational
 112 *
 113 *  =====================================================================
 114       SUBROUTINE CPOEQU( N, A, LDA, S, SCOND, AMAX, INFO )
 115 *
 116 *  -- LAPACK computational routine (version 3.4.0) --
 117 *  -- LAPACK is a software package provided by Univ. of Tennessee,    --
 118 *  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
 119 *     November 2011
 120 *
 121 *     .. Scalar Arguments ..
 122       INTEGER            INFO, LDA, N
 123       REAL               AMAX, SCOND
 124 *     ..
 125 *     .. Array Arguments ..
 126       REAL               S( * )
 127       COMPLEX            A( LDA, * )
 128 *     ..
 129 *
 130 *  =====================================================================
 131 *
 132 *     .. Parameters ..
 133       REAL               ZERO, ONE
 134       PARAMETER          ( ZERO = 0.0E+0, ONE = 1.0E+0 )
 135 *     ..
 136 *     .. Local Scalars ..
 137       INTEGER            I
 138       REAL               SMIN
 139 *     ..
 140 *     .. External Subroutines ..
 141       EXTERNAL           XERBLA
 142 *     ..
 143 *     .. Intrinsic Functions ..
 144       INTRINSIC          MAX, MIN, REAL, SQRT
 145 *     ..
 146 *     .. Executable Statements ..
 147 *
 148 *     Test the input parameters.
 149 *
 150       INFO = 0
 151       IF( N.LT.0 ) THEN
 152          INFO = -1
 153       ELSE IF( LDA.LT.MAX( 1, N ) ) THEN
 154          INFO = -3
 155       END IF
 156       IF( INFO.NE.0 ) THEN
 157          CALL XERBLA( 'CPOEQU', -INFO )
 158          RETURN
 159       END IF
 160 *
 161 *     Quick return if possible
 162 *
 163       IF( N.EQ.0 ) THEN
 164          SCOND = ONE
 165          AMAX = ZERO
 166          RETURN
 167       END IF
 168 *
 169 *     Find the minimum and maximum diagonal elements.
 170 *
 171       S( 1 ) = REAL( A( 1, 1 ) )
 172       SMIN = S( 1 )
 173       AMAX = S( 1 )
 174       DO 10 I = 2, N
 175          S( I ) = REAL( A( I, I ) )
 176          SMIN = MIN( SMIN, S( I ) )
 177          AMAX = MAX( AMAX, S( I ) )
 178    10 CONTINUE
 179 *
 180       IF( SMIN.LE.ZERO ) THEN
 181 *
 182 *        Find the first non-positive diagonal element and return.
 183 *
 184          DO 20 I = 1, N
 185             IF( S( I ).LE.ZERO ) THEN
 186                INFO = I
 187                RETURN
 188             END IF
 189    20    CONTINUE
 190       ELSE
 191 *
 192 *        Set the scale factors to the reciprocals
 193 *        of the diagonal elements.
 194 *
 195          DO 30 I = 1, N
 196             S( I ) = ONE / SQRT( S( I ) )
 197    30    CONTINUE
 198 *
 199 *        Compute SCOND = min(S(I)) / max(S(I))
 200 *
 201          SCOND = SQRT( SMIN ) / SQRT( AMAX )
 202       END IF
 203       RETURN
 204 *
 205 *     End of CPOEQU
 206 *
 207       END