tgexc(3)

📦

version 3.12.1 · 9 versions

3.12.1 · arch rolling (latest)
3.12.0 · opensuse-leap 16.0
3.12.1 · ubuntu stonking
3.12.1 · ubuntu questing
3.12.0 · ubuntu noble
3.12.0 · ubuntu noble
3.12.0 · centos-stream 10, fedora 43, fedora 44
3.12.1 · ubuntu resolute
3.12.1 · debian trixie

🎀 tgexc(3) — reorder generalized Schur form 🎀

okay bestie, we're in the Library Functions Manual and this page is lowkey iconic because it's all about reordering generalized Schur forms. Buckle up, it's giving linear algebra with main character energy. 💅

✨ NAME ✨

tgexc — tgexc: reorder generalized Schur form

🌸 SYNOPSIS 🌸

🧚 Functions 🧚

       subroutine ctgexc (wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz,
           ifst, ilst, info)
           CTGEXC
       subroutine dtgexc (wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz,
           ifst, ilst, work, lwork, info)
           DTGEXC
       subroutine stgexc (wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz,
           ifst, ilst, work, lwork, info)
           STGEXC
       subroutine ztgexc (wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz,
           ifst, ilst, info)
           ZTGEXC

💖 Detailed Description 💖

🦋 Function Documentation 🦋

💅 `subroutine ctgexc` 💅

   subroutine ctgexc (logical wantq, logical wantz, integer n, complex,
       dimension( lda, * ) a, integer lda, complex, dimension( ldb, * ) b,
       integer ldb, complex, dimension( ldq, * ) q, integer ldq, complex,
       dimension( ldz, * ) z, integer ldz, integer ifst, integer ilst, integer
       info)

CTGEXC

🫶 Purpose: 🫶

CTGEXC reorders the generalized Schur decomposition of a complex matrix pair (A,B), using a unitary equivalence transformation (A, B) := Q * (A, B) * Z**H, so that the diagonal block of (A, B) with row index IFST is moved to row ILST.

(A, B) must be in generalized Schur canonical form, that is, A and B are both upper triangular.

Optionally, the matrices Q and Z of generalized Schur vectors are updated.

        Q(in) * A(in) * Z(in)**H = Q(out) * A(out) * Z(out)**H
        Q(in) * B(in) * Z(in)**H = Q(out) * B(out) * Z(out)**H

🌟 Parameters 🌟

WANTQ — WANTQ is LOGICAL

.TRUE. : update the left transformation matrix Q;
.FALSE.: do not update Q.

WANTZ — WANTZ is LOGICAL

.TRUE. : update the right transformation matrix Z;
.FALSE.: do not update Z.

N — N is INTEGER

The order of the matrices A and B. N >= 0.

A — A is COMPLEX array, dimension (LDA,N)

On entry, the upper triangular matrix A in the pair (A, B). On exit, the updated matrix A.

LDA — LDA is INTEGER

The leading dimension of the array A. LDA >= max(1,N).

B — B is COMPLEX array, dimension (LDB,N)

On entry, the upper triangular matrix B in the pair (A, B). On exit, the updated matrix B.

LDB — LDB is INTEGER

The leading dimension of the array B. LDB >= max(1,N).

Q — Q is COMPLEX array, dimension (LDQ,N)

On entry, if WANTQ = .TRUE., the unitary matrix Q. On exit, the updated matrix Q. If WANTQ = .FALSE., Q is not referenced.

LDQ — LDQ is INTEGER

The leading dimension of the array Q. LDQ >= 1; If WANTQ = .TRUE., LDQ >= N.

Z — Z is COMPLEX array, dimension (LDZ,N)

On entry, if WANTZ = .TRUE., the unitary matrix Z. On exit, the updated matrix Z. If WANTZ = .FALSE., Z is not referenced.

LDZ — LDZ is INTEGER

