SRC/ztgsna.f(3)

📦

version 3.12.1 · 7 versions

3.12.1 · arch rolling (latest)
3.9.0 · centos-stream 9
3.10.0 · ubuntu jammy
3.12.0 · ubuntu noble
3.12.0 · ubuntu noble
3.12.0 · centos-stream 10, fedora 43, fedora 44
3.11.0 · debian bookworm

🦋 SRC/ztgsna.f(3) — the LAPACK library functions manual, bestie edition 💅

okay so picture this: you're deep in LAPACK land, the (3) tells you it's a section-3 library function page, and this one? this one is ztgsna fr fr. it computes condition numbers. it's giving "am i stable" energy. let's get into it 🎀

✨ NAME ✨

SRC/ztgsna.f — that's the file, that's the vibe, no notes 💖

🌸 SYNOPSIS 🌸

Functions/Subroutines

subroutine ztgsna (job, howmny, select, n, a, lda, b, ldb, vl, ldvl, vr,
    ldvr, s, dif, mm, m, work, lwork, iwork, info)

ZTGSNA — the main character, obviously 👑

👑 Function/Subroutine Documentation 👑

subroutine ztgsna (character job, character howmny, logical, dimension( * )
    select, integer n, complex*16, dimension( lda, * ) a, integer lda,
    complex*16, dimension( ldb, * ) b, integer ldb, complex*16, dimension(
    ldvl, * ) vl, integer ldvl, complex*16, dimension( ldvr, * ) vr, integer
    ldvr, double precision, dimension( * ) s, double precision, dimension( *
    ) dif, integer mm, integer m, complex*16, dimension( * ) work, integer
    lwork, integer, dimension( * ) iwork, integer info)

ZTGSNA — yes bestie, same name twice, it's just Like That 💀

🎯 PURPOSE 🎯

!> !> ZTGSNA estimates reciprocal condition numbers for specified !> eigenvalues and/or eigenvectors of a matrix pair (A, B). !> !> (A, B) must be in generalized Schur canonical form, that is, A and !> B are both upper triangular. !>

so literally, ZTGSNA hands you a reciprocal condition number for whichever eigenvalues and/or eigenvectors you point at, in the matrix pair (A, B) 🫶 and the key detail: (A, B) has to already be in generalized Schur canonical form — meaning A and B are both upper triangular. no cap, that's a hard requirement 🔥

🧚 PARAMETERS 🧚

`JOB`

!> JOB is CHARACTER*1 !> Specifies whether condition numbers are required for !> eigenvalues (S) or eigenvectors (DIF): !> = 'E': for eigenvalues only (S); !> = 'V': for eigenvectors only (DIF); !> = 'B': for both eigenvalues and eigenvectors (S and DIF). !>

'E' — eigenvalues only, so you get S 💖
'V' — eigenvectors only, so you get DIF ✨
'B' — both bestie, S and DIF, we're doing it all 🎀

`HOWMNY`

!> HOWMNY is CHARACTER*1 !> = 'A': compute condition numbers for all eigenpairs; !> = 'S': compute condition numbers for selected eigenpairs !> specified by the array SELECT. !>

'A' — all the eigenpairs, we're not picking favourites 🌈
'S' — only the ones you picked in SELECT, main character selection energy 👑

`SELECT`

!> SELECT is LOGICAL array, dimension (N) !> If HOWMNY = 'S', SELECT specifies the eigenpairs for which !> condition numbers are required. To select condition numbers !> for the corresponding j-th eigenvalue and/or eigenvector, !> SELECT(j) must be set to .TRUE.. !> If HOWMNY = 'A', SELECT is not referenced. !>

dimension (N) — and if HOWMNY = 'S', then SELECT(j) = .TRUE. is your way of saying "yes queen, this one" for the j-th eigenvalue and/or eigenvector 💅 if HOWMNY = 'A', SELECT doesn't even get looked at, she's not referenced 🙈

`N`

!> N is INTEGER !> The order of the square matrix pair (A, B). N >= 0. !>

the order of the square matrix pair (A, B), and it's N >= 0 ⭐

`A`

!> A is COMPLEX*16 array, dimension (LDA,N) !> The upper triangular matrix A in the pair (A,B). !>

COMPLEX*16, dimension (LDA,N) — the upper triangular matrix A in the pair (A,B) 🦋

`LDA`

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

leading dimension of A, and LDA >= max(1,N) 📏

`B`

!> B is COMPLEX*16 array, dimension (LDB,N) !> The upper triangular matrix B in the pair (A, B). !>

COMPLEX*16, dimension (LDB,N) — the upper triangular matrix B in the pair (A, B) 🌸

`LDB`

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

leading dimension of B, LDB >= max(1,N) 🍓

`VL`

!> VL is COMPLEX*16 array, dimension (LDVL,M) !> IF JOB = 'E' or 'B', VL must contain left eigenvectors of !> (A, B), corresponding to the eigenpairs specified by HOWMNY !> and SELECT. The eigenvectors must be stored in consecutive !> columns of VL, as returned by ZTGEVC. !> If JOB = 'V', VL is not referenced. !>

