ZDRGSX(3)

💅 ZDRGSX(3) 💅

bestie, welcome to ZDRGSX(3) from the Library Functions Manual — yes, the manual name is folded in right here like a little name tag, because the first line used to be the header. This page is about zdrgsx.f, and it is a whole mood.

🎀 NAME 🎀

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/TESTING/EIG/zdrgsx.f — that's the exact file path, no cap. This is the zdrgsx.f page from the Library Functions Manual, and it is not here to be vague.

✨ 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

💖 FUNCTION/SUBROUTINE DOCUMENTATION 💖

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. It is literally the vibe check for ZGGESX, periodt.

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

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. (need more details on what kind of read-in data are needed).

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. triangular form)
(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)|)

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

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

NCMAX 🦋

NCMAX is INTEGER. Maximum allowable NMAX for generating Kroneker matrix in call to ZLAKF2.

THRESH 🦋

THRESH is DOUBLE PRECISION. A test will count as [blank] if the [blank], 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 🦋

C — this part cuts off right here, bestie. No description for C appears in this chunk, so we are not inventing one. More parts follow.

`C` 💅

C is COMPLEX*16 array, dimension (LDC, LDC)

Okay so this is where the matrix lives — it's the one that subroutine ZLAKF2 generated for you, aka the matrix made out of Kronecker products, and the whole reason it exists is to estimate DIF. That's it, that's the vibe.

`LDC` ✨

LDC is INTEGER

The leading dimension of C, bestie. And the rule is: LDC >= max(1, LDA*LDA/2 ). Respect the rule or the routine will simply not respect you back.

`S` 🎀

S is DOUBLE PRECISION array, dimension (LDC)

These are the singular values of C — the actual main characters of this whole operation, lowkey.

`WORK` 🦋

WORK is COMPLEX*16 array, dimension (LWORK)

The scratch space, the backstage dressing room, the place where the messy work happens so the main stage stays cute.

`LWORK` 🌸

LWORK is INTEGER

The dimension of the array WORK, and the requirement is LWORK >= 3*NSIZE*NSIZE/2 — yes, that many. Not a suggestion, iykyk.

`RWORK` 💖

RWORK is DOUBLE PRECISION array, dimension (5*NSIZE*NSIZE/2 - 4)

Double precision, and look at that dimension — 5*NSIZE*NSIZE/2 - 4. Whoever came up with that number was going through something, ngl. But it's exact, so write it down fr fr.

`IWORK` 🫶

IWORK is INTEGER array, dimension (LIWORK)

Integer scratch array, sized by LIWORK — the next entry, keep reading bestie.

`LIWORK` 😭

LIWORK is INTEGER

The dimension of the array IWORK, and it's gotta be LIWORK >= NSIZE + 2. That's the whole requirement. Short and iconic.

`BWORK` 👑

BWORK is LOGICAL array, dimension (NSIZE)

A logical array, sized NSIZE. True/false energy only. 🫡

`INFO` 🔥

INFO is INTEGER

The status report, the vibe check at the end of the whole thing:

= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value.
> 0:  A routine returned an error code.

So: 0 = slay, we're good. Negative = one of your arguments was illegal and it'll tell you which one by index (INFO = -i, i-th argument, caught red-handed 💀). Positive = some deeper routine came back with an error code, so the problem is not in this function's feelings, it's further down the stack.

🌈 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. Not a human, just a very diligent little robot doing its thing 🤖✨

And that's the whole page, bestie! 🎉 This lil' doc came from LAPACK Version 3.12.0, in the source file zdrgsx.f (you'll see it filed under <hotpink>/home/abui...IG/zdrgsx.f(3)</hotpink>). Go forth and call ZDRGSX responsibly — and remember, LDC >= max(1, LDA*LDA/2 ) is not a drill 💅🫶

📦 where this page comes from

opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms