unbdb4(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

✨ NAME ✨

okay so bestie, this page is unbdb4(3) and it documents {un,or}bdb4, which is literally a step in uncsd2by1. that's the name, that's the whole vibe. short and iconic. 💅

🎀 SYNOPSIS 🎀

Functions

these are the four glow-ups of the same routine, one per precision/flavour. all of them have the exact same argument list, no cap:

subroutine cunbdb4 (m, p, q, x11, ldx11, x21, ldx21, theta, phi, taup1,
    taup2, tauq1, phantom, work, lwork, info)
    CUNBDB4
subroutine dorbdb4 (m, p, q, x11, ldx11, x21, ldx21, theta, phi, taup1,
    taup2, tauq1, phantom, work, lwork, info)
    DORBDB4
subroutine sorbdb4 (m, p, q, x11, ldx11, x21, ldx21, theta, phi, taup1,
    taup2, tauq1, phantom, work, lwork, info)
    SORBDB4
subroutine zunbdb4 (m, p, q, x11, ldx11, x21, ldx21, theta, phi, taup1,
    taup2, tauq1, phantom, work, lwork, info)
    ZUNBDB4

🦋 Detailed Description 🦋

bestie. buckle up. we got the Function Documentation for all four of them, one after another. they're twins. quadruplets, actually. the only thing that changes is the type of the arrays (real vs complex) and the word "orthogonal" vs "unitary". everything else is copy-paste behaviour, which honestly? slay, consistency is a love language. 🫶

🌸 subroutine cunbdb4 🌸

subroutine cunbdb4 (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(*) phantom, complex, dimension(*)
    work, integer lwork, integer info)
    CUNBDB4

💜 Purpose:

okay so the whole assignment here: CUNBDB4 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X with orthonormal columns. and when i say simultaneously i mean it does the whole little dance in one go:

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

X11 is P-by-Q, and X21 is (M-P)-by-Q. M-Q must be no larger than P, M-P, or Q. and listen — CUNBDB1, CUNBDB2, and CUNBDB3 handle the cases where M-Q is not the minimum dimension. so if you're in one of those cases you are on the wrong page, bestie, go find your own routine. 🙈

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 — not stored out loud, that's the whole point, we're being efficient here.

B11 and B12 are (M-Q)-by-(M-Q) bidiagonal matrices represented implicitly by angles THETA, PHI.

✨ Parameters ✨

  • M — M is INTEGER. the number of rows in X11 plus the number of rows in X21. that's the total row count, she's the whole height.
  • P — P is INTEGER. the number of rows in X11. constraint: 0 <= P <= M. 🎀
  • Q — Q is INTEGER. the number of columns in X11 and X21. constraint: 0 <= Q <= M and M-Q <= min(P,M-P,Q). that second one is not optional, it's the whole reason this routine (and not its siblings) is the one you want.
  • 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. yes she gets rewritten in place, that's the deal. 💀
  • LDX11 — LDX11 is INTEGER. the leading dimension of X11. must be LDX11 >= P.
  • 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.
  • LDX21 — LDX21 is INTEGER. the leading dimension of X21. must be 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 below, i promise it's cute.
  • PHI — PHI is REAL array, dimension (Q-1). yeah, one shorter than THETA, that's not a typo. the entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. see Further Details.
  • TAUP1 — TAUP1 is COMPLEX array, dimension (M-Q). the scalar factors of the elementary reflectors that define P1.
  • TAUP2 — TAUP2 is COMPLEX array, dimension (M-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.
  • PHANTOM — PHANTOM is COMPLEX array, dimension (M). the routine computes an M-by-1 column vector Y that is orthogonal to the columns of [ X11; X21 ]. PHANTOM(1:P) and PHANTOM(P+1:M) contain Householder vectors for Y(1:P) and Y(P+1:M), respectively. spooky name, extremely real job. 👻
  • WORK — WORK is COMPLEX array, dimension (LWORK).
  • LWORK — LWORK is INTEGER. the dimension of the array WORK. constraint: LWORK >= M-Q.
okay important one: 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 don't panic when nothing yells at you, that's the intended behaviour. 💅
  • INFO — INFO is INTEGER.
    • = 0: successful exit. we love a clean run. ✨
    • < 0: if INFO = -i, the i-th argument had an illegal value. bestie you passed something cursed, check argument number i.

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 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 CUNCSD for details. it's giving trigonometry but make it structural. 🧚

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 210 of file cunbdb4.f.

💖 subroutine dorbdb4 💖

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

💜 Purpose:

DORBDB4 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-Q must be no larger than P, M-P, or Q. DORBDB1, DORBDB2, and DORBDB3 handle cases in which M-Q is not the minimum dimension. same rule as before, no exceptions. 😤

the orthogonal 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-Q)-by-(M-Q) bidiagonal matrices represented implicitly by angles THETA, PHI.

✨ Parameters ✨

  • M — M is INTEGER. the number of rows X11 plus the number of rows in X21.
  • P — P is INTEGER. the number of rows in X11. constraint: 0 <= P <= M.
  • Q — Q is INTEGER. the number of columns in X11 and X21. constraint: 0 <= Q <= M and M-Q <= min(P,M-P,Q).
  • X11 — X11 is DOUBLE PRECISION array, dimension (LDX11,Q). on entry, 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.
  • LDX11 — LDX11 is INTEGER. the leading dimension of X11. must be LDX11 >= P.
  • X21 — X21 is DOUBLE PRECISION 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.
  • LDX21 — LDX21 is INTEGER. the leading dimension of X21. must be LDX21 >= M-P.
  • THETA — THETA is DOUBLE PRECISION array, dimension (Q). the entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. see Further Details.
  • PHI — PHI is DOUBLE PRECISION array, dimension (Q-1). the entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. see Further Details.
  • TAUP1 — TAUP1 is DOUBLE PRECISION array, dimension (M-Q). the scalar factors of the elementary reflectors that define P1.
  • TAUP2 — TAUP2 is DOUBLE PRECISION array, dimension (M-Q). the scalar factors of the elementary reflectors that define P2.
  • TAUQ1 — TAUQ1 is DOUBLE PRECISION array, dimension (Q). the scalar factors of the elementary reflectors that define Q1.
  • PHANTOM — PHANTOM is DOUBLE PRECISION array, dimension (M). the routine computes an M-by-1 column vector Y that is orthogonal to the columns of [ X11; X21 ]. PHANTOM(1:P) and PHANTOM(P+1:M) contain Householder vectors for Y(1:P) and Y(P+1:M), respectively.
  • WORK — WORK is DOUBLE PRECISION array, dimension (LWORK).
  • LWORK — LWORK is INTEGER. the dimension of the array WORK. constraint: LWORK >= M-Q.
again for the cheap seats: 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. 💅
  • INFO
  • INFO — INTEGER, and this is literally the receipts of how the call went, bestie:
    • = 0 — successful exit 💖 everything ate, no notes.
    • < 0 — if INFO = -i, the i-th argument had an illegal value 😭 so like, argument number i showed up to the function wearing the wrong fit.

🎀 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

(the academic icon squad, no cap 👑)

✨ 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 DORCSD for details. 🦋
  • P1, P2, and Q1 are represented as products of elementary reflectors. See DORCSD2BY1 for details on generating P1, P2, and Q1 using DORGQR and DORGLQ. ✨

📚 References:

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

Definition at line 210 of file dorbdb4.f.

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

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

SORBDB4 — okay so this is the single-precision version of DORBDB4, and it's doing the exact same glow-up, just in REAL. ✨

🎀 Purpose:

SORBDB4 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-Q must be no larger than P, M-P, or Q. Routines SORBDB1, SORBDB2, and SORBDB3 handle cases in which M-Q is not the minimum dimension. 🫶

The orthogonal 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-Q)-by-(M-Q) bidiagonal matrices represented implicitly by angles THETA, PHI. ⭐