COMPLEX*16, dimension (LDVL,M). if JOB = 'E' or 'B', VL must hold the left eigenvectors of (A, B) matching whatever eigenpairs HOWMNY and SELECT chose 🫶 and listen — those eigenvectors go in consecutive columns of VL, exactly as returned by ZTGEVC. if JOB = 'V', VL is not referenced, she's off duty 😌

`LDVL`

!> LDVL is INTEGER !> The leading dimension of the array VL. LDVL >= 1; and !> If JOB = 'E' or 'B', LDVL >= N. !>

leading dimension of VL: LDVL >= 1, and if JOB = 'E' or 'B', then LDVL >= N 💜

`VR`

!> VR is COMPLEX*16 array, dimension (LDVR,M) !> IF JOB = 'E' or 'B', VR must contain right eigenvectors of !> (A, B), corresponding to the eigenpairs specified by HOWMNY !> and SELECT. The eigenvectors must be stored in consecutive !> columns of VR, as returned by ZTGEVC. !> If JOB = 'V', VR is not referenced. !>

COMPLEX*16, dimension (LDVR,M). if JOB = 'E' or 'B', VR must contain the right eigenvectors of (A, B) for the eigenpairs picked by HOWMNY and SELECT ✨ consecutive columns of VR, as returned by ZTGEVC, same drill as before. if JOB = 'V', VR is not referenced 🌈

`LDVR`

!> LDVR is INTEGER !> The leading dimension of the array VR. LDVR >= 1; !> If JOB = 'E' or 'B', LDVR >= N. !>

leading dimension of VR: LDVR >= 1, and if JOB = 'E' or 'B', then LDVR >= N 🎀

`S`

!> S is DOUBLE PRECISION array, dimension (MM) !> If JOB = 'E' or 'B', the reciprocal condition numbers of the !> selected eigenvalues, stored in consecutive elements of the !> array. !> If JOB = 'V', S is not referenced. !>

DOUBLE PRECISION, dimension (MM). if JOB = 'E' or 'B', this holds the reciprocal condition numbers of the selected eigenvalues, in consecutive elements. if JOB = 'V', S is not referenced 💅

`DIF`

!> DIF is DOUBLE PRECISION array, dimension (MM) !> If JOB = 'V' or 'B', the estimated reciprocal condition !> numbers of the selected eigenvectors, stored in consecutive !> elements of the array. !> If the eigenvalues cannot be reordered to compute DIF(j), !> DIF(j) is set to 0; this can only occur when the true value !> would be very small anyway. !> For each eigenvalue/vector specified by SELECT, DIF stores !> a Frobenius norm-based estimate of Difl. !> If JOB = 'E', DIF is not referenced. !>

DOUBLE PRECISION, dimension (MM). if JOB = 'V' or 'B', these are the estimated reciprocal condition numbers of the selected eigenvectors, consecutive elements, no gaps 🌸

⚠️ heads up bestie: if the eigenvalues can't be reordered to compute DIF(j), then DIF(j) gets set to 0 — and ngl that can only happen when the true value would be very small anyway, so don't spiral 😭

for each eigenvalue/vector specified by SELECT, DIF stores a Frobenius norm-based estimate of Difl 🔥 and if JOB = 'E', DIF is not referenced 😌

`MM`

!> MM is INTEGER !> The number of elements in the arrays S and DIF. MM >= M. !>

the number of elements in the arrays S and DIF, and MM >= M 📐

`M`

!> M is INTEGER !> The number of elements of the arrays S and DIF used to store !> the specified condition numbers; for each selected eigenvalue !> one element is used. If HOWMNY = 'A', M is set to N. !>

how many elements of S and DIF actually got used to store the specified condition numbers — one element per selected eigenvalue 💖 and if HOWMNY = 'A', then M is set to N 👑

`WORK`

!> WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) !> On exit, if INFO = 0, WORK(1) returns the optimal LWORK. !>

COMPLEX*16, dimension (MAX(1,LWORK)). on exit, if INFO = 0, then WORK(1) returns the optimal LWORK ⭐ that's the little gift LAPACK leaves you 🎁

`LWORK`

!> LWORK is INTEGER !> The dimension of the array WORK. LWORK >= max(1,N). !> If JOB = 'V' or 'B', LWORK >= max(1,2*N*N). !>

the dimension of WORK: LWORK >= max(1,N). but if JOB = 'V' or 'B', then LWORK >= max(1,2*N*N) 🔥 that's a big girl requirement, size accordingly bestie 😭

`IWORK`

!> IWORK is INTEGER array, dimension (N+2) !> If JOB = 'E', IWORK is not referenced. !>

INTEGER array, dimension (N+2). if JOB = 'E', IWORK is not referenced, she's not needed 🙈

`INFO`

!> INFO is INTEGER !> = 0: Successful exit !> < 0: If INFO = -i, the i-th argument had an illegal value !>

