TESTING/EIG/zdrgsx.f(3)

📦
version 3.12.1 · 3 versions
, in arch rolling

💅 TESTING/EIG/zdrgsx.f(3) 💅

okay bestie, welcome to the zdrgsx page from the Library Functions Manual — it's giving Fortran testing-suite main character energy, and we are keeping every single detail because that's the whole vibe. ✨

🌸 NAME 🌸

TESTING/EIG/zdrgsx.f

🎀 SYNOPSIS 🎀

🦋 Functions/Subroutines 🦋

  • subroutine zdrgsx (nsize, ncmax, thresh, nin, nout, a, lda, b, ai, bi, z, q, alpha, beta, c, ldc, s, work, lwork, rwork, iwork, liwork, bwork, info) — ZDRGSX
subroutine zdrgsx (nsize, ncmax, thresh, nin, nout, a, lda, b, ai, bi,
    z, q, alpha, beta, c, ldc, s, work, lwork, rwork, iwork, liwork,
    bwork, info)

💖 Function/Subroutine Documentation 💖

🧚 subroutine zdrgsx 🧚

subroutine zdrgsx (integer nsize, integer ncmax, double precision thresh,
    integer nin, integer nout, complex*16, dimension( lda, * ) a, integer
    lda, complex*16, dimension( lda, * ) b, complex*16, dimension( lda, * )
    ai, complex*16, dimension( lda, * ) bi, complex*16, dimension( lda, * )
    z, complex*16, dimension( lda, * ) q, complex*16, dimension( * ) alpha,
    complex*16, dimension( * ) beta, complex*16, dimension( ldc, * ) c,
    integer ldc, double precision, dimension( * ) s, complex*16, dimension(
    * ) work, integer lwork, double precision, dimension( * ) rwork,
    integer, dimension( * ) iwork, integer liwork, logical, dimension( * )
    bwork, integer info)
    ZDRGSX

✨ Purpose ✨

okay so ZDRGSX checks the nonsymmetric generalized eigenvalue (Schur form) problem expert driver ZGGESX. 💅

ZGGES factors A and B as Q*S*Z' and Q*T*Z', where ' means conjugate transpose, S and T are upper triangular (i.e., in generalized Schur form), and Q and Z are unitary. It also computes the generalized eigenvalues (alpha(j),beta(j)), j=1,...,n. So:

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. slay. 🦋

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

When ZDRGSX is called with NSIZE = 0, it reads in test matrix data to test ZGGESX. The original literally says (need more details on what kind of read-in data are needed) — not me making that up, bestie 😭.

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

  1. Test (1):
| A - Q S Z' | / ( |A| n ulp )
  1. Test (2):
| B - Q T Z' | / ( |B| n ulp )
  1. Test (3):
| I - QQ' | / ( n ulp )
  1. Test (4):
| I - ZZ' | / ( n ulp )
  1. Test (5): if A is in Schur form (i.e. triangular form).
  2. Test (6): maximum over j of D(j) where:
          |alpha(j) - S(j,j)|        |beta(j) - T(j,j)|
D(j) = ------------------------ + -----------------------
       max(|alpha(j)|,|S(j,j)|)   max(|beta(j)|,|T(j,j)|)
  1. Test (7): if sorting worked and SDIM is the number of eigenvalues which were selected.
  2. Test (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. Test (9): If INFO = N+3 is returned by ZGGESX, 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 same 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. Test (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).
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 ZGESVD) 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: 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 DLATM5). 🫶

🍓 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 DGGESX. iykyk ✨
  • NCMAX — NCMAX is INTEGER. Maximum allowable NMAX for generating Kroneker matrix in call to ZLAKF2. not me spelling it Kroneker — that's literally what the page says, bestie. 💅
  • THRESH — THRESH is DOUBLE PRECISION. 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 INFO not equal to 0). 🚨
  • A — A is COMPLEX*16 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 COMPLEX*16 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 COMPLEX*16 array, dimension (LDA, NSIZE). Copy of A, modified by ZGGESX.
  • BI — BI is COMPLEX*16 array, dimension (LDA, NSIZE). Copy of B, modified by ZGGESX.
  • Z — Z is COMPLEX*16 array, dimension (LDA, NSIZE). Z holds the left Schur vectors computed by ZGGESX.
  • Q — Q is COMPLEX*16 array, dimension (LDA, NSIZE). Q holds the right Schur vectors computed by ZGGESX.
  • ALPHA — ALPHA is COMPLEX*16 array, dimension (NSIZE).
  • BETA — BETA is COMPLEX*16 array, dimension (NSIZE). On exit, ALPHA/BETA are the eigenvalues. 💜
  • C

Okay so picking up right inside the parameter lineup — no skipping, bestie, we’re doing all of them 💅

  • C — COMPLEX*16 array, dimension (LDC). Store the matrix generated by subroutine ZLAKF2; this is the matrix formed by Kronecker products used for estimating DIF. Obsessed with a matrix that has lore 🫶
  • LDC — INTEGER. The leading dimension of C. LDC >= max(1, LDA*LDA/2 ). Respect the math, babes ✨
  • S — DOUBLE PRECISION array, dimension (LDC). Singular values of C. Iconic values only 💖
  • WORK — COMPLEX*16 array, dimension (LWORK).
  • LWORK — INTEGER. The dimension of the array WORK. LWORK >= 3*NSIZE*NSIZE/2
  • RWORK — DOUBLE PRECISION array, dimension (5*NSIZE*NSIZE/2 - 4).
  • IWORK — INTEGER array, dimension (LIWORK).
  • LIWORK — INTEGER. The dimension of the array IWORK. LIWORK >= NSIZE + 2.
  • BWORK — LOGICAL array, dimension (NSIZE).
  • INFO — INTEGER:
    • = 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 346 of file zdrgsx.f.

Author 🤖

Generated automatically by Doxygen for LAPACK from the source code.

That’s the whole vibe for TESTING/EIG/zdrgsx.f(3), and the footer is serving LAPACK Version 3.12.0 — bye bestie, go slay your linear algebra 💖🎀✨

📦 where this page comes from