====================================================================
dhseqr examples
====================================================================

====================================================================
Man Page Details
====================================================================

NAME
       DHSEQR - compute the eigenvalues of a Hessenberg matrix H  and, option-
       ally, 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

SYNOPSIS
       SUBROUTINE DHSEQR( JOB, COMPZ, N, ILO, IHI, H, LDH,  WR,  WI,  Z,  LDZ,
                          WORK, LWORK, INFO )

           INTEGER        IHI, ILO, INFO, LDH, LDZ, LWORK, N

           CHARACTER      COMPZ, JOB

           DOUBLE         PRECISION  H( LDH, * ), WI( * ), WORK( * ), WR( * ),
                          Z( LDZ, * )

PURPOSE
          DHSEQR 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.


ARGUMENTS
       JOB   (input) CHARACTER*1
             = 'E':  compute eigenvalues only;
             = 'S':  compute eigenvalues and the Schur form T.

             COMPZ (input) 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 orthog-
             onal matrix Q on entry, and the product Q*Z is returned.

       N     (input) INTEGER
             The order of the matrix H.  N .GE. 0.

       ILO   (input) INTEGER
             IHI   (input) INTEGER It is assumed that H is already upper  tri-
             angular  in rows and columns 1:ILO-1 and IHI+1:N. ILO and IHI are
             normally set by a previous call to DGEBAL,  and  then  passed  to
             DGEHRD  when the matrix output by DGEBAL is reduced to Hessenberg
             form. Otherwise ILO and IHI should be set  to  1  and  N  respec-
             tively.   If  N.GT.0,  then 1.LE.ILO.LE.IHI.LE.N.  If N = 0, then
             ILO = 1 and IHI = 0.

       H     (input/output) DOUBLE PRECISION 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).LT.0.  If  INFO = 0 and JOB = 'E', the contents
             of H are unspecified on  exit.   (The  output  value  of  H  when
             INFO.GT.0 is given under the description of INFO below.)

             Unlike earlier versions of DHSEQR, this subroutine may explicitly
             H(i,j) = 0 for i.GT.j and j = 1, 2,  ...  ILO-1  or  j  =  IHI+1,
             IHI+2, ... N.

       LDH   (input) INTEGER
             The leading dimension of the array H. LDH .GE. max(1,N).

       WR    (output) DOUBLE PRECISION array, dimension (N)
             WI    (output) DOUBLE PRECISION 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) .GT. 0 and WI(i+1) .LT. 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).

       Z     (input/output) DOUBLE PRECISION 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 orthogo-
             nal 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 orthogo-
             nal  matrix  generated  by  DORGHR after the call to DGEHRD which
             formed the Hessenberg matrix H.  (The  output  value  of  Z  when
             INFO.GT.0 is given under the description of INFO below.)

       LDZ   (input) INTEGER
             The  leading dimension of the array Z.  if COMPZ = 'I' or COMPZ =
             'V', then LDZ.GE.MAX(1,N).  Otherwize, LDZ.GE.1.

       WORK  (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
             On exit, if INFO = 0, WORK(1) returns an estimate of the  optimal
             value for LWORK.

             LWORK  (input)  INTEGER  The  dimension of the array WORK.  LWORK
             .GE. max(1,N) is sufficient, but LWORK typically as large as  6*N
             may  be  required  for optimal performance.  A workspace query to
             determine the optimal workspace size is recommended.

             If LWORK = -1, then DHSEQR does a workspace query.  In this case,
             DHSEQR  checks  the  input  parameters  and estimates the optimal
             workspace size for the given values of N, ILO and IHI.  The esti-
             mate  is  returned in WORK(1).  No error message related to LWORK
             is issued by XERBLA.  Neither H nor Z are accessed.

       INFO  (output) INTEGER
             =  0:  successful exit
             value
             the eigenvalues.  Elements 1:ilo-1 and i+1:n of WR and WI contain
             those  eigenvalues which have been successfully computed.  (Fail-
             ures are rare.)

             If INFO .GT. 0 and JOB = 'E', then on exit, the remaining  uncon-
             verged  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 .GT. 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 .GT. 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 .GT. 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 .GT. 0 and COMPZ = 'N', then Z is not accessed.

