SRC/sorcsd2by1.f(3)

📦
version 3.12.1 · 7 versions
, in arch rolling

✨ SRC/sorcsd2by1.f(3) ✨

okay bestie, this is a page from the LAPACK manual (the Library Functions Manual vibe) and it's all about one very specific little subroutine. buckle up 🎀

💖 NAME 💖

SRC/sorcsd2by1.f — literally just the source file name, that's it, that's the name, no notes 💅

🌸 SYNOPSIS 🌸

Functions/Subroutines

  • subroutine sorcsd2by1 (jobu1, jobu2, jobv1t, m, p, q, x11, ldx11, x21, ldx21, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, work, lwork, iwork, info) — the whole squad of arguments, here's the lineup:
SORCSD2BY1

🦋 Function/Subroutine Documentation 🦋

subroutine sorcsd2by1 (character jobu1, character jobu2, character jobv1t, integer m, integer p, integer q, real, dimension(ldx11,*) x11, integer ldx11, real, dimension(ldx21,*) x21, integer ldx21, real, dimension(*) theta, real, dimension(ldu1,*) u1, integer ldu1, real, dimension(ldu2,*) u2, integer ldu2, real, dimension(ldv1t,*) v1t, integer ldv1t, real, dimension(*) work, integer lwork, integer, dimension(*) iwork, integer info)

SORCSD2BY1

⭐ Purpose: ⭐

!>
!> SORCSD2BY1 computes the CS decomposition of an M-by-Q matrix X with
!> orthonormal columns that has been partitioned into a 2-by-1 block
!> structure:
!>
!>                                [  I1 0  0 ]
!>                                [  0  C  0 ]
!>          [ X11 ]   [ U1 |    ] [  0  0  0 ]
!>      X = [-----] = [---------] [----------] V1**T .
!>          [ X21 ]   [    | U2 ] [  0  0  0 ]
!>                                [  0  S  0 ]
!>                                [  0  0  I2]
!>
!> X11 is P-by-Q. The orthogonal matrices U1, U2, and V1 are P-by-P,
!> (M-P)-by-(M-P), and Q-by-Q, respectively. C and S are R-by-R
!> nonnegative diagonal matrices satisfying C^2 + S^2 = I, in which
!> R = MIN(P,M-P,Q,M-Q). I1 is a K1-by-K1 identity matrix and I2 is a
!> K2-by-K2 identity matrix, where K1 = MAX(Q+P-M,0), K2 = MAX(Q-P,0).
!>

like, it factorizes your matrix into those beautiful block pieces — iconic behavior honestly 👑

💜 Parameters 💜

  • JOBU1 — bestie, this one's a CHARACTER
!>          JOBU1 is CHARACTER
!>          = 'Y':      U1 is computed;
!>          otherwise:  U1 is not computed.
!>
  • JOBU2 — also a CHARACTER, yes there's a pattern
!>          JOBU2 is CHARACTER
!>          = 'Y':      U2 is computed;
!>          otherwise:  U2 is not computed.
!>
  • JOBV1T — CHARACTER again, third time's the charm
!>          JOBV1T is CHARACTER
!>          = 'Y':      V1T is computed;
!>          otherwise:  V1T is not computed.
!>
  • M — INTEGER, the number of rows in X 🍓
!>          M is INTEGER
!>          The number of rows in X.
!>
  • P — INTEGER, number of rows in X11. and the rule: 0 <= P <= M. don't break it 🙈
!>          P is INTEGER
!>          The number of rows in X11. 0 <= P <= M.
!>
  • Q — INTEGER, number of columns in X11 and X21. rule: 0 <= Q <= M.
!>          Q is INTEGER
!>          The number of columns in X11 and X21. 0 <= Q <= M.
!>
  • X11 — REAL array, dimension (LDX11,Q). on entry it's part of the orthogonal matrix whose CSD we're craving ✨
!>          X11 is REAL array, dimension (LDX11,Q)
!>          On entry, part of the orthogonal matrix whose CSD is desired.
!>
  • LDX11 — INTEGER, leading dimension of X11, must satisfy LDX11 >= MAX(1,P).
!>          LDX11 is INTEGER
!>          The leading dimension of X11. LDX11 >= MAX(1,P).
!>
  • X21 — REAL array, dimension (LDX21,Q), same deal, the other chunk of the orthogonal matrix 🔥
!>          X21 is REAL array, dimension (LDX21,Q)
!>          On entry, part of the orthogonal matrix whose CSD is desired.
!>
  • LDX21 — INTEGER, leading dimension of X21, must satisfy LDX21 >= MAX(1,M-P).
