SDRGSX(3)

📦 version 3.12.0, in opensuse-leap 16.0

SDRGSX(3) — Library Functions Manual. okay so bestie, buckle up, because this one is a whole vibe: it's a test driver for the nonsymmetric generalized eigenvalue problem, and it has opinions about SGGESX. 💅✨

🌸 NAME 🌸

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/TESTING/EIG/sdrgsx.f

✨ 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

🌈 Function/Subroutine Documentation 🌈

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 bestie, SDRGSX is out here checking the nonsymmetric generalized eigenvalue Schur form problem expert driver SGGESX. no cap, that's the whole assignment. 👑

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. iconic behavior, 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. (1) | A - Q S Z' | / ( |A| n ulp )
  2. (2) | B - Q T Z' | / ( |B| n ulp )
  3. (3) | I - QQ' | / ( n ulp )
  4. (4) | I - ZZ' | / ( n ulp )
  5. (5) — if A is in Schur form (i.e. quasi-triangular form). lowkey a vibe check for triangularity. 🔥
  6. (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.
  1. (7) — if sorting worked and SDIM is the number of eigenvalues which were selected. sorting ate, fr fr. 🍓
  2. (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). 😭
  3. (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. 💀

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:

  1. (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). bestie, that's a lot of condition numbers, but we stay focused. 💜
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. seriously, keep it small. this is not the moment for main character matrix sizes. 🙈

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. slay, prescribed solutions. 🎀

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:

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: 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:

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: (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. (yes, the original says “Kroneker” — we respect the spelling, bestie.)
  • THRESH — THRESH is REAL. a test will count as … if the …, 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 — …
  • Q — Q is REAL array, dimension (LDA, NSIZE), and it’s holding the right Schur vectors computed by SGGESX. That’s the whole vibe, bestie 💅
  • ALPHAR — ALPHAR is REAL array, dimension (NSIZE). Short, sweet, real-array realness ✨
  • ALPHAI — ALPHAI is REAL array, dimension (NSIZE). Same energy, iconic 🎀
  • BETA — BETA is REAL array, dimension (NSIZE). On exit, (ALPHAR + ALPHAI*i)/BETA are the eigenvalues. Math slay 🔥
  • C — C is REAL array, dimension (LDC, LDC). It stores the matrix generated by subroutine SLAKF2 — that’s the matrix formed by Kronecker products used for estimating DIF. We love a KronECKER moment 🦋
  • LDC — LDC is INTEGER, the leading dimension of C. And the bound is LDC >= max(1, LDA*LDA/2 ). Respect it, periodt 💅
  • S — S is REAL array, dimension (LDC), holding the singular values of C. Singular-value slay 🌸
  • WORK — WORK is REAL array, dimension (LWORK). The workspace bestie, no notes 🫶
  • LWORK — LWORK is INTEGER, the dimension of the array WORK. It has to satisfy LWORK >= MAX( 5*NSIZE*NSIZE/2 - 2, 10*(NSIZE+1) ). Math check, no cap 🧚
  • IWORK — IWORK is INTEGER array, dimension (LIWORK). Integer workspace, doing its lil job 💜
  • LIWORK — LIWORK is INTEGER, the dimension of the array IWORK. The rule is LIWORK >= NSIZE + 6. Locked in 🔒
  • BWORK — BWORK is LOGICAL array, dimension (LDA). Logical array, logical queen 👑
  • INFO — INFO is INTEGER, and here’s the status tea:
    • = 0: successful exit
    • < 0: if INFO = -i, the i-th argument had an illegal value.
    • > 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.

and that’s the LAPACK Version 3.12.0 tea, straight from /home/abui...IG/sdrgsx.f(3) — bye bestie, go slay those Schur vectors 💖✨
📦 where this page comes from