?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
FORTRAN 77:

call stgsen(ijob, wantq, wantz, select, n, a, lda, b, ldb, alphar, alphai, beta, q, ldq, z, ldz, m, pl, pr, dif, work, lwork, iwork, liwork, info)
call dtgsen(ijob, wantq, wantz, select, n, a, lda, b, ldb, alphar, alphai, beta, q, ldq, z, ldz, m, pl, pr, dif, work, lwork, iwork, liwork, info)
call ctgsen(ijob, wantq, wantz, select, n, a, lda, b, ldb, alpha, beta, q, ldq, z, ldz, m, pl, pr, dif, work, lwork, iwork, liwork, info)
call ztgsen(ijob, wantq, wantz, select, n, a, lda, b, ldb, alpha, beta, q, ldq, z, ldz, m, pl, pr, dif, work, lwork, iwork, liwork, info)
Fortran 95:

call tgsen(a, b, select [,alphar] [,alphai] [,beta] [,ijob] [,q] [,z] [,pl] [,pr] [,dif] [,m] [,info])
call tgsen(a, b, select [,alpha] [,beta] [,ijob] [,q] [,z] [,pl] [,pr] [, dif] [,m] [,info])
C:

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 );
Description
The routine reorders the generalized realSchur/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 realSchur/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_{11}, B_{11}), (A_{22}, B_{22})]
and Difl[(A_{11}, B_{11}), (A_{22}, B_{22})]
, that is, the separation(s) between the matrix pairs (A_{11}, B_{11}) and (A_{22}, B_{22}) 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
The data types are given for the Fortran interface. A <datatype> placeholder, if present, is used for the C interface data types in the C interface section above. See C Interface Conventions for the C interface principal conventions and type definitions.
 ijob

INTEGER. Specifies whether condition numbers are required for the cluster of eigenvalues (pl and pr) or the deflating subspaces
Difu
andDifl
.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 onDifu
andDifl
, using Fnormbased estimate (dif (1:2));If
ijob =3
, compute estimate ofDifu
andDifl
, sing 1normbased estimate (dif (1:2)). This option is about 5 times as expensive asijob =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

LOGICAL.
If
wantq = .TRUE.
, update the left transformation matrix Q;If
wantq = .FALSE.
, do not update Q;If
wantz = .TRUE.
, update the right transformation matrix Z;If
wantz = .FALSE.
, do not update Z.  select

LOGICAL.
Array, DIMENSION at least max (1, n). Specifies the eigenvalues in the selected cluster.
To select an eigenvalue omega(j), select(j) must be .TRUE. For real flavors: to select a complex conjugate pair of eigenvalues omega(j) and omega(j+1) (corresponding 2 by 2 diagonal block), select(j) and/or select(j+1) must be set to .TRUE.; the complex conjugate omega(j) and omega(j+1) must be either both included in the cluster or both excluded.
 n

INTEGER. The order of the matrices A and B (n ≥ 0).
 a, b, q, z, work

REAL for stgsen
DOUBLE PRECISION for dtgsen
COMPLEX for ctgsen
DOUBLE COMPLEX for ztgsen.
Arrays:
a(lda,*) contains the matrix A.
For real flavors: A is upper quasitriangular, with (A, B) in generalized real Schur canonical form.
For complex flavors: A is upper triangular, in generalized Schur canonical form.
The second dimension of a must be at least max(1, n).
b(ldb,*) 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. The second dimension of b must be at least max(1, n).
q (ldq,*)
If
wantq = .TRUE.
, then q is an nbyn matrix;If
wantq = .FALSE.
, then q is not referenced.The second dimension of q must be at least max(1, n).
z (ldz,*)
If
wantz = .TRUE.
, then z is an nbyn matrix;If
wantz = .FALSE.
, then z is not referenced.The second dimension of z must be at least max(1, n).
work is a workspace array, its dimensionmax(1, lwork)
.  lda

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

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

INTEGER. The leading dimension of q; ldq ≥ 1.
If
wantq = .TRUE.
, then ldq ≥ max(1, n).  ldz

INTEGER. The leading dimension of z; ldz ≥ 1.
If
wantz = .TRUE.
, then ldz ≥ max(1, n).  lwork

INTEGER. The dimension of the array work.
For real flavors:
If
ijob =
1, 2, or 4,lwork ≥ max(4n+16, 2m(nm))
.If
ijob =
3 or 5,lwork ≥ max(4n+16, 4m(nm))
.For complex flavors:
If
ijob =
1, 2, or 4,lwork ≥ max(1, 2m(nm))
.If
ijob =
3 or 5,lwork ≥ max(1, 4m(nm))
.If
lwork = 1
, then a workspace query is assumed; the routine only calculates the optimal size of the work array, returns this value as the first entry of the work array, and no error message related to lwork is issued by xerbla. See Application Notes for details.  iwork

INTEGER. Workspace array, its dimension
max(1, liwork)
.  liwork

