shsein.f

Go to the documentation of this file.

*> \brief \b SHSEIN
*
*  =========== DOCUMENTATION ===========
*
* Online html documentation available at
*            http://www.netlib.org/lapack/explore-html/
*
*> \htmlonly
*> Download SHSEIN + dependencies
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.tgz?format=tgz&filename=/lapack/lapack_routine/shsein.f">
*> [TGZ]</a>
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.zip?format=zip&filename=/lapack/lapack_routine/shsein.f">
*> [ZIP]</a>
*> <a href="http://www.netlib.org/cgi-bin/netlibfiles.txt?format=txt&filename=/lapack/lapack_routine/shsein.f">
*> [TXT]</a>
*> \endhtmlonly
*
*  Definition:
*  ===========
*
*       SUBROUTINE SHSEIN( SIDE, EIGSRC, INITV, SELECT, N, H, LDH, WR, WI,
*                          VL, LDVL, VR, LDVR, MM, M, WORK, IFAILL,
*                          IFAILR, INFO )
*
*       .. Scalar Arguments ..
*       CHARACTER          EIGSRC, INITV, SIDE
*       INTEGER            INFO, LDH, LDVL, LDVR, M, MM, N
*       ..
*       .. Array Arguments ..
*       LOGICAL            SELECT( * )
*       INTEGER            IFAILL( * ), IFAILR( * )
*       REAL               H( LDH, * ), VL( LDVL, * ), VR( LDVR, * ),
*      $                   WI( * ), WORK( * ), WR( * )
*       ..
*
*
*> \par Purpose:
*  =============
*>
*> \verbatim
*>
*> SHSEIN uses inverse iteration to find specified right and/or left
*> eigenvectors of a real upper Hessenberg matrix H.
*>
*> The right eigenvector x and the left eigenvector y of the matrix H
*> corresponding to an eigenvalue w are defined by:
*>
*>              H * x = w * x,     y**h * H = w * y**h
*>
*> where y**h denotes the conjugate transpose of the vector y.
*> \endverbatim
*
*  Arguments:
*  ==========
*
*> \param[in] SIDE
*> \verbatim
*>          SIDE is CHARACTER*1
*>          = 'R': compute right eigenvectors only;
*>          = 'L': compute left eigenvectors only;
*>          = 'B': compute both right and left eigenvectors.
*> \endverbatim
*>
*> \param[in] EIGSRC
*> \verbatim
*>          EIGSRC is CHARACTER*1
*>          Specifies the source of eigenvalues supplied in (WR,WI):
*>          = 'Q': the eigenvalues were found using SHSEQR; thus, if
*>                 H has zero subdiagonal elements, and so is
*>                 block-triangular, then the j-th eigenvalue can be
*>                 assumed to be an eigenvalue of the block containing
*>                 the j-th row/column.  This property allows SHSEIN to
*>                 perform inverse iteration on just one diagonal block.
*>          = 'N': no assumptions are made on the correspondence
*>                 between eigenvalues and diagonal blocks.  In this
*>                 case, SHSEIN must always perform inverse iteration
*>                 using the whole matrix H.
*> \endverbatim
*>
*> \param[in] INITV
*> \verbatim
*>          INITV is CHARACTER*1
*>          = 'N': no initial vectors are supplied;
*>          = 'U': user-supplied initial vectors are stored in the arrays
*>                 VL and/or VR.
*> \endverbatim
*>
*> \param[in,out] SELECT
*> \verbatim
*>          SELECT is LOGICAL array, dimension (N)
*>          Specifies the eigenvectors to be computed. To select the
*>          real eigenvector corresponding to a real eigenvalue WR(j),
*>          SELECT(j) must be set to .TRUE.. To select the complex
*>          eigenvector corresponding to a complex eigenvalue
*>          (WR(j),WI(j)), with complex conjugate (WR(j+1),WI(j+1)),
*>          either SELECT(j) or SELECT(j+1) or both must be set to
*>          .TRUE.; then on exit SELECT(j) is .TRUE. and SELECT(j+1) is
*>          .FALSE..
*> \endverbatim
*>
*> \param[in] N
*> \verbatim
*>          N is INTEGER
*>          The order of the matrix H.  N >= 0.
*> \endverbatim
*>
*> \param[in] H
*> \verbatim
*>          H is REAL array, dimension (LDH,N)
*>          The upper Hessenberg matrix H.
*>          If a NaN is detected in H, the routine will return with INFO=-6.
*> \endverbatim
*>
*> \param[in] LDH
*> \verbatim
*>          LDH is INTEGER
*>          The leading dimension of the array H.  LDH >= max(1,N).
*> \endverbatim
*>
*> \param[in,out] WR
*> \verbatim
*>          WR is REAL array, dimension (N)
*> \endverbatim
*>
*> \param[in] WI
*> \verbatim
*>          WI is REAL array, dimension (N)
*>
*>          On entry, the real and imaginary parts of the eigenvalues of
*>          H; a complex conjugate pair of eigenvalues must be stored in
*>          consecutive elements of WR and WI.
*>          On exit, WR may have been altered since close eigenvalues
*>          are perturbed slightly in searching for independent
*>          eigenvectors.
*> \endverbatim
*>
*> \param[in,out] VL
*> \verbatim
*>          VL is REAL array, dimension (LDVL,MM)
*>          On entry, if INITV = 'U' and SIDE = 'L' or 'B', VL must
*>          contain starting vectors for the inverse iteration for the
*>          left eigenvectors; the starting vector for each eigenvector
*>          must be in the same column(s) in which the eigenvector will
*>          be stored.
*>          On exit, if SIDE = 'L' or 'B', the left eigenvectors
*>          specified by SELECT will be stored consecutively in the
*>          columns of VL, in the same order as their eigenvalues. A
*>          complex eigenvector corresponding to a complex eigenvalue is
*>          stored in two consecutive columns, the first holding the real
*>          part and the second the imaginary part.
*>          If SIDE = 'R', VL is not referenced.
*> \endverbatim
*>
*> \param[in] LDVL
*> \verbatim
*>          LDVL is INTEGER
*>          The leading dimension of the array VL.
*>          LDVL >= max(1,N) if SIDE = 'L' or 'B'; LDVL >= 1 otherwise.
*> \endverbatim
*>
*> \param[in,out] VR
*> \verbatim
*>          VR is REAL array, dimension (LDVR,MM)
*>          On entry, if INITV = 'U' and SIDE = 'R' or 'B', VR must
*>          contain starting vectors for the inverse iteration for the
*>          right eigenvectors; the starting vector for each eigenvector
*>          must be in the same column(s) in which the eigenvector will
*>          be stored.
*>          On exit, if SIDE = 'R' or 'B', the right eigenvectors
*>          specified by SELECT will be stored consecutively in the
*>          columns of VR, in the same order as their eigenvalues. A
*>          complex eigenvector corresponding to a complex eigenvalue is
*>          stored in two consecutive columns, the first holding the real
*>          part and the second the imaginary part.
*>          If SIDE = 'L', VR is not referenced.
*> \endverbatim
*>
*> \param[in] LDVR
*> \verbatim
*>          LDVR is INTEGER
*>          The leading dimension of the array VR.
*>          LDVR >= max(1,N) if SIDE = 'R' or 'B'; LDVR >= 1 otherwise.
*> \endverbatim
*>
*> \param[in] MM
*> \verbatim
*>          MM is INTEGER
*>          The number of columns in the arrays VL and/or VR. MM >= M.
*> \endverbatim
*>
*> \param[out] M
*> \verbatim
*>          M is INTEGER
*>          The number of columns in the arrays VL and/or VR required to
*>          store the eigenvectors; each selected real eigenvector
*>          occupies one column and each selected complex eigenvector
*>          occupies two columns.
*> \endverbatim
*>
*> \param[out] WORK
*> \verbatim
*>          WORK is REAL array, dimension ((N+2)*N)
*> \endverbatim
*>
*> \param[out] IFAILL
*> \verbatim
*>          IFAILL is INTEGER array, dimension (MM)
*>          If SIDE = 'L' or 'B', IFAILL(i) = j > 0 if the left
*>          eigenvector in the i-th column of VL (corresponding to the
*>          eigenvalue w(j)) failed to converge; IFAILL(i) = 0 if the
*>          eigenvector converged satisfactorily. If the i-th and (i+1)th
*>          columns of VL hold a complex eigenvector, then IFAILL(i) and
*>          IFAILL(i+1) are set to the same value.
*>          If SIDE = 'R', IFAILL is not referenced.
*> \endverbatim
*>
*> \param[out] IFAILR
*> \verbatim
*>          IFAILR is INTEGER array, dimension (MM)
*>          If SIDE = 'R' or 'B', IFAILR(i) = j > 0 if the right
*>          eigenvector in the i-th column of VR (corresponding to the
*>          eigenvalue w(j)) failed to converge; IFAILR(i) = 0 if the
*>          eigenvector converged satisfactorily. If the i-th and (i+1)th
*>          columns of VR hold a complex eigenvector, then IFAILR(i) and
*>          IFAILR(i+1) are set to the same value.
*>          If SIDE = 'L', IFAILR is not referenced.
*> \endverbatim
*>
*> \param[out] INFO
*> \verbatim
*>          INFO is INTEGER
*>          = 0:  successful exit
*>          < 0:  if INFO = -i, the i-th argument had an illegal value
*>          > 0:  if INFO = i, i is the number of eigenvectors which
*>                failed to converge; see IFAILL and IFAILR for further
*>                details.
*> \endverbatim
*
*  Authors:
*  ========
*
*> \author Univ. of Tennessee
*> \author Univ. of California Berkeley
*> \author Univ. of Colorado Denver
*> \author NAG Ltd.
*
*> \ingroup hsein
*
*> \par Further Details:
*  =====================
*>
*> \verbatim
*>
*>  Each eigenvector is normalized so that the element of largest
*>  magnitude has magnitude 1; here the magnitude of a complex number
*>  (x,y) is taken to be |x|+|y|.
*> \endverbatim
*>
*  =====================================================================
      SUBROUTINE shsein( SIDE, EIGSRC, INITV, SELECT, N, H, LDH, WR, WI,
     $                   VL, LDVL, VR, LDVR, MM, M, WORK, IFAILL,
     $                   IFAILR, INFO )
