?tgsen

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 3/31/2023

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-12D542CF-2A34-40B4-A2AF-89375F0C5DB8

View Details

?tgsen

Reorders the generalized Schur decomposition of a pair of matrices (A,B) so that a selected cluster of eigenvalues appears in the leading diagonal blocks of (A,B).

Syntax

lapack_int LAPACKE_stgsen( int matrix_layout, lapack_int ijob, lapack_logical wantq, lapack_logical wantz, const lapack_logical* select, lapack_int n, float* a, lapack_int lda, float* b, lapack_int ldb, float* alphar, float* alphai, float* beta, float* q, lapack_int ldq, float* z, lapack_int ldz, lapack_int* m, float* pl, float* pr, float* dif );

lapack_int LAPACKE_dtgsen( int matrix_layout, lapack_int ijob, lapack_logical wantq, lapack_logical wantz, const lapack_logical* select, lapack_int n, double* a, lapack_int lda, double* b, lapack_int ldb, double* alphar, double* alphai, double* beta, double* q, lapack_int ldq, double* z, lapack_int ldz, lapack_int* m, double* pl, double* pr, double* dif );

lapack_int LAPACKE_ctgsen( int matrix_layout, lapack_int ijob, lapack_logical wantq, lapack_logical wantz, const lapack_logical* select, lapack_int n, lapack_complex_float* a, lapack_int lda, lapack_complex_float* b, lapack_int ldb, lapack_complex_float* alpha, lapack_complex_float* beta, lapack_complex_float* q, lapack_int ldq, lapack_complex_float* z, lapack_int ldz, lapack_int* m, float* pl, float* pr, float* dif );

lapack_int LAPACKE_ztgsen( int matrix_layout, lapack_int ijob, lapack_logical wantq, lapack_logical wantz, const lapack_logical* select, lapack_int n, lapack_complex_double* a, lapack_int lda, lapack_complex_double* b, lapack_int ldb, lapack_complex_double* alpha, lapack_complex_double* beta, lapack_complex_double* q, lapack_int ldq, lapack_complex_double* z, lapack_int ldz, lapack_int* m, double* pl, double* pr, double* dif );

Include Files

mkl.h

Description

The routine reorders the generalized real-Schur/Schur decomposition of a real/complex matrix pair (A, B) (in terms of an orthogonal/unitary equivalence transformation Q^T*(A,B)*Z for real flavors or Q^H*(A,B)*Z for complex flavors), so that a selected cluster of eigenvalues appears in the leading diagonal blocks of the pair (A, B). The leading columns of Q and Z form orthonormal/unitary bases of the corresponding left and right eigenspaces (deflating subspaces).

(A, B) must be in generalized real-Schur/Schur canonical form (as returned by gges), that is, A and B are both upper triangular.

?tgsen also computes the generalized eigenvalues

ω_j = (alphar(j) + alphai(j)*i)/beta(j) (for real flavors)

ω_j = alpha(j)/beta(j) (for complex flavors)

of the reordered matrix pair (A, B).

Optionally, the routine computes the estimates of reciprocal condition numbers for eigenvalues and eigenspaces. These are Difu[(A₁₁, B₁₁), (A₂₂, B₂₂)] and Difl[(A₁₁, B₁₁), (A₂₂, B₂₂)], that is, the separation(s) between the matrix pairs (A₁₁, B₁₁) and (A₂₂, B₂₂) that correspond to the selected cluster and the eigenvalues outside the cluster, respectively, and norms of "projections" onto left and right eigenspaces with respect to the selected cluster in the (1,1)-block.

Input Parameters

matrix_layout

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

ijob

Specifies whether condition numbers are required for the cluster of eigenvalues (pl and pr) or the deflating subspaces Difu and Difl.

If ijob =0, only reorder with respect to select;

If ijob =1, reciprocal of norms of "projections" onto left and right eigenspaces with respect to the selected cluster (pl and pr);

If ijob =2, compute upper bounds on Difu and Difl, using F-norm-based estimate (dif (1:2));

If ijob =3, compute estimate of Difu and Difl, using 1-norm-based estimate (dif (1:2)). This option is about 5 times as expensive as ijob =2;

If ijob =4,>compute pl, pr and dif (i.e., options 0, 1 and 2 above). This is an economic version to get it all;

If ijob =5, compute pl, pr and dif (i.e., options 0, 1 and 3 above).

