.TH "hseqr" 3 "Wed Feb 7 2024 11:30:40" "Version 3.12.0" "LAPACK" \" -*- nroff -*- .ad l .nh .SH NAME hseqr \- hseqr: Hessenberg eig, QR iteration .SH SYNOPSIS .br .PP .SS "Functions" .in +1c .ti -1c .RI "subroutine \fBchseqr\fP (job, compz, n, ilo, ihi, h, ldh, w, z, ldz, work, lwork, info)" .br .RI "\fBCHSEQR\fP " .ti -1c .RI "subroutine \fBdhseqr\fP (job, compz, n, ilo, ihi, h, ldh, wr, wi, z, ldz, work, lwork, info)" .br .RI "\fBDHSEQR\fP " .ti -1c .RI "subroutine \fBshseqr\fP (job, compz, n, ilo, ihi, h, ldh, wr, wi, z, ldz, work, lwork, info)" .br .RI "\fBSHSEQR\fP " .ti -1c .RI "subroutine \fBzhseqr\fP (job, compz, n, ilo, ihi, h, ldh, w, z, ldz, work, lwork, info)" .br .RI "\fBZHSEQR\fP " .in -1c .SH "Detailed Description" .PP .SH "Function Documentation" .PP .SS "subroutine chseqr (character job, character compz, integer n, integer ilo, integer ihi, complex, dimension( ldh, * ) h, integer ldh, complex, dimension( * ) w, complex, dimension( ldz, * ) z, integer ldz, complex, dimension( * ) work, integer lwork, integer info)" .PP \fBCHSEQR\fP .PP \fBPurpose:\fP .RS 4 .PP .nf CHSEQR computes the eigenvalues of a Hessenberg matrix H and, optionally, the matrices T and Z from the Schur decomposition H = Z T Z**H, where T is an upper triangular matrix (the Schur form), and Z is the unitary matrix of Schur vectors\&. Optionally Z may be postmultiplied into an input unitary 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 unitary matrix Q: A = Q*H*Q**H = (QZ)*T*(QZ)**H\&. .fi .PP .RE .PP \fBParameters\fP .RS 4 \fIJOB\fP .PP .nf JOB is CHARACTER*1 = 'E': compute eigenvalues only; = 'S': compute eigenvalues and the Schur form T\&. .fi .PP .br \fICOMPZ\fP .PP .nf 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 unitary matrix Q on entry, and the product Q*Z is returned\&. .fi .PP .br \fIN\fP .PP .nf N is INTEGER The order of the matrix H\&. N >= 0\&. .fi .PP .br \fIILO\fP .PP .nf ILO is INTEGER .fi .PP .br \fIIHI\fP .PP .nf 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 CGEBAL, and then passed to ZGEHRD when the matrix output by CGEBAL 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\&. .fi .PP .br \fIH\fP .PP .nf H is COMPLEX array, dimension (LDH,N) On entry, the upper Hessenberg matrix H\&. On exit, if INFO = 0 and JOB = 'S', H contains the upper triangular matrix T from the Schur decomposition (the Schur form)\&. 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 CHSEQR, this subroutine may explicitly H(i,j) = 0 for i > j and j = 1, 2, \&.\&.\&. ILO-1 or j = IHI+1, IHI+2, \&.\&.\&. N\&. .fi .PP .br \fILDH\fP .PP .nf LDH is INTEGER The leading dimension of the array H\&. LDH >= max(1,N)\&. .fi .PP .br \fIW\fP .PP .nf W is COMPLEX array, dimension (N) The computed eigenvalues\&. If JOB = 'S', the eigenvalues are stored in the same order as on the diagonal of the Schur form returned in H, with W(i) = H(i,i)\&. .fi .PP .br \fIZ\fP .PP .nf Z is COMPLEX 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 unitary 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 unitary matrix generated by CUNGHR after the call to CGEHRD which formed the Hessenberg matrix H\&. (The output value of Z when INFO > 0 is given under the description of INFO below\&.) .fi .PP .br \fILDZ\fP .PP .nf LDZ is INTEGER The leading dimension of the array Z\&. if COMPZ = 'I' or COMPZ = 'V', then LDZ >= MAX(1,N)\&. Otherwise, LDZ >= 1\&. .fi .PP .br \fIWORK\fP .PP .nf WORK is COMPLEX array, dimension (LWORK) On exit, if INFO = 0, WORK(1) returns an estimate of the optimal value for LWORK\&. .fi .PP .br \fILWORK\fP .PP .nf 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 CHSEQR does a workspace query\&. In this case, CHSEQR 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\&. .fi .PP .br \fIINFO\fP .PP .nf INFO is INTEGER = 0: successful exit < 0: if INFO = -i, the i-th argument had an illegal value > 0: if INFO = i, CHSEQR failed to compute all of the eigenvalues\&. Elements 1:ilo-1 and i+1:n of W 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 a unitary matrix\&. The final value of H is upper Hessenberg and 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 unitary 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 unitary matrix in (*) (regard- less of the value of JOB\&.) If INFO > 0 and COMPZ = 'N', then Z is not accessed\&. .fi .PP .RE .PP \fBAuthor\fP .RS 4 Univ\&. of Tennessee .PP Univ\&. of California Berkeley .PP Univ\&. of Colorado Denver .PP NAG Ltd\&. .RE .PP \fBContributors:\fP .RS 4 Karen Braman and Ralph Byers, Department of Mathematics, University of Kansas, USA .RE .PP \fBFurther Details:\fP .RS 4 .PP .nf Default values supplied by ILAENV(ISPEC,'CHSEQR',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 CLAHQR vs CLAQR0 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 CLAHQR 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\&. .fi .PP .RE .PP \fBReferences:\fP .RS 4 .PP .nf 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\&. .fi .PP .br 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\&. .RE .PP .SS "subroutine dhseqr (character job, character compz, integer n, integer ilo, integer ihi, double precision, dimension( ldh, * ) h, integer ldh, double precision, dimension( * ) wr, double precision, dimension( * ) wi, double precision, dimension( ldz, * ) z, integer ldz, double precision, dimension( * ) work, integer lwork, integer info)" .PP \fBDHSEQR\fP .PP \fBPurpose:\fP .RS 4 .PP .nf 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\&. .fi .PP .RE .PP \fBParameters\fP .RS 4 \fIJOB\fP .PP .nf JOB is CHARACTER*1 = 'E': compute eigenvalues only; = 'S': compute eigenvalues and the Schur form T\&. .fi .PP .br \fICOMPZ\fP .PP .nf 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\&. .fi .PP .br \fIN\fP .PP .nf N is INTEGER The order of the matrix H\&. N >= 0\&. .fi .PP .br \fIILO\fP .PP .nf ILO is INTEGER .fi .PP .br \fIIHI\fP .PP .nf 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 DGEBAL, and then passed to ZGEHRD when the matrix output by DGEBAL 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\&. .fi .PP .br \fIH\fP .PP .nf H is 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) < 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 DHSEQR, this subroutine may explicitly H(i,j) = 0 for i > j and j = 1, 2, \&.\&.\&. ILO-1 or j = IHI+1, IHI+2, \&.\&.\&. N\&. .fi .PP .br \fILDH\fP .PP .nf LDH is INTEGER The leading dimension of the array H\&. LDH >= max(1,N)\&. .fi .PP .br \fIWR\fP .PP .nf WR is DOUBLE PRECISION array, dimension (N) .fi .PP .br \fIWI\fP .PP .nf WI is 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) > 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)\&. .fi .PP .br \fIZ\fP .PP .nf Z is 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 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 DORGHR after the call to DGEHRD which formed the Hessenberg matrix H\&. (The output value of Z when INFO > 0 is given under the description of INFO below\&.) .fi .PP .br \fILDZ\fP .PP .nf LDZ is INTEGER The leading dimension of the array Z\&. if COMPZ = 'I' or COMPZ = 'V', then LDZ >= MAX(1,N)\&. Otherwise, LDZ >= 1\&. .fi .PP .br \fIWORK\fP .PP .nf WORK is DOUBLE PRECISION array, dimension (LWORK) On exit, if INFO = 0, WORK(1) returns an estimate of the optimal value for LWORK\&. .fi .PP .br \fILWORK\fP .PP .nf 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 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 estimate is returned in WORK(1)\&. No error message related to LWORK is issued by XERBLA\&. Neither H nor Z are accessed\&. .fi .PP .br \fIINFO\fP .PP .nf INFO is INTEGER = 0: successful exit < 0: if INFO = -i, the i-th argument had an illegal value > 0: if INFO = i, DHSEQR 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\&. .fi .PP .RE .PP \fBAuthor\fP .RS 4 Univ\&. of Tennessee .PP Univ\&. of California Berkeley .PP Univ\&. of Colorado Denver .PP NAG Ltd\&. .RE .PP \fBContributors:\fP .RS 4 Karen Braman and Ralph Byers, Department of Mathematics, University of Kansas, USA .RE .PP \fBFurther Details:\fP .RS 4 .PP .nf Default values supplied by ILAENV(ISPEC,'DHSEQR',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 DLAHQR vs DLAQR0 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 DLAHQR 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\&. .fi .PP .RE .PP \fBReferences:\fP .RS 4 .PP .nf 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\&. .fi .PP .br 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\&. .RE .PP .SS "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)" .PP \fBSHSEQR\fP .PP \fBPurpose:\fP .RS 4 .PP .nf 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\&. .fi .PP .RE .PP \fBParameters\fP .RS 4 \fIJOB\fP .PP .nf JOB is CHARACTER*1 = 'E': compute eigenvalues only; = 'S': compute eigenvalues and the Schur form T\&. .fi .PP .br \fICOMPZ\fP .PP .nf 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\&. .fi .PP .br \fIN\fP .PP .nf N is INTEGER The order of the matrix H\&. N >= 0\&. .fi .PP .br \fIILO\fP .PP .nf ILO is INTEGER .fi .PP .br \fIIHI\fP .PP .nf 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\&. .fi .PP .br \fIH\fP .PP .nf 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\&. .fi .PP .br \fILDH\fP .PP .nf LDH is INTEGER The leading dimension of the array H\&. LDH >= max(1,N)\&. .fi .PP .br \fIWR\fP .PP .nf WR is REAL array, dimension (N) .fi .PP .br \fIWI\fP .PP .nf 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)\&. .fi .PP .br \fIZ\fP .PP .nf 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\&.) .fi .PP .br \fILDZ\fP .PP .nf LDZ is INTEGER The leading dimension of the array Z\&. if COMPZ = 'I' or COMPZ = 'V', then LDZ >= MAX(1,N)\&. Otherwise, LDZ >= 1\&. .fi .PP .br \fIWORK\fP .PP .nf WORK is REAL array, dimension (LWORK) On exit, if INFO = 0, WORK(1) returns an estimate of the optimal value for LWORK\&. .fi .PP .br \fILWORK\fP .PP .nf 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\&. .fi .PP .br \fIINFO\fP .PP .nf 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\&. .fi .PP .RE .PP \fBAuthor\fP .RS 4 Univ\&. of Tennessee .PP Univ\&. of California Berkeley .PP Univ\&. of Colorado Denver .PP NAG Ltd\&. .RE .PP \fBContributors:\fP .RS 4 Karen Braman and Ralph Byers, Department of Mathematics, University of Kansas, USA .RE .PP \fBFurther Details:\fP .RS 4 .PP .nf 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\&. .fi .PP .RE .PP \fBReferences:\fP .RS 4 .PP .nf 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\&. .fi .PP .br 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\&. .RE .PP .SS "subroutine zhseqr (character job, character compz, integer n, integer ilo, integer ihi, complex*16, dimension( ldh, * ) h, integer ldh, complex*16, dimension( * ) w, complex*16, dimension( ldz, * ) z, integer ldz, complex*16, dimension( * ) work, integer lwork, integer info)" .PP \fBZHSEQR\fP .PP \fBPurpose:\fP .RS 4 .PP .nf ZHSEQR computes the eigenvalues of a Hessenberg matrix H and, optionally, the matrices T and Z from the Schur decomposition H = Z T Z**H, where T is an upper triangular matrix (the Schur form), and Z is the unitary matrix of Schur vectors\&. Optionally Z may be postmultiplied into an input unitary 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 unitary matrix Q: A = Q*H*Q**H = (QZ)*T*(QZ)**H\&. .fi .PP .RE .PP \fBParameters\fP .RS 4 \fIJOB\fP .PP .nf JOB is CHARACTER*1 = 'E': compute eigenvalues only; = 'S': compute eigenvalues and the Schur form T\&. .fi .PP .br \fICOMPZ\fP .PP .nf 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 unitary matrix Q on entry, and the product Q*Z is returned\&. .fi .PP .br \fIN\fP .PP .nf N is INTEGER The order of the matrix H\&. N >= 0\&. .fi .PP .br \fIILO\fP .PP .nf ILO is INTEGER .fi .PP .br \fIIHI\fP .PP .nf 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 ZGEBAL, and then passed to ZGEHRD when the matrix output by ZGEBAL 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\&. .fi .PP .br \fIH\fP .PP .nf H is COMPLEX*16 array, dimension (LDH,N) On entry, the upper Hessenberg matrix H\&. On exit, if INFO = 0 and JOB = 'S', H contains the upper triangular matrix T from the Schur decomposition (the Schur form)\&. 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 ZHSEQR, this subroutine may explicitly H(i,j) = 0 for i > j and j = 1, 2, \&.\&.\&. ILO-1 or j = IHI+1, IHI+2, \&.\&.\&. N\&. .fi .PP .br \fILDH\fP .PP .nf LDH is INTEGER The leading dimension of the array H\&. LDH >= max(1,N)\&. .fi .PP .br \fIW\fP .PP .nf W is COMPLEX*16 array, dimension (N) The computed eigenvalues\&. If JOB = 'S', the eigenvalues are stored in the same order as on the diagonal of the Schur form returned in H, with W(i) = H(i,i)\&. .fi .PP .br \fIZ\fP .PP .nf Z is COMPLEX*16 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 unitary 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 unitary matrix generated by ZUNGHR after the call to ZGEHRD which formed the Hessenberg matrix H\&. (The output value of Z when INFO > 0 is given under the description of INFO below\&.) .fi .PP .br \fILDZ\fP .PP .nf LDZ is INTEGER The leading dimension of the array Z\&. if COMPZ = 'I' or COMPZ = 'V', then LDZ >= MAX(1,N)\&. Otherwise, LDZ >= 1\&. .fi .PP .br \fIWORK\fP .PP .nf WORK is COMPLEX*16 array, dimension (LWORK) On exit, if INFO = 0, WORK(1) returns an estimate of the optimal value for LWORK\&. .fi .PP .br \fILWORK\fP .PP .nf 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 ZHSEQR does a workspace query\&. In this case, ZHSEQR 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\&. .fi .PP .br \fIINFO\fP .PP .nf INFO is INTEGER = 0: successful exit < 0: if INFO = -i, the i-th argument had an illegal value > 0: if INFO = i, ZHSEQR failed to compute all of the eigenvalues\&. Elements 1:ilo-1 and i+1:n of W 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 a unitary matrix\&. The final value of H is upper Hessenberg and 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 unitary 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 unitary matrix in (*) (regard- less of the value of JOB\&.) If INFO > 0 and COMPZ = 'N', then Z is not accessed\&. .fi .PP .RE .PP \fBAuthor\fP .RS 4 Univ\&. of Tennessee .PP Univ\&. of California Berkeley .PP Univ\&. of Colorado Denver .PP NAG Ltd\&. .RE .PP \fBContributors:\fP .RS 4 Karen Braman and Ralph Byers, Department of Mathematics, University of Kansas, USA .RE .PP \fBFurther Details:\fP .RS 4 .PP .nf Default values supplied by ILAENV(ISPEC,'ZHSEQR',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 ZLAHQR vs ZLAQR0 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 ZLAHQR 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\&. .fi .PP .RE .PP \fBReferences:\fP .RS 4 .PP .nf 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\&. .fi .PP .br 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\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for LAPACK from the source code\&.