TESTING/EIG/sdrgsx.f(3)

📦

version 3.12.1 · 3 versions

3.12.1 · arch rolling (latest)
3.12.0 · opensuse-leap 16.0
3.12.0 · centos-stream 10, fedora 43, fedora 44

🌸 NAME

TESTING/EIG/sdrgsx.f — the Library Functions Manual page for the SDRGSX test routine, bestie. It’s giving “Fortran test-driver energy” and it’s here to check SGGESX.

✨ SYNOPSIS

🎀 Functions/Subroutines

subroutine sdrgsx (nsize, ncmax, thresh, nin, nout, a, lda, b, ai, bi,
    z, q, alphar, alphai, beta, c, ldc, s, work, lwork, iwork, liwork,
    bwork, info)

SDRGSX — yes, that’s the whole name. No notes. Slay.

💫 Function/Subroutine Documentation

🌟 subroutine sdrgsx

subroutine sdrgsx (integer nsize, integer ncmax, real thresh, integer nin,
     integer nout, real, dimension( lda, * ) a, integer lda, real, dimension(
     lda, * ) b, real, dimension( lda, * ) ai, real, dimension( lda, * ) bi,
     real, dimension( lda, * ) z, real, dimension( lda, * ) q, real,
     dimension( * ) alphar, real, dimension( * ) alphai, real, dimension( * )
     beta, real, dimension( ldc, * ) c, integer ldc, real, dimension( * ) s,
     real, dimension( * ) work, integer lwork, integer, dimension( * ) iwork,
     integer liwork, logical, dimension( * ) bwork, integer info)

SDRGSX

💖 Purpose

Okay so SDRGSX checks the nonsymmetric generalized eigenvalue (Schur form) problem expert driver SGGESX. That’s the vibe check. 🔥

SGGESX factors A and B as Q S Z' and Q T Z', where ' means transpose, T is upper triangular, S is in generalized Schur form (block upper triangular, with 1x1 and 2x2 blocks on the diagonal, the 2x2 blocks corresponding to complex conjugate pairs of generalized eigenvalues), and Q and Z are orthogonal. It also computes the generalized eigenvalues (alpha(1),beta(1)), ..., (alpha(n),beta(n)). Thus, w(j) = alpha(j)/beta(j) is a root of the characteristic equation

det( A - w(j) B ) = 0

Optionally it also reorders the eigenvalues so that a selected cluster of eigenvalues appears in the leading diagonal block of the Schur forms; computes a reciprocal condition number for the average of the selected eigenvalues; and computes a reciprocal condition number for the right and left deflating subspaces corresponding to the selected eigenvalues. Obsessed, honestly. 💅

When SDRGSX is called with NSIZE > 0, five (5) types of built-in matrix pairs are used to test the routine SGGESX. 🧪

When SDRGSX is called with NSIZE = 0, it reads in test matrix data to test SGGESX. 📖

For each matrix pair, the following tests will be performed and compared with the threshold THRESH except for the tests (7) and (9):

(1) | A - Q S Z' | / ( |A| n ulp )
(2) | B - Q T Z' | / ( |B| n ulp )
(3) | I - QQ' | / ( n ulp )
(4) | I - ZZ' | / ( n ulp )
(5) if A is in Schur form (i.e. quasi-triangular form)
(6) maximum over j of D(j) where:

if alpha(j) is real:
              |alpha(j) - S(j,j)|        |beta(j) - T(j,j)|
    D(j) = ------------------------ + -----------------------
           max(|alpha(j)|,|S(j,j)|)   max(|beta(j)|,|T(j,j)|)

if alpha(j) is complex:
                          | det( s S - w T ) |
    D(j) = ---------------------------------------------------
           ulp max( s norm(S), |w| norm(T) )*norm( s S - w T )

and S and T are here the 2 x 2 diagonal blocks of S and T corresponding to the j-th and j+1-th eigenvalues.