wantq, wantz

If wantq = 1, update the left transformation matrix Q;

If wantq = 0, do not update Q;

If wantz = 1, update the right transformation matrix Z;

If wantz = 0, do not update Z.

select

Array, size at least max (1, n). Specifies the eigenvalues in the selected cluster.

To select an eigenvalue ω_j, select[j - 1] must be 1For real flavors: to select a complex conjugate pair of eigenvalues ω_j and ω_{j + 1} (corresponding 2 by 2 diagonal block), select[j - 1] and/or select[j] must be set to 1; the complex conjugate ω_j and ω_{j + 1} must be either both included in the cluster or both excluded.

n

The order of the matrices A and B (n≥ 0).

a, b, q, z

Arrays:

a (size max(1, lda*n)) contains the matrix A.

For real flavors: A is upper quasi-triangular, with (A, B) in generalized real Schur canonical form.

For complex flavors: A is upper triangular, in generalized Schur canonical form.

b (size max(1, ldb*n)) contains the matrix B.

For real flavors: B is upper triangular, with (A, B) in generalized real Schur canonical form.

For complex flavors: B is upper triangular, in generalized Schur canonical form.

q (size at least 1 if wantq = 0 and at least max(1, ldq*n) if wantq = 1)

If wantq = 1, then q is an n-by-n matrix;

If wantq = 0, then q is not referenced.

z (size at least 1 if wantz = 0 and at least max(1, ldz*n) if wantz = 1)

If wantz = 1, then z is an n-by-n matrix;

If wantz = 0, then z is not referenced.

lda

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

ldb

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

ldq

The leading dimension of q; ldq≥ 1.

If wantq = 1, then ldq≥ max(1, n).

ldz

The leading dimension of z; ldz≥ 1.

If wantz = 1, then ldz≥ max(1, n).

Output Parameters

a, b

Overwritten by the reordered matrices A and B, respectively.

alphar, alphai

Arrays, size at least max(1, n). Contain values that form generalized eigenvalues in real flavors.

See beta.

alpha

Array, size at least max(1, n). Contain values that form generalized eigenvalues in complex flavors.

See beta.

beta

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

For real flavors:

On exit, (alphar[j] + alphai[j]*i)/beta[j], j=0,..., n - 1, will be the generalized eigenvalues.

alphar[j] + alphai[j]*i and beta[j], j=0,..., n - 1 are the diagonals of the complex Schur form (S,T) that would result if the 2-by-2 diagonal blocks of the real generalized Schur form of (A,B) were further reduced to triangular form using complex unitary transformations.

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

For complex flavors:

The diagonal elements of A and B, respectively, when the pair (A,B) has been reduced to generalized Schur form. alpha[i]/beta[i],i=0,..., n - 1 are the generalized eigenvalues.

q

If wantq = 1, then, on exit, Q has been postmultiplied by the left orthogonal transformation matrix which reorder (A, B). The leading m columns of Q form orthonormal bases for the specified pair of left eigenspaces (deflating subspaces).

z

If wantz = 1, then, on exit, Z has been postmultiplied by the left orthogonal transformation matrix which reorder (A, B). The leading m columns of Z form orthonormal bases for the specified pair of left eigenspaces (deflating subspaces).

m

The dimension of the specified pair of left and right eigen-spaces (deflating subspaces); 0 ≤m≤n.

pl, pr

If ijob = 1, 4, or 5, pl and pr are lower bounds on the reciprocal of the norm of "projections" onto left and right eigenspaces with respect to the selected cluster.

0 < pl, pr≤ 1. If m = 0 or m = n, pl = pr = 1.

If ijob = 0, 2 or 3, pl and pr are not referenced

dif

Array, size (2).

If ijob≥ 2, dif(1:2) store the estimates of Difu and Difl.

If ijob = 2 or 4, dif(1:2) are F-norm-based upper bounds on Difu and Difl.

If ijob = 3 or 5, dif(1:2) are 1-norm-based estimates of Difu and Difl.

If m = 0 or m = n, dif(1:2) = F-norm([A, B]).

If ijob = 0 or 1, dif is not referenced.

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, Reordering of (A, B) failed because the transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is very ill-conditioned. (A, B) may have been partially reordered.

If ijob > 0, 0 is returned in dif, pl and pr.

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

?tgsen