!>          LDX21 is INTEGER
!>           The leading dimension of X21. LDX21 >= MAX(1,M-P).
!>
  • THETA — REAL array, dimension (R), where R = MIN(P,M-P,Q,M-Q). and then the gorgeous part:
!>          THETA is REAL array, dimension (R), in which R =
!>          MIN(P,M-P,Q,M-Q).
!>          C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) ) and
!>          S = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ).
!>
  • U1 — REAL array, dimension (P). if JOBU1 = 'Y', it holds the P-by-P orthogonal matrix U1 💫
!>          U1 is REAL array, dimension (P)
!>          If JOBU1 = 'Y', U1 contains the P-by-P orthogonal matrix U1.
!>
  • LDU1 — INTEGER, leading dimension of U1. if JOBU1 = 'Y', then LDU1 >= MAX(1,P).
!>          LDU1 is INTEGER
!>          The leading dimension of U1. If JOBU1 = 'Y', LDU1 >=
!>          MAX(1,P).
!>
  • U2 — REAL array, dimension (M-P). if JOBU2 = 'Y', it's holding the (M-P)-by-(M-P) orthogonal matrix U2 😌
!>          U2 is REAL array, dimension (M-P)
!>          If JOBU2 = 'Y', U2 contains the (M-P)-by-(M-P) orthogonal
!>          matrix U2.
!>
  • LDU2 — INTEGER, leading dimension of U2. if JOBU2 = 'Y', then LDU2 >= MAX(1,M-P).
!>          LDU2 is INTEGER
!>          The leading dimension of U2. If JOBU2 = 'Y', LDU2 >=
!>          MAX(1,M-P).
!>
  • V1T — REAL array, dimension (Q). if JOBV1T = 'Y', it's the Q-by-Q orthogonal matrix V1**T 🫶
!>          V1T is REAL array, dimension (Q)
!>          If JOBV1T = 'Y', V1T contains the Q-by-Q matrix orthogonal
!>          matrix V1**T.
!>
  • LDV1T — INTEGER, leading dimension of V1T. if JOBV1T = 'Y', then LDV1T >= MAX(1,Q).
!>          LDV1T is INTEGER
!>          The leading dimension of V1T. If JOBV1T = 'Y', LDV1T >=
!>          MAX(1,Q).
!>
  • WORK — REAL array, dimension (MAX(1,LWORK)). on exit, if INFO = 0, then WORK(1) returns the optimal LWORK. but if INFO > 0 on exit, WORK(2:R) has the values PHI(1), ..., PHI(R-1) that, together with THETA(1), ..., THETA(R), define the matrix in intermediate bidiagonal-block form left over after nonconvergence. INFO tells you how many nonzero PHI's there are. not me knowing exactly what that means 😭
!>          WORK is REAL array, dimension (MAX(1,LWORK))
!>          On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
!>          If INFO > 0 on exit, WORK(2:R) contains the values PHI(1),
!>          ..., PHI(R-1) that, together with THETA(1), ..., THETA(R),
!>          define the matrix in intermediate bidiagonal-block form
!>          remaining after nonconvergence. INFO specifies the number
!>          of nonzero PHI's.
!>
  • LWORK — INTEGER, the dimension of the array WORK.
!>          LWORK is INTEGER
!>          The dimension of the array WORK.
!>
!>          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.
!>
ngl that LWORK = -1 thing is the classic "just tell me how much space you want" move — no error message from XERBLA, promise 💅
  • IWORK — INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q)) 👑
!>          IWORK is INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q))
!>
  • INFO — INTEGER, the vibe check at the end:
!>          INFO is INTEGER
!>          = 0:  successful exit.
!>          < 0:  if INFO = -i, the i-th argument had an illegal value.
!>          > 0:  SBBCSD did not converge. See the description of WORK
!>                above for details.
!>
heads up bestie: INFO > 0 means SBBCSD did not converge — go reread the WORK description above for the details, fr fr.

🌈 References: 🌈

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

like, cite your sources, periodt 📚

🎀 Author 🎀

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

Definition at line 230 of file sorcsd2by1.f.

💫 Author 💫

Generated automatically by Doxygen for LAPACK from the source code. (not a human, just a little robot doing its thing 🤖)

and that's the whole page, bestie!! this was LAPACK Version 3.12.0, page SRC/sorcsd2by1.f(3) — stay orthonormal, slay, bye 🦋💖

📦 where this page comes from