claic1.f

Go to the documentation of this file.

*> \brief \b CLAIC1 applies one step of incremental condition estimation.
*
*  =========== DOCUMENTATION ===========
*
* Online html documentation available at 
*            http://www.netlib.org/lapack/explore-html/ 
*
*> \htmlonly
*> Download CLAIC1 + dependencies 
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/claic1.f"> 
*> [TGZ]</a> 
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/claic1.f"> 
*> [ZIP]</a> 
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/claic1.f"> 
*> [TXT]</a>
*> \endhtmlonly 
*
*  Definition:
*  ===========
*
*       SUBROUTINE CLAIC1( JOB, J, X, SEST, W, GAMMA, SESTPR, S, C )
* 
*       .. Scalar Arguments ..
*       INTEGER            J, JOB
*       REAL               SEST, SESTPR
*       COMPLEX            C, GAMMA, S
*       ..
*       .. Array Arguments ..
*       COMPLEX            W( J ), X( J )
*       ..
*  
*
*> \par Purpose:
*  =============
*>
*> \verbatim
*>
*> CLAIC1 applies one step of incremental condition estimation in
*> its simplest version:
*>
*> Let x, twonorm(x) = 1, be an approximate singular vector of an j-by-j
*> lower triangular matrix L, such that
*>          twonorm(L*x) = sest
*> Then CLAIC1 computes sestpr, s, c such that
*> the vector
*>                 [ s*x ]
*>          xhat = [  c  ]
*> is an approximate singular vector of
*>                 [ L      0  ]
*>          Lhat = [ w**H gamma ]
*> in the sense that
*>          twonorm(Lhat*xhat) = sestpr.
*>
*> Depending on JOB, an estimate for the largest or smallest singular
*> value is computed.
*>
*> Note that [s c]**H and sestpr**2 is an eigenpair of the system
*>
*>     diag(sest*sest, 0) + [alpha  gamma] * [ conjg(alpha) ]
*>                                           [ conjg(gamma) ]
*>
*> where  alpha =  x**H*w.
*> \endverbatim
*
*  Arguments:
*  ==========
*
*> \param[in] JOB
*> \verbatim
*>          JOB is INTEGER
*>          = 1: an estimate for the largest singular value is computed.
*>          = 2: an estimate for the smallest singular value is computed.
*> \endverbatim
*>
*> \param[in] J
*> \verbatim
*>          J is INTEGER
*>          Length of X and W
*> \endverbatim
*>
*> \param[in] X
*> \verbatim
*>          X is COMPLEX array, dimension (J)
*>          The j-vector x.
*> \endverbatim
*>
*> \param[in] SEST
*> \verbatim
*>          SEST is REAL
*>          Estimated singular value of j by j matrix L
*> \endverbatim
*>
*> \param[in] W
*> \verbatim
*>          W is COMPLEX array, dimension (J)
*>          The j-vector w.
*> \endverbatim
*>
*> \param[in] GAMMA
*> \verbatim
*>          GAMMA is COMPLEX
*>          The diagonal element gamma.
*> \endverbatim
*>
*> \param[out] SESTPR
*> \verbatim
*>          SESTPR is REAL
*>          Estimated singular value of (j+1) by (j+1) matrix Lhat.
*> \endverbatim
*>
*> \param[out] S
*> \verbatim
*>          S is COMPLEX
*>          Sine needed in forming xhat.
*> \endverbatim
*>
*> \param[out] C
*> \verbatim
*>          C is COMPLEX
*>          Cosine needed in forming xhat.
*> \endverbatim
*
*  Authors:
*  ========
*
*> \author Univ. of Tennessee 
*> \author Univ. of California Berkeley 
*> \author Univ. of Colorado Denver 
*> \author NAG Ltd. 
*
*> \date September 2012
*
*> \ingroup complexOTHERauxiliary
*
*  =====================================================================
      SUBROUTINE claic1( JOB, J, X, SEST, W, GAMMA, SESTPR, S, C )
*
*  -- LAPACK auxiliary routine (version 3.4.2) --
*  -- LAPACK is a software package provided by Univ. of Tennessee,    --
*  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
*     September 2012
*
*     .. Scalar Arguments ..
      INTEGER            j, job
      REAL               sest, sestpr
      COMPLEX            c, gamma, s
*     ..
*     .. Array Arguments ..
      COMPLEX            w( j ), x( j )
*     ..
*
*  =====================================================================
*
*     .. Parameters ..
      REAL               zero, one, two
      parameter( zero = 0.0e0, one = 1.0e0, two = 2.0e0 )
      REAL               half, four
      parameter( half = 0.5e0, four = 4.0e0 )
*     ..
*     .. Local Scalars ..
      REAL               absalp, absest, absgam, b, eps, norma, s1, s2,
     $                   scl, t, test, tmp, zeta1, zeta2
      COMPLEX            alpha, cosine, sine
*     ..
*     .. Intrinsic Functions ..
      INTRINSIC          abs, conjg, max, sqrt
*     ..
*     .. External Functions ..
      REAL               slamch
      COMPLEX            cdotc
      EXTERNAL           slamch, cdotc
*     ..
*     .. Executable Statements ..
*
      eps = slamch( 'Epsilon' )
      alpha = cdotc( j, x, 1, w, 1 )
*
      absalp = abs( alpha )
      absgam = abs( gamma )
      absest = abs( sest )
*
      IF( job.EQ.1 ) THEN
