Developer Reference

  • 0.9
  • 09/09/2020
  • Public Content
Contents

?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
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
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
1
For 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