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

💅 NAME 💅

ok so this is /home/abui.../cunbdb2.f(3), straight out of the Library Functions Manual — girl, it's a whole LAPACK source file path, no cap: /home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/cunbdb2.f. That's the file. That's the name. Iconic. 🎀

---

✨ SYNOPSIS ✨

🦋 Functions/Subroutines

subroutine CUNBDB2 (m, p, q, x11, ldx11, x21, ldx21, theta, phi, taup1,
    taup2, tauq1, work, lwork, info)

CUNBDB2 — that's her. That's the main character. 👑

---

🧚 Function/Subroutine Documentation 🧚

subroutine CUNBDB2 (integer m, integer p, integer q, complex,
    dimension(ldx11,*) x11, integer ldx11, complex, dimension(ldx21,*) x21,
    integer ldx21, real, dimension(*) theta, real, dimension(*) phi,
    complex, dimension(*) taup1, complex, dimension(*) taup2, complex,
    dimension(*) tauq1, complex, dimension(*) work, integer lwork, integer
    info)

🌸 Purpose: 🌸

okok so here's the vibe — CUNBDB2 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X that has orthonormal columns:

                       [ B11 ]
     [ X11 ]   [ P1 |    ] [  0  ]
     [-----] = [---------] [-----] Q1**T .
     [ X21 ]   [    | P2 ] [ B21 ]
                           [  0  ]

so X11 is P-by-Q, and X21 is (M-P)-by-Q. and P must be no larger than M-P, Q, or M-Q. like, that's the rule bestie, don't fight it. the routines CUNBDB1, CUNBDB3, and CUNBDB4 handle the cases where P is not the minimum dimension (they're the understudies for that particular situation, iykyk).

the unitary matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), and (M-Q)-by-(M-Q), respectively. they're represented implicitly by Householder vectors — which is giving very "we don't store the whole thing, we store the glow-up instructions" energy. ✨

B11 and B12 are P-by-P bidiagonal matrices represented implicitly by angles THETA, PHI.

---

💖 Parameters 💖

• M — M is INTEGER. it's the number of rows in X11 plus the number of rows in X21. the whole height, basically.
• P — P is INTEGER. the number of rows in X11. and the constraint is 0 <= P <= min(M-P,Q,M-Q). respect the bounds bestie, the routine will literally check. 😭
• Q — Q is INTEGER. the number of columns in X11 and X21 (both of them, same Q, we love a shared variable). 0 <= Q <= M.
• X11 — X11 is COMPLEX array, dimension (LDX11,Q). On entry, it's the top block of the matrix X to be reduced. On exit, the columns of tril(X11) specify reflectors for P1, and the rows of triu(X11,1) specify reflectors for Q1. so it comes in as data and leaves as instructions. slay. 💅
• LDX11 — LDX11 is INTEGER. the leading dimension of X11. and the rule is LDX11 >= P. non-negotiable.
• X21 — X21 is COMPLEX array, dimension (LDX21,Q). On entry, the bottom block of the matrix X to be reduced. On exit, the columns of tril(X21) specify reflectors for P2. (just P2 bestie, no Q1 in this one.)
• LDX21 — LDX21 is INTEGER. the leading dimension of X21, and LDX21 >= M-P. 🫶
• THETA — THETA is REAL array, dimension (Q). the entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details (spoiler: it's down there 👀).
• PHI — PHI is REAL array, dimension (Q-1). note the Q-1, that's not a typo, that's canon. the entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
• TAUP1 — TAUP1 is COMPLEX array, dimension (P-1). the scalar factors of the elementary reflectors that define P1.
• TAUP2 — TAUP2 is COMPLEX array, dimension (Q). the scalar factors of the elementary reflectors that define P2.
• TAUQ1 — TAUQ1 is COMPLEX array, dimension (Q). the scalar factors of the elementary reflectors that define Q1.
• WORK — WORK is COMPLEX array, dimension (LWORK). just a workspace array, living its life.
• LWORK — LWORK is INTEGER. the dimension of the array WORK. and LWORK >= M-Q.

🚨 okay this part matters: If LWORK = -1, then a workspace query is assumed — the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. so it's like a little "hey how much room do I need" side quest instead of doing the whole job.

• INFO — INFO is INTEGER.
  • = 0: successful exit. we love to see it. ✅
  • < 0: if INFO = -i, the i-th argument had an illegal value. uh oh. 💀

---

👑 Author 👑

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

(the whole squad gets credit, as they should 🫶)

---

🔥 Further Details: 🔥

the upper-bidiagonal blocks B11, B21 are represented implicitly by angles THETA(1), ..., THETA(Q) and PHI(1), ..., PHI(Q-1). every entry in each bidiagonal band is a product of a sine or cosine of a THETA with a sine or cosine of a PHI. like it's all trig all the way down bestie. See [1] or CUNCSD for details.

P1, P2, and Q1 are represented as products of elementary reflectors. See CUNCSD2BY1 for details on generating P1, P2, and Q1 using CUNGQR and CUNGLQ. 🦋

---

⭐ References: ⭐

[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.

---

Definition at line 200 of file cunbdb2.f. (yes, line 200, mark it, it's a whole vibe check)

---

🌈 Author (the meta one) 🌈

Generated automatically by Doxygen for LAPACK from the source code. so nobody hand-wrote this one, it's a bot doing its little thing. 🤖✨

---

💜 ok bye bestie, that's the whole page — <rainbow>LAPACK Version 3.12.0</rainbow>, and this cutie came from /home/abui.../cunbdb2.f(3). go bidiagonalize something. periodt. 💅🎀