*
*  -- LAPACK computational routine --
*  -- LAPACK is a software package provided by Univ. of Tennessee,    --
*  -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
*
*     .. Scalar Arguments ..
      CHARACTER          EIGSRC, INITV, SIDE
      INTEGER            INFO, LDH, LDVL, LDVR, M, MM, N
*     ..
*     .. Array Arguments ..
      LOGICAL            SELECT( * )
      INTEGER            IFAILL( * ), IFAILR( * )
      REAL               H( LDH, * ), VL( LDVL, * ), VR( LDVR, * ),
     $                   wi( * ), work( * ), wr( * )
*     ..
*
*  =====================================================================
*
*     .. Parameters ..
      REAL               ZERO, ONE
      PARAMETER          ( ZERO = 0.0e+0, one = 1.0e+0 )
*     ..
*     .. Local Scalars ..
      LOGICAL            BOTHV, FROMQR, LEFTV, NOINIT, PAIR, RIGHTV
      INTEGER            I, IINFO, K, KL, KLN, KR, KSI, KSR, LDWORK
      REAL               BIGNUM, EPS3, HNORM, SMLNUM, ULP, UNFL, WKI,
     $                   wkr
*     ..
*     .. External Functions ..
      LOGICAL            LSAME, SISNAN
      REAL               SLAMCH, SLANHS
      EXTERNAL           lsame, slamch, slanhs, sisnan