*
*        Estimating largest singular value
*
*        special cases
*
         IF( sest.EQ.zero ) THEN
            s1 = max( absgam, absalp )
            IF( s1.EQ.zero ) THEN
               s = zero
               c = one
               sestpr = zero
            ELSE
               s = alpha / s1
               c = gamma / s1
               tmp = sqrt( s*conjg( s )+c*conjg( c ) )
               s = s / tmp
               c = c / tmp
               sestpr = s1*tmp
            END IF
            return
         ELSE IF( absgam.LE.eps*absest ) THEN
            s = one
            c = zero
            tmp = max( absest, absalp )
            s1 = absest / tmp
            s2 = absalp / tmp
            sestpr = tmp*sqrt( s1*s1+s2*s2 )
            return
         ELSE IF( absalp.LE.eps*absest ) THEN
            s1 = absgam
            s2 = absest
            IF( s1.LE.s2 ) THEN
               s = one
               c = zero
               sestpr = s2
            ELSE
               s = zero
               c = one
               sestpr = s1
            END IF
            return
         ELSE IF( absest.LE.eps*absalp .OR. absest.LE.eps*absgam ) THEN
            s1 = absgam
            s2 = absalp
            IF( s1.LE.s2 ) THEN
               tmp = s1 / s2
               scl = sqrt( one+tmp*tmp )
               sestpr = s2*scl
               s = ( alpha / s2 ) / scl
               c = ( gamma / s2 ) / scl
            ELSE
               tmp = s2 / s1
               scl = sqrt( one+tmp*tmp )
               sestpr = s1*scl
               s = ( alpha / s1 ) / scl
               c = ( gamma / s1 ) / scl
            END IF
            return
         ELSE
*
*           normal case
*
            zeta1 = absalp / absest
            zeta2 = absgam / absest
*
            b = ( one-zeta1*zeta1-zeta2*zeta2 )*half
            c = zeta1*zeta1
            IF( b.GT.zero ) THEN
               t = c / ( b+sqrt( b*b+c ) )
            ELSE
               t = sqrt( b*b+c ) - b
            END IF
*
            sine = -( alpha / absest ) / t
            cosine = -( gamma / absest ) / ( one+t )
            tmp = sqrt( sine*conjg( sine )+cosine*conjg( cosine ) )
            s = sine / tmp
            c = cosine / tmp
            sestpr = sqrt( t+one )*absest
            return
         END IF
*
      ELSE IF( job.EQ.2 ) THEN
*
*        Estimating smallest singular value
*
*        special cases
*
         IF( sest.EQ.zero ) THEN
            sestpr = zero
            IF( max( absgam, absalp ).EQ.zero ) THEN
               sine = one
               cosine = zero
            ELSE
               sine = -conjg( gamma )
               cosine = conjg( alpha )
            END IF
            s1 = max( abs( sine ), abs( cosine ) )
            s = sine / s1
            c = cosine / s1
            tmp = sqrt( s*conjg( s )+c*conjg( c ) )
            s = s / tmp
            c = c / tmp
            return
         ELSE IF( absgam.LE.eps*absest ) THEN
            s = zero
            c = one
            sestpr = absgam
            return
         ELSE IF( absalp.LE.eps*absest ) THEN
            s1 = absgam
            s2 = absest
            IF( s1.LE.s2 ) THEN
               s = zero
               c = one
               sestpr = s1
            ELSE
               s = one
               c = zero
               sestpr = s2
            END IF
            return
         ELSE IF( absest.LE.eps*absalp .OR. absest.LE.eps*absgam ) THEN
            s1 = absgam
            s2 = absalp
            IF( s1.LE.s2 ) THEN
               tmp = s1 / s2
               scl = sqrt( one+tmp*tmp )
               sestpr = absest*( tmp / scl )
               s = -( conjg( gamma ) / s2 ) / scl
               c = ( conjg( alpha ) / s2 ) / scl
            ELSE
               tmp = s2 / s1
               scl = sqrt( one+tmp*tmp )
               sestpr = absest / scl
               s = -( conjg( gamma ) / s1 ) / scl
               c = ( conjg( alpha ) / s1 ) / scl
            END IF
            return
         ELSE
*
*           normal case
*
            zeta1 = absalp / absest
            zeta2 = absgam / absest
*
            norma = max( one+zeta1*zeta1+zeta1*zeta2,
     $              zeta1*zeta2+zeta2*zeta2 )
*
*           See if root is closer to zero or to ONE
*
            test = one + two*( zeta1-zeta2 )*( zeta1+zeta2 )
            IF( test.GE.zero ) THEN
*
*              root is close to zero, compute directly
*
               b = ( zeta1*zeta1+zeta2*zeta2+one )*half
               c = zeta2*zeta2
               t = c / ( b+sqrt( abs( b*b-c ) ) )
               sine = ( alpha / absest ) / ( one-t )
               cosine = -( gamma / absest ) / t
               sestpr = sqrt( t+four*eps*eps*norma )*absest
            ELSE
*
*              root is closer to ONE, shift by that amount
*
               b = ( zeta2*zeta2+zeta1*zeta1-one )*half
               c = zeta1*zeta1
               IF( b.GE.zero ) THEN
                  t = -c / ( b+sqrt( b*b+c ) )
               ELSE
                  t = b - sqrt( b*b+c )
               END IF
               sine = -( alpha / absest ) / t
               cosine = -( gamma / absest ) / ( one+t )
               sestpr = sqrt( one+t+four*eps*eps*norma )*absest
            END IF
            tmp = sqrt( sine*conjg( sine )+cosine*conjg( cosine ) )
            s = sine / tmp
            c = cosine / tmp
            return
*
         END IF
      END IF
      return
*
*     End of CLAIC1
*
      END