= 0 — successful exit, we ate 💅
< 0 — if INFO = -i, the i-th argument had an illegal value 💀 (so check your args, bestie)

🫶 AUTHOR 🫶

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

like, the whole squad showed up for this one 😭👑

🔥 FURTHER DETAILS 🔥

!> !> The reciprocal of the condition number of the i-th generalized !> eigenvalue w = (a, b) is defined as !> !> S(I) = (|vHAu|2 + |vHBu|2)(1/2) / (norm(u)*norm(v)) !> !> where u and v are the right and left eigenvectors of (A, B) !> corresponding to w; |z| denotes the absolute value of the complex !> number, and norm(u) denotes the 2-norm of the vector u. The pair !> (a, b) corresponds to an eigenvalue w = a/b (= vHAu/v**HBu) of the !> matrix pair (A, B). If both a and b equal zero, then (A,B) is !> singular and S(I) = -1 is returned. !> !> An approximate error bound on the chordal distance between the i-th !> computed generalized eigenvalue w and the corresponding exact !> eigenvalue lambda is !> !> chord(w, lambda) <= EPS * norm(A, B) / S(I), !> !> where EPS is the machine precision. !>

okay so the reciprocal of the condition number of the i-th generalized eigenvalue w = (a, b) is:

         S(I) = (|v**HAu|**2 + |v**HBu|**2)**(1/2) / (norm(u)*norm(v))

here u and v are the right and left eigenvectors of (A, B) corresponding to w 💖 |z| means the absolute value of the complex number, and norm(u) means the 2-norm of the vector u. the pair (a, b) corresponds to an eigenvalue w = a/b (= v**HAu/v**HBu) of the matrix pair (A, B) 🦋

⚠️ and if both a and b equal zero, then (A,B) is singular and S(I) = -1 is returned. that's the "we can't, she's singular" signal 💀

and the approximate error bound on the chordal distance between the i-th computed generalized eigenvalue w and the corresponding exact eigenvalue lambda is:

         chord(w, lambda) <=   EPS * norm(A, B) / S(I),

where EPS is the machine precision ✨

!> !> The reciprocal of the condition number of the right eigenvector u !> and left eigenvector v corresponding to the generalized eigenvalue w !> is defined as follows. Suppose !> !> (A, B) = ( a * ) ( b * ) 1 !> ( 0 A22 ),( 0 B22 ) n-1 !> 1 n-1 1 n-1 !> !> Then the reciprocal condition number DIF(I) is !> !> Difl[(a, b), (A22, B22)] = sigma-min( Zl ) !> !> where sigma-min(Zl) denotes the smallest singular value of !> !> Zl = [ kron(a, In-1) -kron(1, A22) ] !> [ kron(b, In-1) -kron(1, B22) ]. !> !> Here In-1 is the identity matrix of size n-1 and X**H is the conjugate !> transpose of X. kron(X, Y) is the Kronecker product between the !> matrices X and Y. !> !> We approximate the smallest singular value of Zl with an upper !> bound. This is done by ZLATDF. !> !> An approximate error bound for a computed eigenvector VL(i) or !> VR(i) is given by !> !> EPS * norm(A, B) / DIF(i). !> !> See ref. [2-3] for more details and further references. !>

so the reciprocal of the condition number of the right eigenvector u and left eigenvector v corresponding to the generalized eigenvalue w goes like this. suppose:

                   (A, B) = ( a   *  ) ( b  *  )  1
                            ( 0  A22 ),( 0 B22 )  n-1
                              1  n-1     1 n-1

then the reciprocal condition number DIF(I) is:

         Difl[(a, b), (A22, B22)]  = sigma-min( Zl )

where sigma-min(Zl) denotes the smallest singular value of:

        Zl = [ kron(a, In-1) -kron(1, A22) ]
             [ kron(b, In-1) -kron(1, B22) ].

here In-1 is the identity matrix of size n-1, and X**H is the conjugate transpose of X 🌸 kron(X, Y) is the Kronecker product between the matrices X and Y 🧚

we approximate the smallest singular value of Zl with an upper bound 🫶 and that's done by ZLATDF 🔥

an approximate error bound for a computed eigenvector VL(i) or VR(i) is given by:

                      EPS * norm(A, B) / DIF(i).

see ref. [2-3] for more details and further references, iykyk 📚

🍓 CONTRIBUTORS: 🍓

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

shoutout, legends only 👑💜

🌈 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. !>

[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 ⭐

Definition at line 308 of file ztgsna.f. 📍

Author

Generated automatically by Doxygen for LAPACK from the source code. 🤖 (yes bestie, a robot wrote this part, we respect the automation 💅)

and that's the whole page!! 🎀 this was LAPACK Version 3.12.0, SRC/ztgsna.f(3), and honestly? iconic. go estimate some condition numbers, stay upper triangular, and remember: if both a and b are zero, S(I) = -1 and that's not your fault 💖✨🦋

📦 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