*     ..
*     .. External Subroutines ..
      EXTERNAL           slaein, xerbla
*     ..
*     .. Intrinsic Functions ..
      INTRINSIC          abs, max
*     ..
*     .. Executable Statements ..
*
*     Decode and test the input parameters.
*
      bothv = lsame( side, 'B' )
      rightv = lsame( side, 'R' ) .OR. bothv
      leftv = lsame( side, 'L' ) .OR. bothv
*
      fromqr = lsame( eigsrc, 'Q' )
*
      noinit = lsame( initv, 'N' )
*
*     Set M to the number of columns required to store the selected
*     eigenvectors, and standardize the array SELECT.
*
      m = 0
      pair = .false.
      DO 10 k = 1, n
         IF( pair ) THEN
            pair = .false.
            SELECT( k ) = .false.
         ELSE
            IF( wi( k ).EQ.zero ) THEN
               IF( SELECT( k ) )
     $            m = m + 1
            ELSE
               pair = .true.
               IF( SELECT( k ) .OR. SELECT( k+1 ) ) THEN
                  SELECT( k ) = .true.
                  m = m + 2
               END IF
            END IF
         END IF
   10 CONTINUE
*
      info = 0
      IF( .NOT.rightv .AND. .NOT.leftv ) THEN
         info = -1
      ELSE IF( .NOT.fromqr .AND. .NOT.lsame( eigsrc, 'N' ) ) THEN
         info = -2
      ELSE IF( .NOT.noinit .AND. .NOT.lsame( initv, 'U' ) ) THEN
         info = -3
      ELSE IF( n.LT.0 ) THEN
         info = -5
      ELSE IF( ldh.LT.max( 1, n ) ) THEN
         info = -7
      ELSE IF( ldvl.LT.1 .OR. ( leftv .AND. ldvl.LT.n ) ) THEN
         info = -11
      ELSE IF( ldvr.LT.1 .OR. ( rightv .AND. ldvr.LT.n ) ) THEN
         info = -13
      ELSE IF( mm.LT.m ) THEN
         info = -14
      END IF
      IF( info.NE.0 ) THEN
         CALL xerbla( 'SHSEIN', -info )
         RETURN
      END IF
*
*     Quick return if possible.
*
      IF( n.EQ.0 )
     $   RETURN
*
*     Set machine-dependent constants.
*
      unfl = slamch( 'Safe minimum' )
      ulp = slamch( 'Precision' )
      smlnum = unfl*( n / ulp )
      bignum = ( one-ulp ) / smlnum