🍓 Parameters

  • M — INTEGER. The number of rows X11 plus the number of rows in X21.
  • P — INTEGER. The number of rows in X11. 0 <= P <= M.
  • Q — INTEGER. The number of columns in X11 and X21. 0 <= Q <= M and M-Q <= min(P,M-P,Q).
  • X11 — REAL array, dimension (LDX11,Q). On entry, 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. 🦋
  • LDX11 — INTEGER. The leading dimension of X11. LDX11 >= P.
  • X21 — REAL 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. 🦋
  • LDX21 — INTEGER. The leading dimension of X21. LDX21 >= M-P.
  • THETA — REAL array, dimension (Q). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
  • PHI — REAL array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
  • TAUP1 — REAL array, dimension (M-Q). The scalar factors of the elementary reflectors that define P1.
  • TAUP2 — REAL array, dimension (M-Q). The scalar factors of the elementary reflectors that define P2.
  • TAUQ1 — REAL array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
  • PHANTOM — REAL array, dimension (M). The routine computes an M-by-1 column vector Y that is orthogonal to the columns of [ X11; X21 ]. PHANTOM(1:P) and PHANTOM(P+1:M) contain Householder vectors for Y(1:P) and Y(P+1:M), respectively. 👻 (yes that's genuinely why it's called phantom, iconic naming tbh)
  • WORK — REAL array, dimension (LWORK).
  • LWORK — INTEGER. The dimension of the array WORK. LWORK >= M-Q.

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. 🔥

  • INFO — INTEGER.
    • = 0 — successful exit 💖
    • < 0 — if INFO = -i, the i-th argument had an illegal value 😭

