TESTING/EIG/cdrves.f(3)

📦

version 3.12.1 · 2 versions

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

💅 TESTING/EIG/cdrves.f

okay so bestie, we're looking at a page from the TESTING/EIG directory — the file is cdrves.f. It's a library functions manual situation and honestly it's kind of a baddie. Let's get into it 🫶

✨ SYNOPSIS ✨

🌈 Functions/Subroutines

subroutine cdrves (nsizes, nn, ntypes, dotype, iseed, thresh, nounit, a,
    lda, h, ht, w, wt, vs, ldvs, result, work, nwork, rwork, iwork,
    bwork, info)

CDRVES — that's the whole vibe, that's the whole name ✨

🎀 Function/Subroutine Documentation 🎀

💖 subroutine cdrves

so the full signature, in all its glory, is:

subroutine cdrves (integer nsizes, integer, dimension( * ) nn, integer
    ntypes, logical, dimension( * ) dotype, integer, dimension( 4 ) iseed,
    real thresh, integer nounit, complex, dimension( lda, * ) a, integer
    lda, complex, dimension( lda, * ) h, complex, dimension( lda, * ) ht,
    complex, dimension( * ) w, complex, dimension( * ) wt, complex,
    dimension( ldvs, * ) vs, integer ldvs, real, dimension( 13 ) result,
    complex, dimension( * ) work, integer nwork, real, dimension( * ) rwork,
    integer, dimension( * ) iwork, logical, dimension( * ) bwork, integer
    info)

CDRVES 💅

🦋 Purpose