(7) if sorting worked and SDIM is the number of eigenvalues which were selected.
(8) the estimated value DIF does not differ from the true values of Difu and Difl more than a factor 10*THRESH. If the estimate DIF equals zero the corresponding true values of Difu and Difl should be less than EPS*norm(A, B). If the true value of Difu and Difl equal zero, the estimate DIF should be less than EPS*norm(A, B).
(9) If INFO = N+3 is returned by SGGESX, the reordering and we check that DIF = PL = PR = 0 and that the true value of Difu and Difl is < EPS*norm(A, B). We count the events when INFO=N+3.
(10) the estimated value PL does not differ from the true value of PLTRU more than a factor THRESH. If the estimate PL equals zero the corresponding true value of PLTRU should be less than EPS*norm(A, B). If the true value of PLTRU equal zero, the estimate PL should be less than EPS*norm(A, B).

For read-in test matrices, the above tests are run except that the exact value for DIF (and PL) is input data. Additionally, there is one more test run for read-in test matrices:

That last one is test (10), bestie — don’t lose it in the group chat. 🫶

Note that for the built-in tests, a total of 10*NSIZE*(NSIZE-1) matrix pairs are generated and tested. NSIZE should be kept small. 🚨

SVD (routine SGESVD) is used for computing the true value of DIF_u and DIF_l when testing the built-in test problems.

🧪 Built-in Test Matrices

All built-in test matrices are the 2 by 2 block of triangular matrices

         A = [ A11 A12 ]    and      B = [ B11 B12 ]
             [     A22 ]                 [     B22 ]

where for different type of A11 and A22 are given as the following. A12 and B12 are chosen so that the generalized Sylvester equation

         A11*R - L*A22 = -A12
         B11*R - L*B22 = -B12

have prescribed solution R and L.

Type 1:

Type 1:  A11 = J_m(1,-1) and A_22 = J_k(1-a,1).
         B11 = I_m, B22 = I_k
         where J_k(a,b) is the k-by-k Jordan block with ``a'' on
         diagonal and ``b'' on superdiagonal.

Type 2:

Type 2:  A11 = (a_ij) = ( 2(.5-sin(i)) ) and
         B11 = (b_ij) = ( 2(.5-sin(ij)) ) for i=1,...,m, j=i,...,m
         A22 = (a_ij) = ( 2(.5-sin(i+j)) ) and
         B22 = (b_ij) = ( 2(.5-sin(ij)) ) for i=m+1,...,k, j=i,...,k

Type 3:

Type 3:  A11, A22 and B11, B22 are chosen as for Type 2, but each
         second diagonal block in A_11 and each third diagonal block
         in A_22 are made as 2 by 2 blocks.

Type 4:

Type 4:  A11 = ( 20(.5 - sin(ij)) ) and B22 = ( 2(.5 - sin(i+j)) )
            for i=1,...,m,  j=1,...,m and
         A22 = ( 20(.5 - sin(i+j)) ) and B22 = ( 2(.5 - sin(ij)) )
            for i=m+1,...,k,  j=m+1,...,k

Type 5:

Type 5:  (A,B) and have potentially close or common eigenvalues and
         very large departure from block diagonality A_11 is chosen
         as the m x m leading submatrix of A_1:
                 |  1  b                            |
                 | -b  1                            |
                 |        1+d  b                    |
                 |         -b 1+d                   |
          A_1 =  |                  d  1            |
                 |                 -1  d            |
                 |                        -d  1     |
                 |                        -1 -d     |
                 |                               1  |
         and A_22 is chosen as the k x k leading submatrix of A_2:
                 | -1  b                            |
                 | -b -1                            |
                 |       1-d  b                     |
                 |       -b  1-d                    |
          A_2 =  |                 d 1+b            |
                 |               -1-b d             |
                 |                       -d  1+b    |
                 |                      -1+b  -d    |
                 |                              1-d |
         and matrix B are chosen as identity matrices (see SLATM5).

🌈 Parameters

