1STGEXC(1) LAPACK routine (version 3.1) STGEXC(1)
2
6 STGEXC - the generalized real Schur decomposition of a real matrix pair
7 (A,B) using an orthogonal equivalence transformation (A, B) = Q * (A,
8 B) * Z',
9
11 SUBROUTINE STGEXC( WANTQ, WANTZ, N, A, LDA, B, LDB, Q, LDQ, Z, LDZ,
12 IFST, ILST, WORK, LWORK, INFO )
13 LOGICAL WANTQ, WANTZ
15 INTEGER IFST, ILST, INFO, LDA, LDB, LDQ, LDZ, LWORK, N
17 REAL A( LDA, * ), B( LDB, * ), Q( LDQ, * ), WORK( * ), Z(
19 LDZ, * )
20
22 STGEXC reorders the generalized real Schur decomposition of a real
23 matrix pair (A,B) using an orthogonal equivalence transformation
24 so that the diagonal block of (A, B) with row index IFST is moved to
26 row ILST.
27 (A, B) must be in generalized real Schur canonical form (as returned by
29 SGGES), i.e. A is block upper triangular with 1-by-1 and 2-by-2 diago‐
30 nal blocks. B is upper triangular.
31 Optionally, the matrices Q and Z of generalized Schur vectors are
33 updated.
34 Q(in) * A(in) * Z(in)' = Q(out) * A(out) * Z(out)'
36 Q(in) * B(in) * Z(in)' = Q(out) * B(out) * Z(out)'
37
41 WANTQ (input) LOGICAL
42 WANTZ (input) LOGICAL
44 N (input) INTEGER
46 The order of the matrices A and B. N >= 0.
47 A (input/output) REAL array, dimension (LDA,N)
49 On entry, the matrix A in generalized real Schur canonical
50 form. On exit, the updated matrix A, again in generalized real
51 Schur canonical form.
52 LDA (input) INTEGER
54 The leading dimension of the array A. LDA >= max(1,N).
55 B (input/output) REAL array, dimension (LDB,N)
57 On entry, the matrix B in generalized real Schur canonical form
58 (A,B). On exit, the updated matrix B, again in generalized
59 real Schur canonical form (A,B).
60 LDB (input) INTEGER
62 The leading dimension of the array B. LDB >= max(1,N).
63 Q (input/output) REAL array, dimension (LDZ,N)
65 On entry, if WANTQ = .TRUE., the orthogonal matrix Q. On exit,
66 the updated matrix Q. If WANTQ = .FALSE., Q is not referenced.
67 LDQ (input) INTEGER
69 The leading dimension of the array Q. LDQ >= 1. If WANTQ =
70 .TRUE., LDQ >= N.
71 Z (input/output) REAL array, dimension (LDZ,N)
73 On entry, if WANTZ = .TRUE., the orthogonal matrix Z. On exit,
74 the updated matrix Z. If WANTZ = .FALSE., Z is not referenced.
75 LDZ (input) INTEGER
77 The leading dimension of the array Z. LDZ >= 1. If WANTZ =
78 .TRUE., LDZ >= N.
79 IFST (input/output) INTEGER
81 ILST (input/output) INTEGER Specify the reordering of the
82 diagonal blocks of (A, B). The block with row index IFST is
83 moved to row ILST, by a sequence of swapping between adjacent
84 blocks. On exit, if IFST pointed on entry to the second row of
85 a 2-by-2 block, it is changed to point to the first row; ILST
86 always points to the first row of the block in its final posi‐
87 tion (which may differ from its input value by +1 or -1). 1 <=
88 IFST, ILST <= N.
89 WORK (workspace/output) REAL array, dimension (MAX(1,LWORK))
91 On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
92 LWORK (input) INTEGER
94 The dimension of the array WORK. LWORK >= 1 when N <= 1, oth‐
95 erwise LWORK >= 4*N + 16.
96 If LWORK = -1, then a workspace query is assumed; the routine
98 only calculates the optimal size of the WORK array, returns
99 this value as the first entry of the WORK array, and no error
100 message related to LWORK is issued by XERBLA.
101 INFO (output) INTEGER
103 =0: successful exit.
104 <0: if INFO = -i, the i-th argument had an illegal value.
105 =1: The transformed matrix pair (A, B) would be too far from
106 generalized Schur form; the problem is ill- conditioned. (A, B)
107 may have been partially reordered, and ILST points to the first
108 row of the current position of the block being moved.
109
111 Based on contributions by
112 Bo Kagstrom and Peter Poromaa, Department of Computing Science,
113 Umea University, S-901 87 Umea, Sweden.
114 [1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the
116 Generalized Real Schur Form of a Regular Matrix Pair (A, B), in
117 M.S. Moonen et al (eds), Linear Algebra for Large Scale and
118 Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
119 LAPACK routine (version 3.1) November 2006 STGEXC(1)