Loading...
Searching...
No Matches

## shseqr()

subroutine shseqr | ( | character | job,
|  | character | compz,
|  | integer | n,
|  | integer | ilo,
|  | integer | ihi,
|  | real, dimension( ldh, * ) | h,
|  | integer | ldh,
|  | real, dimension( * ) | wr,
|  | real, dimension( * ) | wi,
|  | real, dimension( ldz, * ) | z,
|  | integer | ldz,
|  | real, dimension( * ) | work,
|  | integer | lwork,
|  | integer | info )

SHSEQR

Download SHSEQR + dependencies [TGZ] [ZIP] [TXT]

Purpose:

      !>
      !>    SHSEQR computes the eigenvalues of a Hessenberg matrix H
      !>    and, optionally, the matrices T and Z from the Schur decomposition
      !>    H = Z T Z**T, where T is an upper quasi-triangular matrix (the
      !>    Schur form), and Z is the orthogonal matrix of Schur vectors.
      !>
      !>    Optionally Z may be postmultiplied into an input orthogonal
      !>    matrix Q so that this routine can give the Schur factorization
      !>    of a matrix A which has been reduced to the Hessenberg form H
      !>    by the orthogonal matrix Q:  A = Q*H*Q**T = (QZ)*T*(QZ)**T.
      !>

Parameters

  [in]

  JOB

      !>          JOB is CHARACTER*1
      !>           = 'E':  compute eigenvalues only;
      !>           = 'S':  compute eigenvalues and the Schur form T.
      !>

  [in]

  COMPZ

      !>          COMPZ is CHARACTER*1
      !>           = 'N':  no Schur vectors are computed;
      !>           = 'I':  Z is initialized to the unit matrix and the matrix Z
      !>                   of Schur vectors of H is returned;
      !>           = 'V':  Z must contain an orthogonal matrix Q on entry, and
      !>                   the product Q*Z is returned.
      !>

  [in]

  N

      !>          N is INTEGER
      !>           The order of the matrix H.  N >= 0.
      !>

  [in]

  ILO

      !>          ILO is INTEGER
      !>

  [in]

  IHI

      !>          IHI is INTEGER
      !>
      !>           It is assumed that H is already upper triangular in rows
      !>           and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally
      !>           set by a previous call to SGEBAL, and then passed to ZGEHRD
      !>           when the matrix output by SGEBAL is reduced to Hessenberg
      !>           form. Otherwise ILO and IHI should be set to 1 and N
      !>           respectively.  If N > 0, then 1 <= ILO <= IHI <= N.
      !>           If N = 0, then ILO = 1 and IHI = 0.
      !>

  [in,out]

  H

      !>          H is REAL array, dimension (LDH,N)
      !>           On entry, the upper Hessenberg matrix H.
      !>           On exit, if INFO = 0 and JOB = 'S', then H contains the
      !>           upper quasi-triangular matrix T from the Schur decomposition
      !>           (the Schur form); 2-by-2 diagonal blocks (corresponding to
      !>           complex conjugate pairs of eigenvalues) are returned in
      !>           standard form, with H(i,i) = H(i+1,i+1) and
      !>           H(i+1,i)*H(i,i+1) < 0. If INFO = 0 and JOB = 'E', the
      !>           contents of H are unspecified on exit.  (The output value of
      !>           H when INFO > 0 is given under the description of INFO
      !>           below.)
      !>
      !>           Unlike earlier versions of SHSEQR, this subroutine may
      !>           explicitly H(i,j) = 0 for i > j and j = 1, 2, ... ILO-1
      !>           or j = IHI+1, IHI+2, ... N.
      !>

  [in]

  LDH

      !>          LDH is INTEGER
      !>           The leading dimension of the array H. LDH >= max(1,N).
      !>

  [out]

  WR

      !>          WR is REAL array, dimension (N)
      !>

  [out]

  WI

      !>          WI is REAL array, dimension (N)
      !>
      !>           The real and imaginary parts, respectively, of the computed
      !>           eigenvalues. If two eigenvalues are computed as a complex
      !>           conjugate pair, they are stored in consecutive elements of
      !>           WR and WI, say the i-th and (i+1)th, with WI(i) > 0 and
      !>           WI(i+1) < 0. If JOB = 'S', the eigenvalues are stored in
      !>           the same order as on the diagonal of the Schur form returned
      !>           in H, with WR(i) = H(i,i) and, if H(i:i+1,i:i+1) is a 2-by-2
      !>           diagonal block, WI(i) = sqrt(-H(i+1,i)*H(i,i+1)) and
      !>           WI(i+1) = -WI(i).
      !>

  [in,out]

  Z

      !>          Z is REAL array, dimension (LDZ,N)
      !>           If COMPZ = 'N', Z is not referenced.
      !>           If COMPZ = 'I', on entry Z need not be set and on exit,
      !>           if INFO = 0, Z contains the orthogonal matrix Z of the Schur
      !>           vectors of H.  If COMPZ = 'V', on entry Z must contain an
      !>           N-by-N matrix Q, which is assumed to be equal to the unit
      !>           matrix except for the submatrix Z(ILO:IHI,ILO:IHI). On exit,
      !>           if INFO = 0, Z contains Q*Z.
      !>           Normally Q is the orthogonal matrix generated by SORGHR
      !>           after the call to SGEHRD which formed the Hessenberg matrix
      !>           H. (The output value of Z when INFO > 0 is given under
      !>           the description of INFO below.)
      !>

  [in]

  LDZ

      !>          LDZ is INTEGER
      !>           The leading dimension of the array Z.  if COMPZ = 'I' or
      !>           COMPZ = 'V', then LDZ >= MAX(1,N).  Otherwise, LDZ >= 1.
      !>

  [out]

  WORK

      !>          WORK is REAL array, dimension (LWORK)
      !>           On exit, if INFO = 0, WORK(1) returns an estimate of
      !>           the optimal value for LWORK.
      !>

  [in]

  LWORK

      !>          LWORK is INTEGER
      !>           The dimension of the array WORK.  LWORK >= max(1,N)
      !>           is sufficient and delivers very good and sometimes
      !>           optimal performance.  However, LWORK as large as 11*N
      !>           may be required for optimal performance.  A workspace
      !>           query is recommended to determine the optimal workspace
      !>           size.
      !>
      !>           If LWORK = -1, then SHSEQR does a workspace query.
      !>           In this case, SHSEQR checks the input parameters and
      !>           estimates the optimal workspace size for the given
      !>           values of N, ILO and IHI.  The estimate is returned
      !>           in WORK(1).  No error message related to LWORK is
      !>           issued by XERBLA.  Neither H nor Z are accessed.
      !>

  [out]

  INFO

      !>          INFO is INTEGER
      !>             = 0:  successful exit
      !>             < 0:  if INFO = -i, the i-th argument had an illegal
      !>                    value
      !>             > 0:  if INFO = i, SHSEQR failed to compute all of
      !>                the eigenvalues.  Elements 1:ilo-1 and i+1:n of WR
      !>                and WI contain those eigenvalues which have been
      !>                successfully computed.  (Failures are rare.)
      !>
      !>                If INFO > 0 and JOB = 'E', then on exit, the
      !>                remaining unconverged eigenvalues are the eigen-
      !>                values of the upper Hessenberg matrix rows and
      !>                columns ILO through INFO of the final, output
      !>                value of H.
      !>
      !>                If INFO > 0 and JOB   = 'S', then on exit
      !>
      !>           (*)  (initial value of H)*U  = U*(final value of H)
      !>
      !>                where U is an orthogonal matrix.  The final
      !>                value of H is upper Hessenberg and quasi-triangular
      !>                in rows and columns INFO+1 through IHI.
      !>
      !>                If INFO > 0 and COMPZ = 'V', then on exit
      !>
      !>                  (final value of Z)  =  (initial value of Z)*U
      !>
      !>                where U is the orthogonal matrix in (*) (regard-
      !>                less of the value of JOB.)
      !>
      !>                If INFO > 0 and COMPZ = 'I', then on exit
      !>                      (final value of Z)  = U
      !>                where U is the orthogonal matrix in (*) (regard-
      !>                less of the value of JOB.)
      !>
      !>                If INFO > 0 and COMPZ = 'N', then Z is not
      !>                accessed.
      !>

