SCHKBD(3)

📦 version 3.12.0, in opensuse-leap 16.0

💖 SCHKBD(3) — schkbd.f, Library Functions Manual 💖

okay so welcome to the group chat for SCHKBD(3), bestie. This is the Library Functions Manual page for the file path below, and it is literally the LAPACK test routine for the SVD stack. ✨

🌸 NAME 🌸

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

✨ SYNOPSIS ✨

🫶 Functions/Subroutines 🫶

subroutine SCHKBD (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)
           SCHKBD

🧚 Function/Subroutine Documentation 🧚

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

🎯 Purpose 🎯

okay so SCHKBD checks the singular value decomposition (SVD) routines. It is not the main character doing the SVD itself — it is the bestie holding the clipboard and yelling “vibe check” at every routine. 👑

SGEBRD 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'). The matrix B is upper bidiagonal if m >= n and lower bidiagonal if m < n. 🦋

SORGBR generates the orthogonal matrices Q and P' from SGEBRD. Note that Q and P are not necessarily square. 💅

SBDSQR computes the singular value decomposition of the bidiagonal matrix B as B = U S V'. It is 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, SBDSQR has an option to apply the left orthogonal matrix U to a matrix X, useful in least squares applications. 😌

SBDSDC computes the singular value decomposition of the bidiagonal matrix B as B = U S V' using divide-and-conquer. It is 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.

SBDSVDX computes the singular value decomposition of the bidiagonal matrix B as B = U S V' using bisection and inverse iteration. It is 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.

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

For each generated matrix, 14 tests are performed:

🔥 Test SGEBRD and SORGBR 🔥

  • (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 SBDSQR 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 SSVDCH)

🌈 Test SBDSQR 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 SBDSDC 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 SBDSVDX 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 ) SBDSVDX('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 ) SBDSVDX('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 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 )

Special case: 💀

  • (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) SGEBRD 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.

A subset of the full set of matrix types may be selected through the logical array DOTYPE.

🎛 Parameters 🎛

🧸 NSIZES 🧸

NSIZES is INTEGER. It is 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). These are the values of the matrix row dimension M. 💫

🧸 NVAL 🧸

  • NVAL — NVAL is INTEGER array, dimension (NM)</p> and it holds the values of the matrix column dimension N. That's it, bestie, it's giving "just the N values" energy ✨
  • NTYPES — NTYPES is INTEGER and it's the number of elements in DOTYPE. If it's zero, SCHKBD does nothing. It must be at least zero. If it's MAXTYP+1 and NSIZES is 1, then an additional type, MAXTYP+1, is defined, which is to use whatever matrices are in A and B. This is only useful if DOTYPE(1:MAXTYP) is .FALSE. and DOTYPE(MAXTYP+1) is .TRUE. 🫶
  • DOTYPE — DOTYPE is LOGICAL array, dimension (NTYPES). If DOTYPE(j) is .TRUE., then for each size (m,n), a matrix 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. No cap, that's the rule 💅
  • NRHS — NRHS is INTEGER and it's the number of columns in the matrices X, Y, and Z, used in testing SBDSQR. If NRHS = 0, then the operations on the right-hand side will not be tested. NRHS must be at least 0. Zero means we're skipping the right-hand-side era 😌
  • 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 values of ISEED are changed on exit, and can be used in the next call to SCHKBD to continue the same random number sequence. RNG lore, fr fr 🎲
  • THRESH — THRESH is REAL and it's the threshold value for the test ratios. A result is included in the output file if RESULT >= THRESH. To have every 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, e.g., 10 or 100. Keep it cute and small, bestie 🌸
  • A — A is REAL array, dimension (LDA,NMAX) where NMAX is the maximum value of N in NVAL. Main character matrix energy 👑
  • LDA — LDA is INTEGER and it's the leading dimension of the array A. LDA >= max(1,MMAX), where MMAX is the maximum value of M in MVAL. Respect the leading dimension, okay? 💅
  • BD — BD is REAL array, dimension (max(min(MVAL(j),NVAL(j)))). Bidiagonal bestie, no notes 💜
  • BE — BE is REAL array, dimension (max(min(MVAL(j),NVAL(j)))). Same energy as BD, different name 🦋
  • S1 — S1 is REAL array, dimension (max(min(MVAL(j),NVAL(j)))). She's a real one ✨
  • S2 — S2 is REAL array, dimension (max(min(MVAL(j),NVAL(j)))). Sister of S1, slay 🎀
  • X — X is REAL array, dimension (LDX,NRHS). Right-hand-side icon behavior 🌈
  • LDX — LDX is INTEGER and it's the leading dimension of the arrays X, Y, and Z. LDX >= max(1,MMAX). One leading dimension to rule them all 😭
  • Y — Y is REAL array, dimension (LDX,NRHS). Another right-hand-side bestie, we love to see it 💖
  • Z — Z is REAL array, dimension (LDX,NRHS). Third one, completing the trio 👑
  • Q — Q is REAL array, dimension (LDQ,MMAX). Orthogonal-ish queen behavior, iykyk 🧚
  • LDQ — LDQ is INTEGER and it's the leading dimension of the array Q. LDQ >= max(1,MMAX). Don't forget it 💅
  • PT — PT is REAL array, dimension (LDPT,NMAX). She's giving transposed-pretty energy ✨
  • LDPT — LDPT is INTEGER and it's the leading dimension of the arrays PT, U, and V. LDPT >= max(1, max(min(MVAL(j),NVAL(j)))). Big leading-dimension energy 🔥
  • U — U is REAL array, dimension (LDPT,max(min(MVAL(j),NVAL(j)))). U are doing amazing, sweetie 💜
  • VT — VT is REAL array, dimension (LDPT,max(min(MVAL(j),NVAL(j)))). Transposed V, main character vibes 🦋
  • WORK — WORK is REAL array, dimension (LWORK). Workspace bestie, gotta have somewhere to put the math 🫶
  • LWORK — LWORK is INTEGER and it's 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)). Do not skip this, bestie, workspace math is real 😭
  • IWORK — IWORK is INTEGER array, dimension at least 8*min(M,N). Integer workspace, living her best life 💅
  • NOUT — NOUT is INTEGER and it's the FORTRAN unit number for printing out error messages (e.g., if a routine returns IINFO not equal to 0). Yes, IINFO, that's the one 🎀
  • INFO — INFO is INTEGER. If 0, then everything ran OK. The error codes are giving very specific, and we respect that:
    • -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.

If SLATMR, SLATMS, SGEBRD, SORGBR, or SBDSQR, returns an error code, the absolute value of it is returned. So yeah, negative numbers with lore 💀

🧚 Some Local Variables and Parameters 🧚

Okay bestie, these are the local variables and parameters — lore drop time 👑

  • ZERO, ONE — Real 0 and 1. Simple, iconic, foundational ✨
  • 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. Yes, NN, that's what it says 😭
  • NMAX — Largest value in NN. Again, NN. The page said it, not me 💀
  • 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 (yes, four — the page says four, and we're just carrying the message 🫶):

  • 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 schkbd.f.

🎀 Author (again, because Doxygen said so) 🎀

Generated automatically by Doxygen for LAPACK from the source code.

And that's the whole page, bestie — LAPACK Version 3.12.0, source /home/abui...IG/schkbd.f(3). Bye, ily, go test those matrices 💖✨

📦 where this page comes from