CTGEX2(3)

📦 version 3.12.0, in opensuse-leap 16.0

💅 CTGEX2(3) — the LAPACK girlies' guide to swapping blocks

ok so bestie, welcome to CTGEX2 from the LAPACK library manual (yes, that LAPACK, the linear algebra icon herself 🌈). This page lives at /home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/ctgex2.f and honestly? She's giving main character energy in a very specific "reorder your generalized Schur form" way. Let's get into it ✨

🌸 NAME 🌸

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/ctgex2.f

(it's a source file bestie, that's the whole name, no cap 💀)

🦋 SYNOPSIS 🦋

Functions/Subroutines

subroutine CTGEX2 (wantq, wantz, n, a, lda, b, ldb, q, ldq, z, ldz, j1,
    info)

CTGEX2 swaps adjacent diagonal blocks in an upper (quasi) triangular matrix pair by an unitary equivalence transformation. literally her whole job 🫶

👑 Function/Subroutine Documentation 👑

subroutine CTGEX2 (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 j1, integer info)

CTGEX2 swaps adjacent diagonal blocks in an upper (quasi) triangular matrix pair by an unitary equivalence transformation. (yes that's the same sentence twice, she's consistent, we stan 💜)

✨ Purpose ✨

!> CTGEX2 swaps adjacent diagonal 1 by 1 blocks (A11,B11) and (A22,B22) !> in an upper triangular matrix pair (A, B) by an unitary equivalence !> transformation. !> !> (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 !> !>

so basically: two lil 1-by-1 diagonal blocks go in, one swap happens, and the Q/Z bookkeeping is optional but iconic. Note the requirement — (A, B) must be in generalized Schur canonical form, meaning A and B are both upper triangular. No shortcuts, no vibes-based input 🙈

🎀 Parameters 🎀

WANTQ

!> WANTQ is LOGICAL !> .TRUE. : update the left transformation matrix Q; !> .FALSE.: do not update Q. !>
  • WANTQ — a LOGICAL. Set it .TRUE. to update the left transformation matrix Q, or .FALSE. to leave Q alone. choose wisely bestie 💅

WANTZ

!> WANTZ is LOGICAL !> .TRUE. : update the right transformation matrix Z; !> .FALSE.: do not update Z. !>
  • WANTZ — a LOGICAL. .TRUE. updates the right transformation matrix Z; .FALSE. means don't touch Z. the right-side counterpart, we love a symmetrical moment 🫶

N

!> N is INTEGER !> The order of the matrices A and B. N >= 0. !>
  • N — INTEGER, the order of the matrices A and B. Must satisfy N >= 0.

A

!> A is COMPLEX array, dimension (LDA,N) !> On entry, the matrix A in the pair (A, B). !> On exit, the updated matrix A. !>
  • A — COMPLEX array, dimension (LDA,N). On entry: the matrix A in the pair (A, B). On exit: the updated matrix A. she gets a glow-up on the way out ✨

LDA

!> LDA is INTEGER !> The leading dimension of the array A. LDA >= max(1,N). !>
  • LDA — INTEGER, the leading dimension of the array A. Must be LDA >= max(1,N).

B

!> B is COMPLEX array, dimension (LDB,N) !> On entry, the matrix B in the pair (A, B). !> On exit, the updated matrix B. !>
  • B — COMPLEX array, dimension (LDB,N). On entry: the 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). !>
  • LDB — INTEGER, the leading dimension of the array B. Must be LDB >= max(1,N).

Q

!> Q is COMPLEX array, dimension (LDQ,N) !> If WANTQ = .TRUE, on entry, the unitary matrix Q. On exit, !> the updated matrix Q. !> Not referenced if WANTQ = .FALSE.. !>
  • Q — COMPLEX array, dimension (LDQ,N). If WANTQ = .TRUE, on entry it's the unitary matrix Q, and on exit it's the updated matrix Q. Not referenced if WANTQ = .FALSE..

LDQ

!> LDQ is INTEGER !> The leading dimension of the array Q. LDQ >= 1; !> If WANTQ = .TRUE., LDQ >= N. !>
  • LDQ — INTEGER, the leading dimension of the array Q. LDQ >= 1; and if WANTQ = .TRUE., then LDQ >= N.

Z

!> Z is COMPLEX array, dimension (LDZ,N) !> If WANTZ = .TRUE, on entry, the unitary matrix Z. On exit, !> the updated matrix Z. !> Not referenced if WANTZ = .FALSE.. !>
  • Z — COMPLEX array, dimension (LDZ,N). If WANTZ = .TRUE, on entry it's the unitary matrix Z, and on exit it's the updated matrix Z. Not referenced if WANTZ = .FALSE..

LDZ

!> LDZ is INTEGER !> The leading dimension of the array Z. LDZ >= 1; !> If WANTZ = .TRUE., LDZ >= N. !>
  • LDZ — INTEGER, the leading dimension of the array Z. LDZ >= 1; and if WANTZ = .TRUE., then LDZ >= N.

J1

!> J1 is INTEGER !> The index to the first block (A11, B11). !>
  • J1 — INTEGER, the index to the first block (A11, B11). that's your starting point, periodt 📍

INFO

!> INFO is INTEGER !> =0: Successful exit. !> =1: The transformed matrix pair (A, B) would be too far !> from generalized Schur form; the problem is ill- !> conditioned. !>
  • INFO — INTEGER. Exit status, and she is not subtle:
    • =0: successful exit 🎉
    • =1: the transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is ill-conditioned 😭

⭐ Author ⭐

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

(academia said "we all wrote this" and honestly? teamwork makes the dream work 🫶)

🔥 Further Details: 🔥

In the current code both weak and strong stability tests are performed. The user can omit the strong stability test by changing the internal logical parameter WANDS to .FALSE.. See ref. [2] for details.

ok so heads up bestie — this is a "you can do it, but read the ref first" situation. WANDS is an internal logical parameter, and flipping it to .FALSE. drops the strong stability test. Check ref. [2] before you go messing with her internals, fr fr 💀

🧚 Contributors: 🧚

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

(shoutout to the Swedish math girlies 🇸🇪💜)

📚 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.

Definition at line 188 of file ctgex2.f. 📍

🍓 Author 🍓

Generated automatically by Doxygen for LAPACK from the source code. (not a human, just a robot doing her little documentation duty, and honestly? she ate 🤖✨)

and that's the whole page bestie!! 💖 This was LAPACK, Version 3.12.0, dated /home/abui...RC/ctgex2.f(3) — go forth and swap those adjacent diagonal blocks, you absolute icon 👑🦋
📦 where this page comes from