/home/abui.../sbdsvdx.f(3)

🎀 NAME 🎀

okay so this is the Library Functions Manual page for SBDSVDX, bestie — the file it's documenting is literally:

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/sbdsvdx.f

That path is the whole NAME section, no cap. 💅

✨ SYNOPSIS ✨

💅 Functions/Subroutines

Here's the callable icon in all its glory:

subroutine SBDSVDX (uplo, jobz, range, n, d, e, vl, vu, il, iu, ns, s,
    z, ldz, work, iwork, info)
    SBDSVDX

🛠️ Function/Subroutine Documentation

🌸 subroutine SBDSVDX (...)

Full signature, character for character:

subroutine SBDSVDX (character uplo, character jobz, character range, integer
    n, real, dimension( * ) d, real, dimension( * ) e, real vl, real vu,
    integer il, integer iu, integer ns, real, dimension( * ) s, real,
    dimension( ldz, * ) z, integer ldz, real, dimension( * ) work, integer,
    dimension( * ) iwork, integer info)
    SBDSVDX

🔥 Purpose:

okay bestie, SBDSVDX is here to compute the singular value decomposition (SVD) of a real N-by-N (upper or lower) bidiagonal matrix B, where B = U * S * VT. In this glow-up, S is a diagonal matrix with non-negative diagonal elements (the singular values of B), and U and VT are orthogonal matrices of left and right singular vectors, respectively. ✨

If you give it an upper bidiagonal B with diagonal D = [ d_1 d_2 ... d_N ] and superdiagonal E = [ e_1 e_2 ... e_N-1 ], SBDSVDX computes the singular value decomposition of B through the eigenvalues and eigenvectors of the N*2-by-N*2 tridiagonal matrix:

       |  0  d_1                |
       | d_1  0  e_1            |
 TGK = |     e_1  0  d_2        |
       |         d_2  .   .     |
       |              .   .   . |

If (s,u,v) is a singular triplet of B with ||u|| = ||v|| = 1, then (+/-s,q), ||q|| = 1, are eigenpairs of TGK, with:

q = P * ( u' +/-v' ) / sqrt(2) = ( v_1 u_1 v_2 u_2 ... v_n u_n ) / sqrt(2)

and

P = [ e_{n+1} e_{1} e_{n+2} e_{2} ... ]

Given a TGK matrix, you've got two paths, bestie: a) compute -s,-v and change signs so that the singular values (and corresponding vectors) are already in descending order (as in SGESVD/SGESDD), or b) compute s,v and reorder the values (and corresponding vectors). SBDSVDX implements a) by calling SSTEVX (bisection plus inverse iteration, to be replaced with a version of the Multiple Relative Robust Representation algorithm. (See P. Willems and B. Lang, A framework for the MR^3 algorithm: theory and implementation, SIAM J. Sci. Comput., 35:740-766, 2013.))

🍓 Parameters

• UPLO — UPLO is CHARACTER*1 💖
  • = 'U': B is upper bidiagonal;
  • = 'L': B is lower bidiagonal.
• JOBZ — JOBZ is CHARACTER*1 ✨
  • = 'N': Compute singular values only;
  • = 'V': Compute singular values and singular vectors.
• RANGE — RANGE is CHARACTER*1 🎀
  • = 'A': all singular values will be found.
  • = 'V': all singular values in the half-open interval [VL,VU) will be found.
  • = 'I': the IL-th through IU-th singular values will be found.
• N — N is INTEGER — the order of the bidiagonal matrix. N >= 0. 👑
• D — D is REAL array, dimension (N) — the n diagonal elements of the bidiagonal matrix B. 🦋
• E — E is REAL array, dimension (max(1,N-1)) — the (n-1) superdiagonal elements of the bidiagonal matrix B in elements 1 to N-1. 🌸
• VL — VL is REAL — if RANGE='V', the lower bound of the interval to be searched for singular values. VU > VL. Not referenced if RANGE = 'A' or 'I'. ⭐
• VU — VU is REAL — if RANGE='V', the upper bound of the interval to be searched for singular values. VU > VL. Not referenced if RANGE = 'A' or 'I'. 💜
• IL — IL is INTEGER — if RANGE='I', the index of the smallest singular value to be returned. 1 <= IL <= IU <= min(M,N), if min(M,N) > 0. Not referenced if RANGE = 'A' or 'V'. 🔥
• IU — IU is INTEGER — if RANGE='I', the index of the largest singular value to be returned. 1 <= IL <= IU <= min(M,N), if min(M,N) > 0. Not referenced if RANGE = 'A' or 'V'. 💅
• NS — NS is INTEGER — the total number of singular values found. 0 <= NS <= N. If RANGE = 'A', NS = N, and if RANGE = 'I', NS = IU-IL+1. 🍓
• S — S is REAL array, dimension (N) — the first NS elements contain the selected singular values in ascending order. 🌈
• Z — Z is REAL array, dimension (2*N,K) — if JOBZ = 'V', then if INFO = 0 the first NS columns of Z contain the singular vectors of the matrix B corresponding to the selected singular values, with U in rows 1 to N and V in rows N+1 to N*2, i.e.

Z = [ U ]
    [ V ]

If JOBZ = 'N', then Z is not referenced.

Note: The user must ensure that at least K = NS+1 columns are supplied in the array Z; if RANGE = 'V', the exact value of NS is not known in advance and an upper bound must be used. 🫶

• LDZ — LDZ is INTEGER — the leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(2,N*2). 🌟
• WORK — WORK is REAL array, dimension (14*N) — that's the whole description, bestie, no extra lore. 🧚
• IWORK — IWORK is INTEGER array, dimension (12*N) — if JOBZ = 'V', then if INFO = 0, the first NS elements of IWORK are zero. If INFO > 0, then IWORK contains the indices of the eigenvectors that failed to converge in DSTEVX. 👀
• INFO — INFO is INTEGER — the exit-status tea is:

= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, then i eigenvectors failed to converge
         in SSTEVX. The indices of the eigenvectors
         (as returned by SSTEVX) are stored in the
         array IWORK.
      if INFO = N*2 + 1, an internal error occurred.

👑 Author

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

Definition at line 224 of file sbdsvdx.f.

🫶 Author

Generated automatically by Doxygen for LAPACK from the source code.

---

xoxo, your LAPACK bestie 💖 — this footer vibe is LAPACK Version 3.12.0, source file /home/abui.../sbdsvdx.f(3). No separate date is printed on this page, so I'm not gonna manifest one. ✨