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

💅 NAME

okay so bestie, this is the manual page for /home/abui.../zunbdb3.f(3) — it lives in the Library Functions Manual, and it's all about a Fortran subroutine called ZUNBDB3 from the LAPACK source at /home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/zunbdb3.f. Yes that path is a whole meal, we're moving on 🫶

---

✨ SYNOPSIS

So under Functions/Subroutines you've got this icon:

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

---

🎀 Function/Subroutine Documentation

the actual signature (full version, no cuts) 🌸

subroutine ZUNBDB3 (integer m, integer p, integer q, complex*16,
    dimension(ldx11,*) x11, integer ldx11, complex*16, dimension(ldx21,*)
    x21, integer ldx21, double precision, dimension(*) theta, double
    precision, dimension(*) phi, complex*16, dimension(*) taup1, complex*16,
    dimension(*) taup2, complex*16, dimension(*) tauq1, complex*16,
    dimension(*) work, integer lwork, integer info)
    ZUNBDB3

---

Purpose 💖

!> !> ZUNBDB3 simultaneously bidiagonalizes the blocks of a tall and skinny !> matrix X with orthonormal columns: !> !> [ B11 ] !> [ X11 ] [ P1 | ] [ 0 ] !> [-----] = [---------] [-----] Q1**T . !> [ X21 ] [ | P2 ] [ B21 ] !> [ 0 ] !> !> X11 is P-by-Q, and X21 is (M-P)-by-Q. M-P must be no larger than P, !> Q, or M-Q. Routines ZUNBDB1, ZUNBDB2, and ZUNBDB4 handle cases in !> which M-P is not the minimum dimension. !> !> The unitary matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), !> and (M-Q)-by-(M-Q), respectively. They are represented implicitly by !> Householder vectors. !> !> B11 and B12 are (M-P)-by-(M-P) bidiagonal matrices represented !> implicitly by angles THETA, PHI. !> !>

(and yes, it literally says B12 up there — that's what the source says, not me, don't come for me 💀)

Like, the whole vibe is: you hand it a tall skinny matrix X with orthonormal columns, and it goes bidiagonalizes the blocks — that's the main character move 👑 The M-P situation has to be the minimum dimension. If it's not? Then this routine is not the one, and you go hang out with ZUNBDB1, ZUNBDB2, or ZUNBDB4 instead. iykyk ✨

---

Parameters 🦋

• M — INTEGER. It's literally the number of rows of X11 plus the number of rows in X21. Math? Served. 💅
• P — INTEGER. The number of rows in X11. Constraint, no cap: 0 <= P <= M and M-P <= min(P,Q,M-Q).
• Q — INTEGER. The number of columns in X11 and X21. Constraint: 0 <= Q <= M. 🎀
• X11 — COMPLEX*16 array, dimension (LDX11,Q). On entry it's the top block of the matrix X you're reducing. On exit, the columns of tril(X11) specify reflectors for P1, and the rows of triu(X11,1) specify reflectors for Q1. It goes in one thing and comes out a whole different thing, glow-up fr fr ✨
• LDX11 — INTEGER. The leading dimension of X11. Rule: LDX11 >= P. Respect the dimension bestie 🫶
• X21 — COMPLEX*16 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. Same deal, different block 🌸
• LDX21 — INTEGER. The leading dimension of X21. Rule: LDX21 >= M-P. 👑
• THETA — DOUBLE PRECISION array, dimension (Q). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details below, it's giving lore 🔥
• PHI — DOUBLE PRECISION array, dimension (Q-1). Again: the entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. Further Details, bestie, go look 🌈
• TAUP1 — COMPLEX*16 array, dimension (P). The scalar factors of the elementary reflectors that define P1. Iconic little scalars 💜
• TAUP2 — COMPLEX*16 array, dimension (M-P). The scalar factors of the elementary reflectors that define P2. Matching set 🎀
• TAUQ1 — COMPLEX*16 array, dimension (Q). The scalar factors of the elementary reflectors that define Q1. Completing the trio 💅
• WORK — COMPLEX*16 array, dimension (LWORK). It works so WORK can work 😭
• LWORK — INTEGER. The dimension of the array WORK. Rule: LWORK >= M-Q.

okay important caveat 🚨 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 -1 is the "just tell me how much room I need" era, and nobody yells at you. 🙈

• INFO — INTEGER. The receipts:
  • = 0: successful exit. slay 🎉
  • < 0: if INFO = -i, the i-th argument had an illegal value. somebody passed something cursed 💀

---

Author 🌿

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

(the whole squad, credited, periodt 🫶)

---

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. See [1] or ZUNCSD for details. !> !> P1, P2, and Q1 are represented as products of elementary reflectors. !> See ZUNCSD2BY1 for details on generating P1, P2, and Q1 using ZUNGQR !> and ZUNGLQ. !>

so basically every entry in each bidiagonal band is a sine-or-cosine of a THETA times a sine-or-cosine of a PHI — trig girlies stay winning 🧚 And if you wanna actually generate P1, P2, Q1, you're hitting up ZUNCSD2BY1 for the instructions on ZUNGQR and ZUNGLQ. iykyk ⭐

---

References 📚

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

(cite your sources, it's the bare minimum 💅)

---

Definition at line 199 of file zunbdb3.f. — that's where the real code lives, go look if you're nosy 🔍

---

author note: generated automatically by Doxygen for LAPACK from the source code 🎀

✨ and that's the whole page bestie — LAPACK Version 3.12.0, /home/abui.../zunbdb3.f(3), no notes, ate and left no crumbs 👑💖