🌸 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

✨ 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 SORCSD for details. 🦋
  • P1, P2, and Q1 are represented as products of elementary reflectors. See SORCSD2BY1 for details on generating P1, P2, and Q1 using SORGQR and SORGLQ. ✨

📚 References:

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

Definition at line 211 of file sorbdb4.f.

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

subroutine zunbdb4 (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(*) phantom, complex*16, dimension(*) work, integer lwork,
    integer info)

ZUNBDB4 — the complex*16, double-precision-angles glow-up of the family. Same decomposition, but make it unitary and make it shimmer. 💜✨

🎀 Purpose:

ZUNBDB4 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-Q must be no larger than P, M-P, or Q. Routines ZUNBDB1, ZUNBDB2, and ZUNBDB3 handle cases in which M-Q 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-Q)-by-(M-Q) bidiagonal matrices represented implicitly by angles THETA, PHI. ⭐

🍓 Parameters

  • M — INTEGER. The number of rows X11 plus the number of rows in X21.
  • P — INTEGER. The number of rows in X11. 0 <= P <= M.
  • Q — INTEGER. The number of columns in X11 and X21. 0 <= Q <= M and M-Q <= min(P,M-P,Q).
  • X11 — COMPLEX*16 array, dimension (LDX11,Q). On entry, 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. 🦋
  • LDX11 — INTEGER. The leading dimension of X11. LDX11 >= P.
  • 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. 🦋
  • LDX21 — INTEGER. The leading dimension of X21. 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.
  • PHI — DOUBLE PRECISION array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
  • TAUP1 — COMPLEX*16 array, dimension (M-Q). The scalar factors of the elementary reflectors that define P1.
  • TAUP2 — COMPLEX*16 array, dimension (M-Q). The scalar factors of the elementary reflectors that define P2.
  • TAUQ1 — COMPLEX*16 array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
  • PHANTOM — COMPLEX*16 array, dimension (M). The routine computes an M-by-1 column vector Y that is orthogonal to the columns of [ X11; X21 ]. PHANTOM(1:P) and PHANTOM(P+1:M) contain Householder vectors for Y(1:P) and Y(P+1:M), respectively. 👻
  • WORK — COMPLEX*16 array, dimension (LWORK).
  • LWORK
  • LWORK — okay so, LWORK is INTEGER, and it’s the dimension of the array WORK. The rule is LWORK >= M-Q.

If LWORK = -1, then a workspace query is assumed, bestie: 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. No cap.

  • INFO — INFO is INTEGER, and here’s the vibe check:
    • = 0: successful exit. slay.
    • < 0: if INFO = -i, the i-th argument had an illegal value. not slay, but useful.

Author 👑

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

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.

References 📚

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

Definition at line 210 of file zunbdb4.f.

Author 🫶 (autogenerated)

Generated automatically by Doxygen for LAPACK from the source code.

Mwah 💋 — signing off from LAPACK, version 3.12.0, on the unbdb4(3) page. The footer doesn’t list a date, so don’t come for me bestie — that’s the whole source/version situation. 🎀

📦 where this page comes from