The leading dimension of the array Z. LDZ >= 1; If WANTZ = .TRUE., LDZ >= N.

IFST — IFST is INTEGER

ILST — ILST is INTEGER

Specify the reordering of the diagonal blocks of (A, B). The block with row index IFST is moved to row ILST, by a sequence of swapping between adjacent blocks.

INFO — INFO is INTEGER

=0: Successful exit.
<0: if INFO = -i, the i-th argument had an illegal value.
=1: The transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is ill-conditioned. (A, B) may have been partially reordered, and ILST points to the first row of the current position of the block being moved.

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🌟 Contributors: 🌟

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden.

📚 References: 📚

[1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the Generalized Real Schur Form of a Regular Matrix Pair (A, B), in M.S. Moonen et al (eds), Linear Algebra for Large Scale and Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
[2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified Eigenvalues of a Regular Matrix Pair (A, B) and Condition Estimation: Theory, Algorithms and Software, Report UMINF - 94.04, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87. To appear in Numerical Algorithms, 1996.
[3] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software for Solving the Generalized Sylvester Equation and Estimating the Separation between Regular Matrix Pairs, Report UMINF - 93.23, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, December 1993, Revised April 1994, Also as LAPACK working Note 75. To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.

Definition at line 198 of file ctgexc.f.

🔥 `subroutine dtgexc` 🔥

   subroutine dtgexc (logical wantq, logical wantz, integer n, double
       precision, dimension( lda, * ) a, integer lda, double precision,
       dimension( ldb, * ) b, integer ldb, double precision, dimension( ldq, *
       ) q, integer ldq, double precision, dimension( ldz, * ) z, integer ldz,
       integer ifst, integer ilst, double precision, dimension( * ) work,
       integer lwork, integer info)

DTGEXC

🫶 Purpose: 🫶

DTGEXC reorders the generalized real Schur decomposition of a real matrix pair (A,B) using an orthogonal equivalence transformation

                (A, B) = Q * (A, B) * Z**T,

so that the diagonal block of (A, B) with row index IFST is moved to row ILST.

(A, B) must be in generalized real Schur canonical form (as returned by DGGES), i.e. A is block upper triangular with 1-by-1 and 2-by-2 diagonal blocks. B is upper triangular.

Optionally, the matrices Q and Z of generalized Schur vectors are updated.

        Q(in) * A(in) * Z(in)**T = Q(out) * A(out) * Z(out)**T
        Q(in) * B(in) * Z(in)**T = Q(out) * B(out) * Z(out)**T

🌟 Parameters 🌟

WANTQ — WANTQ is LOGICAL

.TRUE. : update the left transformation matrix Q;
.FALSE.: do not update Q.

WANTZ — WANTZ is LOGICAL

.TRUE. : update the right transformation matrix Z;
.FALSE.: do not update Z.

N — N is INTEGER

The order of the matrices A and B. N >= 0.

A — A is DOUBLE PRECISION array, dimension (LDA,N)

On entry, the matrix A in generalized real Schur canonical form. On exit, the updated matrix A, again in generalized real Schur canonical form.

LDA — LDA is INTEGER

The leading dimension of the array A. LDA >= max(1,N).

B — B is DOUBLE PRECISION array, dimension (LDB,N)

On entry, the matrix B in generalized real Schur canonical form (A,B). On exit, the updated matrix B, again in generalized real Schur canonical form (A,B).

LDB — LDB is INTEGER

The leading dimension of the array B. LDB >= max(1,N).

Q — Q is DOUBLE PRECISION array, dimension (LDQ,N)

On entry, if WANTQ = .TRUE., the orthogonal matrix Q. On exit, the updated matrix Q. If WANTQ = .FALSE., Q is not referenced.

LDQ — LDQ is INTEGER

The leading dimension of the array Q. LDQ >= 1. If WANTQ = .TRUE., LDQ >= N.

Z — Z is DOUBLE PRECISION array, dimension (LDZ,N)

On entry, if WANTZ = .TRUE., the orthogonal matrix Z. On exit, the updated matrix Z. If WANTZ = .FALSE., Z is not referenced.

LDZ — LDZ is INTEGER

The leading dimension of the array Z. LDZ >= 1. If WANTZ = .TRUE., LDZ >= N.

IFST — IFST is INTEGER

ILST — ILST is INTEGER

Specify the reordering of the diagonal blocks of (A, B). The block with row index IFST is moved to row ILST, by a sequence of swapping between adjacent blocks. On exit, if IFST pointed on entry to the second row of a 2-by-2 block, it is changed to point to the first row; ILST always points to the first row of the block in its final position (which may differ from its input value by +1 or -1). 1 <= IFST, ILST <= N.

WORK — WORK is DOUBLE PRECISION array, dimension (MAX(1,LWORK))

On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

LWORK — LWORK is INTEGER

The dimension of the array WORK. LWORK >= 1 when N <= 1, otherwise LWORK >= 4*N + 16.

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.

INFO

INFO — is INTEGER, and here's the vibe check on what it tells you:
- =0: successful exit. slay 💅
- <0: if INFO = -i, the i-th argument had an illegal value.
- =1: The transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is ill-conditioned. (A, B) may have been partially reordered, and ILST points to the first row of the current position of the block being moved.

bestie pls note: that =1 is NOT a happy ending — your problem is ill-conditioned and your matrices might be half-reordered. 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden.

References

[1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the Generalized Real Schur Form of a Regular Matrix Pair (A, B), in M.S. Moonen et al (eds), Linear Algebra for Large Scale and Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.

Definition at line 218 of file dtgexc.f.

🌸 `subroutine stgexc` — the single-precision one, same energy 🌸

subroutine stgexc (logical wantq, logical wantz, integer n, real, dimension(
lda, * ) a, integer lda, real, dimension( ldb, * ) b, integer ldb, real,
dimension( ldq, * ) q, integer ldq, real, dimension( ldz, * ) z, integer
ldz, integer ifst, integer ilst, real, dimension( * ) work, integer
lwork, integer info)

STGEXC

Purpose

okay so STGEXC reorders the generalized real Schur decomposition of a real matrix pair (A,B) using an orthogonal equivalence transformation 🦋

         (A, B) = Q * (A, B) * Z**T,

so that the diagonal block of (A, B) with row index IFST is moved to row ILST. literally just moving blocks around, main character energy only 👑

(A, B) must be in generalized real Schur canonical form (as returned by SGGES), i.e. A is block upper triangular with 1-by-1 and 2-by-2 diagonal blocks. B is upper triangular.

Optionally, the matrices Q and Z of generalized Schur vectors are updated 💖

         Q(in) * A(in) * Z(in)**T = Q(out) * A(out) * Z(out)**T
         Q(in) * B(in) * Z(in)**T = Q(out) * B(out) * Z(out)**T

Parameters

WANTQ — is LOGICAL
- .TRUE. : update the left transformation matrix Q;
- .FALSE.: do not update Q. 🙈
WANTZ — is LOGICAL
- .TRUE. : update the right transformation matrix Z;
- .FALSE.: do not update Z. 🙈
N — is INTEGER The order of the matrices A and B. N >= 0.
A — is REAL array, dimension (LDA,N) On entry, the matrix A in generalized real Schur canonical form. On exit, the updated matrix A, again in generalized real Schur canonical form. ✨
LDA — is INTEGER The leading dimension of the array A. LDA >= max(1,N).
B — is REAL array, dimension (LDB,N) On entry, the matrix B in generalized real Schur canonical form (A,B). On exit, the updated matrix B, again in generalized real Schur canonical form (A,B). ✨
LDB — is INTEGER The leading dimension of the array B. LDB >= max(1,N).
Q — is REAL array, dimension (LDQ,N) On entry, if WANTQ = .TRUE., the orthogonal matrix Q. On exit, the updated matrix Q. If WANTQ = .FALSE., Q is not referenced. (it's giving ignored 💀)
LDQ — is INTEGER The leading dimension of the array Q. LDQ >= 1. If WANTQ = .TRUE., LDQ >= N.
Z — is REAL array, dimension (LDZ,N) On entry, if WANTZ = .TRUE., the orthogonal matrix Z. On exit, the updated matrix Z. If WANTZ = .FALSE., Z is not referenced.
LDZ — is INTEGER The leading dimension of the array Z. LDZ >= 1. If WANTZ = .TRUE., LDZ >= N.
IFST — is INTEGER
ILST — is INTEGER Specify the reordering of the diagonal blocks of (A, B). The block with row index IFST is moved to row ILST, by a sequence of swapping between adjacent blocks. On exit, if IFST pointed on entry to the second row of a 2-by-2 block, it is changed to point to the first row; ILST always points to the first row of the block in its final position (which may differ from its input value by +1 or -1). 1 <= IFST, ILST <= N.

that +1 / -1 thing is real btw — don't be shook when ILST comes back different from what you sent in.

WORK — is REAL array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — is INTEGER The dimension of the array WORK. LWORK >= 1 when N <= 1, otherwise LWORK >= 4*N + 16.

INFO — is INTEGER
- =0: successful exit. 🎀
- <0: if INFO = -i, the i-th argument had an illegal value.
- =1: The transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is ill-conditioned. (A, B) may have been partially reordered, and ILST points to the first row of the current position of the block being moved.

fr fr, if you see INFO = 1 just know the problem was ill-conditioned and (A, B) might be partially reordered. not a drill. 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden.

References

Definition at line 218 of file stgexc.f.

🦋 `subroutine ztgexc` — complex*16 edition, she's fancy 🦋

subroutine ztgexc (logical wantq, logical wantz, integer n, complex*16,
dimension( lda, * ) a, integer lda, complex*16, dimension( ldb, * ) b,
integer ldb, complex*16, dimension( ldq, * ) q, integer ldq, complex*16,
dimension( ldz, * ) z, integer ldz, integer ifst, integer ilst, integer
info)

ZTGEXC

Purpose

ZTGEXC reorders the generalized Schur decomposition of a complex matrix pair (A,B), using an unitary equivalence transformation

(A, B) := Q * (A, B) * Z**H,

so that the diagonal block of (A, B) with row index IFST is moved to row ILST. 💜

(A, B) must be in generalized Schur canonical form, that is, A and B are both upper triangular. no 2-by-2 blocks here bestie, complex is built different ⭐

Optionally, the matrices Q and Z of generalized Schur vectors are updated.

         Q(in) * A(in) * Z(in)**H = Q(out) * A(out) * Z(out)**H
         Q(in) * B(in) * Z(in)**H = Q(out) * B(out) * Z(out)**H

Parameters

WANTQ — is LOGICAL
- .TRUE. : update the left transformation matrix Q;
- .FALSE.: do not update Q.
WANTZ — is LOGICAL
- .TRUE. : update the right transformation matrix Z;
- .FALSE.: do not update Z.
N — is INTEGER The order of the matrices A and B. N >= 0.
A — is COMPLEX*16 array, dimension (LDA,N) On entry, the upper triangular matrix A in the pair (A, B). On exit, the updated matrix A. ✨
LDA — is INTEGER The leading dimension of the array A. LDA >= max(1,N).
B — is COMPLEX*16 array, dimension (LDB,N) On entry, the upper triangular matrix B in the pair (A, B). On exit, the updated matrix B. ✨
LDB — is INTEGER The leading dimension of the array B. LDB >= max(1,N).
Q — is COMPLEX*16 array, dimension (LDQ,N) On entry, if WANTQ = .TRUE., the unitary matrix Q. On exit, the updated matrix Q. If WANTQ = .FALSE., Q is not referenced.
LDQ — is INTEGER The leading dimension of the array Q. LDQ >= 1; If WANTQ = .TRUE., LDQ >= N.
Z — is COMPLEX*16 array, dimension (LDZ,N) On entry, if WANTZ = .TRUE., the unitary matrix Z. On exit, the updated matrix Z. If WANTZ = .FALSE., Z is not referenced.
LDZ — is INTEGER The leading dimension of the array Z. LDZ >= 1; If WANTZ = .TRUE., LDZ >= N.
IFST — is INTEGER
ILST — is INTEGER Specify the reordering of the diagonal blocks of (A, B). The block with row index IFST is moved to row ILST, by a sequence of swapping between adjacent blocks.
INFO
INFO — ok she's the last one and she's lowkey the most important bc she's the receipts 💅 she's an INTEGER and here's her whole mood ring:
- =0: Successful exit. we love a clean getaway ✨
- <0: if INFO = -i, the i-th argument had an illegal value. so like, check your args bestie 🙈
- =1: The transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is ill-conditioned. (A, B) may have been partially reordered, and ILST points to the first row of the current position of the block being moved. 💀 not her being ill-conditioned

🌈 Author 🌈

the whole academic committee showed up for this one, no cap:

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🎀 Contributors 🎀

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden. 🫶 absolute icons, putting Swedish computing science on the map fr fr

📚 References 📚

this is the reading list, and yes you should actually read it, it's giving "cited so hard nobody can question me":

[1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the Generalized Real Schur Form of a Regular Matrix Pair (A, B), in M.S. Moonen et al (eds), Linear Algebra for Large Scale and Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
[2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified Eigenvalues of a Regular Matrix Pair (A, B) and Condition Estimation: Theory, Algorithms and Software, Report UMINF - 94.04, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87. To appear in Numerical Algorithms, 1996.
[3] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software for Solving the Generalized Sylvester Equation and Estimating the Separation between Regular Matrix Pairs, Report UMINF - 93.23, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, December 1993, Revised April 1994, Also as LAPACK working Note 75. To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.

three whole papers about this one routine, she's got main character energy for real 👑

Definition at line 198 of file ztgexc.f. 🦋

ngl the fact that this page literally says "Generated automatically by Doxygen for LAPACK from the source code" at the bottom is so funny to me — nobody hand-wrote this, the robots did it, and they ate 💅

and that's a wrap bestie!! 🌸 this lil masterpiece is straight from the LAPACK source, Version 3.12.0, and you've officially been read the whole tgexc(3) page — go forth and reorder those eigenvalues, periodt 💖🎀🦋

📦 where this page comes from

arch rolling: lapack-doc 3.12.1-2 · custom
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

tgexc(3)

🎀 tgexc(3) — reorder generalized Schur form 🎀

✨ NAME ✨

🌸 SYNOPSIS 🌸

🧚 Functions 🧚

💖 Detailed Description 💖

🦋 Function Documentation 🦋

💅 subroutine ctgexc 💅

🫶 Purpose: 🫶

🌟 Parameters 🌟

👑 Author 👑

🌟 Contributors: 🌟

📚 References: 📚

🔥 subroutine dtgexc 🔥

🫶 Purpose: 🫶

🌟 Parameters 🌟

Author

Contributors

References

🌸 subroutine stgexc — the single-precision one, same energy 🌸

Purpose

Parameters

Author

Contributors

References

🦋 subroutine ztgexc — complex*16 edition, she's fancy 🦋

Purpose

Parameters

🌈 Author 🌈

🎀 Contributors 🎀

📚 References 📚

💅 `subroutine ctgexc` 💅

🔥 `subroutine dtgexc` 🔥

🌸 `subroutine stgexc` — the single-precision one, same energy 🌸

🦋 `subroutine ztgexc` — complex*16 edition, she's fancy 🦋