?hgeqz

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 3/22/2024

Version

Public

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

Visible to Intel only — GUID: GUID-93E22168-39EF-498E-A92E-7B231A23B2CF

View Details

?hgeqz

Implements the QZ method for finding the generalized eigenvalues of the matrix pair (H,T).

Syntax

lapack_int LAPACKE_shgeqz( int matrix_layout, char job, char compq, char compz, lapack_int n, lapack_int ilo, lapack_int ihi, float* h, lapack_int ldh, float* t, lapack_int ldt, float* alphar, float* alphai, float* beta, float* q, lapack_int ldq, float* z, lapack_int ldz );

lapack_int LAPACKE_dhgeqz( int matrix_layout, char job, char compq, char compz, lapack_int n, lapack_int ilo, lapack_int ihi, double* h, lapack_int ldh, double* t, lapack_int ldt, double* alphar, double* alphai, double* beta, double* q, lapack_int ldq, double* z, lapack_int ldz );

lapack_int LAPACKE_chgeqz( int matrix_layout, char job, char compq, char compz, lapack_int n, lapack_int ilo, lapack_int ihi, lapack_complex_float* h, lapack_int ldh, lapack_complex_float* t, lapack_int ldt, lapack_complex_float* alpha, lapack_complex_float* beta, lapack_complex_float* q, lapack_int ldq, lapack_complex_float* z, lapack_int ldz );

lapack_int LAPACKE_zhgeqz( int matrix_layout, char job, char compq, char compz, lapack_int n, lapack_int ilo, lapack_int ihi, lapack_complex_double* h, lapack_int ldh, lapack_complex_double* t, lapack_int ldt, lapack_complex_double* alpha, lapack_complex_double* beta, lapack_complex_double* q, lapack_int ldq, lapack_complex_double* z, lapack_int ldz );

Include Files

mkl.h

Description

The routine computes the eigenvalues of a real/complex matrix pair (H,T), where H is an upper Hessenberg matrix and T is upper triangular, using the double-shift version (for real flavors) or single-shift version (for complex flavors) of the QZ method. Matrix pairs of this type are produced by the reduction to generalized upper Hessenberg form of a real/complex matrix pair (A,B):

A = Q₁*H*Z₁^H, B = Q₁*T*Z₁^H,

as computed by ?gghrd.

For real flavors:

If job = 'S', then the Hessenberg-triangular pair (H,T) is reduced to generalized Schur form,

H = Q*S*Z^T, T = Q*P*Z^T,

where Q and Z are orthogonal matrices, P is an upper triangular matrix, and S is a quasi-triangular matrix with 1-by-1 and 2-by-2 diagonal blocks. The 1-by-1 blocks correspond to real eigenvalues of the matrix pair (H,T) and the 2-by-2 blocks correspond to complex conjugate pairs of eigenvalues.

Additionally, the 2-by-2 upper triangular diagonal blocks of P corresponding to 2-by-2 blocks of S are reduced to positive diagonal form, that is, if S_{j + 1, j} is non-zero, then P_{j + 1, j} = P_{j, j + 1} = 0, P_{j, j} > 0, and P_{j + 1, j + 1} > 0.

For complex flavors:

If job = 'S', then the Hessenberg-triangular pair (H,T) is reduced to generalized Schur form,

H = Q* S*Z^H, T = Q*P*Z^H,

where Q and Z are unitary matrices, and S and P are upper triangular.

For all function flavors:

Optionally, the orthogonal/unitary matrix Q from the generalized Schur factorization may be post-multiplied by an input matrix Q₁, and the orthogonal/unitary matrix Z may be post-multiplied by an input matrix Z₁.

If Q₁ and Z₁ are the orthogonal/unitary matrices from ?gghrd that reduced the matrix pair (A,B) to generalized upper Hessenberg form, then the output matrices Q₁Q and Z₁Z are the orthogonal/unitary factors from the generalized Schur factorization of (A,B):

A = (Q₁Q)*S *(Z₁Z)^H, B = (Q₁Q)*P*(Z₁Z)^H.

To avoid overflow, eigenvalues of the matrix pair (H,T) (equivalently, of (A,B)) are computed as a pair of values (alpha,beta). For chgeqz/zhgeqz, alpha and beta are complex, and for shgeqz/dhgeqz, alpha is complex and beta real. If beta is nonzero, λ = alpha/beta is an eigenvalue of the generalized nonsymmetric eigenvalue problem (GNEP)

A*x = λ*B*x

and if alpha is nonzero, μ = beta/alpha is an eigenvalue of the alternate form of the GNEP

μ*A*y = B*y .

Real eigenvalues (for real flavors) or the values of alpha and beta for the i-th eigenvalue (for complex flavors) can be read directly from the generalized Schur form:

alpha = S_{i, i}, beta = P_{i, i}.

Input Parameters

matrix_layout

Specifies whether matrix storage layout is row major (LAPACK_ROW_MAJOR) or column major (LAPACK_COL_MAJOR).

job

Specifies the operations to be performed. Must be 'E' or 'S'.

If job = 'E', then compute eigenvalues only;

If job = 'S', then compute eigenvalues and the Schur form.

compq

Must be 'N', 'I', or 'V'.

If compq = 'N', left Schur vectors (q) are not computed;

If compq = 'I', q is initialized to the unit matrix and the matrix of left Schur vectors of (H,T) is returned;

If compq = 'V', q must contain an orthogonal/unitary matrix Q₁ on entry and the product Q₁*Q is returned.

compz