!>
!>    CDRVES checks the nonsymmetric eigenvalue (Schur form) problem
!>    driver CGEES.
!>
!>    When CDRVES is called, a number of matrix sizes () and a
!>    number of matrix types are specified.  For each size ()
!>    and each type of matrix, one matrix will be generated and used
!>    to test the nonsymmetric eigenroutines.  For each matrix, 13
!>    tests will be performed:
!>
!>    (1)     0 if T is in Schur form, 1/ulp otherwise
!>           (no sorting of eigenvalues)
!>
!>    (2)     | A - VS T VS' | / ( n |A| ulp )
!>
!>      Here VS is the matrix of Schur eigenvectors, and T is in Schur
!>      form  (no sorting of eigenvalues).
!>
!>    (3)     | I - VS VS' | / ( n ulp ) (no sorting of eigenvalues).
!>
!>    (4)     0     if W are eigenvalues of T
!>            1/ulp otherwise
!>            (no sorting of eigenvalues)
!>
!>    (5)     0     if T(with VS) = T(without VS),
!>            1/ulp otherwise
!>            (no sorting of eigenvalues)
!>
!>    (6)     0     if eigenvalues(with VS) = eigenvalues(without VS),
!>            1/ulp otherwise
!>            (no sorting of eigenvalues)
!>
!>    (7)     0 if T is in Schur form, 1/ulp otherwise
!>            (with sorting of eigenvalues)
!>
!>    (8)     | A - VS T VS' | / ( n |A| ulp )
!>
!>      Here VS is the matrix of Schur eigenvectors, and T is in Schur
!>      form  (with sorting of eigenvalues).
!>
!>    (9)     | I - VS VS' | / ( n ulp ) (with sorting of eigenvalues).
!>
!>    (10)    0     if W are eigenvalues of T
!>            1/ulp otherwise
!>            (with sorting of eigenvalues)
!>
!>    (11)    0     if T(with VS) = T(without VS),
!>            1/ulp otherwise
!>            (with sorting of eigenvalues)
!>
!>    (12)    0     if eigenvalues(with VS) = eigenvalues(without VS),
!>            1/ulp otherwise
!>            (with sorting of eigenvalues)
!>
!>    (13)    if sorting worked and SDIM is the number of
!>            eigenvalues which were SELECTed
!>
!>    The matrix sizes are specified by an array NN(1:NSIZES); the value of
!>    each element NN(j) specifies one size.
!>    The matrix types are specified by a logical array DOTYPE( 1:NTYPES );
!>    if DOTYPE(j) is .TRUE., then matrix type j will be generated.
!>    Currently, the list of possible types is:
!>
!>    (1)  The zero matrix.
!>    (2)  The identity matrix.
!>    (3)  A (transposed) Jordan block, with 1's on the diagonal.
!>
!>    (4)  A diagonal matrix with evenly spaced entries
!>         1, ..., ULP  and random complex angles.
!>         (ULP = (first number larger than 1) - 1 )
!>    (5)  A diagonal matrix with geometrically spaced entries
!>         1, ..., ULP  and random complex angles.
!>    (6)  A diagonal matrix with  entries 1, ULP, ..., ULP
!>         and random complex angles.
!>
!>    (7)  Same as (4), but multiplied by a constant near
!>         the overflow threshold
!>    (8)  Same as (4), but multiplied by a constant near
!>         the underflow threshold
!>
!>    (9)  A matrix of the form  U' T U, where U is unitary and
!>         T has evenly spaced entries 1, ..., ULP with random
!>         complex angles on the diagonal and random O(1) entries in
!>         the upper triangle.
!>
!>    (10) A matrix of the form  U' T U, where U is unitary and
!>         T has geometrically spaced entries 1, ..., ULP with random
!>         complex angles on the diagonal and random O(1) entries in
!>         the upper triangle.
!>
!>    (11) A matrix of the form  U' T U, where U is orthogonal and
!>         T has  entries 1, ULP,..., ULP with random
!>         complex angles on the diagonal and random O(1) entries in
!>         the upper triangle.
!>
!>    (12) A matrix of the form  U' T U, where U is unitary and
!>         T has complex eigenvalues randomly chosen from
!>         ULP < |z| < 1   and random O(1) entries in the upper
!>         triangle.
!>
!>    (13) A matrix of the form  X' T X, where X has condition
!>         SQRT( ULP ) and T has evenly spaced entries 1, ..., ULP
!>         with random complex angles on the diagonal and random O(1)
!>         entries in the upper triangle.
!>
!>    (14) A matrix of the form  X' T X, where X has condition
!>         SQRT( ULP ) and T has geometrically spaced entries
!>         1, ..., ULP with random complex angles on the diagonal
!>         and random O(1) entries in the upper triangle.
!>
!>    (15) A matrix of the form  X' T X, where X has condition
!>         SQRT( ULP ) and T has  entries 1, ULP,..., ULP
!>         with random complex angles on the diagonal and random O(1)
!>         entries in the upper triangle.
!>
!>    (16) A matrix of the form  X' T X, where X has condition
!>         SQRT( ULP ) and T has complex eigenvalues randomly chosen
!>         from ULP < |z| < 1 and random O(1) entries in the upper
!>         triangle.
!>
!>    (17) Same as (16), but multiplied by a constant
!>         near the overflow threshold
!>    (18) Same as (16), but multiplied by a constant
!>         near the underflow threshold
!>
!>    (19) Nonsymmetric matrix with random entries chosen from (-1,1).
!>         If N is at least 4, all entries in first two rows and last
!>         row, and first column and last two columns are zero.
!>    (20) Same as (19), but multiplied by a constant
!>         near the overflow threshold
!>    (21) Same as (19), but multiplied by a constant
!>         near the underflow threshold
!>

okay so quick translation bestie: CGEES is the driver being tested — the nonsymmetric eigenvalue / Schur form one. You hand it a bunch of sizes, a bunch of matrix types, and for every combo it builds one matrix and then runs 13 tests on it. First six are the no sorting of eigenvalues era, next six are the with sorting of eigenvalues era, and lucky number thirteen is the sorting-actually-worked check where SDIM is the number of eigenvalues that were SELECTed 🎯

and the 21 matrix types? iconic lineup honestly. zero matrix, identity, transposed Jordan block with 1's on the diagonal, evenly/geometrically/clustered spaced diagonal ones, then the same energy scaled near the overflow and underflow thresholds, then the U' T U unitary squad, then the X' T X gang with condition SQRT( ULP ), and finally the random (-1,1) nonsymmetric ones (with the first two rows, last row, first column and last two columns zeroed out when N is at least 4, iykyk). All 21, no skips, we respect the whole roster 👑

🌸 Parameters

🦋 NSIZES

!>          NSIZES is INTEGER
!>          The number of sizes of matrices to use.  If it is zero,
!>          CDRVES does nothing.  It must be at least zero.
!>

so NSIZES is an INTEGER, it's literally how many sizes of matrices you wanna use. set it to zero and CDRVES does absolutely nothing (respect, honestly). it must be at least zero.

🦋 NN

!>          NN is INTEGER array, dimension (NSIZES)
!>          An array containing the sizes to be used for the matrices.
!>          Zero values will be skipped.  The values must be at least
!>          zero.
!>

NN is an INTEGER array, dimension (NSIZES), holding the actual sizes. zero values get skipped, and every value must be at least zero ✨

🦋 NTYPES

!>          NTYPES is INTEGER
!>          The number of elements in DOTYPE.   If it is zero, CDRVES
!>          does nothing.  It must be at least zero.  If it is MAXTYP+1
!>          and NSIZES is 1, then an additional type, MAXTYP+1 is
!>          defined, which is to use whatever matrix is in A.  This
!>          is only useful if DOTYPE(1:MAXTYP) is .FALSE. and
!>          DOTYPE(MAXTYP+1) is .TRUE. .
!>

NTYPES is an INTEGER — how many elements live in DOTYPE. zero again = CDRVES does nothing. must be at least zero. but here's the spicy part: if it's MAXTYP+1 and NSIZES is 1, then an extra type, MAXTYP+1, gets defined, and that one just uses whatever matrix is already sitting in A. this is only useful when DOTYPE(1:MAXTYP) is .FALSE. and DOTYPE(MAXTYP+1) is .TRUE. — like, very specific scenario, but okay we love a niche use case 💅

🦋 DOTYPE

!>          DOTYPE is LOGICAL array, dimension (NTYPES)
!>          If DOTYPE(j) is .TRUE., then for each size in NN a
!>          matrix of that size and of type j will be generated.
!>          If NTYPES is smaller than the maximum number of types
!>          defined (PARAMETER MAXTYP), then types NTYPES+1 through
!>          MAXTYP will not be generated.  If NTYPES is larger
!>          than MAXTYP, DOTYPE(MAXTYP+1) through DOTYPE(NTYPES)
!>          will be ignored.
!>

DOTYPE is a LOGICAL array, dimension (NTYPES). if DOTYPE(j) is .TRUE., then for each size in NN a matrix of that size and type j gets generated 🫶 and the rules: if NTYPES is smaller than the max number of types defined (PARAMETER MAXTYP), then types NTYPES+1 through MAXTYP are not generated. if NTYPES is larger than MAXTYP, then DOTYPE(MAXTYP+1) through DOTYPE(NTYPES) just get ignored. not me being dramatic about it, that's literally what it says 💀

🦋 ISEED

!>          ISEED is INTEGER array, dimension (4)
!>          On entry ISEED specifies the seed of the random number
!>          generator. The array elements should be between 0 and 4095;
!>          if not they will be reduced mod 4096.  Also, ISEED(4) must
!>          be odd.  The random number generator uses a linear
!>          congruential sequence limited to small integers, and so
!>          should produce machine independent random numbers. The
!>          values of ISEED are changed on exit, and can be used in the
!>          next call to CDRVES to continue the same random number
!>          sequence.
!>