Author
  Univ. of Tennessee
  Univ. of California Berkeley
  Univ. of Colorado Denver
  NAG Ltd.

Contributors:
  Karen Braman and Ralph Byers, Department of Mathematics, University of Kansas, USA

Further Details:

      !>
      !>             Default values supplied by
      !>             ILAENV(ISPEC,'SHSEQR',JOB(:1)//COMPZ(:1),N,ILO,IHI,LWORK).
      !>             It is suggested that these defaults be adjusted in order
      !>             to attain best performance in each particular
      !>             computational environment.
      !>
      !>            ISPEC=12: The SLAHQR vs SLAQR0 crossover point.
      !>                      Default: 75. (Must be at least 11.)
      !>
      !>            ISPEC=13: Recommended deflation window size.
      !>                      This depends on ILO, IHI and NS.  NS is the
      !>                      number of simultaneous shifts returned
      !>                      by ILAENV(ISPEC=15).  (See ISPEC=15 below.)
      !>                      The default for (IHI-ILO+1) <= 500 is NS.
      !>                      The default for (IHI-ILO+1) >  500 is 3*NS/2.
      !>
      !>            ISPEC=14: Nibble crossover point. (See IPARMQ for
      !>                      details.)  Default: 14% of deflation window
      !>                      size.
      !>
      !>            ISPEC=15: Number of simultaneous shifts in a multishift
      !>                      QR iteration.
      !>
      !>                      If IHI-ILO+1 is ...
      !>
      !>                      greater than      ...but less    ... the
      !>                      or equal to ...      than        default is
      !>
      !>                           1               30          NS =   2(+)
      !>                          30               60          NS =   4(+)
      !>                          60              150          NS =  10(+)
      !>                         150              590          NS =  **
      !>                         590             3000          NS =  64
      !>                        3000             6000          NS = 128
      !>                        6000             infinity      NS = 256
      !>
      !>                  (+)  By default some or all matrices of this order
      !>                       are passed to the implicit double shift routine
      !>                       SLAHQR and this parameter is ignored.  See
      !>                       ISPEC=12 above and comments in IPARMQ for
      !>                       details.
      !>
      !>                 (**)  The asterisks (**) indicate an ad-hoc
      !>                       function of N increasing from 10 to 64.
      !>
      !>            ISPEC=16: Select structured matrix multiply.
      !>                      If the number of simultaneous shifts (specified
      !>                      by ISPEC=15) is less than 14, then the default
      !>                      for ISPEC=16 is 0.  Otherwise the default for
      !>                      ISPEC=16 is 2.
      !>

References:

       K. Braman, R. Byers and R. Mathias, The Multi-Shift QR
       Algorithm Part I: Maintaining Well Focused Shifts, and Level 3
       Performance, SIAM Journal of Matrix Analysis, volume 23, pages
       929--947, 2002.

  K. Braman, R. Byers and R. Mathias, The Multi-Shift QR Algorithm Part II: Aggressive Early Deflation, SIAM Journal of Matrix Analysis, volume 23, pages 948–973, 2002.