uncsd2by1(3)
π uncsd2by1(3) β Library Functions Manual
okay so this is uncsd2by1, straight out of the Library Functions Manual, section 3. It's the umbrella page for the whole {un,or}csd2by1 family β the CS-decomposition girlies π β and yes, it's a long one, so buckle up.
π NAME
uncsd2by1 β {un,or}csd2by1: ??
(no cap, the original literally says ?? β we keep it real here π«Ά)
β¨ SYNOPSIS
Functions
The four subroutine besties, verbatim, no edits, character for character:
subroutine cuncsd2by1 (jobu1, jobu2, jobv1t, m, p, q, x11, ldx11, x21,
ldx21, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, work, lwork, rwork,
lrwork, iwork, info)
CUNCSD2BY1
subroutine dorcsd2by1 (jobu1, jobu2, jobv1t, m, p, q, x11, ldx11, x21,
ldx21, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, work, lwork, iwork,
info)
DORCSD2BY1
subroutine sorcsd2by1 (jobu1, jobu2, jobv1t, m, p, q, x11, ldx11, x21,
ldx21, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, work, lwork, iwork,
info)
SORCSD2BY1
subroutine zuncsd2by1 (jobu1, jobu2, jobv1t, m, p, q, x11, ldx11, x21,
ldx21, theta, u1, ldu1, u2, ldu2, v1t, ldv1t, work, lwork, rwork,
lrwork, iwork, info)
ZUNCSD2BY1
π¦ Detailed Description
Yeah bestie, this is where the actual docs live. Scroll down, it's giving long. π
π₯ Function Documentation
cuncsd2by1
subroutine cuncsd2by1 (character jobu1, character jobu2, character jobv1t,
integer m, integer p, integer q, complex, dimension(ldx11,*) x11,
integer ldx11, complex, dimension(ldx21,*) x21, integer ldx21, real,
dimension(*) theta, complex, dimension(ldu1,*) u1, integer ldu1,
complex, dimension(ldu2,*) u2, integer ldu2, complex, dimension(ldv1t,*)
v1t, integer ldv1t, complex, dimension(*) work, integer lwork, real,
dimension(*) rwork, integer lrwork, integer, dimension(*) iwork, integer
info)
CUNCSD2BY1
Purpose
okay so CUNCSD2BY1 computes the CS decomposition of an M-by-Q matrix X with orthonormal columns β and this X has already been partitioned into a 2-by-1 block structure. It's giving this exact picture:
[ 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, periodt. The unitary 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, where 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). Iconic. π
Parameters
JOBU1βJOBU1isCHARACTER.= 'Y':U1is computed; otherwise:U1is not computed. πJOBU2βJOBU2isCHARACTER.= 'Y':U2is computed; otherwise:U2is not computed. πJOBV1TβJOBV1TisCHARACTER.= 'Y':V1Tis computed; otherwise:V1Tis not computed. πMβMisINTEGER. The number of rows inX.PβPisINTEGER. The number of rows inX11.0 <= P <= M.QβQisINTEGER. The number of columns inX11andX21.0 <= Q <= M.X11βX11isCOMPLEXarray, dimension(LDX11,Q). On entry, part of the unitary matrix whose CSD is desired.LDX11βLDX11isINTEGER. The leading dimension ofX11.LDX11 >= MAX(1,P).X21βX21isCOMPLEXarray, dimension(LDX21,Q). On entry, part of the unitary matrix whose CSD is desired.LDX21βLDX21isINTEGER. The leading dimension ofX21.LDX21 >= MAX(1,M-P).THETAβTHETAisREALarray, dimension(R), in whichR = MIN(P,M-P,Q,M-Q).C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) )andS = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ). trig girlies rise πΈU1βU1isCOMPLEXarray, dimension(P). IfJOBU1 = 'Y',U1contains theP-by-Punitary matrixU1.LDU1βLDU1isINTEGER. The leading dimension ofU1. IfJOBU1 = 'Y',LDU1 >= MAX(1,P).U2βU2isCOMPLEXarray, dimension(M-P). IfJOBU2 = 'Y',U2contains the(M-P)-by-(M-P)unitary matrixU2.LDU2βLDU2isINTEGER. The leading dimension ofU2. IfJOBU2 = 'Y',LDU2 >= MAX(1,M-P).V1TβV1TisCOMPLEXarray, dimension(Q). IfJOBV1T = 'Y',V1Tcontains theQ-by-Qmatrix unitary matrixV1**T.LDV1TβLDV1TisINTEGER. The leading dimension ofV1T. IfJOBV1T = 'Y',LDV1T >= MAX(1,Q).WORKβWORKisCOMPLEXarray, dimension(MAX(1,LWORK)). On exit, ifINFO = 0,WORK(1)returns the optimalLWORK.LWORKβLWORKisINTEGER. The dimension of the arrayWORK.
If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK and RWORK arrays, returns this value as the first entry of the WORK and RWORK array, respectively, and no error message related to LWORK or LRWORK is issued by XERBLA. π§ (the ol' -1 trick, iykyk)
RWORKβRWORKisREALarray, dimension(MAX(1,LRWORK)). On exit, ifINFO = 0,RWORK(1)returns the optimalLRWORK.
If INFO > 0 on exit, RWORK(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. π
LRWORKβLRWORKisINTEGER. The dimension of the arrayRWORK.
If LRWORK=-1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK and RWORK arrays, returns this value as the first entry of the WORK and RWORK array, respectively, and no error message related to LWORK or LRWORK is issued by XERBLA.
IWORKβIWORKisINTEGERarray, dimension(M-MIN(P,M-P,Q,M-Q)).INFOβINFOisINTEGER.= 0: successful exit.< 0: ifINFO = -i, thei-th argument had an illegal value.> 0:CBBCSDdid not converge. See the description ofWORKabove for details.
References
[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009. π
Author
Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.
Definition at line 253 of file cuncsd2by1.f.
dorcsd2by1
subroutine dorcsd2by1 (character jobu1, character jobu2, character jobv1t,
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(ldu1,*) u1, integer ldu1, double precision, dimension(ldu2,*)
u2, integer ldu2, double precision, dimension(ldv1t,*) v1t, integer
ldv1t, double precision, dimension(*) work, integer lwork, integer,
dimension(*) iwork, integer info)
DORCSD2BY1
Purpose
DORCSD2BY1 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).
Parameters
JOBU1βJOBU1isCHARACTER.= 'Y':U1is computed; otherwise:U1is not computed.JOBU2βJOBU2isCHARACTER.= 'Y':U2is computed; otherwise:U2is not computed.JOBV1TβJOBV1TisCHARACTER.= 'Y':V1Tis computed; otherwise:V1Tis not computed.MβMisINTEGER. The number of rows inX.PβPisINTEGER. The number of rows inX11.0 <= P <= M.QβQisINTEGER. The number of columns inX11andX21.0 <= Q <= M.X11βX11isDOUBLE PRECISIONarray, dimension(LDX11,Q). On entry, part of the orthogonal matrix whose CSD is desired.LDX11βLDX11isINTEGER. The leading dimension ofX11.LDX11 >= MAX(1,P).X21βX21isDOUBLE PRECISIONarray, dimension(LDX21,Q). On entry, part of the orthogonal matrix whose CSD is desired.LDX21βLDX21isINTEGER. The leading dimension ofX21.LDX21 >= MAX(1,M-P).THETAβTHETAisDOUBLE PRECISIONarray, dimension(R), in whichR = MIN(P,M-P,Q,M-Q).C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) )andS = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ).U1
(...and that's literally exactly where this chunk of the page runs out β the U1 writeup picks right back up in the next part π«Ά)
...and now we're in the outputs, bestie β the places where this thing actually drops the goods. π
U1βDOUBLE PRECISION array, dimension (P). IfJOBU1 = 'Y', thenU1contains theP-by-Porthogonal matrixU1. If you didn't ask for it, she's simply not computed β no freebies.LDU1βINTEGER. The leading dimension ofU1. IfJOBU1 = 'Y', you needLDU1 >= MAX(1,P).U2βDOUBLE PRECISION array, dimension (M-P). IfJOBU2 = 'Y',U2contains the(M-P)-by-(M-P)orthogonal matrixU2. Same deal:'Y'or she stays uncomputed. πLDU2βINTEGER. The leading dimension ofU2. IfJOBU2 = 'Y', thenLDU2 >= MAX(1,M-P).V1TβDOUBLE PRECISION array, dimension (Q). IfJOBV1T = 'Y',V1Tcontains theQ-by-Qmatrix orthogonal matrixV1**T. Yes, the transpose is baked right into the name, she's literally telling you. πLDV1TβINTEGER. The leading dimension ofV1T. IfJOBV1T = 'Y', thenLDV1T >= MAX(1,Q).WORKβDOUBLE PRECISION array, dimension (MAX(1,LWORK)). On exit, ifINFO = 0,WORK(1)returns the optimalLWORK. And here's the tea: ifINFO > 0on exit,WORK(2:R)contains the valuesPHI(1), ...,PHI(R-1)that, together withTHETA(1), ...,THETA(R), define the matrix in intermediate bidiagonal-block form remaining after nonconvergence.INFOspecifies the number of nonzeroPHI's. So even when she doesn't converge, she leaves you a whole forensic trail. π₯LWORKβINTEGER. The dimension of the arrayWORK.
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. Nice β you can just ask her how much room she needs, and she won't yell at you for it. π
IWORKβINTEGER array, dimension (M-MIN(P,M-P,Q,M-Q)). That's the exact dimension, copy it character for character, don't get cute.INFOβINTEGER.= 0: successful exit. we love her, we stan. π< 0: ifINFO = -i, thei-th argument had an illegal value.> 0:DBBCSDdid not converge. See the description ofWORKabove for details.
Fr fr, thatINFO > 0case is not a vibe β nonconvergence is real, and the leftoverPHIvalues inWORKare your only clue about what survived. Read theWORKnote again if you skipped it. π
π References
[1]Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.
π«Ά Author
Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.
Definition at line 230 of file dorcsd2by1.f.
πΈ subroutine sorcsd2by1 β the single-precision twin
She's the REAL version, and she's iconic in her own right:
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
Okay so picture this β 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).
Literally the same decomposition as the double-precision one, just in single precision. π
π Parameters
JOBU1βCHARACTER.= 'Y':U1is computed;- otherwise:
U1is not computed.
JOBU2βCHARACTER.= 'Y':U2is computed;- otherwise:
U2is not computed.
JOBV1TβCHARACTER.= 'Y':V1Tis computed;- otherwise:
V1Tis not computed.
MβINTEGER. The number of rows inX.PβINTEGER. The number of rows inX11.0 <= P <= M.QβINTEGER. The number of columns inX11andX21.0 <= Q <= M.X11βREAL array, dimension (LDX11,Q). On entry, part of the orthogonal matrix whose CSD is desired.LDX11βINTEGER. The leading dimension ofX11.LDX11 >= MAX(1,P).X21βREAL array, dimension (LDX21,Q). On entry, part of the orthogonal matrix whose CSD is desired.LDX21βINTEGER. The leading dimension ofX21.LDX21 >= MAX(1,M-P).THETAβREAL array, dimension (R), in whichR = MIN(P,M-P,Q,M-Q).C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) )andS = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ). The angles go in, the cosines and sines come out β it's giving trigonometry main character energy. πβ¨U1βREAL array, dimension (P). IfJOBU1 = 'Y',U1contains theP-by-Porthogonal matrixU1.LDU1βINTEGER. The leading dimension ofU1. IfJOBU1 = 'Y',LDU1 >= MAX(1,P).U2βREAL array, dimension (M-P). IfJOBU2 = 'Y',U2contains the(M-P)-by-(M-P)orthogonal matrixU2.LDU2βINTEGER. The leading dimension ofU2. IfJOBU2 = 'Y',LDU2 >= MAX(1,M-P).V1TβREAL array, dimension (Q). IfJOBV1T = 'Y',V1Tcontains theQ-by-Qmatrix orthogonal matrixV1**T.LDV1TβINTEGER. The leading dimension ofV1T. IfJOBV1T = 'Y',LDV1T >= MAX(1,Q).WORKβREAL array, dimension (MAX(1,LWORK)). On exit, ifINFO = 0,WORK(1)returns the optimalLWORK. IfINFO > 0on exit,WORK(2:R)contains the valuesPHI(1), ...,PHI(R-1)that, together withTHETA(1), ...,THETA(R), define the matrix in intermediate bidiagonal-block form remaining after nonconvergence.INFOspecifies the number of nonzeroPHI's.LWORKβINTEGER. The dimension of the arrayWORK.
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.
IWORKβINTEGER array, dimension (M-MIN(P,M-P,Q,M-Q)).INFOβINTEGER.= 0: successful exit.< 0: ifINFO = -i, thei-th argument had an illegal value.> 0:SBBCSDdid not converge. See the description ofWORKabove for details.
Notice the difference from the double-precision page: here it'sSBBCSDthat failed to converge, notDBBCSD. Type the right one, iykyk. π
π References
[1]Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.
π«Ά Author
Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.
Definition at line 230 of file sorcsd2by1.f.
π¦ subroutine zuncsd2by1 β now with complex*16 and everything
And here's the complex*16 one, with a whole extra RWORK situation. She's doing the most and honestly? deserved. π
subroutine zuncsd2by1 (character jobu1, character jobu2, character jobv1t,
integer m, integer p, integer q, complex*16, dimension(ldx11,*) x11,
integer ldx11, complex*16, dimension(ldx21,*) x21, integer ldx21, double
precision, dimension(*) theta, complex*16, dimension(ldu1,*) u1, integer
ldu1, complex*16, dimension(ldu2,*) u2, integer ldu2, complex*16,
dimension(ldv1t,*) v1t, integer ldv1t, complex*16, dimension(*) work,
integer lwork, double precision, dimension(*) rwork, integer lrwork,
integer, dimension(*) iwork, integer info)
β¨ ZUNCSD2BY1
Purpose
ZUNCSD2BY1 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 unitary 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).
Key difference, don't miss it:U1,U2,V1are unitary here, not orthogonal β because complex. π
π Parameters
JOBU1βCHARACTER.= 'Y':U1is computed;- otherwise:
U1is not computed.
JOBU2βCHARACTER.= 'Y':U2is computed;- otherwise:
U2is not computed.
JOBV1TβCHARACTER.= 'Y':V1Tis computed;- otherwise:
V1Tis not computed.
MβINTEGER. The number of rows inX.PβINTEGER. The number of rows inX11.0 <= P <= M.QβINTEGER. The number of columns inX11andX21.0 <= Q <= M.X11X11β aCOMPLEX*16array, dimension(LDX11,Q). On entry, this is part of the unitary matrix whose CSD you're after, bestie. πLDX11βINTEGER. The leading dimension ofX11. Gotta obeyLDX11 >= MAX(1,P). No cap. β¨X21β aCOMPLEX*16array, dimension(LDX21,Q). On entry, this is part of the unitary matrix whose CSD is desired. π¦LDX21βINTEGER. The leading dimension ofX21. It must satisfyLDX21 >= MAX(1,M-P). π₯THETAβ aDOUBLE PRECISIONarray, dimension(R), whereR = MIN(P,M-P,Q,M-Q). And then:C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) )andS = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ). That's the whole vibe. πU1β aCOMPLEX*16array, dimension(P). IfJOBU1 = 'Y',U1contains theP-by-Punitary matrixU1. πLDU1βINTEGER. The leading dimension ofU1. IfJOBU1 = 'Y', thenLDU1 >= MAX(1,P). πU2β aCOMPLEX*16array, dimension(M-P). IfJOBU2 = 'Y',U2contains the(M-P)-by-(M-P)unitary matrixU2. πΈLDU2βINTEGER. The leading dimension ofU2. IfJOBU2 = 'Y', thenLDU2 >= MAX(1,M-P). βV1Tβ aCOMPLEX*16array, dimension(Q). IfJOBV1T = 'Y',V1Tcontains theQ-by-Qmatrix unitary matrixV1**Tβ yes, the source says βmatrix unitary matrix,β and honestly? Iconic. πLDV1TβINTEGER. The leading dimension ofV1T. IfJOBV1T = 'Y', thenLDV1T >= MAX(1,Q). π«ΆWORKβ aCOMPLEX*16array, dimension(MAX(1,LWORK)). On exit, ifINFO = 0,WORK(1)returns the optimalLWORK. β¨LWORKβINTEGER. The dimension of the arrayWORK.
If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK and RWORK arrays, returns this value as the first entry of the WORK and RWORK array, respectively, and no error message related to LWORK or LRWORK is issued by XERBLA. Not me getting a whole query mode and zero scolding. π
RWORKβ aDOUBLE PRECISIONarray, dimension(MAX(1,LRWORK)). On exit, ifINFO = 0,RWORK(1)returns the optimalLRWORK.
If INFO > 0 on exit, RWORK(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. Lowkey important tea. π
LRWORKβINTEGER. The dimension of the arrayRWORK.
If LRWORK=-1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK and RWORK arrays, returns this value as the first entry of the WORK and RWORK array, respectively, and no error message related to LWORK or LRWORK is issued by XERBLA. Same energy, same query mode. π
IWORKβINTEGERarray, dimension(M-MIN(P,M-P,Q,M-Q)). π§INFOβINTEGER.
= 0: successful exit. Slay. β
< 0: if INFO = -i, the i-th argument had an illegal value. π
> 0: ZBBCSD did not converge. See the description of WORK above for details. π¨
π References
- [1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009. π
π Author
- Univ. of Tennessee
- Univ. of California Berkeley
- Univ. of Colorado Denver
- NAG Ltd.
Definition at line 252 of file zuncsd2by1.f. π―
π€ Author
Generated automatically by Doxygen for LAPACK from the source code. β¨
Source/version sign-off, bestie: this iconic page is from LAPACK, Version 3.12.0 β and the footer doesn't show a date, so we're not inventing one. ππ«Ά
π¦ where this page comes from
- arch rolling: lapack-doc 3.12.1-2 Β· custom
- π girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms