TESTING/EIG/dchkbd.f(3)

📦
version 3.12.1 · 2 versions
, in arch rolling

💅 TESTING/EIG/dchkbd.f — the dchkbd files (part 1)

okay so you found the man page for TESTING/EIG/dchkbd.f and honestly? she's a whole testing legend. let's get into it 🦋

✨ NAME ✨

TESTING/EIG/dchkbd.f — bestie, that's the file. that's the whole name. short, sweet, iconic 👑

🎀 SYNOPSIS 🎀

Functions/Subroutines

  • subroutine dchkbd — the main character herself:
subroutine dchkbd (nsizes, mval, nval, ntypes, dotype, nrhs, iseed,
    thresh, a, lda, bd, be, s1, s2, x, ldx, y, z, q, ldq, pt, ldpt, u,
    vt, work, lwork, iwork, nout, info)

DCHKBD

🌸 Function/Subroutine Documentation 🌸

💜 subroutine dchkbd

here's the full signature, every single argument, no cap, not one of them dropped:

subroutine dchkbd (integer nsizes, integer, dimension( * ) mval, integer,
    dimension( * ) nval, integer ntypes, logical, dimension( * ) dotype,
    integer nrhs, integer, dimension( 4 ) iseed, double precision thresh,
    double precision, dimension( lda, * ) a, integer lda, double precision,
    dimension( * ) bd, double precision, dimension( * ) be, double
    precision, dimension( * ) s1, double precision, dimension( * ) s2,
    double precision, dimension( ldx, * ) x, integer ldx, double precision,
    dimension( ldx, * ) y, double precision, dimension( ldx, * ) z, double
    precision, dimension( ldq, * ) q, integer ldq, double precision,
    dimension( ldpt, * ) pt, integer ldpt, double precision, dimension(
    ldpt, * ) u, double precision, dimension( ldpt, * ) vt, double
    precision, dimension( * ) work, integer lwork, integer, dimension( * )
    iwork, integer nout, integer info)

DCHKBD

🔥 Purpose 🔥

so. what does DCHKBD actually do? she checks the singular value decomposition (SVD) routines. that's the whole vibe check 💅

DGEBRD reduces a real general m by n matrix A to upper or lower bidiagonal form B by an orthogonal transformation: Q' * A * P = B (or A = Q * B * P'). and the tea is: B is upper bidiagonal if m >= n and lower bidiagonal if m < n. periodt.

DORGBR generates the orthogonal matrices Q and P' from DGEBRD. slight plot twist though — note that Q and P are not necessarily square 🫶

DBDSQR computes the singular value decomposition of the bidiagonal matrix B as B = U S V'. it gets called three times to compute:

  1. B = U S1 V', where S1 is the diagonal matrix of singular values and the columns of the matrices U and V are the left and right singular vectors, respectively, of B.
  2. Same as 1), but the singular values are stored in S2 and the singular vectors are not computed.
  3. A = (UQ) S (P'V'), the SVD of the original matrix A.

in addition, DBDSQR has an option to apply the left orthogonal matrix U to a matrix X, useful in least squares applications. very "i contain multitudes" of it 💀

DBDSDC computes the singular value decomposition of the bidiagonal matrix B as B = U S V' using divide-and-conquer. it gets called twice to compute:

  1. B = U S1 V', where S1 is the diagonal matrix of singular values and the columns of the matrices U and V are the left and right singular vectors, respectively, of B.
  2. Same as 1), but the singular values are stored in S2 and the singular vectors are not computed.

DBDSVDX computes the singular value decomposition of the bidiagonal matrix B as B = U S V' using bisection and inverse iteration. it gets called six times to compute:

  1. B = U S1 V', RANGE='A', where S1 is the diagonal matrix of singular values and the columns of the matrices U and V are the left and right singular vectors, respectively, of B.
  2. Same as 1), but the singular values are stored in S2 and the singular vectors are not computed.
  3. B = U S1 V', RANGE='I', with where S1 is the diagonal matrix of singular values and the columns of the matrices U and V are the left and right singular vectors, respectively, of B
  4. Same as 3), but the singular values are stored in S2 and the singular vectors are not computed.
  5. B = U S1 V', RANGE='V', with where S1 is the diagonal matrix of singular values and the columns of the matrices U and V are the left and right singular vectors, respectively, of B
  6. Same as 5), but the singular values are stored in S2 and the singular vectors are not computed.

🌈 the setup — dimensions, bestie 🌈

for each pair of matrix dimensions (M,N) and each selected matrix type, an M by N matrix A and an M by NRHS matrix X are generated. the problem dimensions are as follows:

A:          M x N
Q:          M x min(M,N) (but M x M if NRHS > 0)
P:          min(M,N) x N
B:          min(M,N) x min(M,N)
U, V:       min(M,N) x min(M,N)
S1, S2      diagonal, order min(M,N)
X:          M x NRHS

⭐ the 14 tests ⭐

for each generated matrix, 14 tests are performed (yes she says 14, and yes there are more below — she contains multitudes, don't come for her 😭).

Test DGEBRD and DORGBR

(1)   | A - Q B PT | / ( |A| max(M,N) ulp ), PT = P'

(2)   | I - Q' Q | / ( M ulp )

(3)   | I - PT PT' | / ( N ulp )

Test DBDSQR on bidiagonal matrix B

(4)   | B - U S1 VT | / ( |B| min(M,N) ulp ), VT = V'

(5)   | Y - U Z | / ( |Y| max(min(M,N),k) ulp ), where Y = Q' X
                                                 and   Z = U' Y.
(6)   | I - U' U | / ( min(M,N) ulp )

(7)   | I - VT VT' | / ( min(M,N) ulp )

(8)   S1 contains min(M,N) nonnegative values in decreasing order.
      (Return 0 if true, 1/ULP if false.)

(9)   | S1 - S2 | / ( |S1| ulp ), where S2 is computed without
                                  computing U and V.

(10)  0 if the true singular values of B are within THRESH of
      those in S1.  2*THRESH if they are not.  (Tested using
      DSVDCH)

Test DBDSQR on matrix A

(11)  | A - (QU) S (VT PT) | / ( |A| max(M,N) ulp )

(12)  | X - (QU) Z | / ( |X| max(M,k) ulp )

(13)  | I - (QU)'(QU) | / ( M ulp )

(14)  | I - (VT PT) (PT'VT') | / ( N ulp )

Test DBDSDC on bidiagonal matrix B

(15)  | B - U S1 VT | / ( |B| min(M,N) ulp ), VT = V'

(16)  | I - U' U | / ( min(M,N) ulp )

(17)  | I - VT VT' | / ( min(M,N) ulp )

(18)  S1 contains min(M,N) nonnegative values in decreasing order.
      (Return 0 if true, 1/ULP if false.)

(19)  | S1 - S2 | / ( |S1| ulp ), where S2 is computed without
                                  computing U and V.

Test DBDSVDX on bidiagonal matrix B

(20)  | B - U S1 VT | / ( |B| min(M,N) ulp ), VT = V'

(21)  | I - U' U | / ( min(M,N) ulp )

(22)  | I - VT VT' | / ( min(M,N) ulp )

(23)  S1 contains min(M,N) nonnegative values in decreasing order.
      (Return 0 if true, 1/ULP if false.)

(24)  | S1 - S2 | / ( |S1| ulp ), where S2 is computed without
                                  computing U and V.

(25)  | S1 - U' B VT' | / ( |S| n ulp )    DBDSVDX('V', 'I')

(26)  | I - U' U | / ( min(M,N) ulp )

(27)  | I - VT VT' | / ( min(M,N) ulp )

(28)  S1 contains min(M,N) nonnegative values in decreasing order.
      (Return 0 if true, 1/ULP if false.)

(29)  | S1 - S2 | / ( |S1| ulp ), where S2 is computed without
                                  computing U and V.

(30)  | S1 - U' B VT' | / ( |S1| n ulp )   DBDSVDX('V', 'V')

(31)  | I - U' U | / ( min(M,N) ulp )

(32)  | I - VT VT' | / ( min(M,N) ulp )

(33)  S1 contains min(M,N) nonnegative values in decreasing order.
      (Return 0 if true, 1/ULP if false.)

(34)  | S1 - S2 | / ( |S1| ulp ), where S2 is computed without
                                  computing U and V.

🧚 the matrix types — all sixteen of them 🧚

the possible matrix types are:

(1)  The zero matrix.
(2)  The identity matrix.

(3)  A diagonal matrix with evenly spaced entries
     1, ..., ULP  and random signs.
     (ULP = (first number larger than 1) - 1 )
(4)  A diagonal matrix with geometrically spaced entries
     1, ..., ULP  and random signs.
(5)  A diagonal matrix with  entries 1, ULP, ..., ULP
     and random signs.

(6)  Same as (3), but multiplied by SQRT( overflow threshold )
(7)  Same as (3), but multiplied by SQRT( underflow threshold )

(8)  A matrix of the form  U D V, where U and V are orthogonal and
     D has evenly spaced entries 1, ..., ULP with random signs
     on the diagonal.

(9)  A matrix of the form  U D V, where U and V are orthogonal and
     D has geometrically spaced entries 1, ..., ULP with random
     signs on the diagonal.

(10) A matrix of the form  U D V, where U and V are orthogonal and
     D has  entries 1, ULP,..., ULP with random
     signs on the diagonal.

(11) Same as (8), but multiplied by SQRT( overflow threshold )
(12) Same as (8), but multiplied by SQRT( underflow threshold )

(13) Rectangular matrix with random entries chosen from (-1,1).
(14) Same as (13), but multiplied by SQRT( overflow threshold )
(15) Same as (13), but multiplied by SQRT( underflow threshold )

and then there's the special case, she's got her own rules 👑:

(16) A bidiagonal matrix with random entries chosen from a
     logarithmic distribution on [ulp^2,ulp^(-2)]  (I.e., each
     entry is  e^x, where x is chosen uniformly on
     [ 2 log(ulp), -2 log(ulp) ] .)  For *this* type:
     (a) DGEBRD is not called to reduce it to bidiagonal form.
     (b) the bidiagonal is  min(M,N) x min(M,N); if M<N, the
         matrix will be lower bidiagonal, otherwise upper.
     (c) only tests 5--8 and 14 are performed.
🫶 heads up: a subset of the full set of matrix types may be selected through the logical array DOTYPE. you don't have to run all of them, bestie, you get to pick.

💖 Parameters 💖

NSIZES

NSIZES is INTEGER The number of values of M and N contained in the vectors MVAL and NVAL. The matrix sizes are used in pairs (M,N).

MVAL

MVAL is INTEGER array, dimension (NM) The values of the matrix row dimension M.

NVAL

  • NVAL — INTEGER array, dimension (NM). It's the values of the matrix column dimension N. 💫
  • NTYPES — INTEGER. The number of elements in DOTYPE. If it's zero, DCHKBD literally does nothing (slay, a no-op queen). It must be at least zero. If it's MAXTYP+1 and NSIZES is 1, then an extra type MAXTYP+1 gets defined — that one means "just use whatever matrices are already sitting in A and B". Ngl that's only useful when DOTYPE(1:MAXTYP) is .FALSE. and DOTYPE(MAXTYP+1) is .TRUE.. 🎀
  • DOTYPE — LOGICAL array, dimension (NTYPES). If DOTYPE(j) is .TRUE., then for each size (m,n) a matrix of type j gets generated. If NTYPES is smaller than the max number of types defined (PARAMETER MAXTYP), then types NTYPES+1 through MAXTYP don't get generated at all. And if NTYPES is larger than MAXTYP, then DOTYPE(MAXTYP+1) through DOTYPE(NTYPES) get straight-up ignored. 🫥
  • NRHS — INTEGER. The number of columns in the matrices X, Y, and Z, used in testing DBDSQR. If NRHS = 0, then the operations on the right-hand side don't get tested. NRHS must be at least 0.
  • ISEED — 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 they're not, they get reduced mod 4096. Also ISEED(4) must be odd, no cap. The values of ISEED are changed on exit and can be used in the next call to DCHKBD to continue the same random number sequence. 🎲✨
  • THRESH — DOUBLE PRECISION. The threshold value for the test ratios. A result gets included in the output file if RESULT >= THRESH. Want every single test ratio printed? Use THRESH = 0. Note that the expected value of the test ratios is O(1), so THRESH should be a reasonably small multiple of 1, like 10 or 100.
  • A — DOUBLE PRECISION array, dimension (LDA,NMAX) where NMAX is the maximum value of N in NVAL.
  • LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,MMAX), where MMAX is the maximum value of M in MVAL.
  • BD — DOUBLE PRECISION array, dimension
(max(min(MVAL(j),NVAL(j))))
  • BE — DOUBLE PRECISION array, dimension
(max(min(MVAL(j),NVAL(j))))
  • S1 — DOUBLE PRECISION array, dimension
(max(min(MVAL(j),NVAL(j))))
  • S2 — DOUBLE PRECISION array, dimension
(max(min(MVAL(j),NVAL(j))))
  • X — DOUBLE PRECISION array, dimension (LDX,NRHS).
  • LDX — INTEGER. The leading dimension of the arrays X, Y, and Z. LDX >= max(1,MMAX). 🦋
  • Y — DOUBLE PRECISION array, dimension (LDX,NRHS).
  • Z — DOUBLE PRECISION array, dimension (LDX,NRHS).
  • Q — DOUBLE PRECISION array, dimension (LDQ,MMAX).
  • LDQ — INTEGER. The leading dimension of the array Q. LDQ >= max(1,MMAX).
  • PT — DOUBLE PRECISION array, dimension (LDPT,NMAX).
  • LDPT — INTEGER. The leading dimension of the arrays PT, U, and V. LDPT >= max(1, max(min(MVAL(j),NVAL(j)))).
  • U — DOUBLE PRECISION array, dimension
(LDPT,max(min(MVAL(j),NVAL(j))))
  • VT — DOUBLE PRECISION array, dimension