NSIZE — NSIZE is INTEGER. The maximum size of the matrices to use. NSIZE >= 0. If NSIZE = 0, no built-in tests matrices are used, but read-in test matrices are used to test SGGESX. 💖
NCMAX — NCMAX is INTEGER. Maximum allowable NMAX for generating Kroneker matrix in call to SLAKF2. 🎀
THRESH — THRESH is REAL. A test will count as a fail if the error, computed as described above, exceeds THRESH. Note that the error is scaled to be O(1), so THRESH should be a reasonably small multiple of 1, e.g., 10 or 100. In particular, it should not depend on the precision (single vs. double) or the size of the matrix. THRESH >= 0. ✨
NIN — NIN is INTEGER. The FORTRAN unit number for reading in the data file of problems to solve. 📖
NOUT — NOUT is INTEGER. The FORTRAN unit number for printing out error messages (e.g., if a routine returns IINFO not equal to 0.) 🚨
A — A is REAL array, dimension (LDA, NSIZE). Used to store the matrix whose eigenvalues are to be computed. On exit, A contains the last matrix actually used. 💅
LDA — LDA is INTEGER. The leading dimension of A, B, AI, BI, Z and Q, LDA >= max( 1, NSIZE ). For the read-in test, LDA >= max( 1, N ), N is the size of the test matrices. 🫶
B — B is REAL array, dimension (LDA, NSIZE). Used to store the matrix whose eigenvalues are to be computed. On exit, B contains the last matrix actually used. 🌸
AI — AI is REAL array, dimension (LDA, NSIZE). Copy of A, modified by SGGESX. 🦋
BI — BI is REAL array, dimension (LDA, NSIZE). Copy of B, modified by SGGESX. 🧚
Z — Z is REAL array, dimension (LDA, NSIZE). Z holds the left Schur vectors computed by SGGESX. 👑
Q — the next part picks up right here, bestie. Description continues in part 2. 🎀
Q — REAL array, dimension (LDA, NSIZE). This one holds the right Schur vectors that SGGESX computed. iconic behavior honestly 💅
ALPHAR — REAL array, dimension (NSIZE). Real part of the eigenvalue situation, bestie ✨
ALPHAI — REAL array, dimension (NSIZE). Imaginary part of the eigenvalue situation 🦋
BETA — REAL array, dimension (NSIZE). On exit, (ALPHAR + ALPHAI*i)/BETA are the eigenvalues. periodt.
C — REAL array, dimension (LDC, LDC). Stores the matrix generated by subroutine SLAKF2; this is the matrix formed by Kronecker products used for estimating DIF. no cap, it's giving very serious math 🎀
LDC — INTEGER. The leading dimension of C. LDC >= max(1, LDA*LDA/2 ). respect the bounds or else 😭
S — REAL array, dimension (LDC). Singular values of C. slay 🔥
WORK — REAL array, dimension (LWORK). workspace vibes ✨
LWORK — INTEGER. The dimension of the array WORK. LWORK >= MAX( 5*NSIZE*NSIZE/2 - 2, 10*(NSIZE+1) ). do not skimp on this, fr fr 🫶
IWORK — INTEGER array, dimension (LIWORK). integer workspace, living its best life 💜
LIWORK — INTEGER. The dimension of the array IWORK. LIWORK >= NSIZE + 6. lowkey important, don't ignore her 💅
BWORK — LOGICAL array, dimension (LDA). logical workspace, she's just here for the vibes 🌸
INFO — INTEGER. the ultimate vibe check:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. not cute 😭
- > 0: a routine returned an error code. 💀

👑 Author

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

Definition at line 356 of file sdrgsx.f.

🧚 Author

Generated automatically by Doxygen for LAPACK from the source code.

okay that's the whole page bestie 🫶 shoutout to LAPACK Version 3.12.0 and the source TESTING/EIG/sdrgsx.f(3) — footer said what it said, no date in sight, and we respect it 💅✨

📦 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