ISEED is an INTEGER array, dimension (4) — the RNG seed, bestie 🌱 on entry it's the seed. the elements should be between 0 and 4095; if they're not, they get reduced mod 4096. also ISEED(4) must be odd (caveat, don't skip it 🙈). the generator uses a linear congruential sequence limited to small integers so it should produce machine independent random numbers — cute and portable. and the values of ISEED get changed on exit, so you can pass 'em into the next CDRVES call to continue the same random number sequence. continuity queen 👑

🦋 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.  It must be at least zero.
!>

THRESH is REAL. a test counts as failed if the error, computed as described above, exceeds THRESH 💀 the error is scaled to be O(1), so THRESH should be a reasonably small multiple of 1 — like 10 or 100. and like, in particular, it should not depend on the precision (single vs. double) or the size of the matrix. must be at least zero. read that twice, it's giving important ✨

🦋 NOUNIT

!>          NOUNIT is INTEGER
!>          The FORTRAN unit number for printing out error messages
!>          (e.g., if a routine returns INFO not equal to 0.)
!>

NOUNIT is an INTEGER — the FORTRAN unit number where error messages get printed. like, for example if a routine returns INFO not equal to 0 👀

🦋 A

!>          A is COMPLEX array, dimension (LDA, max(NN))
!>          Used to hold the matrix whose eigenvalues are to be
!>          computed.  On exit, A contains the last matrix actually used.
!>

A is a COMPLEX array, dimension (LDA, max(NN)) — holds the matrix whose eigenvalues are getting computed. on exit, A contains the last matrix actually used. main character matrix energy 💖

🦋 LDA

!>          LDA is INTEGER
!>          The leading dimension of A, and H. LDA must be at
!>          least 1 and at least max( NN ).
!>

LDA is an INTEGER — the leading dimension of A, and H. LDA must be at least 1 and at least max( NN ). both conditions, no picking favourites 🎀

🦋 H

!>          H is COMPLEX array, dimension (LDA, max(NN))
!>          Another copy of the test matrix A, modified by CGEES.
!>

H is a COMPLEX array, dimension (LDA, max(NN)) — another copy of the test matrix A, modified by CGEES. a little remix, if you will 🎧

🦋 HT

!>          HT is COMPLEX array, dimension (LDA, max(NN))
!>          Yet another copy of the test matrix A, modified by CGEES.
!>

HT is a COMPLEX array, dimension (LDA, max(NN)) — yet another copy of the test matrix A, modified by CGEES. yes bestie, a third one. we contain multitudes 🌈

🦋 W

🌸 and that's where part 1 wraps — W continues in part 2, don't you dare close the tab 💅

W — okay so bestie, this is a COMPLEX array, dimension (max(NN)). It's literally holding the computed eigenvalues of A. 💜
WT — also a COMPLEX array, dimension (max(NN)). Like W, this array contains the eigenvalues of A, but those computed when CGEES only computes a partial eigendecomposition, i.e. not Schur vectors. So it's the "partial" edition, no cap. ✨
VS — COMPLEX array, dimension (LDVS, max(NN)). VS holds the computed Schur vectors. Iconic behavior. 👑
LDVS — INTEGER. Leading dimension of VS. Must be at least max(1,max(NN)). Don't skimp on this, fr fr.
RESULT — REAL array, dimension (13). The values computed by the 13 tests described above. The values are currently limited to 1/ulp, to avoid overflow. So it's test results with a safety cap. 🛡️
WORK — COMPLEX array, dimension (NWORK). That's the workspace, bestie.
NWORK — INTEGER. The number of entries in WORK. This must be at least 5*NN(j)+2*NN(j)**2 for all j. That's the bare minimum, periodt.
RWORK — REAL array, dimension (max(NN)).
IWORK — INTEGER array, dimension (max(NN)).
BWORK — LOGICAL array, dimension (max(NN)).
INFO — INTEGER. If 0, then everything ran OK. 🎉 But if not, here's the tea:
- -1: NSIZES < 0
- -2: Some NN(j) < 0
- -3: NTYPES < 0
- -6: THRESH < 0
- -9: LDA < 1 or LDA < NMAX, where NMAX is max( NN(j) ).
- -15: LDVS < 1 or LDVS < NMAX, where NMAX is max( NN(j) ).
- -18: NWORK too small.
- If CLATMR, CLATMS, CLATME or CGEES returns an error code, the absolute value of it is returned.

🧮 Some Local Variables and Parameters:

---- ----- --------- --- ----------

ZERO, ONE — Real 0 and 1. The basics, bestie.
MAXTYP — The number of types defined.
NMAX — Largest value in NN.
NERRS — The number of tests which have exceeded THRESH.
COND, CONDS, IMODE — Values to be passed to the matrix generators.
ANORM — Norm of A; passed to matrix generators.
OVFL, UNFL — Overflow and underflow thresholds.
ULP, ULPINV — Finest relative precision and its inverse.
RTULP, RTULPI — Square roots of the previous 4 values.

The following four arrays decode JTYPE:

KTYPE(j) — The general type (1-10) for type .
KMODE(j) — The MODE value to be passed to the matrix generator for type .
KMAGN(j) — The order of magnitude ( O(1), O(overflow^(1/2) ), O(underflow^(1/2) )
KCONDS(j) — Select whether CONDS is to be 1 or 1/sqrt(ulp). (0 means irrelevant.)

👑 Author

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

Definition at line 375 of file cdrves.f.

👑 Author

Generated automatically by Doxygen for LAPACK from the source code.

✨ That's the whole page, bestie! This one's from LAPACK Version 3.12.0, file TESTING/EIG/cdrves.f(3) — and the date? The footer doesn't say, but honestly the vibes are timeless. 💅

📦 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