Developer Reference for Intel® oneAPI Math Kernel Library for Fortran

ID 766686
Date 6/24/2024
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

p?hseqr

Computes eigenvalues and (optionally) the Schur factorization of a matrix reduced to Hessenberg form.

Syntax

call pshseqr( job, compz, n, ilo, ihi, h, desch, wr, wi, z, descz, work, lwork, iwork, liwork, info )

call pdhseqr( job, compz, n, ilo, ihi, h, desch, wr, wi, z, descz, work, lwork, iwork, liwork, info )

Include Files

Description

p?hseqr computes the eigenvalues of an upper Hessenberg matrix H and, optionally, the matrices T and Z from the Schur decomposition H = Z*T*ZT, 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*QT = (QZ)*T*(QZ)T.

NOTE:

These restrictions apply to the use of p?hseqr:

  • The code requires the distributed block size to be square and at least 6.

  • The code requires A and Z to be distributed identically and have identical contexts.

  • The matrix A must be in upper Hessenberg form. If elements below the subdiagonal are non-zero, the resulting transformations can be nonsimilar.

  • All eigenvalues are distributed to all the nodes.

Input Parameters

job

(global) CHARACTER*1

= 'E': compute eigenvalues only;

= 'S': compute eigenvalues and the Schur form T.

compz

(global) 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.

n

(global ) INTEGER

The order of the Hessenberg matrix H. n 0.

ilo, ihi

(global ) 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 p gebal, and then passed to p?gehrd when the matrix output by p?gebal is reduced to Hessenberg form. Otherwise ilo and ihi should be set to 1 and n respectively. If n>0, then 1iloihin.

If n = 0, then ilo = 1 and ihi = 0.

h

REAL for pshseqr

DOUBLE PRECISION for pdhseqr

(global ) array of size (desch(lld_),LOCc(n))

The upper Hessenberg matrix H.

desch

(global and local) INTEGER array of size dlen_

The array descriptor for the distributed matrix H.

z

REAL for pshseqr

DOUBLE PRECISION for pdhseqr

(global ) array

If compz = 'V', on entry z must contain the current matrix Z of accumulated transformations from, for example, p?gehrd.

If compz = 'I', on entry z need not be set.

descz

(global and local) INTEGER array of size dlen_

The array descriptor for the distributed matrix z.

work

REAL for pshseqr

DOUBLE PRECISION for pdhseqr

(local workspace) array of size lwork.

lwork

(local ) INTEGER

The length of the workspace array work.

If lwork = -1, then work(1) gets set to the above number and the code returns immediately.

iwork

(local workspace) INTEGER array of size liwork

liwork

(local ) INTEGER

The length of the workspace array iwork.

If liwork=-1, then iwork(1) is set to -1 and the code returns immediately.

OUTPUT Parameters

h

If job = 'S', H is upper quasi-triangular in rows and columns ilo:ihi, with 1-by-1 and 2-by-2 blocks on the main diagonal. The 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.

wr, wi

REAL for pshseqr

DOUBLE PRECISION for pdhseqr

(global ) array of size n

The real and imaginary parts, respectively, of the computed eigenvalues ilo to ihi are stored in the corresponding elements of wr and wi. 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.

z

REAL for pshseqr

DOUBLE PRECISION for pdhseqr

(global ) array

z is updated; transformations are applied only to the submatrix z(ilo:ihi,ilo:ihi).

If compz = 'N', z is not referenced.

If compz = 'I' and info = 0, z contains the orthogonal matrix Z of the Schur vectors of H.

info

INTEGER

= 0: successful exit

< 0: if info = -i, the i-th argument had an illegal value (see also below for -7777 and -8888).

> 0: if info = i, p?hseqr 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 eigenvalues 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 (*) (regardless 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 (*) (regardless of the value of job.)

If info > 0 and compz = 'N', then z is not accessed.

= -7777: p laqr0 failed to converge and p laqr1 was called instead.

= -8888: p?laqr1 failed to converge and p?laqr0 was called instead.

See Also