INTEGER. The dimension of the array iwork.
For real flavors:
If
ijob =
1, 2, or 4,liwork ≥ n+6
.If
ijob =
3 or 5,liwork ≥ max(n+6, 2m(nm))
.For complex flavors:
If
ijob =
1, 2, or 4,liwork ≥ n+2
.If
ijob =
3 or 5,liwork ≥ max(n+2, 2m(nm))
.If
liwork = 1
, then a workspace query is assumed; the routine only calculates the optimal size of the iwork array, returns this value as the first entry of the iwork array, and no error message related to liwork is issued by xerbla. See Application Notes for details.
Output Parameters
 a, b

Overwritten by the reordered matrices A and B, respectively.
 alphar, alphai

REAL for stgsen;
DOUBLE PRECISION for dtgsen.
Arrays, DIMENSION at least max(1, n). Contain values that form generalized eigenvalues in real flavors.
See beta.
 alpha

COMPLEX for ctgsen;
DOUBLE COMPLEX for ztgsen.
Array, DIMENSION at least max(1, n). Contain values that form generalized eigenvalues in complex flavors.
See beta.
 beta

REAL for stgsen
DOUBLE PRECISION for dtgsen
COMPLEX for ctgsen
DOUBLE COMPLEX for ztgsen.
Array, DIMENSION at least max(1, n).
For real flavors:
On exit,
(alphar(j) + alphai(j)*i)/beta(j)
, j=1,..., n, will be the generalized eigenvalues.alphar(j) + alphai(j)*i
andbeta(j)
, j=1,..., n are the diagonals of the complex Schur form (S,T) that would result if the 2by2 diagonal blocks of the real generalized Schur form of (A,B) were further reduced to triangular form using complex unitary transformations.If
alphai(j)
is zero, then the jth eigenvalue is real; if positive, then the jth and (j+1)st eigenvalues are a complex conjugate pair, withalphai(j+1)
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=1,..., n are the generalized eigenvalues.  q

If wantq =.TRUE., 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 =.TRUE., 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

INTEGER.
The dimension of the specified pair of left and right eigenspaces (deflating subspaces);
0 ≤ m ≤ n
.  pl, pr

REAL for single precision flavors;
DOUBLE PRECISION for double precision flavors.
If
ijob = 1, 4
, or5
, 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
. Ifm = 0
orm = n
,pl =
.pr = 1
If
ijob = 0
,2
or3
, pl and pr are not referenced  dif

REAL for single precision flavors;DOUBLE PRECISION for double precision flavors.
Array, DIMENSION (2).
If
ijob ≥ 2
, dif(1:2) store the estimates ofDifu
andDifl
.If
ijob = 2
or 4, dif(1:2) are Fnormbased upper bounds onDifu
andDifl
.If
ijob = 3
or 5, dif(1:2) are 1normbased estimates ofDifu
andDifl
.If
m = 0
or n,dif(1:2) = Fnorm([A, B])
.If
ijob = 0
or 1, dif is not referenced.  work
(1)

If ijob is not 0 and
info = 0
, on exit,work(1)
contains the minimum value of lwork required for optimum performance. Use this lwork for subsequent runs.  iwork
(1)

If ijob is not 0 and
info = 0
, on exit,iwork(1)
contains the minimum value of liwork required for optimum performance. Use this liwork for subsequent runs.  info

INTEGER.
If
info = 0
, the execution is successful.If
info = i
, the ith 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 illconditioned. (A, B) may have been partially reordered.If requested, 0 is returned in dif(*), pl and pr.
Fortran 95 Interface Notes
Routines in Fortran 95 interface have fewer arguments in the calling sequence than their FORTRAN 77 counterparts. For general conventions applied to skip redundant or restorable arguments, see Fortran 95 Interface Conventions.
Specific details for the routine tgsen interface are the following:
 a

Holds the matrix A of size (n,n).
 b

Holds the matrix B of size (n,n).
 select

Holds the vector of length n.
 alphar

Holds the vector of length n. Used in real flavors only.
 alphai

Holds the vector of length n. Used in real flavors only.
 alpha

Holds the vector of length n. Used in complex flavors only.
 beta

Holds the vector of length n.
 q

Holds the matrix Q of size (n,n).
 z

Holds the matrix Z of size (n,n).
 dif

Holds the vector of length (2).
 ijob

Must be 0, 1, 2, 3, 4, or 5. The default value is 0.
 wantq

Restored based on the presence of the argument q as follows:
wantq = .TRUE, if q is present,
wantq = .FALSE, if q is omitted.
 wantz

Restored based on the presence of the argument z as follows:
wantz = .TRUE, if z is present,
wantz = .FALSE, if z is omitted.
Application Notes
If it is not clear how much workspace to supply, use a generous value of lwork (or liwork) for the first run or set lwork = 1
(liwork = 1
).
If lwork (or liwork) has any of admissible sizes, which is no less than the minimal value described, the routine completes the task, though probably not so fast as with a recommended workspace, and provides the recommended workspace in the first element of the corresponding array (work, iwork) on exit. Use this value (work(1)
, iwork(1)
) for subsequent runs.
If lwork = 1
(liwork = 1
), the routine returns immediately and provides the recommended workspace in the first element of the corresponding array (work, iwork). This operation is called a workspace query.
Note that if lwork (liwork) is less than the minimal required value and is not equal to 1, the routine returns immediately with an error exit and does not provide any information on the recommended workspace.