Must be 'N', 'I', or 'V'.

If compz = 'N', right Schur vectors (z) are not computed;

If compz = 'I', z is initialized to the unit matrix and the matrix of right Schur vectors of (H,T) is returned;

If compz = 'V', z must contain an orthogonal/unitary matrix Z₁ on entry and the product Z₁*Z is returned.

n

The order of the matrices H, T, Q, and Z

(n≥ 0).

ilo, ihi

ilo and ihi mark the rows and columns of H which are in Hessenberg form. It is assumed that H is already upper triangular in rows and columns 1:ilo-1 and ihi+1:n.

Constraint:

If n > 0, then 1 ≤ilo≤ihi≤n;

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

h, t, q, z

Arrays:

On entry, h (size max(1, ldh*n)) contains the n-by-n upper Hessenberg matrix H.

On entry, t (size max(1, ldt*n)) contains the n-by-n upper triangular matrix T.

q (size max(1, ldq*n)) :

On entry, if compq = 'V', this array contains the orthogonal/unitary matrix Q₁ used in the reduction of (A,B) to generalized Hessenberg form.

If compq = 'N', then q is not referenced.

z (size max(1, ldz*n)) :

On entry, if compz = 'V', this array contains the orthogonal/unitary matrix Z₁ used in the reduction of (A,B) to generalized Hessenberg form.

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

ldh

The leading dimension of h; at least max(1, n).

ldt

The leading dimension of t; at least max(1, n).

ldq

The leading dimension of q;

If compq = 'N', then ldq≥ 1.

If compq = 'I'or 'V', then ldq≥ max(1, n).

ldz

The leading dimension of z;

If compq = 'N', then ldz≥ 1.

If compq = 'I'or 'V', then ldz≥ max(1, n).

Output Parameters

h

For real flavors:

If job = 'S', then on exit h contains the upper quasi-triangular matrix S from the generalized Schur factorization.

If job = 'E', then on exit the diagonal blocks of h match those of S, but the rest of h is unspecified.

For complex flavors:

If job = 'S', then, on exit, h contains the upper triangular matrix S from the generalized Schur factorization.

If job = 'E', then on exit the diagonal of h matches that of S, but the rest of h is unspecified.

t

If job = 'S', then, on exit, t contains the upper triangular matrix P from the generalized Schur factorization.

For real flavors:

2-by-2 diagonal blocks of P corresponding to 2-by-2 blocks of S are reduced to positive diagonal form, that is, if h(j+1,j) is non-zero, then t(j+1,j)=t(j,j+1)=0 and t(j,j) and t(j+1,j+1) will be positive.

If job = 'E', then on exit the diagonal blocks of t match those of P, but the rest of t is unspecified.

For complex flavors:

if job = 'E', then on exit the diagonal of t matches that of P, but the rest of t is unspecified.

alphar, alphai

Arrays, size at least max(1, n). The real and imaginary parts, respectively, of each scalar alpha defining an eigenvalue of GNEP.

If alphai[j - 1] is zero, then the j-th eigenvalue is real; if positive, then the j-th and (j+1)-th eigenvalues are a complex conjugate pair, with

alphai[j] = -alphai[j - 1].

alpha

Array, size at least max(1, n).

The complex scalars alpha that define the eigenvalues of GNEP. alphai[i - 1] = S_{i, i} in the generalized Schur factorization.

beta

Array, size at least max(1, n).

For real flavors:

The scalars beta that define the eigenvalues of GNEP.

Together, the quantities alpha = (alphar[j - 1], alphai[j - 1]) and beta = beta[j - 1] represent the j-th eigenvalue of the matrix pair (A,B), in one of the forms lambda = alpha/beta or mu = beta/alpha. Since either lambda or mu may overflow, they should not, in general, be computed.

For complex flavors:

The real non-negative scalars beta that define the eigenvalues of GNEP.

beta[i - 1] = P_{i, i} in the generalized Schur factorization. Together, the quantities alpha = alpha[j - 1] and beta = beta[j - 1] represent the j-th eigenvalue of the matrix pair (A,B), in one of the forms lambda = alpha/beta or mu = beta/alpha. Since either lambda or mu may overflow, they should not, in general, be computed.

q

On exit, if compq = 'I', q is overwritten by the orthogonal/unitary matrix of left Schur vectors of the pair (H,T), and if compq = 'V', q is overwritten by the orthogonal/unitary matrix of left Schur vectors of (A,B).

z

On exit, if compz = 'I', z is overwritten by the orthogonal/unitary matrix of right Schur vectors of the pair (H,T), and if compz = 'V', z is overwritten by the orthogonal/unitary matrix of right Schur vectors of (A,B).

Return Values

This function returns a value info.

If info=0, the execution is successful.

If info = -i, the i-th parameter had an illegal value.

If info = 1,..., n, the QZ iteration did not converge.

(H,T) is not in Schur form, but alphar[i - 1], alphai[i - 1] (for real flavors), alpha[i - 1] (for complex flavors), and beta[i - 1], i=info+1,..., n should be correct.

If info = n+1,...,2n, the shift calculation failed.

(H,T) is not in Schur form, but alphar[i - 1], alphai[i - 1] (for real flavors), alpha[i - 1] (for complex flavors), and beta[i - 1], i =info-n+1,..., n should be correct.

Parent topic: Generalized Nonsymmetric Eigenvalue Problems: LAPACK Computational Routines

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

?hgeqz

Syntax

Include Files

Description

Input Parameters

Output Parameters

Return Values