(LDPT,max(min(MVAL(j),NVAL(j))))
  • WORK — DOUBLE PRECISION array, dimension (LWORK).
  • LWORK — INTEGER. The number of entries in WORK. This must be at least 3(M+N) and M(M + max(M,N,k) + 1) + N*min(M,N) for all pairs (M,N)=(MM(j),NN(j)). 👑
  • IWORK — INTEGER array, dimension at least 8*min(M,N).
  • NOUT — INTEGER. The FORTRAN unit number for printing out error messages — like, if a routine returns IINFO not equal to 0, bestie, that's where it goes.
  • INFO — INTEGER. If 0, then everything ran OK. 💖 Otherwise:
    • -1: NSIZES < 0
    • -2: Some MM(j) < 0
    • -3: Some NN(j) < 0
    • -4: NTYPES < 0
    • -6: NRHS < 0
    • -8: THRESH < 0
    • -11: LDA < 1 or LDA < MMAX, where MMAX is max( MM(j) )
    • -17: LDB < 1 or LDB < MMAX
    • -21: LDQ < 1 or LDQ < MMAX
    • -23: LDPT< 1 or LDPT< MNMAX
    • -27: LWORK too small

And if DLATMR, SLATMS, DGEBRD, DORGBR, or DBDSQR returns an error code, the absolute value of it is what comes back. 😭

🧚 Some Local Variables and Parameters 🧚

Like, the internal lore, iykyk:

  • ZERO, ONE — Real 0 and 1.
  • MAXTYP — The number of types defined.
  • NTEST — The number of tests performed, or which can be performed so far, for the current matrix.
  • MMAX — Largest value in NN.
  • NMAX — Largest value in NN.
  • MNMIN — min(MM(j), NN(j)) (the dimension of the bidiagonal matrix).
  • MNMAX — The maximum value of MNMIN for j=1,...,NSIZES.
  • NFAIL — The number of tests which have exceeded THRESH.
  • COND, IMODE — Values to be passed to the matrix generators.
  • ANORM — Norm of A; passed to matrix generators.
  • OVFL, UNFL — Overflow and underflow thresholds.
  • RTOVFL, RTUNFL — Square roots of the previous 2 values.
  • ULP, ULPINV — Finest relative precision and its inverse.

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

🌸 Author 🌸

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

Definition at line 489 of file dchkbd.f.

👑 Author 👑

Generated automatically by Doxygen for LAPACK from the source code. Not a human, just vibes and a build script. 💀

ok that's the whole page bestie, go forth and test those bidiagonal routines 💅

mwah 💖 this was LAPACK Version 3.12.0, page TESTING/EIG/dchkbd.f(3) — catch you in the next manpage, periodt. 🎀✨

📦 where this page comes from