*
      ldwork = n + 1
*
      kl = 1
      kln = 0
      IF( fromqr ) THEN
         kr = 0
      ELSE
         kr = n
      END IF
      ksr = 1
*
      DO 120 k = 1, n
         IF( SELECT( k ) ) THEN
*
*           Compute eigenvector(s) corresponding to W(K).
*
            IF( fromqr ) THEN
*
*              If affiliation of eigenvalues is known, check whether
*              the matrix splits.
*
*              Determine KL and KR such that 1 <= KL <= K <= KR <= N
*              and H(KL,KL-1) and H(KR+1,KR) are zero (or KL = 1 or
*              KR = N).
*
*              Then inverse iteration can be performed with the
*              submatrix H(KL:N,KL:N) for a left eigenvector, and with
*              the submatrix H(1:KR,1:KR) for a right eigenvector.
*
               DO 20 i = k, kl + 1, -1
                  IF( h( i, i-1 ).EQ.zero )
     $               GO TO 30
   20          CONTINUE
   30          CONTINUE
               kl = i
               IF( k.GT.kr ) THEN
                  DO 40 i = k, n - 1
                     IF( h( i+1, i ).EQ.zero )
     $                  GO TO 50
   40             CONTINUE
   50             CONTINUE
                  kr = i
               END IF
            END IF
*
            IF( kl.NE.kln ) THEN
               kln = kl
*
*              Compute infinity-norm of submatrix H(KL:KR,KL:KR) if it
*              has not ben computed before.
*
               hnorm = slanhs( 'I', kr-kl+1, h( kl, kl ), ldh, work )
               IF( sisnan( hnorm ) ) THEN
                  info = -6
                  RETURN
               ELSE IF( hnorm.GT.zero ) THEN
                  eps3 = hnorm*ulp
               ELSE
                  eps3 = smlnum
               END IF
            END IF
*
*           Perturb eigenvalue if it is close to any previous
*           selected eigenvalues affiliated to the submatrix
*           H(KL:KR,KL:KR). Close roots are modified by EPS3.
*
            wkr = wr( k )
            wki = wi( k )
   60       CONTINUE
            DO 70 i = k - 1, kl, -1
               IF( SELECT( i ) .AND. abs( wr( i )-wkr )+
     $             abs( wi( i )-wki ).LT.eps3 ) THEN
                  wkr = wkr + eps3
                  GO TO 60
               END IF
   70       CONTINUE
            wr( k ) = wkr
*
            pair = wki.NE.zero
            IF( pair ) THEN
               ksi = ksr + 1
            ELSE
               ksi = ksr
            END IF
            IF( leftv ) THEN
*
*              Compute left eigenvector.
*
               CALL slaein( .false., noinit, n-kl+1, h( kl, kl ), ldh,
     $                      wkr, wki, vl( kl, ksr ), vl( kl, ksi ),
     $                      work, ldwork, work( n*n+n+1 ), eps3, smlnum,
     $                      bignum, iinfo )
               IF( iinfo.GT.0 ) THEN
                  IF( pair ) THEN
                     info = info + 2
                  ELSE
                     info = info + 1
                  END IF
                  ifaill( ksr ) = k
                  ifaill( ksi ) = k
               ELSE
                  ifaill( ksr ) = 0
                  ifaill( ksi ) = 0
               END IF
               DO 80 i = 1, kl - 1
                  vl( i, ksr ) = zero
   80          CONTINUE
               IF( pair ) THEN
                  DO 90 i = 1, kl - 1
                     vl( i, ksi ) = zero
   90             CONTINUE
               END IF
            END IF
            IF( rightv ) THEN
*
*              Compute right eigenvector.
*
               CALL slaein( .true., noinit, kr, h, ldh, wkr, wki,
     $                      vr( 1, ksr ), vr( 1, ksi ), work, ldwork,
     $                      work( n*n+n+1 ), eps3, smlnum, bignum,
     $                      iinfo )
               IF( iinfo.GT.0 ) THEN
                  IF( pair ) THEN
                     info = info + 2
                  ELSE
                     info = info + 1
                  END IF
                  ifailr( ksr ) = k
                  ifailr( ksi ) = k
               ELSE
                  ifailr( ksr ) = 0
                  ifailr( ksi ) = 0
               END IF
               DO 100 i = kr + 1, n
                  vr( i, ksr ) = zero
  100          CONTINUE
               IF( pair ) THEN
                  DO 110 i = kr + 1, n
                     vr( i, ksi ) = zero
  110             CONTINUE
               END IF
            END IF
*
            IF( pair ) THEN
               ksr = ksr + 2
            ELSE
               ksr = ksr + 1
            END IF
         END IF
  120 CONTINUE
*
      RETURN
*
*     End of SHSEIN
*
      END