complexOTHERcomputational(3)

📦

version 3.11.0 · 2 versions

3.11.0 · debian bookworm (latest)
3.10.0 · ubuntu jammy

✨ NAME ✨

Okay so bestie, welcome to complexOTHERcomputational(3) — that's the whole title, that's the manual page, that's the moment. It lives in the LAPACK corner of the man pages and it's lowkey just here to tell you its name. 💅

complexOTHERcomputational — complex

That's it. That's the whole description. The name, a dash, and the word complex. No options, no arguments, no environment variables, no exit statuses, no bugs, no authors — nothing. It's giving minimal. It's giving "I said what I said". 🎀

complexOTHERcomputational is literally the identifier you're looking at, and the manual is describing it as complex. That's the vibe check, that's the whole summary, and honestly? Iconic of it to not over-explain. 🦋

Heads up bestie: this is just the top of the page. There is so much more coming, so don't go anywhere. 💖

✨ SYNOPSIS ✨

🫶 Functions 🫶

okay so bestie, this is the function roll call 💖 every single one of these lives in this library, and the signature is the vibe check you gotta pass. Read the args exactly, no cap. 🔥

`cbbcsd` — CBBCSD

subroutine cbbcsd (JOBU1, JOBU2, JOBV1T, JOBV2T, TRANS, M, P, Q, THETA,
    PHI, U1, LDU1, U2, LDU2, V1T, LDV1T, V2T, LDV2T, B11D, B11E, B12D,
    B12E, B21D, B21E, B22D, B22E, RWORK, LRWORK, INFO)

that's it, that's the whole description. iconic 💅

`cbdsqr` — CBDSQR

subroutine cbdsqr (UPLO, N, NCVT, NRU, NCC, D, E, VT, LDVT, U, LDU, C,
    LDC, RWORK, INFO)

also just vibes, name only 🦋

`cgghd3` — CGGHD3

subroutine cgghd3 (COMPQ, COMPZ, N, ILO, IHI, A, LDA, B, LDB, Q, LDQ, Z,
    LDZ, WORK, LWORK, INFO)

she's here and she's serving 🎀

`cgghrd` — CGGHRD

subroutine cgghrd (COMPQ, COMPZ, N, ILO, IHI, A, LDA, B, LDB, Q, LDQ, Z,
    LDZ, INFO)

no description bestie, just the name 😭

`cggqrf` — CGGQRF

subroutine cggqrf (N, M, P, A, LDA, TAUA, B, LDB, TAUB, WORK, LWORK,
    INFO)

she's giving generalized QR factorization energy ✨ (jk, the original didn't say that — just her name, that's all we got 💜)

`cggrqf` — CGGRQF

subroutine cggrqf (M, P, N, A, LDA, TAUA, B, LDB, TAUB, WORK, LWORK,
    INFO)

just the name, just the name, periodt 💅

`cggsvp3` — CGGSVP3

subroutine cggsvp3 (JOBU, JOBV, JOBQ, M, P, N, A, LDA, B, LDB, TOLA,
    TOLB, K, L, U, LDU, V, LDV, Q, LDQ, IWORK, RWORK, TAU, WORK, LWORK,
    INFO)

again, name only. she keeps her secrets 🔒

`cgsvj0` — CGSVJ0

subroutine cgsvj0 (JOBV, M, N, A, LDA, D, SVA, MV, V, LDV, EPS, SFMIN,
    TOL, NSWEEP, WORK, LWORK, INFO)

pre-processor for the routine cgesvj. like she does the warm-up so the main character can shine ✨

`cgsvj1` — CGSVJ1

subroutine cgsvj1 (JOBV, M, N, N1, A, LDA, D, SVA, MV, V, LDV, EPS,
    SFMIN, TOL, NSWEEP, WORK, LWORK, INFO)

pre-processor for the routine cgesvj, applies Jacobi rotations targeting only particular pivots. selective queen behavior, we love to see it 👑

`chbgst` — CHBGST

subroutine chbgst (VECT, UPLO, N, KA, KB, AB, LDAB, BB, LDBB, X, LDX,
    WORK, RWORK, INFO)

name only 🍓

`chbtrd` — CHBTRD

subroutine chbtrd (VECT, UPLO, N, KD, AB, LDAB, D, E, Q, LDQ, WORK,
    INFO)

name only again 💖

`chetrd_hb2st` — CHETRD_HB2ST

subroutine chetrd_hb2st (STAGE1, VECT, UPLO, N, KD, AB, LDAB, D, E,
    HOUS, LHOUS, WORK, LWORK, INFO)

reduces a complex Hermitian band matrix A to real symmetric tridiagonal form T — she's a transformer fr fr 🦋✨

`chfrk` — CHFRK

subroutine chfrk (TRANSR, UPLO, TRANS, N, K, ALPHA, A, LDA, BETA, C)

performs a Hermitian rank-k operation for matrix in RFP format. math girlie doing her lil rank-k thing 💅

`chpcon` — CHPCON

subroutine chpcon (UPLO, N, AP, IPIV, ANORM, RCOND, WORK, INFO)

name only bestie 🌸

`chpgst` — CHPGST

subroutine chpgst (ITYPE, UPLO, N, AP, BP, INFO)

name only 😭

`chprfs` — CHPRFS

subroutine chprfs (UPLO, N, NRHS, AP, AFP, IPIV, B, LDB, X, LDX, FERR,
    BERR, WORK, RWORK, INFO)

name only, again 💜

`chptrd` — CHPTRD

subroutine chptrd (UPLO, N, AP, D, E, TAU, INFO)

name only 🎀

`chptrf` — CHPTRF

subroutine chptrf (UPLO, N, AP, IPIV, INFO)

name only ✨

`chptri` — CHPTRI

subroutine chptri (UPLO, N, AP, IPIV, WORK, INFO)

name only 🦋

`chptrs` — CHPTRS

subroutine chptrs (UPLO, N, NRHS, AP, IPIV, B, LDB, INFO)

name only, no notes 💅

`chsein` — CHSEIN

subroutine chsein (SIDE, EIGSRC, INITV, SELECT, N, H, LDH, W, VL, LDVL,
    VR, LDVR, MM, M, WORK, RWORK, IFAILL, IFAILR, INFO)

name only 🔥

`chseqr` — CHSEQR

subroutine chseqr (JOB, COMPZ, N, ILO, IHI, H, LDH, W, Z, LDZ, WORK,
    LWORK, INFO)

name only ⭐

`cla_lin_berr` — CLA_LIN_BERR

subroutine cla_lin_berr (N, NZ, NRHS, RES, AYB, BERR)

computes a component-wise relative backward error. error girlie stays precise 🎯

`cla_wwaddw` — CLA_WWADDW

subroutine cla_wwaddw (N, X, Y, W)

adds a vector into a doubled-single vector. adding vectors, adding vibes, adding everything ✨

`claed0` — CLAED0

subroutine claed0 (QSIZ, N, D, E, Q, LDQ, QSTORE, LDQS, RWORK, IWORK,
    INFO)

used by CSTEDC. Computes all eigenvalues and corresponding eigenvectors of an unreduced symmetric tridiagonal matrix using the divide and conquer method. divide AND conquer?? main character energy fr 👑

`claed7` — CLAED7

subroutine claed7 (N, CUTPNT, QSIZ, TLVLS, CURLVL, CURPBM, D, Q, LDQ,
    RHO, INDXQ, QSTORE, QPTR, PRMPTR, PERM, GIVPTR, GIVCOL, GIVNUM,
    WORK, RWORK, IWORK, INFO)

used by CSTEDC. Computes the updated eigensystem of a diagonal matrix after modification by a rank-one symmetric matrix. Used when the original matrix is dense. dense matrix? she handles it, no problem 💅

`claed8` — CLAED8

subroutine claed8 (K, N, QSIZ, Q, LDQ, D, RHO, CUTPNT, Z, DLAMDA, Q2,
    LDQ2, W, INDXP, INDX, INDXQ, PERM, GIVPTR, GIVCOL, GIVNUM, INFO)

used by CSTEDC. Merges eigenvalues and deflates secular equation. Used when the original matrix is dense. merging + deflating, the duality of girlhood 🦋

`clals0` — CLALS0

subroutine clals0 (ICOMPQ, NL, NR, SQRE, NRHS, B, LDB, BX, LDBX, PERM,
    GIVPTR, GIVCOL, LDGCOL, GIVNUM, LDGNUM, POLES, DIFL, DIFR, Z, K, C,
    S, RWORK, INFO)

applies back multiplying factors in solving the least squares problem using divide and conquer SVD approach. Used by sgelsd. (yes bestie, sgelsd — that's what it says, don't come for me 🙈)

`clalsa` — CLALSA

subroutine clalsa (ICOMPQ, SMLSIZ, N, NRHS, B, LDB, BX, LDBX, U, LDU,
    VT, K, DIFL, DIFR, Z, POLES, GIVPTR, GIVCOL, LDGCOL, PERM, GIVNUM,
    C, S, RWORK, IWORK, INFO)

computes the SVD of the coefficient matrix in compact form. Used by sgelsd. compact form, compact energy ✨

`clalsd` — CLALSD

subroutine clalsd (UPLO, SMLSIZ, N, NRHS, D, E, B, LDB, RCOND, RANK,
    WORK, RWORK, IWORK, INFO)

uses the singular value decomposition of A to solve the least squares problem. SVD girlie solving least squares like it's nothing 💖

`clanhf` — CLANHF

real function clanhf (NORM, TRANSR, UPLO, N, A, WORK)

returns the value of the 1-norm, or the Frobenius norm, or the infinity norm, or the element of largest absolute value of a Hermitian matrix in RFP format. norm check = vibe check 🌈

`clarscl2` — CLARSCL2

subroutine clarscl2 (M, N, D, X, LDX)

performs reciprocal diagonal scaling on a matrix. scaling, but make it reciprocal 💅

`clarz` — CLARZ

subroutine clarz (SIDE, M, N, L, V, INCV, TAU, C, LDC, WORK)

applies an elementary reflector (as returned by stzrzf) to a general matrix. reflection is self-care fr 🪞

`clarzb` — CLARZB

subroutine clarzb (SIDE, TRANS, DIRECT, STOREV, M, N, K, L, V, LDV, T,
    LDT, C, LDC, WORK, LDWORK)

applies a block reflector or its conjugate-transpose to a general matrix. block reflector, or her conjugate-transpose twin — two icons, one routine 👑

`clarzt` — CLARZT

subroutine clarzt (DIRECT, STOREV, N, K, V, LDV, TAU, T, LDT)

forms the triangular factor T of a block reflector H = I - vtvH. she's forming things, we stan a builder 🎀

`clascl2` — CLASCL2

subroutine clascl2 (M, N, D, X, LDX)

performs diagonal scaling on a matrix. the non-reciprocal sibling, iconic behavior 🦋

`clatrz` — CLATRZ

subroutine clatrz (M, N, L, A, LDA, TAU, WORK)

factors an upper trapezoidal matrix by means of unitary transformations. trapezoidal?? geometry queen 💅

`cpbcon` — CPBCON

subroutine cpbcon (UPLO, N, KD, AB, LDAB, ANORM, RCOND, WORK, RWORK,
    INFO)

name only, as usual ✨

`cpbequ` — CPBEQU

subroutine cpbequ (UPLO, N, KD, AB, LDAB, S, SCOND, AMAX, INFO)

name only 🌸

`cpbrfs` — CPBRFS

subroutine cpbrfs (UPLO, N, KD, NRHS, AB, LDAB, AFB, LDAFB, B, LDB, X,
    LDX, FERR, BERR, WORK, RWORK, INFO)

name only 🍓

`cpbstf` — CPBSTF

subroutine cpbstf (UPLO, N, KD, AB, LDAB, INFO)

name only 💜

`cpbtf2` — CPBTF2

subroutine cpbtf2 (UPLO, N, KD, AB, LDAB, INFO)

computes the Cholesky factorization of a symmetric/Hermitian positive definite band matrix (unblocked algorithm). unblocked algorithm, unbothered queen 💅

`cpbtrf` — CPBTRF

subroutine cpbtrf (UPLO, N, KD, AB, LDAB, INFO)

name only 🎀

`cpbtrs` — CPBTRS

subroutine cpbtrs (UPLO, N, KD, NRHS, AB, LDAB, B, LDB, INFO)

name only 🦋

`cpftrf` — CPFTRF

subroutine cpftrf (TRANSR, UPLO, N, A, INFO)

name only 💖

`cpftri` — CPFTRI

subroutine cpftri (TRANSR, UPLO, N, A, INFO)

name only 🔥

`cpftrs` — CPFTRS

subroutine cpftrs (TRANSR, UPLO, N, NRHS, A, B, LDB, INFO)

name only ⭐

`cppcon` — CPPCON

subroutine cppcon (UPLO, N, AP, ANORM, RCOND, WORK, RWORK, INFO)

name only 🌈

`cppequ` — CPPEQU

subroutine cppequ (UPLO, N, AP, S, SCOND, AMAX, INFO)

name only 💜

`cpprfs` — CPPRFS

subroutine cpprfs (UPLO, N, NRHS, AP, AFP, B, LDB, X, LDX, FERR, BERR,
    WORK, RWORK, INFO)

name only 🫶

`cpptrf` — CPPTRF

subroutine cpptrf (UPLO, N, AP, INFO)

name only ✨

`cpptri` — CPPTRI

subroutine cpptri (UPLO, N, AP, INFO)

name only 🎀

`cpptrs` — CPPTRS

subroutine cpptrs (UPLO, N, NRHS, AP, B, LDB, INFO)

name only 💅

`cpstf2` — CPSTF2

subroutine cpstf2 (UPLO, N, A, LDA, PIV, RANK, TOL, WORK, INFO)

computes the Cholesky factorization with complete pivoting of complex Hermitian positive semidefinite matrix. complete pivoting?? she's thorough, that's the tea 🍵

`cpstrf` — CPSTRF

subroutine cpstrf (UPLO, N, A, LDA, PIV, RANK, TOL, WORK, INFO)

computes the Cholesky factorization with complete pivoting of complex Hermitian positive semidefinite matrix. same energy, different name, slay 🦋

`cspcon` — CSPCON

subroutine cspcon (UPLO, N, AP, IPIV, ANORM, RCOND, WORK, INFO)

name only 🌸

`csprfs` — CSPRFS

subroutine csprfs (UPLO, N, NRHS, AP, AFP, IPIV, B, LDB, X, LDX, FERR,
    BERR, WORK, RWORK, INFO)

name only 💜

`csptrf` — CSPTRF

subroutine csptrf (UPLO, N, AP, IPIV, INFO)

name only 🔥

`csptri` — CSPTRI

subroutine csptri (UPLO, N, AP, IPIV, WORK, INFO)

name only ⭐

`csptrs` — CSPTRS

subroutine csptrs (UPLO, N, NRHS, AP, IPIV, B, LDB, INFO)

name only 🎀

`cstedc` — CSTEDC

subroutine cstedc (COMPZ, N, D, E, Z, LDZ, WORK, LWORK, RWORK, LRWORK,
    IWORK, LIWORK, INFO)

name only, she lets her reputation speak 💅

`cstegr` — CSTEGR

subroutine cstegr (JOBZ, RANGE, N, D, E, VL, VU, IL, IU, ABSTOL, M, W,
    Z, LDZ, ISUPPZ, WORK, LWORK, IWORK, LIWORK, INFO)

name only ✨

`cstein` — CSTEIN

subroutine cstein (N, D, E, M, W, IBLOCK, ISPLIT, Z, LDZ, WORK, IWORK,
    IFAIL, INFO)

name only 🦋

`cstemr` — CSTEMR

subroutine cstemr (JOBZ, RANGE, N, D, E, VL, VU, IL, IU, M, W, Z, LDZ,
    NZC, ISUPPZ, TRYRAC, WORK, LWORK, IWORK, LIWORK, INFO)

name only 🍓

`csteqr` — CSTEQR

subroutine csteqr (COMPZ, N, D, E, Z, LDZ, WORK, INFO)

name only 💜

`ctbcon` — CTBCON

subroutine ctbcon (NORM, UPLO, DIAG, N, KD, AB, LDAB, RCOND, WORK,
    RWORK, INFO)

name only 🌈

`ctbrfs` — CTBRFS

subroutine ctbrfs (UPLO, TRANS, DIAG, N, KD, NRHS, AB, LDAB, B, LDB, X,
    LDX, FERR, BERR, WORK, RWORK, INFO)

name only 🫶

`ctbtrs` — CTBTRS

subroutine ctbtrs (UPLO, TRANS, DIAG, N, KD, NRHS, AB, LDAB, B, LDB,
    INFO)

name only 💖

`ctfsm` — CTFSM

subroutine ctfsm (TRANSR, SIDE, UPLO, TRANS, DIAG, M, N, ALPHA, A, B,
    LDB)

solves a matrix equation (one operand is a triangular matrix in RFP format). solving equations with a triangular operand — casual flex 👑

`ctftri` — CTFTRI

subroutine ctftri (TRANSR, UPLO, DIAG, N, A, INFO)

name only ✨

`ctfttp` — CTFTTP

subroutine ctfttp (TRANSR, UPLO, N, ARF, AP, INFO)

copies a triangular matrix from the rectangular full packed format (TF) to the standard packed format (TP). a format glow-up, she's a makeover montage 💅

`ctfttr` — CTFTTR

subroutine ctfttr (TRANSR, UPLO, N, ARF, A, LDA, INFO)

copies a triangular matrix from the rectangular full packed format (TF) to the standard full format (TR). TF → TR, another transformation, another slay 🦋

`ctgsen` — CTGSEN

subroutine ctgsen (IJOB, WANTQ, WANTZ, SELECT, N, A, LDA, B, LDB, ALPHA,
    BETA, Q, LDQ, Z, LDZ, M, PL, PR, DIF, WORK, LWORK, IWORK, LIWORK,
    INFO)

name only 🎀

`ctgsja` — CTGSJA

subroutine ctgsja (JOBU, JOBV, JOBQ, M, P, N, K, L, A, LDA, B, LDB,
    TOLA, TOLB, ALPHA, BETA, U, LDU, V, LDV, Q, LDQ, WORK, NCYCLE, INFO)

name only 🔥

`ctgsna` — CTGSNA

subroutine ctgsna (JOB, HOWMNY, SELECT, N, A, LDA, B, LDB, VL, LDVL, VR,
    LDVR, S, DIF, MM, M, WORK, LWORK, IWORK, INFO)

name only ⭐

`ctpcon` — CTPCON

subroutine ctpcon (NORM, UPLO, DIAG, N, AP, RCOND, WORK, RWORK, INFO)

name only 🌸

`ctpmqrt` — CTPMQRT

subroutine ctpmqrt (SIDE, TRANS, M, N, K, L, NB, V, LDV, T, LDT, A, LDA,
    B, LDB, WORK, INFO)

name only 💜

`ctpqrt` — CTPQRT

subroutine ctpqrt (M, N, L, NB, A, LDA, B, LDB, T, LDT, WORK, INFO)

name only 🍓

`ctpqrt2` — CTPQRT2

subroutine ctpqrt2 (M, N, L, A, LDA, B, LDB, T, LDT, INFO)

computes a QR factorization of a real or complex 'triangular-pentagonal' matrix, which is composed of a triangular block and a pentagonal block, using the compact WY representation for Q. triangular-pentagonal?? she's doing origami with matrices, obsessed 😭✨

`ctprfs` — CTPRFS

subroutine ctprfs (UPLO, TRANS, DIAG, N, NRHS, AP, B, LDB, X, LDX, FERR,
    BERR, WORK, RWORK, INFO)

name only 💖

`ctptri` — CTPTRI

subroutine ctptri (UPLO, DIAG, N, AP, INFO)

name only 🌈

`ctptrs` — CTPTRS

subroutine ctptrs (UPLO, TRANS, DIAG, N, NRHS, AP, B, LDB, INFO)

name only 🫶

`ctpttf` — CTPTTF

subroutine ctpttf (TRANSR, UPLO, N, AP, ARF, INFO)

copies a triangular matrix from the standard packed format (TP) to the rectangular full packed format (TF). the reverse glow-up, we love a two-way street 💅

`ctpttr` — CTPTTR

subroutine ctpttr (UPLO, N, AP, A, LDA, INFO)

name only, bestie — and that's where this part wraps for now 🦋✨

Okay so CTPTTR is literally copying a triangular matrix from the standard packed format (TP) to the standard full format (TR). 💅

And here's the rest of the squad, bestie — all the complex other computational routines doing their thing: ✨

subroutine ctrcon (NORM, UPLO, DIAG, N, A, LDA, RCOND, WORK, RWORK, INFO) — CTRCON
subroutine ctrevc (SIDE, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, MM, M, WORK, RWORK, INFO) — CTREVC
subroutine ctrevc3 (SIDE, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, MM, M, WORK, LWORK, RWORK, LRWORK, INFO) — CTREVC3
subroutine ctrexc (COMPQ, N, T, LDT, Q, LDQ, IFST, ILST, INFO) — CTREXC
subroutine ctrrfs (UPLO, TRANS, DIAG, N, NRHS, A, LDA, B, LDB, X, LDX, FERR, BERR, WORK, RWORK, INFO) — CTRRFS
subroutine ctrsen (JOB, COMPQ, SELECT, N, T, LDT, Q, LDQ, W, M, S, SEP, WORK, LWORK, INFO) — CTRSEN
subroutine ctrsna (JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, S, SEP, MM, M, WORK, LDWORK, RWORK, INFO) — CTRSNA
subroutine ctrti2 (UPLO, DIAG, N, A, LDA, INFO) — CTRTI2 computes the inverse of a triangular matrix (unblocked algorithm). It's giving "I'll flip that for you" energy. 🔥
subroutine ctrtri (UPLO, DIAG, N, A, LDA, INFO) — CTRTRI
subroutine ctrtrs (UPLO, TRANS, DIAG, N, NRHS, A, LDA, B, LDB, INFO) — CTRTRS
subroutine ctrttf (TRANSR, UPLO, N, A, LDA, ARF, INFO) — CTRTTF copies a triangular matrix from the standard full format (TR) to the rectangular full packed format (TF).
subroutine ctrttp (UPLO, N, A, LDA, AP, INFO) — CTRTTP copies a triangular matrix from the standard full format (TR) to the standard packed format (TP).
subroutine ctzrzf (M, N, A, LDA, TAU, WORK, LWORK, INFO) — CTZRZF
subroutine cunbdb (TRANS, SIGNS, M, P, Q, X11, LDX11, X12, LDX12, X21, LDX21, X22, LDX22, THETA, PHI, TAUP1, TAUP2, TAUQ1, TAUQ2, WORK, LWORK, INFO) — CUNBDB
subroutine cunbdb1 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — CUNBDB1
subroutine cunbdb2 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — CUNBDB2
subroutine cunbdb3 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — CUNBDB3
subroutine cunbdb4 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, PHANTOM, WORK, LWORK, INFO) — CUNBDB4
subroutine cunbdb5 (M1, M2, N, X1, INCX1, X2, INCX2, Q1, LDQ1, Q2, LDQ2, WORK, LWORK, INFO) — CUNBDB5
subroutine cunbdb6 (M1, M2, N, X1, INCX1, X2, INCX2, Q1, LDQ1, Q2, LDQ2, WORK, LWORK, INFO) — CUNBDB6
recursive subroutine cuncsd (JOBU1, JOBU2, JOBV1T, JOBV2T, TRANS, SIGNS, M, P, Q, X11, LDX11, X12, LDX12, X21, LDX21, X22, LDX22, THETA, U1, LDU1, U2, LDU2, V1T, LDV1T, V2T, LDV2T, WORK, LWORK, RWORK, LRWORK, IWORK, INFO) — CUNCSD
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 cung2l (M, N, K, A, LDA, TAU, WORK, INFO) — CUNG2L generates all or part of the unitary matrix Q from a QL factorization determined by cgeqlf (unblocked algorithm).
subroutine cung2r (M, N, K, A, LDA, TAU, WORK, INFO) — CUNG2R
subroutine cunghr (N, ILO, IHI, A, LDA, TAU, WORK, LWORK, INFO) — CUNGHR
subroutine cungl2 (M, N, K, A, LDA, TAU, WORK, INFO) — CUNGL2 generates all or part of the unitary matrix Q from an LQ factorization determined by cgelqf (unblocked algorithm).
subroutine cunglq (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — CUNGLQ
subroutine cungql (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — CUNGQL
subroutine cungqr (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — CUNGQR
subroutine cungr2 (M, N, K, A, LDA, TAU, WORK, INFO) — CUNGR2 generates all or part of the unitary matrix Q from an RQ factorization determined by cgerqf (unblocked algorithm).
subroutine cungrq (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — CUNGRQ
subroutine cungtr (UPLO, N, A, LDA, TAU, WORK, LWORK, INFO) — CUNGTR
subroutine cungtsqr (M, N, MB, NB, A, LDA, T, LDT, WORK, LWORK, INFO) — CUNGTSQR
subroutine cungtsqr_row (M, N, MB, NB, A, LDA, T, LDT, WORK, LWORK, INFO) — CUNGTSQR_ROW
subroutine cunhr_col (M, N, NB, A, LDA, T, LDT, D, INFO) — CUNHR_COL
subroutine cunm22 (SIDE, TRANS, M, N, N1, N2, Q, LDQ, C, LDC, WORK, LWORK, INFO) — CUNM22 multiplies a general matrix by a banded unitary matrix.
subroutine cunm2l (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — CUNM2L multiplies a general matrix by the unitary matrix from a QL factorization determined by cgeqlf (unblocked algorithm).
subroutine cunm2r (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — CUNM2R multiplies a general matrix by the unitary matrix from a QR factorization determined by cgeqrf (unblocked algorithm).
subroutine cunmbr (VECT, SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — CUNMBR
subroutine cunmhr (SIDE, TRANS, M, N, ILO, IHI, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — CUNMHR
subroutine cunml2 (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — CUNML2 multiplies a general matrix by the unitary matrix from a LQ factorization determined by cgelqf (unblocked algorithm).
subroutine cunmlq (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — CUNMLQ
subroutine cunmql (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — CUNMQL
subroutine cunmqr (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — CUNMQR
subroutine cunmr2 (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — CUNMR2 multiplies a general matrix by the unitary matrix from a RQ factorization determined by cgerqf (unblocked algorithm).
subroutine cunmr3 (SIDE, TRANS, M, N, K, L, A, LDA, TAU, C, LDC, WORK, INFO) — CUNMR3 multiplies a general matrix by the unitary matrix from a RZ factorization determined by ctzrzf (unblocked algorithm).
subroutine cunmrq (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — CUNMRQ
subroutine cunmrz (SIDE, TRANS, M, N, K, L, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — CUNMRZ
subroutine cunmtr (SIDE, UPLO, TRANS, M, N, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — CUNMTR
subroutine cupgtr (UPLO, N, AP, TAU, Q, LDQ, WORK, INFO) — CUPGTR
subroutine cupmtr (SIDE, UPLO, TRANS, M, N, AP, TAU, C, LDC, WORK, INFO) — CUPMTR
subroutine dorm22 (SIDE, TRANS, M, N, N1, N2, Q, LDQ, C, LDC, WORK, LWORK, INFO) — DORM22 multiplies a general matrix by a banded orthogonal matrix.
subroutine sorm22 (SIDE, TRANS, M, N, N1, N2, Q, LDQ, C, LDC, WORK, LWORK, INFO) — SORM22 multiplies a general matrix by a banded orthogonal matrix.
subroutine zunm22 (SIDE, TRANS, M, N, N1, N2, Q, LDQ, C, LDC, WORK, LWORK, INFO) — ZUNM22 multiplies a general matrix by a banded unitary matrix.

Detailed Description

This is the group of complex other Computational routines.

Okay so literally this whole page is the group of complex other Computational routines. It's giving "we do the math so you don't have to" energy. 💅

Function Documentation

subroutine cbbcsd (character JOBU1, character JOBU2, character JOBV1T, character JOBV2T, character TRANS, integer M, integer P, integer Q, real, dimension( * ) THETA, real, dimension( * ) PHI, complex, dimension( ldu1, * ) U1, integer LDU1, complex, dimension( ldu2, * ) U2, integer LDU2, complex, dimension( ldv1t, * ) V1T, integer LDV1T, complex, dimension( ldv2t, * ) V2T, integer LDV2T, real, dimension( * ) B11D, real, dimension( * ) B11E, real, dimension( * ) B12D, real, dimension( * ) B12E, real, dimension( * ) B21D, real, dimension( * ) B21E, real, dimension( * ) B22D, real, dimension( * ) B22E, real, dimension( * ) RWORK, integer LRWORK, integer INFO)

   subroutine cbbcsd (character JOBU1, character JOBU2, character JOBV1T,
       character JOBV2T, character TRANS, integer M, integer P, integer Q,
       real, dimension( * ) THETA, real, dimension( * ) PHI, complex,
       dimension( ldu1, * ) U1, integer LDU1, complex, dimension( ldu2, * ) U2,
       integer LDU2, complex, dimension( ldv1t, * ) V1T, integer LDV1T,
       complex, dimension( ldv2t, * ) V2T, integer LDV2T, real, dimension( * )
       B11D, real, dimension( * ) B11E, real, dimension( * ) B12D, real,
       dimension( * ) B12E, real, dimension( * ) B21D, real, dimension( * )
       B21E, real, dimension( * ) B22D, real, dimension( * ) B22E, real,
       dimension( * ) RWORK, integer LRWORK, integer INFO)

CBBCSD

Purpose:

CBBCSD computes the CS decomposition of a unitary matrix in bidiagonal-block form, bestie. It's giving linear algebra realness. 💅

                [ B11 | B12 0  0 ]
                [  0  |  0 -I  0 ]
            X = [----------------]
                [ B21 | B22 0  0 ]
                [  0  |  0  0  I ]

and it's equal to:

                                          [  C | -S  0  0 ]
                              [ U1 |    ] [  0 |  0 -I  0 ] [ V1 |    ]**H
                            = [---------] [---------------] [---------]   .
                              [    | U2 ] [  S |  C  0  0 ] [    | V2 ]
                                          [  0 |  0  0  I ]

So X is M-by-M, its top-left block is P-by-Q, and Q has to be no larger than P, M-P, or M-Q. (If Q isn't the smallest index, then X has to be transposed and/or permuted. You can do that in constant time using the TRANS and SIGNS options. See CUNCSD for the full tea.)

The bidiagonal matrices B11, B12, B21, and B22 are represented implicitly by angles THETA(1:Q) and PHI(1:Q-1).

The unitary matrices U1, U2, V1T, and V2T are input/output. The input matrices are pre- or post-multiplied by the appropriate singular vector matrices.

Parameters

JOBU1 — JOBU1 is CHARACTER. If it's 'Y', then U1 is updated; otherwise, U1 is not updated.

JOBU2 — JOBU2 is CHARACTER. If it's 'Y', then U2 is updated; otherwise, U2 is not updated.

JOBV1T — JOBV1T is CHARACTER. If it's 'Y', then V1T is updated; otherwise, V1T is not updated.

JOBV2T — JOBV2T is CHARACTER. If it's 'Y', then V2T is updated; otherwise, V2T is not updated.

TRANS — TRANS is CHARACTER. If it's 'T', then X, U1, U2, V1T, and V2T are stored in row-major order; otherwise, they're stored in column-major order.

M — M is INTEGER. The number of rows and columns in X, the unitary matrix in bidiagonal-block form.

P — P is INTEGER. The number of rows in the top-left block of X. 0 <= P <= M.

Q — Q is INTEGER. The number of columns in the top-left block of X. 0 <= Q <= MIN(P,M-P,M-Q).

THETA — THETA is REAL array, dimension (Q). On entry, the angles THETA(1),...,THETA(Q) that, along with PHI(1), ...,PHI(Q-1), define the matrix in bidiagonal-block form. On exit, the angles whose cosines and sines define the diagonal blocks in the CS decomposition.

PHI

PHI — REAL array, dimension (Q-1). These are the angles PHI(1),...,PHI(Q-1) that, together with THETA(1),...,THETA(Q), define the matrix in bidiagonal-block form. bestie these are the ✨ vibe coordinates ✨ of your whole decomposition 💫
U1 — COMPLEX array, dimension (LDU1,P). On entry, a P-by-P matrix. On exit, U1 is postmultiplied by the left singular vector matrix common to [ B11 ; 0 ] and [ B12 0 0 ; 0 -I 0 0 ]. so it goes in normal and comes out wearing a whole new outfit 💅
LDU1 — INTEGER. The leading dimension of the array U1, LDU1 >= MAX(1,P). don't fumble this one, she's picky 🎀
U2 — COMPLEX array, dimension (LDU2,M-P). On entry, an (M-P)-by-(M-P) matrix. On exit, U2 is postmultiplied by the left singular vector matrix common to [ B21 ; 0 ] and [ B22 0 0 ; 0 0 I ]. same energy, different block 🌸
LDU2 — INTEGER. The leading dimension of the array U2, LDU2 >= MAX(1,M-P).
V1T — COMPLEX array, dimension (LDV1T,Q). On entry, a Q-by-Q matrix. On exit, V1T is premultiplied by the conjugate transpose of the right singular vector matrix common to [ B11 ; 0 ] and [ B21 ; 0 ]. note the conjugate transpose bestie, she's fancy like that ✨
LDV1T — INTEGER. The leading dimension of the array V1T, LDV1T >= MAX(1,Q).
V2T — COMPLEX array, dimension (LDV2T,M-Q). On entry, an (M-Q)-by-(M-Q) matrix. On exit, V2T is premultiplied by the conjugate transpose of the right singular vector matrix common to [ B12 0 0 ; 0 -I 0 ] and [ B22 0 0 ; 0 0 I ]. 🦋
LDV2T — INTEGER. The leading dimension of the array V2T, LDV2T >= MAX(1,M-Q).
B11D — REAL array, dimension (Q). When CBBCSD converges, B11D contains the cosines of THETA(1), ..., THETA(Q). If CBBCSD fails to converge, then B11D contains the diagonal of the partially reduced top-left block. 😭 it tried its best
B11E — REAL array, dimension (Q-1). When CBBCSD converges, B11E contains zeros. If CBBCSD fails to converge, then B11E contains the superdiagonal of the partially reduced top-left block.
B12D — REAL array, dimension (Q). When CBBCSD converges, B12D contains the negative sines of THETA(1), ..., THETA(Q). If CBBCSD fails to converge, then B12D contains the diagonal of the partially reduced top-right block. negative sines?? it's giving unbothered 💀
B12E — REAL array, dimension (Q-1). When CBBCSD converges, B12E contains zeros. If CBBCSD fails to converge, then B12E contains the subdiagonal of the partially reduced top-right block.
B21D — REAL array, dimension (Q). When CBBCSD converges, B21D contains the negative sines of THETA(1), ..., THETA(Q). If CBBCSD fails to converge, then B21D contains the diagonal of the partially reduced bottom-left block.
B21E — REAL array, dimension (Q-1). When CBBCSD converges, B21E contains zeros. If CBBCSD fails to converge, then B21E contains the subdiagonal of the partially reduced bottom-left block.
B22D — REAL array, dimension (Q). When CBBCSD converges, B22D contains the negative sines of THETA(1), ..., THETA(Q). If CBBCSD fails to converge, then B22D contains the diagonal of the partially reduced bottom-right block.
B22E — REAL array, dimension (Q-1). When CBBCSD converges, B22E contains zeros. If CBBCSD fails to converge, then B22E contains the subdiagonal of the partially reduced bottom-right block. that's all four corners accounted for, slay 🫶
RWORK — REAL array, dimension (MAX(1,LRWORK)). On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. she's the workspace bestie, she's carrying the whole operation 🧚
LRWORK — INTEGER. The dimension of the array RWORK. LRWORK >= MAX(1,8*Q).

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the RWORK array, returns this value as the first entry of the work array, and no error message related to LRWORK is issued by XERBLA. so you can just ask first, iconic behaviour honestly 👑

INFO — INTEGER.
- = 0: successful exit. we love to see it 💖
- < 0: if INFO = -i, the i-th argument had an illegal value. bestie you fed her something wrong 🙈
- > 0: if CBBCSD did not converge, INFO specifies the number of nonzero entries in PHI, and B11D, B11E, etc., contain the partially reduced matrix. the QR loop said "not today" 😭

🧠 Internal Parameters 🧠

TOLMUL — REAL, default = MAX(10,MIN(100,EPS**(-1/8))). TOLMUL controls the convergence criterion of the QR loop. Angles THETA(i), PHI(i) are rounded to 0 or PI/2 when they are within TOLMUL*EPS of either bound. so it's the "close enough, wrap it up" threshold, periodt ✨

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

subroutine cbdsqr (character UPLO, integer N, integer NCVT, integer NRU,
    integer NCC, real, dimension( * ) D, real, dimension( * ) E, complex,
    dimension( ldvt, * ) VT, integer LDVT, complex, dimension( ldu, * ) U,
    integer LDU, complex, dimension( ldc, * ) C, integer LDC, real,
    dimension( * ) RWORK, integer INFO)

🦋 CBDSQR 🦋

✨ Purpose ✨

Okay so CBDSQR computes the singular values and, optionally, the right and/or left singular vectors from the singular value decomposition (SVD) of a real N-by-N (upper or lower) bidiagonal matrix B using the implicit zero-shift QR algorithm. 🎀

The SVD of B has the form

   B = Q * S * P**H

where S is the diagonal matrix of singular values, Q is an orthogonal matrix of left singular vectors, and P is an orthogonal matrix of right singular vectors. 💫

If left singular vectors are requested, this subroutine actually returns U*Q instead of Q, and, if right singular vectors are requested, this subroutine returns P**H*VT instead of P**H, for given complex input matrices U and VT. When U and VT are the unitary matrices that reduce a general matrix A to bidiagonal form: A = U*B*VT, as computed by CGEBRD, then

   A = (U*Q) * S * (P**H*VT)

is the SVD of A. Optionally, the subroutine may also compute Q**H*C for a given complex input matrix C. no cap, it just does all that 🔥

See 'Computing Small Singular Values of Bidiagonal Matrices With Guaranteed High Relative Accuracy,' by J. Demmel and W. Kahan, LAPACK Working Note #3 (or SIAM J. Sci. Statist. Comput. vol. 11, no. 5, pp. 873-912, Sept 1990) and 'Accurate singular values and differential qd algorithms,' by B. Parlett and V. Fernando, Technical Report CPAM-554, Mathematics Department, University of California at Berkeley, July 1992 for a detailed description of the algorithm. the lore is deep, iykyk 📖

🎀 Parameters 🎀

UPLO — CHARACTER*1.
- = 'U': B is upper bidiagonal;
- = 'L': B is lower bidiagonal.
N — INTEGER. The order of the matrix B. N >= 0.
NCVT — INTEGER. The number of columns of the matrix VT. NCVT >= 0.
NRU — INTEGER. The number of rows of the matrix U. NRU >= 0.
NCC — INTEGER. The number of columns of the matrix C. NCC >= 0.
D — REAL array, dimension (N). On entry, the n diagonal elements of the bidiagonal matrix B. On exit, if INFO=0, the singular values of B in decreasing order. ⭐
E — REAL array, dimension (N-1). On entry, the N-1 offdiagonal elements of the bidiagonal matrix B. On exit, if INFO = 0, E is destroyed; if INFO > 0, D and E will contain the diagonal and superdiagonal elements of a bidiagonal matrix orthogonally equivalent to the one given as input. 😭 gone but not forgotten
VT — COMPLEX array, dimension (LDVT, NCVT). On entry, an N-by-NCVT matrix VT. On exit, VT is overwritten by P**H * VT. Not referenced if NCVT = 0.
LDVT — INTEGER. The leading dimension of the array VT. LDVT >= max(1,N) if NCVT > 0; LDVT >= 1 if NCVT = 0. read that again bestie, it's conditional 💅
U — COMPLEX array, dimension (LDU, N). On entry, an NRU-by-N matrix U. On exit, U is overwritten by U * Q. Not referenced if NRU = 0.
LDU — INTEGER. The leading dimension of the array U. LDU >= max(1,NRU).
C — COMPLEX array, dimension (LDC, NCC). On entry, an N-by-NCC matrix C. On exit, C is overwritten by Q**H * C. Not referenced if NCC = 0.
LDC — INTEGER. The leading dimension of the array C. LDC >= max(1,N) if NCC > 0; LDC >=1 if NCC = 0.
RWORK — REAL array, dimension (4*N).
INFO — INTEGER.
- = 0: successful exit 💖
- < 0: If INFO = -i, the i-th argument had an illegal value
- > 0: the algorithm did not converge; D and E contain the elements of a bidiagonal matrix which is orthogonally similar to the input matrix B; if INFO = i, i elements of E have not converged to zero. the QR loop clocked out early, we've all been there 🫠

🧠 Internal Parameters 🧠

TOLMUL REAL, default = max(10,min(100,EPS**(-1/8))) — okay bestie, this one controls the convergence criterion of the QR loop. It's giving precision vibes ✨. Let's break it down:
- If it's positive, then TOLMUL*EPS is the desired relative precision in the computed singular values.
- If it's negative, then abs(TOLMUL*EPS*sigma_max) is the desired absolute accuracy in the computed singular values (which corresponds to relative accuracy abs(TOLMUL*EPS) in the largest singular value).
- abs(TOLMUL) should be between 1 and 1/EPS, and preferably between 10 (for fast convergence) and .1/EPS (so there's actually some accuracy in the results).
- The default is to lose at either one eighth or 2 of the available decimal digits in each computed singular value (whichever is smaller).
MAXITR INTEGER, default = 6 — this controls the maximum number of passes of the algorithm through its inner loop. The algorithm stops (and so fails to converge) if the number of passes through the inner loop exceeds MAXITR*N**2. No cap, that's a lot of passes. 💀

✨ Author ✨

Shoutout to the authors, periodt. 💅

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

subroutine cgghd3 (character COMPQ, character COMPZ, integer N, integer ILO,
    integer IHI, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( ldb, * ) B, integer LDB, complex, dimension( ldq, * ) Q,
    integer LDQ, complex, dimension( ldz, * ) Z, integer LDZ, complex,
    dimension( * ) WORK, integer LWORK, integer INFO)

👑 CGGHD3 👑

✨ Purpose ✨

Okay so CGGHD3 is literally the main character here 🎀. It reduces a pair of complex matrices (A,B) to generalized upper Hessenberg form using unitary transformations, where A is a general matrix and B is upper triangular. The form of the generalized eigenvalue problem is

A*x = lambda*B*x,

and B is typically made upper triangular by computing its QR factorization and moving the unitary matrix Q to the left side of the equation. It's giving "let's make this problem easier" energy. ✨

This subroutine simultaneously reduces A to a Hessenberg matrix H:

Q**H*A*Z = H

and transforms B to another upper triangular matrix T:

Q**H*B*Z = T

in order to reduce the problem to its standard form

H*y = lambda*T*y

where y = Z**H*x. Obsessed with this transformation, fr fr. 💖

The unitary matrices Q and Z are determined as products of Givens rotations. They may either be formed explicitly, or they may be postmultiplied into input matrices Q1 and Z1, so that

Q1 * A * Z1**H = (Q1*Q) * H * (Z1*Z)**H

Q1 * B * Z1**H = (Q1*Q) * T * (Z1*Z)**H

If Q1 is the unitary matrix from the QR factorization of B in the original equation A*x = lambda*B*x, then CGGHD3 reduces the original problem to generalized Hessenberg form. Slay. 💅

This is a blocked variant of CGGHRD, using matrix-matrix multiplications for parts of the computation to enhance performance. So it's like CGGHRD but with extra glow-up. ✨

✨ Parameters ✨

COMPQ — CHARACTER1*
- 'N': do not compute Q;
- 'I': Q is initialized to the unit matrix, and the unitary matrix Q is returned;
- 'V': Q must contain a unitary matrix Q1 on entry, and the product Q1*Q is returned.
COMPZ — CHARACTER1*
- 'N': do not compute Z;
- 'I': Z is initialized to the unit matrix, and the unitary matrix Z is returned;
- 'V': Z must contain a unitary matrix Z1 on entry, and the product Z1*Z is returned.
N — INTEGER The order of the matrices A and B. N >= 0.
ILO — INTEGER
IHI — INTEGER ILO and IHI mark the rows and columns of A which are to be reduced. It is assumed that A is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally set by a previous call to CGGBAL; otherwise they should be set to 1 and N respectively. 1 <= ILO <= IHI <= N, if N > 0; ILO=1 and IHI=0, if N=0.
A — COMPLEX array, dimension (LDA, N) On entry, the N-by-N general matrix to be reduced. On exit, the upper triangle and the first subdiagonal of A are overwritten with the upper Hessenberg matrix H, and the rest is set to zero.
LDA — INTEGER The leading dimension of the array A. LDA >= max(1,N).
B — COMPLEX array, dimension (LDB, N) On entry, the N-by-N upper triangular matrix B. On exit, the upper triangular matrix T = Q**H B Z. The elements below the diagonal are set to zero.
LDB — INTEGER The leading dimension of the array B. LDB >= max(1,N).
Q — COMPLEX array, dimension (LDQ, N) On entry, if COMPQ = 'V', the unitary matrix Q1, typically from the QR factorization of B. On exit, if COMPQ='I', the unitary matrix Q, and if COMPQ = 'V', the product Q1*Q. Not referenced if COMPQ='N'.
LDQ — INTEGER The leading dimension of the array Q. LDQ >= N if COMPQ='V' or 'I'; LDQ >= 1 otherwise.
Z — COMPLEX array, dimension (LDZ, N) On entry, if COMPZ = 'V', the unitary matrix Z1. On exit, if COMPZ='I', the unitary matrix Z, and if COMPZ = 'V', the product Z1*Z. Not referenced if COMPZ='N'.
LDZ — INTEGER The leading dimension of the array Z. LDZ >= N if COMPZ='V' or 'I'; LDZ >= 1 otherwise.
WORK — COMPLEX array, dimension (LWORK) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — INTEGER The length of the array WORK. LWORK >= 1. For optimum performance LWORK >= 6*N*NB, where NB is the optimal blocksize.

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 ✨

This routine reduces A to Hessenberg form and maintains B in triangular form using a blocked variant of Moler and Stewart's original algorithm, as described by Kagstrom, Kressner, Quintana-Orti, and Quintana-Orti (BIT 2008). Iconic. 👑

subroutine cgghrd (character COMPQ, character COMPZ, integer N, integer ILO,
    integer IHI, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( ldb, * ) B, integer LDB, complex, dimension( ldq, * ) Q,
    integer LDQ, complex, dimension( ldz, * ) Z, integer LDZ, integer INFO)

👑 CGGHRD 👑

✨ Purpose ✨

CGGHRD reduces a pair of complex matrices (A,B) to generalized upper Hessenberg form using unitary transformations, where A is a general matrix and B is upper triangular. The form of the generalized eigenvalue problem is

A*x = lambda*B*x,

and B is typically made upper triangular by computing its QR factorization and moving the unitary matrix Q to the left side of the equation. It's the same vibe as CGGHD3 but without the blocked variant glow-up. ✨

This subroutine simultaneously reduces A to a Hessenberg matrix H:

Q**H*A*Z = H

and transforms B to another upper triangular matrix T:

Q**H*B*Z = T

in order to reduce the problem to its standard form

H*y = lambda*T*y

where y = Z**H*x. Obsessed. 💖

The unitary matrices Q and Z are determined as products of Givens rotations. They may either be formed explicitly, or they may be postmultiplied into input matrices Q1 and Z1, so that

Q1 * A * Z1**H = (Q1*Q) * H * (Z1*Z)**H

Q1 * B * Z1**H = (Q1*Q) * T * (Z1*Z)**H

If Q1 is the unitary matrix from the QR factorization of B in the original equation A*x = lambda*B*x, then CGGHRD reduces the original problem to generalized Hessenberg form. Slay. 💅

✨ Parameters ✨

COMPQ — CHARACTER1*
- 'N': do not compute Q;
- 'I': Q is initialized to the unit matrix, and the unitary matrix Q is returned;
- 'V': Q must contain a unitary matrix Q1 on entry, and the product Q1*Q is returned.
COMPZ — CHARACTER1*
- 'N': do not compute Z;
- 'I': Z is initialized to the unit matrix, and the unitary matrix Z is returned;
- 'V': Z must contain a unitary matrix Z1 on entry, and the product Z1*Z is returned.
N — INTEGER The order of the matrices A and B. N >= 0.
ILO — INTEGER
IHI — INTEGER ILO and IHI mark the rows and columns of A which are to be reduced. It is assumed that A is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally set by a previous call to CGGBAL; otherwise they should be set to 1 and N respectively. 1 <= ILO <= IHI <= N, if N > 0; ILO=1 and IHI=0, if N=0.
A — COMPLEX array, dimension (LDA, N) On entry, the N-by-N general matrix to be reduced. On exit, the upper triangle and the first subdiagonal of A are overwritten with the upper Hessenberg matrix H, and the rest is set to zero.
LDA — INTEGER The leading dimension of the array A. LDA >= max(1,N).
B
B — a COMPLEX array, dimension (LDB, N). On entry, this is the N-by-N upper triangular matrix B bestie. On exit, it becomes the upper triangular matrix T = Q**H B Z. The elements below the diagonal? Set to zero. Wiped. Gone. 💅
LDB — INTEGER. The leading dimension of the array B. Rule is LDB >= max(1,N), no exceptions, no cap. 👑
Q — a COMPLEX array, dimension (LDQ, N). On entry, if COMPQ = 'V', this is the unitary matrix Q1, typically straight out of the QR factorization of B. On exit, if COMPQ='I' you get the unitary matrix Q, and if COMPQ = 'V' you get the product Q1*Q. And if COMPQ='N'? Not referenced at all, she's off the clock. 😌
LDQ — INTEGER. The leading dimension of the array Q. You need LDQ >= N if COMPQ='V' or 'I'; otherwise LDQ >= 1. That's it. That's the rule. ✨
Z — a COMPLEX array, dimension (LDZ, N). On entry, if COMPZ = 'V', it holds the unitary matrix Z1. On exit, if COMPZ='I' you get the unitary matrix Z, and if COMPZ = 'V' you get the product Z1*Z. If COMPZ='N' she is simply not referenced, living her best life elsewhere. 🦋
LDZ — INTEGER. The leading dimension of the array Z. LDZ >= N when COMPZ='V' or 'I'; LDZ >= 1 otherwise. Simple math, gorgeous math. 🌸
INFO — INTEGER. The vibe report:
- = 0: successful exit. We ate. 🔥
- < 0: if INFO = -i, the i-th argument had an illegal value. Somebody passed a bad number and the routine is telling on them. 💀

👑 Author

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

🔍 Further Details:

This routine reduces A to Hessenberg and B to triangular form by an unblocked reduction, as described in _Matrix_Computations_, by Golub and van Loan (Johns Hopkins Press).

🫶 subroutine cggqrf

subroutine cggqrf (integer N, integer M, integer P, complex, dimension( lda,
* ) A, integer LDA, complex, dimension( * ) TAUA, complex, dimension(
ldb, * ) B, integer LDB, complex, dimension( * ) TAUB, complex,
dimension( * ) WORK, integer LWORK, integer INFO)

CGGQRF — okay so this one is the moment. 💖

✨ Purpose:

CGGQRF computes a generalized QR factorization of an N-by-M matrix A and an N-by-P matrix B:

            A = Q*R,        B = Q*T*Z,

where Q is an N-by-N unitary matrix, Z is a P-by-P unitary matrix, and R and T assume one of the forms:

if N >= M,  R = ( R11 ) M  ,   or if N < M,  R = ( R11  R12 ) N,
                (  0  ) N-M                         N   M-N
                   M

where R11 is upper triangular, and

if N <= P,  T = ( 0  T12 ) N,   or if N > P,  T = ( T11 ) N-P,
                 P-N  N                           ( T21 ) P
                                                     P

where T12 or T21 is upper triangular.

In particular, if B is square and nonsingular, the GQR factorization of A and B implicitly gives the QR factorization of inv(B)*A:

             inv(B)*A = Z**H * (inv(T)*R)

where inv(B) denotes the inverse of the matrix B, and Z' denotes the conjugate transpose of matrix Z. No cap, that's just what she does. 🧚

🌈 Parameters

N — INTEGER. The number of rows of the matrices A and B. N >= 0. Don't come at her with negatives. 🙈
M — INTEGER. The number of columns of the matrix A. M >= 0.
P — INTEGER. The number of columns of the matrix B. P >= 0.
A — a COMPLEX array, dimension (LDA,M). On entry, the N-by-M matrix A. On exit, the elements on and above the diagonal of the array contain the min(N,M)-by-M upper trapezoidal matrix R (R is upper triangular if N >= M); the elements below the diagonal, together with the array TAUA, represent the unitary matrix Q as a product of min(N,M) elementary reflectors (see Further Details). She's multifunctional like that. 💅
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,N). Standard.
TAUA — a COMPLEX array, dimension (min(N,M)). The scalar factors of the elementary reflectors which represent the unitary matrix Q (see Further Details). ✨
B — a COMPLEX array, dimension (LDB,P). On entry, the N-by-P matrix B. On exit, if N <= P, the upper triangle of the subarray B(1:N,P-N+1:P) contains the N-by-N upper triangular matrix T; if N > P, the elements on and above the (N-P)-th subdiagonal contain the N-by-P upper trapezoidal matrix T; the remaining elements, with the array TAUB, represent the unitary matrix Z as a product of elementary reflectors (see Further Details). The way she reshapes a matrix... obsessed. 😭
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
TAUB — a COMPLEX array, dimension (min(N,P)). The scalar factors of the elementary reflectors which represent the unitary matrix Z (see Further Details).
WORK — a COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. Little sneak peek energy. 👀
LWORK — INTEGER. The dimension of the array WORK. LWORK >= max(1,N,M,P). For optimum performance, LWORK >= max(N,M,P)*max(NB1,NB2,NB3), where NB1 is the optimal blocksize for the QR factorization of an N-by-M matrix, NB2 is the optimal blocksize for the RQ factorization of an N-by-P matrix, and NB3 is the optimal blocksize for a call of CUNMQR.

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. She's not going to yell at you for a query, bestie. 🕊️

INFO — INTEGER. The receipts:
- = 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 matrix Q is represented as a product of elementary reflectors

   Q = H(1) H(2) . . . H(k), where k = min(n,m).

Each H(i) has the form

   H(i) = I - taua * v * v**H

where taua is a complex scalar, and v is a complex vector with v(1:i-1) = 0 and v(i) = 1; v(i+1:n) is stored on exit in A(i+1:n,i), and taua in TAUA(i).

To form Q explicitly, use LAPACK subroutine CUNGQR.

To use Q to update another matrix, use LAPACK subroutine CUNMQR.

The matrix Z is represented as a product of elementary reflectors

   Z = H(1) H(2) . . . H(k), where k = min(n,p).

Each H(i) has the form

   H(i) = I - taub * v * v**H

where taub is a complex scalar, and v is a complex vector with v(p-k+i+1:p) = 0 and v(p-k+i) = 1; v(1:p-k+i-1) is stored on exit in B(n-k+i,1:p-k+i-1), and taub in TAUB(i).

To form Z explicitly, use LAPACK subroutine CUNGRQ.

To use Z to update another matrix, use LAPACK subroutine CUNMRQ.

🎀 subroutine cggrqf

subroutine cggrqf (integer M, integer P, integer N, complex, dimension( lda,
* ) A, integer LDA, complex, dimension( * ) TAUA, complex, dimension(
ldb, * ) B, integer LDB, complex, dimension( * ) TAUB, complex,
dimension( * ) WORK, integer LWORK, integer INFO)

CGGRQF — the RQ sibling, and she is equally iconic. 🌟

✨ Purpose:

CGGRQF computes a generalized RQ factorization of an M-by-N matrix A and a P-by-N matrix B:

            A = R*Q,        B = Z*T*Q,

where Q is an N-by-N unitary matrix, Z is a P-by-P unitary matrix, and R and T assume one of the forms:

if M <= N,  R = ( 0  R12 ) M,   or if M > N,  R = ( R11 ) M-N,
                 N-M  M                           ( R21 ) N
                                                     N

where R12 or R21 is upper triangular, and

if P >= N,  T = ( T11 ) N  ,   or if P < N,  T = ( T11  T12 ) P,
                (  0  ) P-N                         P   N-P
                   N

where T11 is upper triangular.

In particular, if B is square and nonsingular, the GRQ factorization of A and B implicitly gives the RQ factorization of A*inv(B):

             A*inv(B) = (R*inv(T))*Z**H

where inv(B) denotes the inverse of the matrix B, and Z**H denotes the conjugate transpose of the matrix Z. Math girlies stay winning. 💜

🌈 Parameters

M — INTEGER. The number of rows of the matrix A. M >= 0.
P — INTEGER. The number of rows of the matrix B. P >= 0.
N — INTEGER. The number of columns of the matrices A and B. N >= 0.
A — a COMPLEX array, dimension (LDA,N). On entry, the M-by-N matrix A. On exit, if M <= N, the upper triangle of the subarray A(1:M,N-M+1:N) contains the M-by-M upper triangular matrix R; if M > N, the elements on and above the (M-N)-th subdiagonal contain the M-by-N upper trapezoidal matrix R; the remaining elements, with the array TAUA, represent the unitary matrix Q as a product of elementary reflectors (see Further Details). She contains multitudes fr fr. 🌈
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,M).
TAUA — a COMPLEX array, dimension (min(M,N)). The scalar factors of the elementary reflectors which represent the unitary matrix Q (see Further Details).
B — a COMPLEX array, dimension (LDB,N). On entry, the P-by-N matrix B. On exit, the elements on and above the diagonal of the array contain the min(P,N)-by-N upper trapezoidal matrix T (T is upper triangular if P >= N); the elements below the diagonal, with the array TAUB, represent the unitary matrix Z as a product of elementary reflectors (see Further Details).
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,P).
TAUB — a COMPLEX array, dimension (min(P,N)). The scalar factors of the elementary reflectors which represent the unitary matrix Z (see Further Details).
WORK
WORK — a COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. 💅
LWORK — INTEGER. It's the dimension of the array WORK. So LWORK >= max(1,N,M,P).

Now for the optimum performance ✨ glow-up: LWORK >= max(N,M,P)*max(NB1,NB2,NB3), where NB1 is the optimal blocksize for the RQ factorization of an M-by-N matrix, NB2 is the optimal blocksize for the QR factorization of a P-by-N matrix, and NB3 is the optimal blocksize for a call of CUNMRQ.

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. no cap 🧚

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: 🔍

Okay so the matrix Q is represented as a product of elementary reflectors:

Q = H(1) H(2) . . . H(k), where k = min(m,n).

Each H(i) has the form:

H(i) = I - taua * v * v**H

where taua is a complex scalar, and v is a complex vector with v(n-k+i+1:n) = 0 and v(n-k+i) = 1; v(1:n-k+i-1) is stored on exit in A(m-k+i,1:n-k+i-1), and taua in TAUA(i).

To form Q explicitly, use LAPACK subroutine CUNGRQ. To use Q to update another matrix, use LAPACK subroutine CUNMRQ.

And the matrix Z is represented as a product of elementary reflectors:

Z = H(1) H(2) . . . H(k), where k = min(p,n).

Each H(i) has the form:

H(i) = I - taub * v * v**H

where taub is a complex scalar, and v is a complex vector with v(1:i-1) = 0 and v(i) = 1; v(i+1:p) is stored on exit in B(i+1:p,i), and taub in TAUB(i).

To form Z explicitly, use LAPACK subroutine CUNGQR. To use Z to update another matrix, use LAPACK subroutine CUNMQR.

✨ subroutine cggsvp3 ✨

subroutine cggsvp3 (character JOBU, character JOBV, character JOBQ, integer
    M, integer P, integer N, complex, dimension( lda, * ) A, integer LDA,
    complex, dimension( ldb, * ) B, integer LDB, real TOLA, real TOLB,
    integer K, integer L, complex, dimension( ldu, * ) U, integer LDU,
    complex, dimension( ldv, * ) V, integer LDV, complex, dimension( ldq, *
    ) Q, integer LDQ, integer, dimension( * ) IWORK, real, dimension( * )
    RWORK, complex, dimension( * ) TAU, complex, dimension( * ) WORK,
    integer LWORK, integer INFO)
    CGGSVP3

🦋 Purpose: 🦋

Bestie, CGGSVP3 computes unitary matrices U, V and Q such that:

                   N-K-L  K    L
 U**H*A*Q =     K ( 0    A12  A13 )  if M-K-L >= 0;
                L ( 0     0   A23 )
            M-K-L ( 0     0    0  )

                 N-K-L  K    L
        =     K ( 0    A12  A13 )  if M-K-L < 0;
            M-K ( 0     0   A23 )

                 N-K-L  K    L
 V**H*B*Q =   L ( 0     0   B13 )
            P-L ( 0     0    0  )

where the K-by-K matrix A12 and the L-by-L matrix B13 are nonsingular upper triangular; A23 is L-by-L upper triangular if M-K-L >= 0, otherwise A23 is (M-K)-by-L upper trapezoidal. K+L = the effective numerical rank of the (M+P)-by-N matrix (A**H,B**H)**H. 🫶

This decomposition is the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see subroutine CGGSVD3.

🌸 Parameters 🌸

JOBU — CHARACTER*1
- 'U': Unitary matrix U is computed;
- 'N': U is not computed.
JOBV — CHARACTER*1
- 'V': Unitary matrix V is computed;
- 'N': V is not computed.
JOBQ — CHARACTER*1
- 'Q': Unitary matrix Q is computed;
- 'N': Q is not computed.
M — INTEGER. The number of rows of the matrix A. M >= 0.
P — INTEGER. The number of rows of the matrix B. P >= 0.
N — INTEGER. The number of columns of the matrices A and B. N >= 0.
A — COMPLEX array, dimension (LDA,N). On entry, the M-by-N matrix A. On exit, A contains the triangular (or trapezoidal) matrix described in the Purpose section. 💜
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,M).
B — COMPLEX array, dimension (LDB,N). On entry, the P-by-N matrix B. On exit, B contains the triangular matrix described in the Purpose section.
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,P).
TOLA — REAL
TOLB — REAL
- TOLA and TOLB are the thresholds to determine the effective numerical rank of matrix B and a subblock of A. Generally, they are set to

TOLA = MAX(M,N)*norm(A)*MACHEPS,
TOLB = MAX(P,N)*norm(B)*MACHEPS.

The size of TOLA and TOLB may affect the size of backward errors of the decomposition. so like, choose wisely 😭

K — INTEGER
L — INTEGER
- On exit, K and L specify the dimension of the subblocks described in Purpose section. K + L = effective numerical rank of (A**H,B**H)**H.
U — COMPLEX array, dimension (LDU,M). If JOBU = 'U', U contains the unitary matrix U. If JOBU = 'N', U is not referenced.
LDU — INTEGER. The leading dimension of the array U. LDU >= max(1,M) if JOBU = 'U'; LDU >= 1 otherwise.
V — COMPLEX array, dimension (LDV,P). If JOBV = 'V', V contains the unitary matrix V. If JOBV = 'N', V is not referenced.
LDV — INTEGER. The leading dimension of the array V. LDV >= max(1,P) if JOBV = 'V'; LDV >= 1 otherwise.
Q — COMPLEX array, dimension (LDQ,N). If JOBQ = 'Q', Q contains the unitary matrix Q. If JOBQ = 'N', Q is not referenced.
LDQ — INTEGER. The leading dimension of the array Q. LDQ >= max(1,N) if JOBQ = 'Q'; LDQ >= 1 otherwise.
IWORK — INTEGER array, dimension (N)
RWORK — REAL array, dimension (2*N)
TAU — COMPLEX array, dimension (N)
WORK — COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. ✨
LWORK — 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.
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 subroutine uses LAPACK subroutine CGEQP3 for the QR factorization with column pivoting to detect the effective numerical rank of a matrix. It may be replaced by a better rank determination strategy. fr fr, future you could do better 👑

CGGSVP3 replaces the deprecated subroutine CGGSVP.

✨ subroutine cgsvj0 ✨

subroutine cgsvj0 (character*1 JOBV, integer M, integer N, complex,
    dimension( lda, * ) A, integer LDA, complex, dimension( n ) D, real,
    dimension( n ) SVA, integer MV, complex, dimension( ldv, * ) V, integer
    LDV, real EPS, real SFMIN, real TOL, integer NSWEEP, complex, dimension(
    lwork ) WORK, integer LWORK, integer INFO)

CGSVJ0 pre-processor for the routine cgesvj.

🦋 Purpose: 🦋

CGSVJ0 is called from CGESVJ as a pre-processor and that is its main purpose. It applies Jacobi rotations in the same way as CGESVJ does, but it does not check convergence (stopping criterion). Few tuning parameters (marked by [TP]) are available for the implementer. slay, do your thing ✨

🌸 Parameters 🌸

JOBV — CHARACTER*1. Specifies whether the output from this procedure is used to compute the matrix V:
- 'V': the product of the Jacobi rotations is accumulated by postmulyiplying the N-by-N array V. (See the description of V.)
- 'A': the product of the Jacobi rotations is accumulated by postmulyiplying the MV-by-N array V. (See the descriptions of MV and V.)
- 'N': the Jacobi rotations are not accumulated.
M — INTEGER. The number of rows of the input matrix A. M >= 0.
N — INTEGER. The number of columns of the input matrix A. M >= N >= 0.
A — COMPLEX array, dimension (LDA,N). On entry, M-by-N matrix A, such that A*diag(D) represents the input matrix. On exit, A_onexit * diag(D_onexit) represents the input matrix A*diag(D) post-multiplied by a sequence of Jacobi rotations, where the rotation threshold and the total number of sweeps are given in TOL and NSWEEP, respectively. (See the descriptions of D, TOL and NSWEEP.) 💅
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,M).
D
D — okay bestie, D is a COMPLEX array, dimension (N). The array D accumulates the scaling factors from the complex scaled Jacobi rotations. On entry, A*diag(D) represents the input matrix. On exit, A_onexit*diag(D_onexit) represents the input matrix post-multiplied by a sequence of Jacobi rotations, where the rotation threshold and the total number of sweeps are given in TOL and NSWEEP, respectively. (See the descriptions of A, TOL, and NSWEEP.) She's the scaling queen. 💅
SVA — SVA is a REAL array, dimension (N). On entry, SVA contains the Euclidean norms of the columns of the matrix A*diag(D). On exit, SVA contains the Euclidean norms of the columns of the matrix A_onexit*diag(D_onexit). Norms, but make it fashion. ✨
MV — MV is an INTEGER. If JOBV = 'A', then MV rows of V are post-multipled by a sequence of Jacobi rotations. If JOBV = 'N', then MV is not referenced. She's only on the guest list when JOBV says so. 🙈
V — V is a COMPLEX array, dimension (LDV,N). If JOBV = 'V', then N rows of V are post-multipled by a sequence of Jacobi rotations. If JOBV = 'A', then MV rows of V are post-multipled by a sequence of Jacobi rotations. If JOBV = 'N', then V is not referenced. She's the transformation matrix, obviously. 👑
LDV — LDV is an INTEGER. The leading dimension of the array V, so LDV >= 1. If JOBV = 'V', then LDV >= N. If JOBV = 'A', then LDV >= MV. Respect the dimensions. 💅
EPS — EPS is REAL. And EPS = SLAMCH('Epsilon'). Periodt.
SFMIN — SFMIN is REAL. And SFMIN = SLAMCH('Safe Minimum'). Safety first, bestie. 🛟
TOL — TOL is REAL. TOL is the threshold for Jacobi rotations. For a pair A(:,p), A(:,q) of pivot columns, the Jacobi rotation is applied only if ABS(COS(angle(A(:,p),A(:,q)))) > TOL. She's picky, and that's the point. 💅
NSWEEP — NSWEEP is an INTEGER. NSWEEP is the number of sweeps of Jacobi rotations to be performed. Get into the sweep era. 🧹
WORK — WORK is a COMPLEX array, dimension (LWORK). The workspace, the backstage crew. 🎀
LWORK — LWORK is an INTEGER. LWORK is the dimension of WORK. So LWORK >= M. Don't be stingy with the workspace. 💖
INFO — INFO is an INTEGER. = 0: successful exit. < 0: if INFO = -i, then the i-th argument had an illegal value. So if it's negative, something's sus. 😭

Author

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

Further Details:

CGSVJ0 is used just to enable CGESVJ to call a simplified version of itself to work on a submatrix of the original matrix. It's giving "I can do it myself" but make it linear algebra. 😇

Contributor:

Zlatko Drmac (Zagreb, Croatia) — the icon, the legend. 👑

Bugs, Examples and Comments:

Please report all bugs and send interesting test examples and comments to drmac@math.hr. Thank you! 💌

subroutine cgsvj1

subroutine cgsvj1 (character*1 JOBV, integer M, integer N, integer N1,
    complex, dimension( lda, * ) A, integer LDA, complex, dimension( n ) D,
    real, dimension( n ) SVA, integer MV, complex, dimension( ldv, * ) V,
    integer LDV, real EPS, real SFMIN, real TOL, integer NSWEEP, complex,
    dimension( lwork ) WORK, integer LWORK, integer INFO)

CGSVJ1 pre-processor for the routine cgesvj, applies Jacobi rotations targeting only particular pivots.

Purpose:

CGSVJ1 is called from CGESVJ as a pre-processor and that is its main purpose. It applies Jacobi rotations in the same way as CGESVJ does, but it targets only particular pivots and it does not check convergence (stopping criterion). A few tuning parameters (marked by [TP]) are available for the implementer. You know, for the customizations. 💅

Further Details

CGSVJ1 applies few sweeps of Jacobi rotations in the column space of the input M-by-N matrix A. The pivot pairs are taken from the (1,2) off-diagonal block in the corresponding N-by-N Gram matrix A^T * A. The block-entries (tiles) of the (1,2) off-diagonal block are marked by the [x]'s in the following scheme:

   | *  *  * [x] [x] [x]|
   | *  *  * [x] [x] [x]|    Row-cycling in the nblr-by-nblc [x] blocks.
   | *  *  * [x] [x] [x]|    Row-cyclic pivoting inside each [x] block.
   |[x] [x] [x] *  *  * |
   |[x] [x] [x] *  *  * |
   |[x] [x] [x] *  *  * |

In terms of the columns of A, the first N1 columns are rotated 'against' the remaining N-N1 columns, trying to increase the angle between the corresponding subspaces. The off-diagonal block is N1-by-(N-N1) and it is tiled using quadratic tiles of side KBL. Here, KBL is a tuning parameter. The number of sweeps is given in NSWEEP and the orthogonality threshold is given in TOL. So basically it's a targeted glow-up for the matrix. ✨

Parameters

JOBV — JOBV is a CHARACTER*1. Specifies whether the output from this procedure is used to compute the matrix V:
- = 'V': the product of the Jacobi rotations is accumulated by postmulyiplying the N-by-N array V. (See the description of V.)
- = 'A': the product of the Jacobi rotations is accumulated by postmulyiplying the MV-by-N array V. (See the descriptions of MV and V.)
- = 'N': the Jacobi rotations are not accumulated. She said "not me." 🙈
M — M is an INTEGER. The number of rows of the input matrix A. So M >= 0. Keep it non-negative, bestie. 💖
N — N is an INTEGER. The number of columns of the input matrix A. And M >= N >= 0. The hierarchy is real. 👑
N1 — N1 is an INTEGER. N1 specifies the 2 x 2 block partition, the first N1 columns are rotated 'against' the remaining N-N1 columns of A. It's giving "versus" energy. ⚔️
A — A is a COMPLEX array, dimension (LDA,N). On entry, M-by-N matrix A, such that A*diag(D) represents the input matrix. On exit, A_onexit * D_onexit represents the input matrix A*diag(D) post-multiplied by a sequence of Jacobi rotations, where the rotation threshold and the total number of sweeps are given in TOL and NSWEEP, respectively. (See the descriptions of N1, D, TOL, and NSWEEP.) She's the main character, obviously. 🌟
LDA — LDA is an INTEGER. The leading dimension of the array A. So LDA >= max(1,M). Respect the leading dimension. 💅
D — D is a COMPLEX array, dimension (N). The array D accumulates the scaling factors from the fast scaled Jacobi rotations. On entry, A*diag(D) represents the input matrix. On exit, A_onexit*diag(D_onexit) represents the input matrix post-multiplied by a sequence of Jacobi rotations, where the rotation threshold and the total number of sweeps are given in TOL and NSWEEP, respectively. (See the descriptions of N1, A, TOL, and NSWEEP.) She's the fast one, okay? 🏎️
SVA — SVA is a REAL array, dimension (N). On entry, SVA contains the Euclidean norms of the columns of the matrix A*diag(D). On exit, SVA contains the Euclidean norms of the columns of the matrix onexit*diag(D_onexit). (Yes, it says onexit — we're keeping it exactly as the original. 😌)
MV — MV is an INTEGER. If JOBV = 'A', then MV rows of V are post-multipled by a sequence of Jacobi rotations. If JOBV = 'N', then MV is not referenced. She's only relevant when JOBV says so. 💅
V — V is a COMPLEX array, dimension (LDV,N). If JOBV = 'V', then N rows of V are post-multipled by a sequence of Jacobi rotations. If JOBV = 'A', then MV rows of V are post-multipled by a sequence of Jacobi rotations. If JOBV = 'N', then V is not referenced. She's the transformation matrix, serving looks. 👑
LDV — LDV is an INTEGER. The leading dimension of the array V, so LDV >= 1. If JOBV = 'V', then LDV >= N. If JOBV = 'A', then LDV >= MV. Math checks out. 🔢
EPS — EPS is REAL. And EPS = SLAMCH('Epsilon'). Same as before, but still iconic. ✨
SFMIN — SFMIN is REAL. And SFMIN = SLAMCH('Safe Minimum'). Safety first. 🛟
TOL — TOL is REAL. TOL is the threshold for Jacobi rotations. For a pair A(:,p), A(:,q) of pivot columns, the Jacobi rotation is applied only if ABS(COS(angle(A(:,p),A(:,q)))) > TOL. She's picky, and that's okay. 💅
NSWEEP — NSWEEP is an INTEGER. NSWEEP is the number of sweeps of Jacobi rotations to be performed. Get those sweeps in. 🧹
WORK — WORK is a COMPLEX array, dimension (LWORK). The workspace, the behind-the-scenes queen. 🎀
LWORK — LWORK is an INTEGER. LWORK is the dimension of WORK. So LWORK >= M. Don't skimp on the workspace. 💖
INFO — INFO is an INTEGER. = 0: successful exit. < 0: if INFO = -i, then the i-th argument had an illegal value. So if it's negative, something's not giving. 😭

Author

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

Contributor:

Zlatko Drmac (Zagreb, Croatia) — again, the legend. 👑

subroutine chbgst

subroutine chbgst (character VECT, character UPLO, integer N, integer KA,
    integer KB, complex, dimension( ldab, * ) AB, integer LDAB, complex,
    dimension( ldbb, * ) BB, integer LDBB, complex, dimension( ldx, * ) X,
    integer LDX, complex, dimension( * ) WORK, real, dimension( * ) RWORK,
    integer INFO)

CHBGST

Purpose:

CHBGST reduces a complex Hermitian-definite banded generalized eigenproblem A*x = lambda*B*x to standard form C*y = lambda*y, such that C has the same bandwidth as A.

B must have been previously factorized as S**H*S by CPBSTF, using a split Cholesky factorization. A is overwritten by C = X**H*A*X, where X = S**(-1)*Q and Q is a unitary matrix chosen to preserve the bandwidth of A. So it's a glow-up that keeps the shape. 💅

Parameters

VECT — VECT is a CHARACTER*1. = 'N': do not form the transformation matrix X; = 'V': form X. She decides if X gets to exist. ✨
UPLO — UPLO is a CHARACTER*1. = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. Pick your side. 💅
N — N is an INTEGER. The order of the matrices A and B. So N >= 0. The size queen. 👑
KA
KA (INTEGER) — the number of superdiagonals of matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KA >= 0. 💅
KB (INTEGER) — the number of superdiagonals of matrix B if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KA >= KB >= 0. ✨
AB (COMPLEX array, dimension (LDAB,N)) — On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first ka+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(ka+1+i-j,j) = A(i,j) for max(1,j-ka)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+ka).

On exit, the transformed matrix X**H*A*X, stored in the same format as A. 🦋

LDAB (INTEGER) — the leading dimension of the array AB. LDAB >= KA+1. 💖
BB (COMPLEX array, dimension (LDBB,N)) — the banded factor S from the split Cholesky factorization of B, as returned by CPBSTF, stored in the first kb+1 rows of the array. 🌸
LDBB (INTEGER) — the leading dimension of the array BB. LDBB >= KB+1. 🎀
X (COMPLEX array, dimension (LDX,N)) — if VECT = 'V', the n-by-n matrix X. If VECT = 'N', the array X is not referenced. 🧚
LDX (INTEGER) — the leading dimension of the array X. LDX >= max(1,N) if VECT = 'V'; LDX >= 1 otherwise. 💜
WORK (COMPLEX array, dimension (N)) — your workspace, bestie. ✨
RWORK (REAL array, dimension (N)) — real workspace, no cap. 💅
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.

subroutine `chbtrd`

subroutine chbtrd (character VECT, character UPLO, integer N, integer KD,
    complex, dimension( ldab, * ) AB, integer LDAB, real, dimension( * ) D,
    real, dimension( * ) E, complex, dimension( ldq, * ) Q, integer LDQ,
    complex, dimension( * ) WORK, integer INFO)
    CHBTRD

Purpose

CHBTRD reduces a complex Hermitian band matrix A to real symmetric tridiagonal form T by a unitary similarity transformation: Q**H * A * Q = T. 🔥

Parameters

VECT (CHARACTER1)* — = 'N': do not form Q; = 'V': form Q; = 'U': update a matrix X, by forming X*Q. 👑
UPLO (CHARACTER1)* — = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. 🌈
N (INTEGER) — The order of the matrix A. N >= 0. 💖
KD (INTEGER) — The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0. ✨
AB (COMPLEX array, dimension (LDAB,N)) — On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

On exit, the diagonal elements of AB are overwritten by the diagonal elements of the tridiagonal matrix T; if KD > 0, the elements on the first superdiagonal (if UPLO = 'U') or the first subdiagonal (if UPLO = 'L') are overwritten by the off-diagonal elements of T; the rest of AB is overwritten by values generated during the reduction. 🦋

LDAB (INTEGER) — The leading dimension of the array AB. LDAB >= KD+1. 🎀
D (REAL array, dimension (N)) — The diagonal elements of the tridiagonal matrix T. 💜
E (REAL array, dimension (N-1)) — The off-diagonal elements of the tridiagonal matrix T: E(i) = T(i,i+1) if UPLO = 'U'; E(i) = T(i+1,i) if UPLO = 'L'. 🧚
Q (COMPLEX array, dimension (LDQ,N)) — On entry, if VECT = 'U', then Q must contain an N-by-N matrix X; if VECT = 'N' or 'V', then Q need not be set.

On exit:

if VECT = 'V', Q contains the N-by-N unitary matrix Q;
if VECT = 'U', Q contains the product X*Q;
if VECT = 'N', the array Q is not referenced. 🌸

LDQ (INTEGER) — The leading dimension of the array Q. LDQ >= 1, and LDQ >= N if VECT = 'V' or 'U'. 💅
WORK (COMPLEX array, dimension (N)) — workspace, periodt. ✨
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

Modified by Linda Kaufman, Bell Labs. 👑

subroutine `chetrd_hb2st`

subroutine chetrd_hb2st (character STAGE1, character VECT, character UPLO,
    integer N, integer KD, complex, dimension( ldab, * ) AB, integer LDAB,
    real, dimension( * ) D, real, dimension( * ) E, complex, dimension( * )
    HOUS, integer LHOUS, complex, dimension( * ) WORK, integer LWORK,
    integer INFO)
    CHETRD_HB2ST reduces a complex Hermitian band matrix A to real symmetric
    tridiagonal form T

CHETRD_HB2ST reduces a complex Hermitian band matrix A to real symmetric tridiagonal form T. 🔥

Purpose

CHETRD_HB2ST reduces a complex Hermitian band matrix A to real symmetric tridiagonal form T by a unitary similarity transformation: Q**H * A * Q = T. 💖

Parameters

STAGE1 (CHARACTER1)* — = 'N': 'No': to mention that the stage 1 of the reduction from dense to band using the chetrd_he2hb routine was not called before this routine to reproduce AB. In other term this routine is called as standalone. = 'Y': 'Yes': to mention that the stage 1 of the reduction from dense to band using the chetrd_he2hb routine has been called to produce AB (e.g., AB is the output of chetrd_he2hb). 🦋
VECT (CHARACTER1)* — = 'N': No need for the Householder representation, and thus LHOUS is of size max(1, 4*N); = 'V': the Householder representation is needed to either generate or to apply Q later on, then LHOUS is to be queried and computed. (NOT AVAILABLE IN THIS RELEASE). 💅
UPLO (CHARACTER1)* — = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. 🌈
N (INTEGER) — The order of the matrix A. N >= 0. ✨
KD (INTEGER) — The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0. 💖
AB (COMPLEX array, dimension (LDAB,N)) — On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

LDAB (INTEGER) — The leading dimension of the array AB. LDAB >= KD+1. 💜
D (REAL array, dimension (N)) — The diagonal elements of the tridiagonal matrix T. 🧚
E (REAL array, dimension (N-1)) — The off-diagonal elements of the tridiagonal matrix T: E(i) = T(i,i+1) if UPLO = 'U'; E(i) = T(i+1,i) if UPLO = 'L'. 🌸
HOUS (COMPLEX array, dimension LHOUS) — that store the Householder representation. 💅
LHOUS (INTEGER) — The dimension of the array HOUS. LHOUS = MAX(1, dimension). If LWORK = -1, or LHOUS=-1, then a query is assumed; the routine only calculates the optimal size of the HOUS array, returns this value as the first entry of the HOUS array, and no error message related to LHOUS is issued by XERBLA. LHOUS = MAX(1, dimension) where dimension = 4*N if VECT='N'; not available now if VECT='H'. ✨
WORK (COMPLEX array, dimension LWORK) — workspace, bestie. 💖
LWORK (INTEGER) — The dimension of the array WORK. LWORK = MAX(1, dimension). If LWORK = -1, or LHOUS=-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. LWORK = MAX(1, dimension) where dimension = (2KD+1)*N + KD*NTHREADS where KD is the blocking size of the reduction, FACTOPTNB is the blocking used by the QR or LQ algorithm, usually FACTOPTNB=128 is a good choice, NTHREADS is the number of threads used when openMP compilation is enabled, otherwise =1. 🦋
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:

Implemented by Azzam Haidar.

All details are available on technical report, SC11, SC13 papers.

Azzam Haidar, Hatem Ltaief, and Jack Dongarra. Parallel reduction to condensed forms for symmetric eigenvalue problems using aggregated fine-grained and memory-aware kernels. In Proceedings of 2011 International Conference for High Performance Computing, Networking, Storage and Analysis (SC '11), New York, NY, USA, Article 8 , 11 pages. http://doi.acm.org/10.1145/2063384.2063394

A. Haidar, J. Kurzak, P. Luszczek, 2013. An improved parallel singular value algorithm and its implementation for multicore hardware, In Proceedings of 2013 International Conference for High Performance Computing, Networking, Storage and Analysis (SC '13). Denver, Colorado, USA, 2013. Article 90, 12 pages. http://doi.acm.org/10.1145/2503210.2503292

A. Haidar, R. Solca, S. Tomov, T. Schulthess and J. Dongarra. A novel hybrid CPU-GPU generalized eigensolver for electronic structure calculations based on fine-grained memory aware tasks. International Journal of High Performance Computing Applications. Volume 28 Issue 2, Pages 196-209, May 2014. http://hpc.sagepub.com/content/28/2/196

`subroutine chfrk (character TRANSR, character UPLO, character TRANS, integer N, integer K, real ALPHA, complex, dimension( lda, * ) A, integer LDA, real BETA, complex, dimension( * ) C)`

Okay so CHFRK performs a Hermitian rank-k operation for matrix in RFP format. It's giving major BLAS energy, bestie. 💅

Purpose:

Level 3 BLAS like routine for C in RFP Format.

CHFRK performs one of the Hermitian rank--k operations

C := alpha*A*A**H + beta*C,

C := alpha*A**H*A + beta*C,

where alpha and beta are real scalars, C is an n--by--n Hermitian matrix and A is an n--by--k matrix in the first case and a k--by--n matrix in the second case. No cap. 🫶

Parameters

TRANSR — TRANSR is CHARACTER*1. = 'N': The Normal Form of RFP A is stored; = 'C': The Conjugate-transpose Form of RFP A is stored.
UPLO — UPLO is CHARACTER*1. On entry, UPLO specifies whether the upper or lower triangular part of the array C is to be referenced as follows: UPLO = 'U' or 'u': Only the upper triangular part of C is to be referenced. UPLO = 'L' or 'l': Only the lower triangular part of C is to be referenced. Unchanged on exit.
TRANS — TRANS is CHARACTER*1. On entry, TRANS specifies the operation to be performed as follows: TRANS = 'N' or 'n': C := alpha*A*A**H + beta*C. TRANS = 'C' or 'c': C := alpha*A**H*A + beta*C. Unchanged on exit.
N — N is INTEGER. On entry, N specifies the order of the matrix C. N must be at least zero. Unchanged on exit.
K — K is INTEGER. On entry with TRANS = 'N' or 'n', K specifies the number of columns of the matrix A, and on entry with TRANS = 'C' or 'c', K specifies the number of rows of the matrix A. K must be at least zero. Unchanged on exit.
ALPHA — ALPHA is REAL. On entry, ALPHA specifies the scalar alpha. Unchanged on exit.
A — A is COMPLEX array, dimension (LDA,ka) where KA is K when TRANS = 'N' or 'n', and is N otherwise. Before entry with TRANS = 'N' or 'n', the leading N--by--K part of the array A must contain the matrix A, otherwise the leading K--by--N part of the array A must contain the matrix A. Unchanged on exit.
LDA — LDA is INTEGER. On entry, LDA specifies the first dimension of A as declared in the calling (sub) program. When TRANS = 'N' or 'n' then LDA must be at least max( 1, n ), otherwise LDA must be at least max( 1, k ). Unchanged on exit.
BETA — BETA is REAL. On entry, BETA specifies the scalar beta. Unchanged on exit.
C — C is COMPLEX array, dimension (N*(N+1)/2). On entry, the matrix A in RFP Format. RFP Format is described by TRANSR, UPLO and N. Note that the imaginary parts of the diagonal elements need not be set, they are assumed to be zero, and on exit they are set to zero.

✨ Author ✨

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

`subroutine chpcon (character UPLO, integer N, complex, dimension( * ) AP, integer, dimension( * ) IPIV, real ANORM, real RCOND, complex, dimension( * ) WORK, integer INFO)`

CHPCON is here to estimate condition numbers, and honestly? Iconic. 💖

Purpose:

CHPCON estimates the reciprocal of the condition number of a complex Hermitian packed matrix A using the factorization A = U*D*U**H or A = L*D*L**H computed by CHPTRF.

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))).

Parameters

UPLO — UPLO is CHARACTER*1. Specifies whether the details of the factorization are stored as an upper or lower triangular matrix. = 'U': Upper triangular, form is A = U*D*U**H; = 'L': Lower triangular, form is A = L*D*L**H.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). The block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by CHPTRF, stored as a packed triangular matrix.
IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by CHPTRF.
ANORM — ANORM is REAL. The 1-norm of the original matrix A.
RCOND — RCOND is REAL. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(ANORM * AINVNM), where AINVNM is an estimate of the 1-norm of inv(A) computed in this routine.
WORK — WORK is COMPLEX array, dimension (2*N).
INFO — INFO is 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.

`subroutine chpgst (integer ITYPE, character UPLO, integer N, complex, dimension( * ) AP, complex, dimension( * ) BP, integer INFO)`

CHPGST reduces a complex Hermitian-definite generalized eigenproblem to standard form, using packed storage. It's giving "let's make this problem standard" realness. 🌸

Purpose:

CHPGST reduces a complex Hermitian-definite generalized eigenproblem to standard form, using packed storage.

If ITYPE = 1, the problem is A*x = lambda*B*x, and A is overwritten by inv(U**H)*A*inv(U) or inv(L)*A*inv(L**H)

If ITYPE = 2 or 3, the problem is A*B*x = lambda*x or B*A*x = lambda*x, and A is overwritten by U*A*U**H or L**H*A*L.

B must have been previously factorized as U**H*U or L*L**H by CPPTRF.

Parameters

ITYPE — ITYPE is INTEGER. = 1: compute inv(U**H)*A*inv(U) or inv(L)*A*inv(L**H); = 2 or 3: compute U*A*U**H or L**H*A*L.
UPLO — UPLO is CHARACTER*1. = 'U': Upper triangle of A is stored and B is factored as U**H*U; = 'L': Lower triangle of A is stored and B is factored as L*L**H.
N — N is INTEGER. The order of the matrices A and B. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows: if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n. On exit, if INFO = 0, the transformed matrix, stored in the same format as A.
BP — BP is COMPLEX array, dimension (N*(N+1)/2). The triangular factor from the Cholesky factorization of B, stored in the same format as A, as returned by CPPTRF.
INFO — INFO is 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.

`subroutine chprfs (character UPLO, integer N, integer NRHS, complex, dimension( * ) AP, complex, dimension( * ) AFP, integer, dimension( * ) IPIV, complex, dimension( ldb, * ) B, integer LDB, complex, dimension( ldx, * ) X, integer LDX, real, dimension( * ) FERR, real, dimension( * ) BERR, complex, dimension( * ) WORK, real, dimension( * ) RWORK, integer INFO)`

CHPRFS is the glow-up your solution needed. It improves the computed solution and gives you error bounds, because accuracy is self-care. 💅

Purpose:

CHPRFS improves the computed solution to a system of linear equations when the coefficient matrix is Hermitian indefinite and packed, and provides error bounds and backward error estimates for the solution.

Parameters

UPLO — UPLO is CHARACTER*1. = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AP —

okay bestie, back to the parameter lineup for the routine from before — she's still serving 💅

AP — AP is COMPLEX array, dimension (N*(N+1)/2). The upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.

AFP — AFP is COMPLEX array, dimension (N*(N+1)/2). The factored form of the matrix A. AFP contains the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U**H or A = L*D*L**H as computed by CHPTRF, stored as a packed triangular matrix.
IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by CHPTRF.
B — B is COMPLEX array, dimension (LDB,NRHS). The right hand side matrix B.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
X — X is COMPLEX array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by CHPTRS. On exit, the improved solution matrix X.
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is REAL array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.
BERR — BERR is REAL array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
WORK — WORK is COMPLEX array, dimension (2*N).
RWORK — RWORK is REAL array, dimension (N).
INFO — INFO is INTEGER:
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

✨ Internal Parameters ✨

ITMAX is the maximum number of steps of iterative refinement.

👑 Author 👑

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

🦋 subroutine chptrd 🦋

subroutine chptrd (character UPLO, integer N, complex, dimension( * ) AP,
    real, dimension( * ) D, real, dimension( * ) E, complex, dimension( * )
    TAU, integer INFO)

CHPTRD

🌸 Purpose 🌸

CHPTRD reduces a complex Hermitian matrix A stored in packed form to real symmetric tridiagonal form T by a unitary similarity transformation: Q**H * A * Q = T.

🌺 Parameters 🌺

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.

On exit, if UPLO = 'U', the diagonal and first superdiagonal of A are overwritten by the corresponding elements of the tridiagonal matrix T, and the elements above the first superdiagonal, with the array TAU, represent the unitary matrix Q as a product of elementary reflectors; if UPLO = 'L', the diagonal and first subdiagonal of A are over-written by the corresponding elements of the tridiagonal matrix T, and the elements below the first subdiagonal, with the array TAU, represent the unitary matrix Q as a product of elementary reflectors. See Further Details.

D — D is REAL array, dimension (N). The diagonal elements of the tridiagonal matrix T: D(i) = A(i,i).
E — E is REAL array, dimension (N-1). The off-diagonal elements of the tridiagonal matrix T: E(i) = A(i,i+1) if UPLO = 'U', E(i) = A(i+1,i) if UPLO = 'L'.
TAU — TAU is COMPLEX array, dimension (N-1). The scalar factors of the elementary reflectors (see Further Details).
INFO — INFO is 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 ✨

If UPLO = 'U', the matrix Q is represented as a product of elementary reflectors

Q = H(n-1) . . . H(2) H(1).

Each H(i) has the form

H(i) = I - tau * v * v**H

where tau is a complex scalar, and v is a complex vector with v(i+1:n) = 0 and v(i) = 1; v(1:i-1) is stored on exit in AP, overwriting A(1:i-1,i+1), and tau is stored in TAU(i).

If UPLO = 'L', the matrix Q is represented as a product of elementary reflectors

Q = H(1) H(2) . . . H(n-1).

Each H(i) has the form

H(i) = I - tau * v * v**H

where tau is a complex scalar, and v is a complex vector with v(1:i) = 0 and v(i+1) = 1; v(i+2:n) is stored on exit in AP, overwriting A(i+2:n,i), and tau is stored in TAU(i).

🔥 subroutine chptrf 🔥

subroutine chptrf (character UPLO, integer N, complex, dimension( * ) AP,
    integer, dimension( * ) IPIV, integer INFO)

CHPTRF

🌟 Purpose 🌟

CHPTRF computes the factorization of a complex Hermitian packed matrix A using the Bunch-Kaufman diagonal pivoting method:

A = U*D*U**H  or  A = L*D*L**H

where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is Hermitian and block diagonal with 1-by-1 and 2-by-2 diagonal blocks.

💫 Parameters 💫

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

On exit, the block diagonal matrix D and the multipliers used to obtain the factor U or L, stored as a packed triangular matrix overwriting A (see below for further details).

IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D. If IPIV(k) > 0, then rows and columns k and IPIV(k) were interchanged and D(k,k) is a 1-by-1 diagonal block. If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then rows and columns k-1 and -IPIV(k) were interchanged and D(k-1:k,k-1:k) is a 2-by-2 diagonal block. If UPLO = 'L' and IPIV(k) = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k) were interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, and division by zero will occur if it is used to solve a system of equations.

🌈 Author 🌈

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

🎀 Further Details 🎀

If UPLO = 'U', then A = U*D*U**H, where

U = P(n)*U(n)* ... *P(k)U(k)* ...,

i.e., U is a product of terms P(k)*U(k), where k decreases from n to 1 in steps of 1 or 2, and D is a block diagonal matrix with 1-by-1 and 2-by-2 diagonal blocks D(k). P(k) is a permutation matrix as defined by IPIV(k), and U(k) is a unit upper triangular matrix, such that if the diagonal block D(k) is of order s (s = 1 or 2), then

                        (   I    v    0   )   k-s
                U(k) =  (   0    I    0   )   s
                        (   0    0    I   )   n-k
                           k-s   s   n-k

If s = 1, D(k) overwrites A(k,k), and v overwrites A(1:k-1,k). If s = 2, the upper triangle of D(k) overwrites A(k-1,k-1), A(k-1,k), and A(k,k), and v overwrites A(1:k-2,k-1:k).

If UPLO = 'L', then A = L*D*L**H, where

L = P(1)*L(1)* ... *P(k)*L(k)* ...,

i.e., L is a product of terms P(k)*L(k), where k increases from 1 to n in steps of 1 or 2, and D is a block diagonal matrix with 1-by-1 and 2-by-2 diagonal blocks D(k). P(k) is a permutation matrix as defined by IPIV(k), and L(k) is a unit lower triangular matrix, such that if the diagonal block D(k) is of order s (s = 1 or 2), then

                        (   I    0     0   )  k-1
                L(k) =  (   0    I     0   )  s
                        (   0    v     I   )  n-k-s+1
                           k-1   s  n-k-s+1

If s = 1, D(k) overwrites A(k,k), and v overwrites A(k+1:n,k). If s = 2, the lower triangle of D(k) overwrites A(k,k), A(k+1,k), and A(k+1,k+1), and v overwrites A(k+2:n,k:k+1).

💜 Contributors 💜

J. Lewis, Boeing Computer Services Company

🦋 `chptri`

subroutine chptri (character UPLO, integer N, complex, dimension( * ) AP,
    integer, dimension( * ) IPIV, complex, dimension( * ) WORK, integer
    INFO)

💅 Purpose

Okay so CHPTRI computes the inverse of a complex Hermitian indefinite matrix A in packed storage, using the factorization A = U*D*U**H or A = L*D*L**H that got computed by CHPTRF. She's taking what CHPTRF built and flipping the whole thing inside out. Iconic behavior honestly. ✨

🌸 Parameters

UPLO — UPLO is CHARACTER*1. Tells us whether the factorization details are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**H;
- = 'L': Lower triangular, form is A = L*D*L**H.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). On entry: the block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by CHPTRF, stored as a packed triangular matrix. On exit, if INFO = 0, the (Hermitian) inverse of the original matrix, stored as a packed triangular matrix. The j-th column of inv(A) is stored in the array AP like this:
- if UPLO = 'U', AP(i + (j-1)*j/2) = inv(A)(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = inv(A)(i,j) for j<=i<=n.
IPIV — IPIV is INTEGER array, dimension (N). The details of the interchanges and the block structure of D as determined by CHPTRF.
WORK — WORK is COMPLEX array, dimension (N).
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, D(i,i) = 0; the matrix is singular and its inverse could not be computed. Bestie she literally cannot do it, the math said no. 💀

👑 Author

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

🌈 `chptrs`

subroutine chptrs (character UPLO, integer N, integer NRHS, complex,
    dimension( * ) AP, integer, dimension( * ) IPIV, complex, dimension(
    ldb, * ) B, integer LDB, integer INFO)

✨ Purpose

CHPTRS solves a system of linear equations A*X = B with a complex Hermitian matrix A stored in packed format, using the factorization A = U*D*U**H or A = L*D*L**H computed by CHPTRF. She's the solver of the family, fr fr. 🫶

🎀 Parameters

UPLO — UPLO is CHARACTER*1. Specifies whether the details of the factorization are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**H;
- = 'L': Lower triangular, form is A = L*D*L**H.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). The block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by CHPTRF, stored as a packed triangular matrix.
IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by CHPTRF.
B — B is COMPLEX array, dimension (LDB,NRHS). On entry: the right hand side matrix B. On exit: the solution matrix X. She came in as the problem and left as the answer, main character energy.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
INFO — INFO is 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.

🦋 `chsein`

subroutine chsein (character SIDE, character EIGSRC, character INITV,
    logical, dimension( * ) SELECT, integer N, complex, dimension( ldh, * )
    H, integer LDH, complex, dimension( * ) W, complex, dimension( ldvl, * )
    VL, integer LDVL, complex, dimension( ldvr, * ) VR, integer LDVR,
    integer MM, integer M, complex, dimension( * ) WORK, real, dimension( *
    ) RWORK, integer, dimension( * ) IFAILL, integer, dimension( * ) IFAILR,
    integer INFO)

💜 Purpose

CHSEIN uses inverse iteration to find specified right and/or left eigenvectors of a complex upper Hessenberg matrix H. Obsessed with her technique ngl. 🌸

The right eigenvector x and the left eigenvector y of the matrix H corresponding to an eigenvalue w are defined by:

             H * x = w * x,     y**h * H = w * y**h

where y**h denotes the conjugate transpose of the vector y.

🍓 Parameters

SIDE — SIDE is CHARACTER*1.
- = 'R': compute right eigenvectors only;
- = 'L': compute left eigenvectors only;
- = 'B': compute both right and left eigenvectors.
EIGSRC — EIGSRC is CHARACTER*1. Specifies the source of eigenvalues supplied in W:
- = 'Q': the eigenvalues were found using CHSEQR; thus, if H has zero subdiagonal elements, and so is block-triangular, then the j-th eigenvalue can be assumed to be an eigenvalue of the block containing the j-th row/column. This property allows CHSEIN to perform inverse iteration on just one diagonal block. Shortcut era, we love efficiency.
- = 'N': no assumptions are made on the correspondence between eigenvalues and diagonal blocks. In this case, CHSEIN must always perform inverse iteration using the whole matrix H. No shortcuts, she does the full thing every time.
INITV — INITV is CHARACTER*1.
- = 'N': no initial vectors are supplied;
- = 'U': user-supplied initial vectors are stored in the arrays VL and/or VR.
SELECT — SELECT is LOGICAL array, dimension (N). Specifies the eigenvectors to be computed. To select the eigenvector corresponding to the eigenvalue W(j), SELECT(j) must be set to .TRUE..
N — N is INTEGER. The order of the matrix H. N >= 0.
H — H is COMPLEX array, dimension (LDH,N). The upper Hessenberg matrix H.

If a NaN is detected in H, the routine will return with INFO=-6. 🚨

LDH — LDH is INTEGER. The leading dimension of the array H. LDH >= max(1,N).
W — W is COMPLEX array, dimension (N). On entry: the eigenvalues of H. On exit: the real parts of W may have been altered since close eigenvalues are perturbed slightly in searching for independent eigenvectors. Yeah she tweaks them a lil, no biggie, it's for the greater good.
VL — VL is COMPLEX array, dimension (LDVL,MM). On entry, if INITV = 'U' and SIDE = 'L' or 'B', VL must contain starting vectors for the inverse iteration for the left eigenvectors; the starting vector for each eigenvector must be in the same column in which the eigenvector will be stored. On exit, if SIDE = 'L' or 'B', the left eigenvectors specified by SELECT will be stored consecutively in the columns of VL, in the same order as their eigenvalues. If SIDE = 'R', VL is not referenced.
LDVL — LDVL is INTEGER. The leading dimension of the array VL. LDVL >= max(1,N) if SIDE = 'L' or 'B'; LDVL >= 1 otherwise.
VR — VR is COMPLEX array, dimension (LDVR,MM). On entry, if INITV = 'U' and SIDE = 'R' or 'B', VR must contain starting vectors for the inverse iteration for the right eigenvectors; the starting vector for each eigenvector must be in the same column in which the eigenvector will be stored. On exit, if SIDE = 'R' or 'B', the right eigenvectors specified by SELECT will be stored consecutively in the columns of VR, in the same order as their eigenvalues. If SIDE = 'L', VR is not referenced.
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= max(1,N) if SIDE = 'R' or 'B'; LDVR >= 1 otherwise.
MM — MM is INTEGER. The number of columns in the arrays VL and/or VR. MM >= M.
M — M is INTEGER. The number of columns in the arrays VL and/or VR required to store the eigenvectors (= the number of .TRUE. elements in SELECT).
WORK — WORK is COMPLEX array, dimension (N*N).
RWORK — RWORK is REAL array, dimension (N).
IFAILL — IFAILL is INTEGER array, dimension (MM). If SIDE = 'L' or 'B', IFAILL(i) = j > 0 if the left eigenvector in the i-th column of VL (corresponding to the eigenvalue w(j)) failed to converge; IFAILL(i) = 0 if the eigenvector converged satisfactorily. If SIDE = 'R', IFAILL is not referenced.
IFAILR — IFAILR is INTEGER array, dimension (MM). If SIDE = 'R' or 'B', IFAILR(i) = j > 0 if the right eigenvector in the i-th column of VR (corresponding to the eigenvalue w(j)) failed to converge; IFAILR(i) = 0 if the eigenvector converged satisfactorily. If SIDE = 'L', IFAILR is not referenced.
INFO — INFO is INTEGER.
- = 0: successful exit 💖
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, i is the number of eigenvectors which failed to converge; see IFAILL and IFAILR for further details. If this is nonzero, some of them did NOT converge bestie, check the failure arrays.

👑 Author

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

🌟 Further Details:

Each eigenvector is normalized so that the element of largest magnitude has magnitude 1; here the magnitude of a complex number (x,y) is taken to be |x|+|y|. Yes it's |x|+|y| and not the sqrt-of-squares thing, that's just how she rolls, iykyk. 💅

💅 `chseqr` — eigenvalues AND the Schur form, bestie

subroutine chseqr (character JOB, character COMPZ, integer N, integer ILO,
    integer IHI, complex, dimension( ldh, * ) H, integer LDH, complex,
    dimension( * ) W, complex, dimension( ldz, * ) Z, integer LDZ, complex,
    dimension( * ) WORK, integer LWORK, integer INFO)

CHSEQR

✨ Purpose ✨

So CHSEQR computes the eigenvalues of a Hessenberg matrix H, and if you want, it also hands you the matrices T and Z from the Schur decomposition

H = Z T Z**H

where T is an upper triangular matrix (that's the Schur form, icon behavior) and Z is the unitary matrix of Schur vectors. 🎀

And plot twist — Z can optionally be postmultiplied into an input unitary matrix Q, so this routine can give you the Schur factorization of a matrix A that's already been reduced to Hessenberg form H by the unitary matrix Q:

A = Q*H*Q**H = (QZ)*T*(QZ)**H

🌸 Parameters 🌸

JOB — JOB is CHARACTER*1.
- = 'E': compute eigenvalues only;
- = 'S': compute eigenvalues and the Schur form T.
COMPZ — COMPZ is CHARACTER*1.
- = 'N': no Schur vectors are computed;
- = 'I': Z is initialized to the unit matrix and the matrix Z of Schur vectors of H is returned;
- = 'V': Z must contain a unitary matrix Q on entry, and the product Q*Z is returned.
N — N is INTEGER. The order of the matrix H. N >= 0.
ILO — ILO is INTEGER.
IHI — IHI is INTEGER.

Okay so here's the vibe: it's assumed that H is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally set by a previous call to CGEBAL, and then passed to ZGEHRD when the matrix output by CGEBAL is reduced to Hessenberg form. Otherwise, bestie, you set ILO and IHI to 1 and N respectively. If N > 0, then 1 <= ILO <= IHI <= N. If N = 0, then ILO = 1 and IHI = 0. No cap. 💅

H — H is COMPLEX array, dimension (LDH,N).
- On entry, the upper Hessenberg matrix H.
- On exit, if INFO = 0 and JOB = 'S', H contains the upper triangular matrix T from the Schur decomposition (the Schur form). If INFO = 0 and JOB = 'E', the contents of H are unspecified on exit. (The output value of H when INFO > 0 is given under the description of INFO below.)
- Unlike earlier versions of CHSEQR, this subroutine may explicitly set H(i,j) = 0 for i > j and j = 1, 2, ... ILO-1 or j = IHI+1, IHI+2, ... N.
LDH — LDH is INTEGER. The leading dimension of the array H. LDH >= max(1,N).
W — W is COMPLEX array, dimension (N). The computed eigenvalues. If JOB = 'S', the eigenvalues are stored in the same order as on the diagonal of the Schur form returned in H, with W(i) = H(i,i).
Z — Z is COMPLEX array, dimension (LDZ,N).
- If COMPZ = 'N', Z is not referenced.
- If COMPZ = 'I', on entry Z need not be set and on exit, if INFO = 0, Z contains the unitary matrix Z of the Schur vectors of H.
- If COMPZ = 'V', on entry Z must contain an N-by-N matrix Q, which is assumed to be equal to the unit matrix except for the submatrix Z(ILO:IHI,ILO:IHI). On exit, if INFO = 0, Z contains Q*Z.
- Normally Q is the unitary matrix generated by CUNGHR after the call to CGEHRD which formed the Hessenberg matrix H. (The output value of Z when INFO > 0 is given under the description of INFO below.)
LDZ — LDZ is INTEGER. The leading dimension of the array Z. If COMPZ = 'I' or COMPZ = 'V', then LDZ >= MAX(1,N). Otherwise, LDZ >= 1.
WORK — WORK is COMPLEX array, dimension (LWORK). On exit, if INFO = 0, WORK(1) returns an estimate of the optimal value for LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= max(1,N) is sufficient and delivers very good and sometimes optimal performance. However, LWORK as large as 11*N may be required for optimal performance. A workspace query is recommended to determine the optimal workspace size.
- If LWORK = -1, then CHSEQR does a workspace query. In this case, CHSEQR checks the input parameters and estimates the optimal workspace size for the given values of N, ILO and IHI. The estimate is returned in WORK(1). No error message related to LWORK is issued by XERBLA. Neither H nor Z are accessed.
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, CHSEQR failed to compute all of the eigenvalues. Elements 1:ilo-1 and i+1:n of W contain those eigenvalues which have been successfully computed. (Failures are rare.)

If INFO > 0 and JOB = 'E', then on exit, the remaining unconverged eigenvalues are the eigenvalues of the upper Hessenberg matrix rows and columns ILO through INFO of the final, output value of H.

If INFO > 0 and JOB = 'S', then on exit

(*)  (initial value of H)*U  = U*(final value of H)

where U is a unitary matrix. The final value of H is upper Hessenberg and triangular in rows and columns INFO+1 through IHI.

If INFO > 0 and COMPZ = 'V', then on exit

(final value of Z)  =  (initial value of Z)*U

where U is the unitary matrix in (*) (regardless of the value of JOB.)

If INFO > 0 and COMPZ = 'I', then on exit

(final value of Z)  = U

where U is the unitary matrix in (*) (regardless of the value of JOB.)

If INFO > 0 and COMPZ = 'N', then Z is not accessed.

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🫶 Contributors

Karen Braman and Ralph Byers, Department of Mathematics, University of Kansas, USA

💖 Further Details

Default values supplied by

ILAENV(ISPEC,'CHSEQR',JOB(:1)//COMPZ(:1),N,ILO,IHI,LWORK).

It is suggested that these defaults be adjusted in order to attain best performance in each particular computational environment.

ISPEC=12: The CLAHQR vs CLAQR0 crossover point. Default: 75. (Must be at least 11.)
ISPEC=13: Recommended deflation window size. This depends on ILO, IHI and NS. NS is the number of simultaneous shifts returned by ILAENV(ISPEC=15). (See ISPEC=15 below.) The default for (IHI-ILO+1) <= 500 is NS. The default for (IHI-ILO+1) > 500 is 3*NS/2.
ISPEC=14: Nibble crossover point. (See IPARMQ for details.) Default: 14% of deflation window size.
ISPEC=15: Number of simultaneous shifts in a multishift QR iteration.

If IHI-ILO+1 is...

greater than or equal to 1, but less than 30 → the default is NS = 2(+)
greater than or equal to 30, but less than 60 → the default is NS = 4(+)
greater than or equal to 60, but less than 150 → the default is NS = 10(+)
greater than or equal to 150, but less than 590 → the default is NS = **
greater than or equal to 590, but less than 3000 → the default is NS = 64
greater than or equal to 3000, but less than 6000 → the default is NS = 128
greater than or equal to 6000, up to infinity → the default is NS = 256

(+) By default some or all matrices of this order are passed to the implicit double shift routine CLAHQR and this parameter is ignored. See ISPEC=12 above and comments in IPARMQ for details.

(**) The asterisks (**) indicate an ad-hoc function of N increasing from 10 to 64.

ISPEC=16: Select structured matrix multiply. If the number of simultaneous shifts (specified by ISPEC=15) is less than 14, then the default for ISPEC=16 is 0. Otherwise the default for ISPEC=16 is 2.

🌈 References

K. Braman, R. Byers and R. Mathias, The Multi-Shift QR Algorithm Part I: Maintaining Well Focused Shifts, and Level 3 Performance, SIAM Journal of Matrix Analysis, volume 23, pages 929--947, 2002.

K. Braman, R. Byers and R. Mathias, The Multi-Shift QR Algorithm Part II: Aggressive Early Deflation, SIAM Journal of Matrix Analysis, volume 23, pages 948--973, 2002.

🦋 `cla_lin_berr` — the component-wise relative backward error girlie

subroutine cla_lin_berr (integer N, integer NZ, integer NRHS, complex,
    dimension( n, nrhs ) RES, real, dimension( n, nrhs ) AYB, real,
    dimension( nrhs ) BERR)

CLA_LIN_BERR computes a component-wise relative backward error.

✨ Purpose ✨

CLA_LIN_BERR computes componentwise relative backward error from the formula

max(i) ( abs(R(i)) / ( abs(op(A_s))*abs(Y) + abs(B_s) )(i) )

where abs(Z) is the componentwise absolute value of the matrix or vector Z.

🌸 Parameters 🌸

N — N is INTEGER. The number of linear equations, i.e., the order of the matrix A. N >= 0.
NZ — NZ
NZ — NZ is INTEGER. We add (NZ+1)*SLAMCH( 'Safe minimum' ) to R(i) in the numerator to guard against spuriously zero residuals. Default value is N.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e. the number of columns of the matrices AYB, RES, and BERR. NRHS >= 0.
RES — RES is COMPLEX array, dimension (N,NRHS). The residual matrix, i.e. the matrix R in the relative backward error formula above.
AYB — AYB is REAL array, dimension (N, NRHS). The denominator in the relative backward error formula above, i.e. the matrix abs(op(A_s))*abs(Y) + abs(B_s). The matrices A, Y, and B are from iterative refinement (see cla_gerfsx_extended.f).
BERR — BERR is REAL array, dimension (NRHS). The componentwise relative backward error from the formula above.

Author

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

`subroutine cla_wwaddw`

   subroutine cla_wwaddw (integer N, complex, dimension( * ) X, complex,
       dimension( * ) Y, complex, dimension( * ) W)

CLA_WWADDW adds a vector into a doubled-single vector. Periodt. 💅

Purpose

CLA_WWADDW adds a vector W into a doubled-single vector (X, Y).

This works for all extant IBM's hex and binary floating point arithmetic, but not for decimal.

Parameters

N — N is INTEGER. The length of vectors X, Y, and W.
X — X is COMPLEX array, dimension (N). The first part of the doubled-single accumulation vector.
Y — Y is COMPLEX array, dimension (N). The second part of the doubled-single accumulation vector.
W — W is COMPLEX array, dimension (N). The vector to be added.

Author

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

`subroutine claed0`

   subroutine claed0 (integer QSIZ, integer N, real, dimension( * ) D, real,
       dimension( * ) E, complex, dimension( ldq, * ) Q, integer LDQ, complex,
       dimension( ldqs, * ) QSTORE, integer LDQS, real, dimension( * ) RWORK,
       integer, dimension( * ) IWORK, integer INFO)

CLAED0 used by CSTEDC. Computes all eigenvalues and corresponding eigenvectors of an unreduced symmetric tridiagonal matrix using the divide and conquer method. Iconic behavior. ✨

Purpose

Using the divide and conquer method, CLAED0 computes all eigenvalues of a symmetric tridiagonal matrix which is one diagonal block of those from reducing a dense or band Hermitian matrix and corresponding eigenvectors of the dense or band matrix.

Parameters

QSIZ — QSIZ is INTEGER. The dimension of the unitary matrix used to reduce the full matrix to tridiagonal form. QSIZ >= N if ICOMPQ = 1.
N — N is INTEGER. The dimension of the symmetric tridiagonal matrix. N >= 0.
D — D is REAL array, dimension (N). On entry, the diagonal elements of the tridiagonal matrix. On exit, the eigenvalues in ascending order.
E — E is REAL array, dimension (N-1). On entry, the off-diagonal elements of the tridiagonal matrix. On exit, E has been destroyed.
Q — Q is COMPLEX array, dimension (LDQ,N). On entry, Q must contain an QSIZ x N matrix whose columns unitarily orthonormal. It is a part of the unitary matrix that reduces the full dense Hermitian matrix to a (reducible) symmetric tridiagonal matrix.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,N).
IWORK — IWORK is INTEGER array, the dimension of IWORK must be at least 6 + 6*N + 5*N*lg N (lg( N ) = smallest integer k such that 2^k >= N).
RWORK — RWORK is REAL array, dimension (1 + 3*N + 2*N*lg N + 3*N**2) (lg( N ) = smallest integer k such that 2^k >= N).
QSTORE — QSTORE is COMPLEX array, dimension (LDQS, N). Used to store parts of the eigenvector matrix when the updating matrix multiplies take place.
LDQS — LDQS is INTEGER. The leading dimension of the array QSTORE. LDQS >= max(1,N).
INFO — INFO is INTEGER. = 0: successful exit. < 0: if INFO = -i, the i-th argument had an illegal value. > 0: The algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and columns INFO/(N+1) through mod(INFO,N+1).

Author

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

`subroutine claed7`

   subroutine claed7 (integer N, integer CUTPNT, integer QSIZ, integer TLVLS,
       integer CURLVL, integer CURPBM, real, dimension( * ) D, complex,
       dimension( ldq, * ) Q, integer LDQ, real RHO, integer, dimension( * )
       INDXQ, real, dimension( * ) QSTORE, integer, dimension( * ) QPTR,
       integer, dimension( * ) PRMPTR, integer, dimension( * ) PERM, integer,
       dimension( * ) GIVPTR, integer, dimension( 2, * ) GIVCOL, real,
       dimension( 2, * ) GIVNUM, complex, dimension( * ) WORK, real, dimension(
       * ) RWORK, integer, dimension( * ) IWORK, integer INFO)

CLAED7 used by CSTEDC. Computes the updated eigensystem of a diagonal matrix after modification by a rank-one symmetric matrix. Used when the original matrix is dense. Main character energy only. 👑

Purpose

CLAED7 computes the updated eigensystem of a diagonal matrix after modification by a rank-one symmetric matrix. This routine is used only for the eigenproblem which requires all eigenvalues and optionally eigenvectors of a dense or banded Hermitian matrix that has been reduced to tridiagonal form.

T = Q(in) ( D(in) + RHO * Z*Z**H ) Q**H(in) = Q(out) * D(out) * Q**H(out)

where Z = Q**Hu, u is a vector of length N with ones in the
CUTPNT and CUTPNT + 1 th elements and zeros elsewhere.

The eigenvectors of the original matrix are stored in Q, and the eigenvalues are in D. The algorithm consists of three stages:

The first stage consists of deflating the size of the problem when there are multiple eigenvalues or if there is a zero in the Z vector. For each such occurrence the dimension of the secular equation problem is reduced by one. This stage is performed by the routine SLAED2.
The second stage consists of calculating the updated eigenvalues. This is done by finding the roots of the secular equation via the routine SLAED4 (as called by SLAED3). This routine also calculates the eigenvectors of the current problem.
The final stage consists of computing the updated eigenvectors directly using the updated eigenvalues. The eigenvectors for the current problem are multiplied with the eigenvectors from the overall problem.

Parameters

N — N is INTEGER. The dimension of the symmetric tridiagonal matrix. N >= 0.
CUTPNT — CUTPNT is INTEGER. Contains the location of the last eigenvalue in the leading sub-matrix. min(1,N) <= CUTPNT <= N.
QSIZ — QSIZ is INTEGER. The dimension of the unitary matrix used to reduce the full matrix to tridiagonal form. QSIZ >= N.
TLVLS — TLVLS is INTEGER. The total number of merging levels in the overall divide and conquer tree.
CURLVL — CURLVL is INTEGER. The current level in the overall merge routine, 0 <= curlvl <= tlvls.
CURPBM — CURPBM is INTEGER. The current problem in the current level in the overall merge routine (counting from upper left to lower right).
D — D is REAL array, dimension (N). On entry, the eigenvalues of the rank-1-perturbed matrix. On exit, the eigenvalues of the repaired matrix.
Q — Q is COMPLEX array, dimension (LDQ,N). On entry, the eigenvectors of the rank-1-perturbed matrix. On exit, the eigenvectors of the repaired tridiagonal matrix.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,N).
RHO — RHO is REAL. Contains the subdiagonal element used to create the rank-1 modification.
INDXQ — INDXQ is INTEGER array, dimension (N). This contains the permutation which will reintegrate the subproblem just solved back into sorted order, ie. D( INDXQ( I = 1, N ) ) will be in ascending order.
IWORK — IWORK is INTEGER array, dimension (4*N).
RWORK — RWORK is REAL array, dimension (3*N+2*QSIZ*N).
WORK — WORK is COMPLEX array, dimension (QSIZ*N).
QSTORE — QSTORE is REAL array, dimension (N**2+1). Stores eigenvectors of submatrices encountered during divide and conquer, packed together. QPTR points to beginning of the submatrices.
QPTR — QPTR is INTEGER array, dimension (N+2). List of indices pointing to beginning of submatrices stored in QSTORE. The submatrices are numbered starting at the bottom left of the divide and conquer tree, from left to right and bottom to top.
PRMPTR — PRMPTR is INTEGER array, dimension (N lg N). Contains a list of pointers which indicate where in PERM a level's permutation is stored. PRMPTR(i+1) - PRMPTR(i) indicates the size of the permutation and also the size of the full, non-deflated problem.
PERM —
PERM — PERM is an INTEGER array, dimension (N lg N). It's holding the permutations (from deflation and sorting) that get applied to each eigenblock. 💫
GIVPTR — GIVPTR is an INTEGER array, dimension (N lg N). It's a list of pointers that show where in GIVCOL a level's Givens rotations are stored. GIVPTR(i+1) - GIVPTR(i) tells you the number of Givens rotations. 🔄
GIVCOL — GIVCOL is an INTEGER array, dimension (2, N lg N). Each pair of numbers means a pair of columns to take place in a Givens rotation. 🎯
GIVNUM — GIVNUM is a REAL array, dimension (2, N lg N). Each number is the S value to be used in the corresponding Givens rotation. 🔢
INFO — INFO is an INTEGER. = 0: successful exit. < 0: if INFO = -i, the i-th argument had an illegal value. > 0: if INFO = 1, an eigenvalue did not converge. 😭

Author

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

`claed8`

   subroutine claed8 (integer K, integer N, integer QSIZ, complex, dimension(
       ldq, * ) Q, integer LDQ, real, dimension( * ) D, real RHO, integer
       CUTPNT, real, dimension( * ) Z, real, dimension( * ) DLAMDA, complex,
       dimension( ldq2, * ) Q2, integer LDQ2, real, dimension( * ) W, integer,
       dimension( * ) INDXP, integer, dimension( * ) INDX, integer, dimension(
       * ) INDXQ, integer, dimension( * ) PERM, integer GIVPTR, integer,
       dimension( 2, * ) GIVCOL, real, dimension( 2, * ) GIVNUM, integer INFO)

CLAED8 used by CSTEDC. Merges eigenvalues and deflates secular equation. Used when the original matrix is dense.

Purpose

CLAED8 merges the two sets of eigenvalues together into a single sorted set. Then it tries to deflate the size of the problem. There are two ways deflation can occur: when two or more eigenvalues are close together, or if there is a tiny element in the Z vector. For each such occurrence, the order of the related secular equation problem is reduced by one. ✨

Parameters

K — K is INTEGER. It contains the number of non-deflated eigenvalues. This is the order of the related secular equation. 👑
N — N is INTEGER. The dimension of the symmetric tridiagonal matrix. N >= 0. 📐
QSIZ — QSIZ is INTEGER. The dimension of the unitary matrix used to reduce the dense or band matrix to tridiagonal form. QSIZ >= N if ICOMPQ = 1. 🔍
Q — Q is COMPLEX array, dimension (LDQ,N). On entry, Q contains the eigenvectors of the partially solved system which has been previously updated in matrix multiplies with other partially solved eigensystems. On exit, Q contains the trailing (N-K) updated eigenvectors (those which were deflated) in its last N-K columns. 🌀
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max( 1, N ). 📏
D — D is REAL array, dimension (N). On entry, D contains the eigenvalues of the two submatrices to be combined. On exit, D contains the trailing (N-K) updated eigenvalues (those which were deflated) sorted into increasing order. 🔢
RHO — RHO is REAL. It contains the off diagonal element associated with the rank-1 cut which originally split the two submatrices which are now being recombined. RHO is modified during the computation to the value required by SLAED3. 🎚️
CUTPNT — CUTPNT is INTEGER. It contains the location of the last eigenvalue in the leading sub-matrix. MIN(1,N) <= CUTPNT <= N. ✂️
Z — Z is REAL array, dimension (N). On input this vector contains the updating vector (the last row of the first sub-eigenvector matrix and the first row of the second sub-eigenvector matrix). The contents of Z are destroyed during the updating process. 💀
DLAMDA — DLAMDA is REAL array, dimension (N). It contains a copy of the first K eigenvalues which will be used by SLAED3 to form the secular equation. 📋
Q2 — Q2 is COMPLEX array, dimension (LDQ2,N). If ICOMPQ = 0, Q2 is not referenced. Otherwise, it contains a copy of the first K eigenvectors which will be used by SLAED7 in a matrix multiply (SGEMM) to update the new eigenvectors. 🔁
LDQ2 — LDQ2 is INTEGER. The leading dimension of the array Q2. LDQ2 >= max( 1, N ). 📐
W — W is REAL array, dimension (N). This will hold the first k values of the final deflation-altered z-vector and will be passed to SLAED3. 📦
INDXP — INDXP is INTEGER array, dimension (N). This will contain the permutation used to place deflated values of D at the end of the array. On output INDXP(1:K) points to the nondeflated D-values and INDXP(K+1:N) points to the deflated eigenvalues. 🗂️
INDX — INDX is INTEGER array, dimension (N). This will contain the permutation used to sort the contents of D into ascending order. 🔤
INDXQ — INDXQ is INTEGER array, dimension (N). This contains the permutation which separately sorts the two sub-problems in D into ascending order. Note that elements in the second half of this permutation must first have CUTPNT added to their values in order to be accurate. ➕
PERM — PERM is INTEGER array, dimension (N). It contains the permutations (from deflation and sorting) to be applied to each eigenblock. 🧩
GIVPTR — GIVPTR is INTEGER. It contains the number of Givens rotations which took place in this subproblem. 🔄
GIVCOL — GIVCOL is INTEGER array, dimension (2, N). Each pair of numbers indicates a pair of columns to take place in a Givens rotation. 🎯
GIVNUM — GIVNUM is REAL array, dimension (2, N). Each number indicates the S value to be used in the corresponding Givens rotation. 🔢
INFO — INFO is 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.

`clals0`

   subroutine clals0 (integer ICOMPQ, integer NL, integer NR, integer SQRE,
       integer NRHS, complex, dimension( ldb, * ) B, integer LDB, complex,
       dimension( ldbx, * ) BX, integer LDBX, integer, dimension( * ) PERM,
       integer GIVPTR, integer, dimension( ldgcol, * ) GIVCOL, integer LDGCOL,
       real, dimension( ldgnum, * ) GIVNUM, integer LDGNUM, real, dimension(
       ldgnum, * ) POLES, real, dimension( * ) DIFL, real, dimension( ldgnum, *
       ) DIFR, real, dimension( * ) Z, integer K, real C, real S, real,
       dimension( * ) RWORK, integer INFO)

CLALS0 applies back multiplying factors in solving the least squares problem using divide and conquer SVD approach. Used by sgelsd.

Purpose

CLALS0 applies back the multiplying factors of either the left or the right singular vector matrix of a diagonal matrix appended by a row to the right hand side matrix B in solving the least squares problem using the divide-and-conquer SVD approach.

For the left singular vector matrix, three types of orthogonal matrices are involved:

(1L) Givens rotations: the number of such rotations is GIVPTR; the pairs of columns/rows they were applied to are stored in GIVCOL; and the C- and S-values of these rotations are stored in GIVNUM. 🔄
(2L) Permutation. The (NL+1)-st row of B is to be moved to the first row, and for J=2:N, PERM(J)-th row of B is to be moved to the J-th row. 🔀
(3L) The left singular vector matrix of the remaining matrix. 🧮

For the right singular vector matrix, four types of orthogonal matrices are involved:

(1R) The right singular vector matrix of the remaining matrix. 🧮
(2R) If SQRE = 1, one extra Givens rotation to generate the right null space. 🌀
(3R) The inverse transformation of (2L). ↩️
(4R) The inverse transformation of (1L). ↩️

Parameters

ICOMPQ — ICOMPQ is INTEGER. Specifies whether singular vectors are to be computed in factored form: = 0: Left singular vector matrix. = 1: Right singular vector matrix. 🎛️
NL — NL is INTEGER. The row dimension of the upper block. NL >= 1. ⬆️
NR — NR is INTEGER. The row dimension of the lower block. NR >= 1. ⬇️
SQRE — SQRE is INTEGER. = 0: the lower block is an NR-by-NR square matrix. = 1: the lower block is an NR-by-(NR+1) rectangular matrix. The bidiagonal matrix has row dimension N = NL + NR + 1, and column dimension M = N + SQRE. 📐
NRHS — NRHS is INTEGER. The number of columns of B and BX. NRHS must be at least 1. 🔢
B — B is COMPLEX array, dimension ( LDB, NRHS ). On input, B contains the right hand sides of the least squares problem in rows 1 through M. On output, B contains the solution X in rows 1 through N. 🧾
LDB — LDB is INTEGER. The leading dimension of B. LDB must be at least max(1,MAX( M, N )). 📏
BX — BX is COMPLEX array, dimension ( LDBX, NRHS ). 📦
LDBX — LDBX is INTEGER. The leading dimension of BX. 📐
PERM — PERM is INTEGER array, dimension ( N ). The permutations (from deflation and sorting) applied to the two blocks. 🧩
GIVPTR — GIVPTR is INTEGER. The number of Givens rotations which took place in this subproblem. 🔄
GIVCOL —
GIVCOL — an INTEGER array, dimension ( LDGCOL, 2 ). Every pair of numbers in there is a little tag team: it says which pair of rows/columns got swept up in a Givens rotation. 🌀
LDGCOL — LDGCOL is INTEGER. It's the leading dimension of GIVCOL, and bestie, it must be at least N. No negotiating. 💅
GIVNUM — a REAL array, dimension ( LDGNUM, 2 ). Each number is the C or S value used in the matching Givens rotation. ✨
LDGNUM — LDGNUM is INTEGER. The leading dimension of the arrays DIFR, POLES and GIVNUM, and it must be at least K.
POLES — a REAL array, dimension ( LDGNUM, 2 ). On entry, POLES(1:K, 1) holds the new singular values you got from solving the secular equation, and POLES(1:K, 2) is the array holding the poles in the secular equation. 👑
DIFL — a REAL array, dimension ( K ). On entry, DIFL(I) is the distance between the I-th updated (undeflated) singular value and the I-th (undeflated) old singular value.
DIFR — a REAL array, dimension ( LDGNUM, 2 ). On entry, DIFR(I, 1) holds the distances between the I-th updated (undeflated) singular value and the I+1-th (undeflated) old singular value. And DIFR(I, 2) is the normalizing factor for the I-th right singular vector. 🎀
Z — a REAL array, dimension ( K ). Holds the components of the deflation-adjusted updating row vector.
K — K is INTEGER. It holds the dimension of the non-deflated matrix, which is the order of the related secular equation. 1 <= K <=N. 💫
C — C is REAL. It holds garbage if SQRE =0, and the C-value of a Givens rotation related to the right null space if SQRE = 1.
S — S is REAL. It holds garbage if SQRE =0, and the S-value of a Givens rotation related to the right null space if SQRE = 1.
RWORK — a REAL array, dimension ( K*(1+NRHS) + 2*NRHS )
INFO — INFO is 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.

Contributors 🌈

Ming Gu and Ren-Cang Li, Computer Science Division, University of California at Berkeley, USA

Osni Marques, LBNL/NERSC, USA

subroutine `clalsa` 🦋

subroutine clalsa (integer ICOMPQ, integer SMLSIZ, integer N, integer NRHS,
    complex, dimension( ldb, * ) B, integer LDB, complex, dimension( ldbx, *
    ) BX, integer LDBX, real, dimension( ldu, * ) U, integer LDU, real,
    dimension( ldu, * ) VT, integer, dimension( * ) K, real, dimension( ldu,
    * ) DIFL, real, dimension( ldu, * ) DIFR, real, dimension( ldu, * ) Z,
    real, dimension( ldu, * ) POLES, integer, dimension( * ) GIVPTR,
    integer, dimension( ldgcol, * ) GIVCOL, integer LDGCOL, integer,
    dimension( ldgcol, * ) PERM, real, dimension( ldu, * ) GIVNUM, real,
    dimension( * ) C, real, dimension( * ) S, real, dimension( * ) RWORK,
    integer, dimension( * ) IWORK, integer INFO)

CLALSA computes the SVD of the coefficient matrix in compact form. It's the one sgelsd leans on. 💖

Purpose ✨

CLALSA is an intermediate step in solving the least squares problem — it computes the SVD of the coefficient matrix in compact form. And when I say compact, I mean it: the singular vectors are computed as products of simple orthogonal matrices. 🎀

If ICOMPQ = 0, CLALSA applies the inverse of the left singular vector matrix of an upper bidiagonal matrix to the right hand side. And if ICOMPQ = 1, CLALSA applies the right singular vector matrix to the right hand side. Those singular vector matrices? They were generated in compact form by CLALSA itself. Iconic, self-sufficient behaviour. 👑

Parameters 💅

ICOMPQ — ICOMPQ is INTEGER. It says whether we're dealing with the left or the right singular vector matrix.
- = 0: Left singular vector matrix
- = 1: Right singular vector matrix
SMLSIZ — SMLSIZ is INTEGER. The maximum size of the subproblems sitting at the bottom of the computation tree. 🌸
N — N is INTEGER. The row and column dimensions of the upper bidiagonal matrix.
NRHS — NRHS is INTEGER. The number of columns of B and BX. NRHS must be at least 1.
B — B is COMPLEX array, dimension ( LDB, NRHS ). On input, B holds the right hand sides of the least squares problem in rows 1 through M. On output, B holds the solution X in rows 1 through N. 🫶
LDB — LDB is INTEGER. The leading dimension of B in the calling subprogram. LDB must be at least max(1,MAX( M, N ) ).
BX — BX is COMPLEX array, dimension ( LDBX, NRHS ). On exit, it's the result of applying the left or right singular vector matrix to B. ✨
LDBX — LDBX is INTEGER. The leading dimension of BX.
U — U is REAL array, dimension ( LDU, SMLSIZ ). On entry, U contains the left singular vector matrices of all subproblems at the bottom level.
LDU — LDU is INTEGER, LDU = > N. The leading dimension of arrays U, VT, DIFL, DIFR, POLES, GIVNUM, and Z.
VT — VT is REAL array, dimension ( LDU, SMLSIZ+1 ). On entry, VT**H contains the right singular vector matrices of all subproblems at the bottom level. 💜
K — K is INTEGER array, dimension ( N ).
DIFL — DIFL is REAL array, dimension ( LDU, NLVL ), where NLVL = INT(log_2 (N/(SMLSIZ+1))) + 1.
DIFR — DIFR is REAL array, dimension ( LDU, 2 * NLVL ). On entry, DIFL(*, I) and DIFR(*, 2 * I -1) record distances between singular values on the I-th level and singular values on the (I -1)-th level, and DIFR(*, 2 * I) records the normalizing factors of the right singular vectors matrices of subproblems on I-th level. 🎀
Z — Z is REAL array, dimension ( LDU, NLVL ). On entry, Z(1, I) contains the components of the deflation-adjusted updating row vector for subproblems on the I-th level.
POLES — POLES is REAL array, dimension ( LDU, 2 * NLVL ). On entry, POLES(*, 2 * I -1: 2 * I) contains the new and old singular values involved in the secular equations on the I-th level. 👑
GIVPTR — GIVPTR is INTEGER array, dimension ( N ). On entry, GIVPTR( I ) records the number of Givens rotations performed on the I-th problem on the computation tree.
GIVCOL — GIVCOL is INTEGER array, dimension ( LDGCOL, 2 * NLVL ). On entry, for each I, GIVCOL(*, 2 * I - 1: 2 * I) records the locations of Givens rotations performed on the I-th level on the computation tree. 🌀
LDGCOL — LDGCOL is INTEGER, LDGCOL = > N. The leading dimension of arrays GIVCOL and PERM.
PERM — PERM is INTEGER array, dimension ( LDGCOL, NLVL ). On entry, PERM(*, I) records permutations done on the I-th level of the computation tree.
GIVNUM — GIVNUM is REAL array, dimension ( LDU, 2 * NLVL ). On entry, GIVNUM(*, 2 *I -1 : 2 * I) records the C- and S-values of Givens rotations performed on the I-th level on the computation tree. ✨
C — C is REAL array, dimension ( N ). On entry, if the I-th subproblem is not square, C( I ) contains the C-value of a Givens rotation related to the right null space of the I-th subproblem.
S — S is REAL array, dimension ( N ). On entry, if the I-th subproblem is not square, S( I ) contains the S-value of a Givens rotation related to the right null space of the I-th subproblem.
RWORK — RWORK is REAL array, dimension at least MAX( (SMLSZ+1)*NRHS*3, N*(1+NRHS) + 2*NRHS ).
IWORK — IWORK is INTEGER array, dimension (3*N)
INFO — INFO is 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.

Contributors 🌈

Ming Gu and Ren-Cang Li, Computer Science Division, University of California at Berkeley, USA

Osni Marques, LBNL/NERSC, USA

subroutine `clalsd` 💖

subroutine clalsd (character UPLO, integer SMLSIZ, integer N, integer NRHS,
    real, dimension( * ) D, real, dimension( * ) E, complex, dimension( ldb,
    * ) B, integer LDB, real RCOND, integer RANK, complex, dimension( * )
    WORK, real, dimension( * ) RWORK, integer, dimension( * ) IWORK, integer
    INFO)

CLALSD uses the singular value decomposition of A to solve the least squares problem. Slay. 👑

Purpose ✨

CLALSD uses the SVD of A to solve the least squares problem of finding X that minimizes the Euclidean norm of each column of A*X-B, where A is N-by-N upper bidiagonal, and X and B are N-by-NRHS. The solution X overwrites B. 🫶

Any singular values of A smaller than RCOND times the largest singular value get treated as zero while solving the least squares problem — and in that case a minimum norm solution is what you get back. The actual singular values are returned in D in ascending order. 📈

Now, this code makes very mild assumptions about floating point arithmetic. It'll work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray XMP, Cray YMP, Cray C 90, or Cray 2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but bestie, we know of none. 💀

Parameters 🎀

UPLO
UPLO is CHARACTER*1 — it's giving bidiagonal energy:
- = 'U': D and E define an upper bidiagonal matrix.
- = 'L': D and E define a lower bidiagonal matrix.
SMLSIZ is INTEGER — the maximum size of the subproblems at the bottom of the computation tree. It's the smallest chunk, bestie. 🌳
N is INTEGER — the dimension of the bidiagonal matrix. N >= 0. Periodt.
NRHS is INTEGER — the number of columns of B. NRHS must be at least 1. No empty columns. 🚫
D is REAL array, dimension (N) — on entry D contains the main diagonal of the bidiagonal matrix. On exit, if INFO = 0, D contains its singular values. Glow up! ✨
E is REAL array, dimension (N-1) — contains the super-diagonal entries of the bidiagonal matrix. On exit, E has been destroyed. RIP E. 💀
B is COMPLEX array, dimension (LDB,NRHS) — on input, B contains the right hand sides of the least squares problem. On output, B contains the solution X. Main character transformation. 👑
LDB is INTEGER — the leading dimension of B in the calling subprogram. LDB must be at least max(1,N). Don't skip this. 🙅‍♀️
RCOND is REAL — the singular values of A less than or equal to RCOND times the largest singular value are treated as zero in solving the least squares problem. If RCOND is negative, machine precision is used instead. For example, if diag(S)*X=B were the least squares problem, where diag(S) is a diagonal matrix of singular values, the solution would be X(i) = B(i) / S(i) if S(i) is greater than RCOND*max(S), and X(i) = 0 if S(i) is less than or equal to RCOND*max(S).
RANK is INTEGER — the number of singular values of A greater than RCOND times the largest singular value. It's giving rank. 💅
WORK is COMPLEX array, dimension (N * NRHS).
RWORK is REAL array, dimension at least

(9*N + 2*N*SMLSIZ + 8*N*NLVL + 3*SMLSIZ*NRHS +
MAX( (SMLSIZ+1)**2, N*(1+NRHS) + 2*NRHS ),
where
NLVL = MAX( 0, INT( LOG_2( MIN( M,N )/(SMLSIZ+1) ) ) + 1 )

IWORK is INTEGER array, dimension (3*N*NLVL + 11*N).
INFO is INTEGER — the tea:
- = 0: successful exit. 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. 🚨
- > 0: The algorithm failed to compute a singular value while working on the submatrix lying in rows and columns INFO/(N+1) through MOD(INFO,N+1). 😭

✍️ Author

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

🫶 Contributors:

Ming Gu and Ren-Cang Li, Computer Science Division, University of California at Berkeley, USA Osni Marques, LBNL/NERSC, USA

🌟 real function `clanhf`

real function clanhf (character NORM, character TRANSR, character UPLO,
    integer N, complex, dimension( 0: * ) A, real, dimension( 0: * ) WORK)

CLANHF returns the value of the 1-norm, or the Frobenius norm, or the infinity norm, or the element of largest absolute value of a Hermitian matrix in RFP format.

🎯 Purpose

CLANHF returns the value of the one norm, or the Frobenius norm, or the infinity norm, or the element of largest absolute value of a complex Hermitian matrix A in RFP format.

🔙 Returns

CLANHF

    CLANHF = ( max(abs(A(i,j))), NORM = 'M' or 'm'
             (
             ( norm1(A),         NORM = '1', 'O' or 'o'
             (
             ( normI(A),         NORM = 'I' or 'i'
             (
             ( normF(A),         NORM = 'F', 'f', 'E' or 'e'

where norm1 denotes the one norm of a matrix (maximum column sum), normI denotes the infinity norm of a matrix (maximum row sum) and normF denotes the Frobenius norm of a matrix (square root of sum of squares). Note that max(abs(A(i,j))) is not a matrix norm.

🧩 Parameters

NORM is CHARACTER — Specifies the value to be returned in CLANHF as described above.
TRANSR is CHARACTER — Specifies whether the RFP format of A is normal or conjugate-transposed format.
- = 'N': RFP format is Normal
- = 'C': RFP format is Conjugate-transposed
UPLO is CHARACTER — On entry, UPLO specifies whether the RFP matrix A came from an upper or lower triangular matrix as follows:
- UPLO = 'U' or 'u': RFP A came from an upper triangular matrix
- UPLO = 'L' or 'l': RFP A came from a lower triangular matrix
N is INTEGER — The order of the matrix A. N >= 0. When N = 0, CLANHF is set to zero.
A is COMPLEX array, dimension ( N*(N+1)/2 ); — On entry, the matrix A in RFP Format. RFP Format is described by TRANSR, UPLO and N as follows: If TRANSR='N' then RFP A is (0:N,0:K-1) when N is even; K=N/2. RFP A is (0:N-1,0:K) when N is odd; K=N/2. If TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: If UPLO = 'U' the RFP A contains the ( N*(N+1)/2 ) elements of upper packed A either in normal or conjugate-transpose Format. If UPLO = 'L' the RFP A contains the ( N*(N+1) /2 ) elements of lower packed A either in normal or conjugate-transpose Format. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and is N when is odd. See the Note below for more details. Unchanged on exit.
WORK is REAL array, dimension (LWORK), — where LWORK >= N when NORM = 'I' or '1' or 'O'; otherwise, WORK is not referenced.

✍️ Author

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

🔍 Further Details:

Okay bestie, this is where the RFP format really shows off. Let's break it down.

We first consider Standard Packed Format when N is even. We give an example where N = 6.

                 AP is Upper             AP is Lower

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

Let TRANSR = 'N'. RFP holds AP as follows: For UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. The lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper. For UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. The upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower. To denote conjugate we place -- above the element. This covers the case N even and TRANSR = 'N'.

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP as follows: For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper. For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower. To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'.

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

✨ `clarscl2` ✨

subroutine clarscl2 (integer M, integer N, real, dimension( * ) D, complex,
    dimension( ldx, * ) X, integer LDX)

CLARSCL2 does a reciprocal diagonal scaling on a matrix. That's it, that's the whole vibe. 💅

Purpose:

okay so bestie, here's the entire personality of this routine:

x <-- inv(D) * x

where the REAL diagonal matrix D is stored as a vector. That's the move. 🫶

And listen — this one's eventually getting replaced by BLAS_cge_diag_scale in the new BLAS standard, so it's giving legacy icon energy. 👑

Parameters

M — M is INTEGER — the number of rows of D and X. M >= 0.
N — N is INTEGER — the number of columns of X. N >= 0.
D — D is REAL array, length M — the diagonal matrix D, stored as a vector of length M. slay.
X — X is COMPLEX array, dimension (LDX,N) — on entry, the matrix X to be scaled by D. On exit, the scaled matrix. it literally transforms in front of you, main character behavior ✨
LDX — LDX is INTEGER — the leading dimension of the matrix X. LDX >= M.

Author

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

🌸 `clarz` 🌸

subroutine clarz (character SIDE, integer M, integer N, integer L, complex,
    dimension( * ) V, integer INCV, complex TAU, complex, dimension( ldc, * )
    C, integer LDC, complex, dimension( * ) WORK)

CLARZ applies an elementary reflector (as returned by stzrzf) to a general matrix. yes bestie, we're doing reflectors today, buckle up 🎀

Purpose:

CLARZ applies a complex elementary reflector H to a complex M-by-N matrix C, from either the left or the right. And H is represented in the form

H = I - tau * v * v**H

where tau is a complex scalar and v is a complex vector.

If tau = 0, then H is taken to be the unit matrix. (the humble zero, doing nothing, iconic)

To apply H**H (the conjugate transpose of H), supply conjg(tau) instead of tau. 🔁

Also — H is a product of k elementary reflectors as returned by CTZRZF. so it's a whole ensemble cast, not a solo act 💫

Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': form H * C
- = 'R': form C * H
M — M is INTEGER — the number of rows of the matrix C.
N — N is INTEGER — the number of columns of the matrix C.
L — L is INTEGER — the number of entries of the vector V containing the meaningful part of the Householder vectors. If SIDE = 'L', M >= L >= 0; if SIDE = 'R', N >= L >= 0.
V — V is COMPLEX array, dimension (1+(L-1)*abs(INCV)) — the vector v in the representation of H as returned by CTZRZF. V is not used if TAU = 0. (ghosted, fr)
INCV — INCV is INTEGER — the increment between elements of v. INCV <> 0.
TAU — TAU is COMPLEX — the value tau in the representation of H.
C — C is COMPLEX array, dimension (LDC,N) — on entry, the M-by-N matrix C. On exit, C is overwritten by the matrix H * C if SIDE = 'L', or C * H if SIDE = 'R'. 💀 gone, replaced, no notes
LDC — LDC is INTEGER — the leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension
- (N) if SIDE = 'L'
- or (M) if SIDE = 'R'

Author

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

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details:

this section is literally empty in the original, bestie. nothing to report. the silence is the content. 🙈

🦋 `clarzb` 🦋

subroutine clarzb (character SIDE, character TRANS, character DIRECT,
    character STOREV, integer M, integer N, integer K, integer L, complex,
    dimension( ldv, * ) V, integer LDV, complex, dimension( ldt, * ) T,
    integer LDT, complex, dimension( ldc, * ) C, integer LDC, complex,
    dimension( ldwork, * ) WORK, integer LDWORK)

CLARZB applies a block reflector or its conjugate-transpose to a general matrix. big block energy. 🔥

Purpose:

CLARZB applies a complex block reflector H or its transpose H**H to a complex distributed M-by-N C from the left or the right.

Currently, only STOREV = 'R' and DIRECT = 'B' are supported. bestie if you came here for anything else, the answer is no. not yet. 💀

Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply H or H**H from the Left
- = 'R': apply H or H**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply H (No transpose)
- = 'C': apply H**H (Conjugate transpose)
DIRECT — DIRECT is CHARACTER*1 — indicates how H is formed from a product of elementary reflectors
- = 'F': H = H(1) H(2) . . . H(k) (Forward, not supported yet)
- = 'B': H = H(k) . . . H(2) H(1) (Backward)
STOREV — STOREV is CHARACTER*1 — indicates how the vectors which define the elementary reflectors are stored:
- = 'C': Columnwise (not supported yet)
- = 'R': Rowwise
M — M is INTEGER — the number of rows of the matrix C.
N — N is INTEGER — the number of columns of the matrix C.
K — K is INTEGER — the order of the matrix T (= the number of elementary reflectors whose product defines the block reflector).
L — L is INTEGER — the number of columns of the matrix V containing the meaningful part of the Householder reflectors. If SIDE = 'L', M >= L >= 0; if SIDE = 'R', N >= L >= 0.
V — V is COMPLEX array, dimension (LDV,NV). If STOREV = 'C', NV = K; if STOREV = 'R', NV = L.
LDV — LDV is INTEGER — the leading dimension of the array V. If STOREV = 'C', LDV >= L; if STOREV = 'R', LDV >= K.
T — T is COMPLEX array, dimension (LDT,K) — the triangular K-by-K matrix T in the representation of the block reflector.
LDT — LDT is INTEGER — the leading dimension of the array T. LDT >= K.
C — C is COMPLEX array, dimension (LDC,N) — on entry, the M-by-N matrix C. On exit, C is overwritten by H*C or H**H*C or C*H or C*H**H. choose your own adventure but make it linear algebra 💅
LDC — LDC is INTEGER — the leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension (LDWORK,K)
LDWORK — LDWORK is INTEGER — the leading dimension of the array WORK. If SIDE = 'L', LDWORK >= max(1,N); if SIDE = 'R', LDWORK >= max(1,M).

Author

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

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details:

also empty in the original. two for two. we love a minimalist. ✨

🧚 `clarzt` 🧚

subroutine clarzt (character DIRECT, character STOREV, integer N, integer K,
    complex, dimension( ldv, * ) V, integer LDV, complex, dimension( * ) TAU,
    complex, dimension( ldt, * ) T, integer LDT)

CLARZT forms the triangular factor T of a block reflector H = I - vtvH. 🎀

Purpose:

CLARZT forms the triangular factor T of a complex block reflector H of order > n, which is defined as a product of k elementary reflectors.

If DIRECT = 'F', H = H(1) H(2) . . . H(k) and T is upper triangular;

If DIRECT = 'B', H = H(k) . . . H(2) H(1) and T is lower triangular.

If STOREV = 'C', the vector which defines the elementary reflector H(i) is stored in the i-th column of the array V, and

H  =  I - V * T * V**H

If STOREV = 'R', the vector which defines the elementary reflector H(i) is stored in the i-th row of the array V, and

H  =  I - V**H * T * V

Currently, only STOREV = 'R' and DIRECT = 'B' are supported. same deal as before bestie, it's giving very exclusive guest list. 👑

Parameters

DIRECT — DIRECT is CHARACTER*1 — specifies the order in which the elementary reflectors are multiplied to form the block reflector:
- = 'F': H = H(1) H(2) . . . H(k) (Forward, not supported yet)
- = 'B': H = H(k) . . . H(2) H(1) (Backward)
STOREV — STOREV is CHARACTER*1 — specifies how the vectors which define the elementary reflectors are stored (see also Further Details):
- = 'C': columnwise (not supported yet)
- = 'R': rowwise
N — N is INTEGER — the order of the block reflector H. N >= 0.
K — K is INTEGER — the order of the triangular factor T (= the number of elementary reflectors). K >= 1.
V — V is COMPLEX array, dimension
- (LDV,K) if STOREV = 'C'
- (LDV,N) if STOREV = 'R'

The matrix V. See Further Details.

LDV — LDV is INTEGER — the leading dimension of the array V. If STOREV = 'C', LDV >= max(1,N); if STOREV = 'R', LDV >= K.
TAU — TAU is COMPLEX array, dimension (K) — TAU(i) must contain the scalar factor of the elementary reflector H(i).
T — T is COMPLEX array, dimension (LDT,K) — the k by k triangular factor T of the block reflector. If DIRECT = 'F', T is upper triangular; if DIRECT = 'B', T is lower triangular. The rest of the array is not used.
LDT — LDT is INTEGER — the leading dimension of the array T. LDT >= K.

Author

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

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details:

The shape of the matrix V and the storage of the vectors which define the H(i) is best illustrated by the following example with n = 5 and k = 3. The elements equal to 1 are not stored; the corresponding array elements are modified but restored on exit. The rest of the array is not used. 🌈

DIRECT = 'F' and STOREV = 'C':         DIRECT = 'F' and STOREV = 'R':

okay so before we get into the next subroutines, here's the matrix diagram vibe you need to clock, bestie. no cap, this is exactly how it was handed down:

                                                         ______V_____
                    ( v1 v2 v3 )                        /            \
                    ( v1 v2 v3 )                      ( v1 v1 v1 v1 v1 . . . . 1 )
                V = ( v1 v2 v3 )                      ( v2 v2 v2 v2 v2 . . . 1   )
                    ( v1 v2 v3 )                      ( v3 v3 v3 v3 v3 . . 1     )
                    ( v1 v2 v3 )
                       .  .  .
                       .  .  .
                       1  .  .
                          1  .
                             1

and then the other one, because of course there's another one:

             DIRECT = 'B' and STOREV = 'C':         DIRECT = 'B' and STOREV = 'R':

                                                                   ______V_____
                       1                                          /            \
                       .  1                           ( 1 . . . . v1 v1 v1 v1 v1 )
                       .  .  1                        ( . 1 . . . v2 v2 v2 v2 v2 )
                       .  .  .                        ( . . 1 . . v3 v3 v3 v3 v3 )
                       .  .  .
                    ( v1 v2 v3 )
                    ( v1 v2 v3 )
                V = ( v1 v2 v3 )
                    ( v1 v2 v3 )
                    ( v1 v2 v3 )

now, the subroutines. 💅

✨ subroutine `clascl2` ✨

   subroutine clascl2 (integer M, integer N, real, dimension( * ) D, complex,
       dimension( ldx, * ) X, integer LDX)

CLASCL2 performs diagonal scaling on a matrix. it's giving "multiply by D and move on." 🦋

Purpose:

CLASCL2 performs a diagonal scaling on a matrix:

x <-- D * x

where the diagonal REAL matrix D is stored as a matrix.

Eventually to be replaced by BLAS_cge_diag_scale in the new BLAS standard. (so yes, it's lowkey on the way out, but still iconic for now.)

Parameters

M — M is INTEGER. The number of rows of D and X. M >= 0.
N — N is INTEGER. The number of columns of X. N >= 0.
D — D is REAL array, length M. Diagonal matrix D, stored as a vector of length M.
X — X is COMPLEX array, dimension (LDX,N). On entry, the matrix X to be scaled by D. On exit, the scaled matrix.
LDX — LDX is INTEGER. The leading dimension of the matrix X. LDX >= M.

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

✨ subroutine `clatrz` ✨

   subroutine clatrz (integer M, integer N, integer L, complex, dimension( lda,
       * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * )
       WORK)

CLATRZ factors an upper trapezoidal matrix by means of unitary transformations. periodt. 💅

Purpose:

CLATRZ factors the M-by-(M+L) complex upper trapezoidal matrix

[ A1 A2 ] = [ A(1:M,1:M) A(1:M,N-L+1:N) ]

as ( R 0 ) * Z by means of unitary transformations, where Z is an (M+L)-by-(M+L) unitary matrix and, R and A1 are M-by-M upper triangular matrices.

Parameters

M — M is INTEGER. The number of rows of the matrix A. M >= 0.
N — N is INTEGER. The number of columns of the matrix A. N >= 0.
L — L is INTEGER. The number of columns of the matrix A containing the meaningful part of the Householder vectors. N-M >= L >= 0.
A — A is COMPLEX array, dimension (LDA,N). On entry, the leading M-by-N upper trapezoidal part of the array A must contain the matrix to be factorized. On exit, the leading M-by-M upper triangular part of A contains the upper triangular matrix R, and elements N-L+1 to N of the first M rows of A, with the array TAU, represent the unitary matrix Z as a product of M elementary reflectors.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
TAU — TAU is COMPLEX array, dimension (M). The scalar factors of the elementary reflectors.
WORK — WORK is COMPLEX array, dimension (M).

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details:

The factorization is obtained by Householder's method. The kth transformation matrix, Z( k ), which is used to introduce zeros into the ( m - k + 1 )th row of A, is given in the form

                Z( k ) = ( I     0   ),
                         ( 0  T( k ) )

where

                T( k ) = I - tau*u( k )*u( k )**H,   u( k ) = (   1    ),
                                                            (   0    )
                                                            ( z( k ) )

tau is a scalar and z( k ) is an l element vector. tau and z( k ) are chosen to annihilate the elements of the kth row of A2.

The scalar tau is returned in the kth element of TAU and the vector u( k ) in the kth row of A2, such that the elements of z( k ) are in a( k, l + 1 ), ..., a( k, n ). The elements of R are returned in the upper triangular part of A1.

Z is given by

                Z =  Z( 1 ) * Z( 2 ) * ... * Z( m ).

✨ subroutine `cpbcon` ✨

   subroutine cpbcon (character UPLO, integer N, integer KD, complex,
       dimension( ldab, * ) AB, integer LDAB, real ANORM, real RCOND, complex,
       dimension( * ) WORK, real, dimension( * ) RWORK, integer INFO)

CPBCON — condition number detective for complex Hermitian positive definite band matrices. she's estimating the reciprocal, and she's doing it in the 1-norm. iconic.

Purpose:

CPBCON estimates the reciprocal of the condition number (in the 1-norm) of a complex Hermitian positive definite band matrix using the Cholesky factorization A = U**H*U or A = L*L**H computed by CPBTRF.

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))).

Parameters

UPLO — UPLO is CHARACTER*1. = 'U': Upper triangular factor stored in AB; = 'L': Lower triangular factor stored in AB.
N — N is INTEGER. The order of the matrix A. N >= 0.
KD — KD is INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of sub-diagonals if UPLO = 'L'. KD >= 0.
AB — AB is COMPLEX array, dimension (LDAB,N). The triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H of the band matrix A, stored in the first KD+1 rows of the array. The j-th column of U or L is stored in the j-th column of the array AB as follows:

if UPLO ='U', AB(kd+1+i-j,j) = U(i,j) for max(1,j-kd)<=i<=j;
if UPLO ='L', AB(1+i-j,j)    = L(i,j) for j<=i<=min(n,j+kd).

LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
ANORM — ANORM is REAL. The 1-norm (or infinity-norm) of the Hermitian band matrix A.
RCOND — RCOND is REAL. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(ANORM * AINVNM), where AINVNM is an estimate of the 1-norm of inv(A) computed in this routine.
WORK — WORK is COMPLEX array, dimension (2*N).
RWORK — RWORK is REAL array, dimension (N).
INFO — INFO is 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.

✨ subroutine `cpbequ` ✨

   subroutine cpbequ (character UPLO, integer N, integer KD, complex,
       dimension( ldab, * ) AB, integer LDAB, real, dimension( * ) S, real
       SCOND, real AMAX, integer INFO)

CPBEQU — she computes row and column scalings to equilibrate a Hermitian positive definite band matrix. it's giving "make the diagonal ones and chill." 💅

Purpose:

CPBEQU computes row and column scalings intended to equilibrate a Hermitian positive definite band matrix A and reduce its condition number (with respect to the two-norm). S contains the scale factors, S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal. This choice of S puts the condition number of B within a factor N of the smallest possible condition number over all possible diagonal scalings.

Parameters

UPLO — UPLO is CHARACTER*1. = 'U': Upper triangular of A is stored; = 'L': Lower triangular of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
KD — KD is INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — AB is COMPLEX array, dimension (LDAB,N). The upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

LDAB — LDAB is INTEGER. The leading dimension of the array A. LDAB >= KD+1.
S — S is REAL array, dimension (N). If INFO = 0, S contains the scale factors for A.
SCOND — SCOND is REAL. If INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S.
AMAX — AMAX is REAL. Absolute value of largest matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
INFO — INFO is INTEGER. = 0: successful exit; < 0: if INFO = -i, the i-th argument had an illegal value; > 0: if INFO = i, the i-th diagonal element is nonpositive.

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 Purpose 🌸

Okay bestie, so CPBRFS is the glow-up routine for your solution 💅 — it improves the computed solution to a system of linear equations when the coefficient matrix is Hermitian positive definite and banded, and it also hands you error bounds and backward error estimates for that solution. It's giving "your answer but make it accurate." ✨

🎀 Parameters 🎀

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER
- The order of the matrix A. N >= 0.
KD — KD is INTEGER
- The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
NRHS — NRHS is INTEGER
- The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AB — AB is COMPLEX array, dimension (LDAB,N)
- The upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).
LDAB — LDAB is INTEGER
- The leading dimension of the array AB. LDAB >= KD+1.
AFB — AFB is COMPLEX array, dimension (LDAFB,N)
- The triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H of the band matrix A as computed by CPBTRF, in the same storage format as A (see AB).
LDAFB — LDAFB is INTEGER
- The leading dimension of the array AFB. LDAFB >= KD+1.
B — B is COMPLEX array, dimension (LDB,NRHS)
- The right hand side matrix B.
LDB — LDB is INTEGER
- The leading dimension of the array B. LDB >= max(1,N).
X — X is COMPLEX array, dimension (LDX,NRHS)
- On entry, the solution matrix X, as computed by CPBTRS.
- On exit, the improved solution matrix X. (glow-up complete 🦋)
LDX — LDX is INTEGER
- The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is REAL array, dimension (NRHS)
- The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.
BERR — BERR is REAL array, dimension (NRHS)
- The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
WORK — WORK is COMPLEX array, dimension (2*N)
RWORK — RWORK is REAL array, dimension (N)
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

💜 Internal Parameters 💜

ITMAX is the maximum number of steps of iterative refinement. (yes bestie, it loops, and it has a vibe limit 🌀)

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 `cpbstf` 🌈

   subroutine cpbstf (character UPLO, integer N, integer KD, complex,
       dimension( ldab, * ) AB, integer LDAB, integer INFO)
       CPBSTF

✨ Purpose ✨

CPBSTF computes a split Cholesky factorization of a complex Hermitian positive definite band matrix A. 🎀

This routine is designed to be used in conjunction with CHBGST. iykyk 🤝

The factorization has the form A = S**H*S where S is a band matrix of the same bandwidth as A and the following structure:

  S = ( U    )
      ( M  L )

where U is upper triangular of order m = (n+kd)/2, and L is lower triangular of order n-m.

🎀 Parameters 🎀

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER
- The order of the matrix A. N >= 0.
KD — KD is INTEGER
- The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — AB is COMPLEX array, dimension (LDAB,N)
- On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first kd+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).
- On exit, if INFO = 0, the factor S from the split Cholesky factorization A = S**H*S. See Further Details.
LDAB — LDAB is INTEGER
- The leading dimension of the array AB. LDAB >= KD+1.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, the factorization could not be completed, because the updated element a(i,i) was negative; the matrix A is not positive definite. 😭

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 Further Details 🦋

The band storage scheme is illustrated by the following example, when N = 7, KD = 2:

  S = ( s11  s12  s13                     )
      (      s22  s23  s24                )
      (           s33  s34                )
      (                s44                )
      (           s53  s54  s55           )
      (                s64  s65  s66      )
      (                     s75  s76  s77 )

If UPLO = 'U', the array AB holds:

 on entry:                          on exit:

  *    *   a13  a24  a35  a46  a57   *    *   s13  s24  s53**H s64**H s75**H
  *   a12  a23  a34  a45  a56  a67   *   s12  s23  s34  s54**H s65**H s76**H
 a11  a22  a33  a44  a55  a66  a77  s11  s22  s33  s44  s55    s66    s77

If UPLO = 'L', the array AB holds:

 on entry:                          on exit:

 a11  a22  a33  a44  a55  a66  a77  s11    s22    s33    s44  s55  s66  s77
 a21  a32  a43  a54  a65  a76   *   s12**H s23**H s34**H s54  s65  s76   *
 a31  a42  a53  a64  a64   *    *   s13**H s24**H s53    s64  s75   *    *

Array elements marked * are not used by the routine; s12**H denotes conjg(s12); the diagonal elements of S are real. 💅

⭐ `cpbtf2` ⭐

   subroutine cpbtf2 (character UPLO, integer N, integer KD, complex,
       dimension( ldab, * ) AB, integer LDAB, integer INFO)

CPBTF2 computes the Cholesky factorization of a symmetric/Hermitian positive definite band matrix (unblocked algorithm). (unblocked = no fancy blocking, just straight up Level 2 BLAS energy ⚡)

✨ Purpose ✨

CPBTF2 computes the Cholesky factorization of a complex Hermitian positive definite band matrix A. 🌸

The factorization has the form

   A = U**H * U ,  if UPLO = 'U', or
   A = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix, U**H is the conjugate transpose of U, and L is lower triangular.

This is the unblocked version of the algorithm, calling Level 2 BLAS. No cap. 🫶

🎀 Parameters 🎀

UPLO — UPLO is CHARACTER*1
- Specifies whether the upper or lower triangular part of the Hermitian matrix A is stored:
- = 'U': Upper triangular
- = 'L': Lower triangular
N — N is INTEGER
- The order of the matrix A. N >= 0.
KD — KD is INTEGER
- The number of super-diagonals of the matrix A if UPLO = 'U', or the number of sub-diagonals if UPLO = 'L'. KD >= 0.
AB — AB is COMPLEX array, dimension (LDAB,N)
- On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).
- On exit, if INFO = 0, the triangular factor U or L from the Cholesky factorization A = U**H *U or A = L*L**H of the band matrix A, in the same storage format as A.
LDAB — LDAB is INTEGER
- The leading dimension of the array AB. LDAB >= KD+1.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -k, the k-th argument had an illegal value
- > 0: if INFO = k, the leading minor of order k is not positive definite, and the factorization could not be completed. 💀

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 Further Details 🦋

The band storage scheme is illustrated by the following example, when N = 6, KD = 2, and UPLO = 'U':

 On entry:                       On exit:

     *    *   a13  a24  a35  a46      *    *   u13  u24  u35  u46
     *   a12  a23  a34  a45  a56      *   u12  u23  u34  u45  u56
    a11  a22  a33  a44  a55  a66     u11  u22  u33  u44  u55  u66

Similarly, if UPLO = 'L' the format of A is as follows:

 On entry:                       On exit:

                a11  a22  a33  a44  a55  a66     l11  l22  l33  l44  l55  l66
                a21  a32  a43  a54  a65   *      l21  l32  l43  l54  l65   *
                a31  a42  a53  a64   *    *      l31  l42  l53  l64   *    *

see those lil stars? those are the spots the routine literally never touches. not "touches gently". not "reads for fun". not used by the routine, periodt. 💅

Contributors (the lore ✨)

Peter Mayes and Giuseppe Radicati, IBM ECSEC, Rome, March 23, 1989 — actual icons, we stan. 🫶

🦋 subroutine `cpbtrf` was cute but now meet `cpbtrs`

subroutine cpbtrs (character UPLO, integer N, integer KD, integer NRHS,
    complex, dimension( ldab, * ) AB, integer LDAB, complex, dimension( ldb,
    * ) B, integer LDB, integer INFO)

CPBTRS 🎀

Purpose 💖

okay so CPBTRS solves a system of linear equations A*X = B with a Hermitian positive definite band matrix A, and it does it using the Cholesky factorization A = U**H*U or A = L*L**H that CPBTRF already computed for you. bestie reuses the work, it's giving efficient. ✨

Parameters 🌸

UPLO — it's a CHARACTER*1, and it tells us which triangle we're working with:
- = 'U': Upper triangular factor stored in AB;
- = 'L': Lower triangular factor stored in AB.
N — an INTEGER, the order of the matrix A. N >= 0.
KD — an INTEGER, the number of superdiagonals of A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
NRHS — an INTEGER, the number of right hand sides, i.e. the number of columns of the matrix B. NRHS >= 0.
AB — a COMPLEX array, dimension (LDAB,N). this is the triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H of the band matrix A, stored in the first KD+1 rows of the array. the j-th column of U or L lives in the j-th column of AB like so:
- if UPLO ='U', AB(kd+1+i-j,j) = U(i,j) for max(1,j-kd)<=i<=j;
- if UPLO ='L', AB(1+i-j,j) = L(i,j) for j<=i<=min(n,j+kd).
LDAB — an INTEGER, the leading dimension of the array AB. LDAB >= KD+1.
B — a COMPLEX array, dimension (LDB,NRHS). on entry it's the right hand side matrix B. on exit? it's the solution matrix X. glow up. ✨
- On entry: the right hand side matrix B.
- On exit: the solution matrix X.
LDB — an INTEGER, the leading dimension of the array B. LDB >= max(1,N).
INFO — an INTEGER, the receipts 📋:
- = 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.

🧚 subroutine `cpftrf` (RFP format girlies rise)

subroutine cpftrf (character TRANSR, character UPLO, integer N, complex,
    dimension( 0: * ) A, integer INFO)

CPFTRF 💜

Purpose 💖

so CPFTRF computes the Cholesky factorization of a complex Hermitian positive definite matrix A.

the factorization has the form:

   A = U**H * U,  if UPLO = 'U', or
   A = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix and L is lower triangular. 💅

and the tea? this is the block version of the algorithm, calling Level 3 BLAS. fancy. fast. iconic. 🔥

Parameters 🌸

TRANSR — a CHARACTER*1:
- = 'N': the Normal TRANSR of RFP A is stored;
- = 'C': the Conjugate-transpose TRANSR of RFP A is stored.
UPLO — a CHARACTER*1:
- = 'U': upper triangle of RFP A is stored;
- = 'L': lower triangle of RFP A is stored.
N — an INTEGER, the order of the matrix A. N >= 0.
A — a COMPLEX array, dimension ( N*(N+1)/2 ). buckle up bestie, this one's a whole essay 📖:

On entry, it's the Hermitian matrix A in RFP format. RFP format is described by TRANSR, UPLO, and N as follows: if TRANSR = 'N' then RFP A is (0:N,0:k-1) when N is even; k=N/2. RFP A is (0:N-1,0:k) when N is odd; k=N/2. If TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: if UPLO = 'U' the RFP A contains the nt elements of upper packed A. If UPLO = 'L' the RFP A contains the elements of lower packed A. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and N is odd. See the Note below for more details. 👀

On exit, if INFO = 0, the factor U or L from the Cholesky factorization RFP A = U**H*U or RFP A = L*L**H. ✨

INFO — an INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭
- > 0: if INFO = i, the leading minor of order i is not positive definite, and the factorization could not be completed. she said nope. 💀

Further Notes on RFP Format: 🔍

============================

first up: Standard Packed Format when N is even. example where N = 6:

                AP is Upper             AP is Lower

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

let TRANSR = 'N'. RFP holds AP as follows:

for UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. the lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper.

for UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. the upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower.

to denote conjugate we place -- above the element. this covers the case N even and TRANSR = 'N'.

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. one therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

next we consider Standard Packed Format when N is odd. example where N = 5:

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

ok so now we're on the N-odd era of this whole saga, and the trapezoid is doing the absolute most, but stay with me bestie because it's actually so clean once you see it:

             Let TRANSR = 'N'. RFP holds AP as follows:
             For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last
             three columns of AP upper. The lower triangle A(3:4,0:1) consists of
             conjugate-transpose of the first two   columns of AP upper.
             For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first
             three columns of AP lower. The upper triangle A(0:1,1:2) consists of
             conjugate-transpose of the last two   columns of AP lower.
             To denote conjugate we place -- above the element. This covers the
             case N odd  and TRANSR = 'N'.

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Those little -- marks floating above an element? that's the conjugate indicator, it's not a typo, it's a vibe ✨

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. plot twist but make it math — one therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

👑 Author 👑

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

🎀 CPFTRI 🎀

   subroutine cpftri (character TRANSR, character UPLO, integer N, complex,
       dimension( 0: * ) A, integer INFO)

CPFTRI

💖 Purpose 💖

CPFTRI computes the inverse of a complex Hermitian positive definite matrix A using the Cholesky factorization A = U**H*U or A = L*L**H computed by CPFTRF.

inverse arc unlocked, no cap 🔥

🌸 Parameters 🌸

TRANSR — TRANSR is CHARACTER*1
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'C': The Conjugate-transpose TRANSR of RFP A is stored.
UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
A — A is COMPLEX array, dimension ( N*(N+1)/2 ).

On entry, the Hermitian matrix A in RFP format. RFP format is described by TRANSR, UPLO, and N as follows: if TRANSR = 'N' then RFP A is (0:N,0:k-1) when N is even; k=N/2. RFP A is (0:N-1,0:k) when N is odd; k=N/2. IF TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: If UPLO = 'U' the RFP A contains the nt elements of upper packed A. If UPLO = 'L' the RFP A contains the elements of lower packed A. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and N is odd. See the Note below for more details.

On exit, the Hermitian inverse of the original matrix, in the same storage format. same fit, new function 💅

INFO — INFO is INTEGER
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 😭
- > 0: if INFO = i, the (i,i) element of the factor U or L is zero, and the inverse could not be computed. 💀

👑 Author 👑

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

🔍 Further Details 🔍

First up: Standard Packed Format when N is even. Example where N = 6. exhibit A, the receipts:

                 AP is Upper             AP is Lower

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. Example where N = 5. odd numbers stay booked and busy fr fr:

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

🦋 CPFTRS 🦋

   subroutine cpftrs (character TRANSR, character UPLO, integer N, integer
       NRHS, complex, dimension( 0: * ) A, complex, dimension( ldb, * ) B,
       integer LDB, integer INFO)

CPFTRS

💖 Purpose 💖

CPFTRS solves a system of linear equations A*X = B with a Hermitian positive definite matrix A using the Cholesky factorization A = U**H*U or A = L*L**H computed by CPFTRF.

<s>solve</s> slay the system, bestie 🔥

🌸 Parameters 🌸

TRANSR — TRANSR is CHARACTER*1
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'C': The Conjugate-transpose TRANSR of RFP A is stored.
UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of RFP A is stored;
- = 'L': Lower triangle of RFP A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
A — A is COMPLEX array, dimension ( N*(N+1)/2 ). The triangular factor U or L from the Cholesky factorization of RFP A = U**H*U or RFP A = L*L**H, as computed by CPFTRF. See note below for more details about RFP A.
B — B is COMPLEX array, dimension (LDB,NRHS).
- On entry, the right hand side matrix B.
- On exit, the solution matrix X. glow up complete ✨
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
INFO — INFO is 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 🔍

We first consider Standard Packed Format when N is even. We give an example where N = 6.

                 AP is Upper             AP is Lower

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

                    RFP A                   RFP A

so the whole even-N situation? Same tea, different TRANSR. Now let TRANSR = 'C'. RFP A in both UPLO cases is literally just the conjugate-transpose of RFP A above. So bestie, you get:

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

and then:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

okay now we pivot 🌸 We next consider Standard Packed Format when N is odd. Example time, and we're giving one where N = 5:

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP like this:

For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper.
For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'.

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

💖 subroutine cppcon 💖

subroutine cppcon (character UPLO, integer N, complex, dimension( * ) AP,
    real ANORM, real RCOND, complex, dimension( * ) WORK, real, dimension( *
    ) RWORK, integer INFO)

CPPCON — okay so the name is doing a lot of work here, but it's giving condition number energy ✨

🎀 Purpose

CPPCON estimates the reciprocal of the condition number (in the 1-norm) of a complex Hermitian positive definite packed matrix using the Cholesky factorization A = U**H*U or A = L*L**H computed by CPPTRF.

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))).

🌸 Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER The order of the matrix A. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2) The triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, packed columnwise in a linear array. The j-th column of U or L is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = U(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = L(i,j) for j<=i<=n.
ANORM — ANORM is REAL The 1-norm (or infinity-norm) of the Hermitian matrix A.
RCOND — RCOND is REAL The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(ANORM * AINVNM), where AINVNM is an estimate of the 1-norm of inv(A) computed in this routine.
WORK — WORK is COMPLEX array, dimension (2*N)
RWORK — RWORK is REAL array, dimension (N)
INFO — INFO is 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.

🦋 subroutine cppequ 🦋

subroutine cppequ (character UPLO, integer N, complex, dimension( * ) AP,
    real, dimension( * ) S, real SCOND, real AMAX, integer INFO)

✨ Purpose

CPPEQU computes row and column scalings intended to equilibrate a Hermitian positive definite matrix A in packed storage and reduce its condition number (with respect to the two-norm). S contains the scale factors, S(i)=1/sqrt(A(i,i)), chosen so that the scaled matrix B with elements B(i,j)=S(i)*A(i,j)*S(j) has ones on the diagonal. This choice of S puts the condition number of B within a factor N of the smallest possible condition number over all possible diagonal scalings. slay 💅

🌈 Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER The order of the matrix A. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2) The upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
S — S is REAL array, dimension (N) If INFO = 0, S contains the scale factors for A.
SCOND — SCOND is REAL If INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S.
AMAX — AMAX is REAL Absolute value of largest matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, the i-th diagonal element is nonpositive.

🫶 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💜 subroutine cpprfs 💜

subroutine cpprfs (character UPLO, integer N, integer NRHS, complex,
    dimension( * ) AP, complex, dimension( * ) AFP, complex, dimension( ldb,
    * ) B, integer LDB, complex, dimension( ldx, * ) X, integer LDX, real,
    dimension( * ) FERR, real, dimension( * ) BERR, complex, dimension( * )
    WORK, real, dimension( * ) RWORK, integer INFO)

🔥 Purpose

CPPRFS improves the computed solution to a system of linear equations when the coefficient matrix is Hermitian positive definite and packed, and provides error bounds and backward error estimates for the solution. it's giving glow-up for your answer vector, fr fr ✨

💖 Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2) The upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
AFP — AFP is COMPLEX array, dimension (N*(N+1)/2) The triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, as computed by SPPTRF/CPPTRF, packed columnwise in a linear array in the same format as A (see AP).
B — B is COMPLEX array, dimension (LDB,NRHS) The right hand side matrix B.
LDB — LDB is INTEGER The leading dimension of the array B. LDB >= max(1,N).
X — X is COMPLEX array, dimension (LDX,NRHS) On entry, the solution matrix X, as computed by CPPTRS. On exit, the improved solution matrix X.
LDX — LDX is INTEGER The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is REAL array, dimension (NRHS) The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.
BERR — BERR is REAL array, dimension (NRHS) The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
WORK — WORK is COMPLEX array, dimension (2*N)
RWORK — RWORK is REAL array, dimension (N)
INFO
INFO — is INTEGER. = 0: successful exit; < 0: if INFO = -i, the i-th argument had an illegal value. the classic INFO moment 💅

Internal Parameters:

ITMAX — is the maximum number of steps of iterative refinement. the limit bestie ✨

Author

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

subroutine cpptrf (character UPLO, integer N, complex, dimension( * ) AP, integer INFO)

CPPTRF 💖

Purpose

okay so CPPTRF computes the Cholesky factorization of a complex Hermitian positive definite matrix A stored in packed format. <sparkle>slay</sparkle> ✨

The factorization has the form:

A = U**H * U,  if UPLO = 'U', or
A = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix and L is lower triangular. the way that works is iconic 💜

Parameters

UPLO — is CHARACTER*1. = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. pick your fighter 🎀
N — is INTEGER. The order of the matrix A. N >= 0. no negatives bestie 🌼
AP — is COMPLEX array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows: if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n. See below for further details. packed like a lunchbox fr 🍓

On exit, if INFO = 0, the triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, in the same storage format as A. she transforms 🦋

INFO — is INTEGER. = 0: successful exit; < 0: if INFO = -i, the i-th argument had an illegal value; > 0: if INFO = i, the leading minor of order i is not positive definite, and the factorization could not be completed. not the vibe if positive definite is missing 💀

Author

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

Further Details:

The packed storage scheme is illustrated by the following example when N = 4, UPLO = 'U':

Two-dimensional storage of the Hermitian matrix A:

   a11 a12 a13 a14
       a22 a23 a24
           a33 a34     (aij = conjg(aji))
               a44

Packed storage of the upper triangle of A:

AP = [ a11, a12, a22, a13, a23, a33, a14, a24, a34, a44 ]

the way the packing just lines up is so satisfying ✨

subroutine cpptri (character UPLO, integer N, complex, dimension( * ) AP, integer INFO)

CPPTRI 💖

Purpose

CPPTRI computes the inverse of a complex Hermitian positive definite matrix A using the Cholesky factorization A = U**H*U or A = L*L**H computed by CPPTRF. we love a glow-up 🫶

Parameters

UPLO — is CHARACTER*1. = 'U': Upper triangular factor is stored in AP; = 'L': Lower triangular factor is stored in AP. upper or lower, your call 💜
N — is INTEGER. The order of the matrix A. N >= 0. same energy ✨
AP — is COMPLEX array, dimension (N*(N+1)/2). On entry, the triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, packed columnwise as a linear array. The j-th column of U or L is stored in the array AP as follows: if UPLO = 'U', AP(i + (j-1)*j/2) = U(i,j) for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = L(i,j) for j<=i<=n. packed and ready 🎀

On exit, the upper or lower triangle of the (Hermitian) inverse of A, overwriting the input factor U or L. she ate and left no crumbs 💅

INFO — is INTEGER. = 0: successful exit; < 0: if INFO = -i, the i-th argument had an illegal value; > 0: if INFO = i, the (i,i) element of the factor U or L is zero, and the inverse could not be computed. zero pivot? not today bestie 😭

Author

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

subroutine cpptrs (character UPLO, integer N, integer NRHS, complex, dimension( * ) AP, complex, dimension( ldb, * ) B, integer LDB, integer INFO)

CPPTRS 💖

Purpose

CPPTRS solves a system of linear equations A*X = B with a Hermitian positive definite matrix A in packed storage using the Cholesky factorization A = U**H*U or A = L*L**H computed by CPPTRF. solve it bestie ✨

Parameters

UPLO — is CHARACTER*1. = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored. classic 🎀
N — is INTEGER. The order of the matrix A. N >= 0. no negativity allowed 🌼
NRHS — is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0. so many right hand sides, so little time 💜
AP — is COMPLEX array, dimension (N*(N+1)/2). The triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, packed columnwise in a linear array. The j-th column of U or L is stored in the array AP as follows: if UPLO = 'U', AP(i + (j-1)*j/2) = U(i,j) for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = L(i,j) for j<=i<=n. same packing, same slay 🦋
B — is COMPLEX array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, the solution matrix X. glow up from B to X 💅
LDB — is INTEGER. The leading dimension of the array B. LDB >= max(1,N). don't skimp on the leading dimension ⚠️
INFO — is INTEGER. = 0: successful exit; < 0: if INFO = -i, the i-th argument had an illegal value. all good or illegal argument, no in between ✨

Author

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

subroutine cpstf2 (character UPLO, integer N, complex, dimension( lda, * ) A, integer LDA, integer, dimension( n ) PIV, integer RANK, real TOL, real, dimension( 2*n ) WORK, integer INFO)

CPSTF2 💖

CPSTF2 computes the Cholesky factorization with complete pivoting of complex Hermitian positive semidefinite matrix. pivoting but make it complete ✨

Purpose

CPSTF2 computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix A. semidefinite, not definite, bestie 🎀

The factorization has the form:

P**T * A * P = U**H * U ,  if UPLO = 'U',
P**T * A * P = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix and L is lower triangular, and P is stored as vector PIV. permutation vector, periodt 💅

This algorithm does not attempt to check that A is positive semidefinite. This version of the algorithm calls level 2 BLAS. no checking, just vibes 😭

Parameters

UPLO — is CHARACTER*1. Specifies whether the upper or lower triangular part of the symmetric matrix A is stored. = 'U': Upper triangular; = 'L': Lower triangular. choose your triangle 🦋
N — is INTEGER. The order of the matrix A. N >= 0. non-negative always 🌼
A — is COMPLEX array, dimension (LDA,N). On entry, the symmetric matrix A. If UPLO = 'U', the leading n by n upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading n by n lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced. only half the tea is stored 🍓

On exit, if INFO = 0, the factor U or L from the Cholesky factorization as above. she factorized ✨

PIV — is INTEGER array, dimension (N). PIV is such that the nonzero entries are P( PIV(K), K ) = 1. the permutation is giving 💜
RANK — is INTEGER. The rank of A given by the number of steps the algorithm completed. rank on rank on rank 👑
TOL — is REAL. User defined tolerance. If TOL < 0, then N*U*MAX( A( K,K ) ) will be used. The algorithm terminates at the (K-1)st step if the pivot <= TOL. tolerance level: set it right ⚠️
LDA — is INTEGER. The leading dimension of the array A. LDA >= max(1,N). leading dimension said what she said 💅
WORK — is REAL array, dimension (2*N). Work space. the workspace, the moment ✨
INFO — is INTEGER. < 0: If INFO = -K, the K-th argument had an illegal value; = 0: algorithm completed successfully; > 0: the matrix A is either rank deficient with computed rank as returned in RANK, or is not positive semidefinite. See Section 7 of LAPACK Working Note #161 for further information. read the working note for the lore 📚

Author

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

subroutine cpstrf (character UPLO, integer N, complex, dimension( lda, * ) A, integer LDA, integer, dimension( n ) PIV, integer RANK, real TOL, real, dimension( 2*n ) WORK, integer INFO)

CPSTRF 💖

CPSTRF computes the Cholesky factorization with complete pivoting of complex Hermitian positive semidefinite matrix. level 3 BLAS, level 3 slay ✨

Purpose

CPSTRF computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix A. semidefinite again, keep up 🎀

The factorization has the form:

P**T * A * P = U**H * U ,  if UPLO = 'U',
P**T * A * P = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix and L is lower triangular, and P is stored as vector PIV. same as cpstf2 but level 3 💅

This algorithm does not attempt to check that A is positive semidefinite. This version of the algorithm calls level 3 BLAS. still no checking, still iconic 😭

Parameters

UPLO — is CHARACTER*1. Specifies whether the upper or lower triangular part of the symmetric matrix A is stored. = 'U': Upper triangular; = 'L': Lower triangular. triangle choice 🦋
N — is INTEGER. The order of the matrix A. N >= 0. non-negative 🌼
A —
A — COMPLEX array, dimension (LDA,N). On entry, this is your symmetric matrix A, and she is the main character. If UPLO = 'U', the leading n by n upper triangular part of A holds the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced (she's literally not invited 💅). If UPLO = 'L', the leading n by n lower triangular part of A holds the lower triangular part of the matrix A, and the strictly upper triangular part is not referenced either. On exit, if INFO = 0, you get the factor U or L from the Cholesky factorization as above. iconic behavior ✨
LDA — INTEGER. The leading dimension of the array A. Rule of the house: LDA >= max(1,N). No cap. 🫶
PIV — INTEGER array, dimension (N). PIV is such that the nonzero entries are P( PIV(K), K ) = 1. That's it, that's the whole vibe.
RANK — INTEGER. The rank of A, given by the number of steps the algorithm completed. She counts her own progress, obsessed 😌
TOL — REAL. User defined tolerance. If TOL < 0, then N*U*MAX( A(K,K) ) will be used instead. The algorithm terminates at the (K-1)st step if the pivot <= TOL. So if you don't set a tolerance, bestie, she'll pick one for you. 🎀
WORK — REAL array, dimension (2*N). Work space. It's giving backstage crew 🌸
INFO — INTEGER. The whole tea:
- < 0: If INFO = -K, the K-th argument had an illegal value (somebody typed wrong 😭).
- = 0: algorithm completed successfully.
- > 0: the matrix A is either rank deficient with computed rank as returned in RANK, or is not positive semidefinite. See Section 7 of LAPACK Working Note #161 for further information.

👑 Author

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

💖 subroutine `cspcon`

subroutine cspcon (character UPLO, integer N, complex, dimension( * ) AP, integer, dimension( * ) IPIV, real ANORM, real RCOND, complex, dimension( * ) WORK, integer INFO)

🎀 CSPCON

Okay so this one estimates how ill-conditioned your matrix is. Very "are you okay? are you stable?" energy. 🦋

✨ Purpose

CSPCON estimates the reciprocal of the condition number (in the 1-norm) of a complex symmetric packed matrix A using the factorization A = U*D*U**T or A = L*D*L**T computed by CSPTRF.

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))). Literally just a little division, slay 💅

🍓 Parameters

UPLO — UPLO is CHARACTER*1. Specifies whether the details of the factorization are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**T;
- = 'L': Lower triangular, form is A = L*D*L**T.
N — N is INTEGER. The order of the matrix A. N >= 0. Zero is allowed, she's flexible ✨
AP — AP is COMPLEX array, dimension (N*(N+1)/2). The block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by CSPTRF, stored as a packed triangular matrix. All crammed in there, cozy 🧚
IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by CSPTRF. She's reporting what CSPTRF did, not deciding anything herself 💜
ANORM — ANORM is REAL. The 1-norm of the original matrix A. Yes, original — before all the factoring drama.
RCOND — RCOND is REAL. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(ANORM * AINVNM), where AINVNM is an estimate of the 1-norm of inv(A) computed in this routine. Small number = scary matrix, big number = chill matrix 😌
WORK — WORK is COMPLEX array, dimension (2*N). Scratch space, do not perceive it.
INFO — INFO is 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.

🦋 subroutine `csprfs`

subroutine csprfs (character UPLO, integer N, integer NRHS, complex, dimension( * ) AP, complex, dimension( * ) AFP, integer, dimension( * ) IPIV, complex, dimension( ldb, * ) B, integer LDB, complex, dimension( ldx, * ) X, integer LDX, real, dimension( * ) FERR, real, dimension( * ) BERR, complex, dimension( * ) WORK, real, dimension( * ) RWORK, integer INFO)

💜 CSPRFS

The glow-up routine. You already solved the system; now she makes your answer better and also tells you how wrong it still is. Honesty is the brand bestie 💅

✨ Purpose

CSPRFS improves the computed solution to a system of linear equations when the coefficient matrix is symmetric indefinite and packed, and provides error bounds and backward error estimates for the solution.

So: iterative refinement plus receipts. 📝

🍓 Parameters

UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). The upper or lower triangle of the symmetric matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.

Yes, you have to do the math yourself, no she will not do it for you 🙈

AFP — AFP is COMPLEX array, dimension (N*(N+1)/2). The factored form of the matrix A. AFP contains the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U**T or A = L*D*L**T as computed by CSPTRF, stored as a packed triangular matrix.
IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by CSPTRF.
B — B is COMPLEX array, dimension (LDB,NRHS). The right hand side matrix B. The problem itself, the origin story.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
X — X is COMPLEX array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by CSPTRS. On exit, the improved solution matrix X. She went to the gym 🏋️
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is REAL array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. Dramatic, but honest.
BERR — BERR is REAL array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution). The "how much would reality have to change for you to be right" number 💀
WORK — WORK is COMPLEX array, dimension (2*N). Scratch space.
RWORK — RWORK is REAL array, dimension (N). More scratch space, but make it real 🌸
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value.

🔥 Internal Parameters

ITMAX is the maximum number of steps of iterative refinement. She will not go forever, bestie, she has boundaries ✋

👑 Author

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

🌸 subroutine `csptrf`

subroutine csptrf (character UPLO, integer N, complex, dimension( * ) AP, integer, dimension( * ) IPIV, integer INFO)

💅 CSPTRF

The origin story of the whole packed complex symmetric saga. Everything else in this part is downstream of her.

✨ Purpose

CSPTRF computes the factorization of a complex symmetric matrix A stored in packed format using the Bunch-Kaufman diagonal pivoting method:

A = U*D*U**T  or  A = L*D*L**T

where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is symmetric and block diagonal with 1-by-1 and 2-by-2 diagonal blocks. Small blocks, big consequences 💅

🍓 Parameters

UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2).

On entry, the upper or lower triangle of the symmetric matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

On exit, the block diagonal matrix D and the multipliers used to obtain the factor U or L, stored as a packed triangular matrix overwriting A (see below for further details). She does not ask permission, she just moves in and redecorates 🎀

IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D.
- If IPIV(k) > 0, then rows and columns k and IPIV(k) were interchanged and D(k,k) is a 1-by-1 diagonal block.
- If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then rows and columns k-1 and -IPIV(k) were interchanged and D(k-1:k,k-1:k) is a 2-by-2 diagonal block.
- If UPLO = 'L' and IPIV(k) = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k) were interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.

Negative entries mean 2-by-2 blocks, positive means 1-by-1. Read the signs, bestie, iykyk 🧐

INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, and division by zero will occur if it is used to solve a system of equations.

⚠️ Not me warning you twice: INFO > 0 means the factorization finished but D is singular. If you then try to solve with it, you get division by zero. She told you. Don't act surprised 😭

👑 Author

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

🔍 Further Details:

5-96 - Based on modifications by J. Lewis, Boeing Computer Services Company

okay so like, here's the tea on how the factorization is stored, bestie. if UPLO = 'U', then A = U*D*U**T, where U = P(n)*U(n)* ... *P(k)U(k)* ..., i.e., U is a product of terms P(k)*U(k), where k decreases from n to 1 in steps of 1 or 2, and D is a block diagonal matrix with 1-by-1 and 2-by-2 diagonal blocks D(k). P(k) is a permutation matrix as defined by IPIV(k), and U(k) is a unit upper triangular matrix, such that if the diagonal block D(k) is of order s (s = 1 or 2), then

                        (   I    v    0   )   k-s
                U(k) =  (   0    I    0   )   s
                        (   0    0    I   )   n-k
                           k-s   s   n-k

if s = 1, D(k) overwrites A(k,k), and v overwrites A(1:k-1,k). if s = 2, the upper triangle of D(k) overwrites A(k-1,k-1), A(k-1,k), and A(k,k), and v overwrites A(1:k-2,k-1:k).

if UPLO = 'L', then A = L*D*L**T, where L = P(1)*L(1)* ... *P(k)*L(k)* ..., i.e., L is a product of terms P(k)*L(k), where k increases from 1 to n in steps of 1 or 2, and D is a block diagonal matrix with 1-by-1 and 2-by-2 diagonal blocks D(k). P(k) is a permutation matrix as defined by IPIV(k), and L(k) is a unit lower triangular matrix, such that if the diagonal block D(k) is of order s (s = 1 or 2), then

                        (   I    0     0   )  k-1
                L(k) =  (   0    I     0   )  s
                        (   0    v     I   )  n-k-s+1
                           k-1   s  n-k-s+1

if s = 1, D(k) overwrites A(k,k), and v overwrites A(k+1:n,k). if s = 2, the lower triangle of D(k) overwrites A(k,k), A(k+1,k), and A(k+1,k+1), and v overwrites A(k+2:n,k:k+1).

💅 subroutine csptri 💅

subroutine csptri (character UPLO, integer N, complex, dimension( * ) AP,
    integer, dimension( * ) IPIV, complex, dimension( * ) WORK, integer
    INFO)

CSPTRI

🎯 Purpose 🎯

so like, CSPTRI computes the inverse of a complex symmetric indefinite matrix A in packed storage using the factorization A = U*D*U**T or A = L*D*L**T computed by CSPTRF. slay.

📋 Parameters 📋

`UPLO`

UPLO is CHARACTER*1. it tells you if the details of the factorization are stored as an upper or lower triangular matrix. = 'U': upper triangular, form is A = U*D*U**T; = 'L': lower triangular, form is A = L*D*L**T.

`N`

N is INTEGER. it's the order of the matrix A. N >= 0.

`AP`

AP is COMPLEX array, dimension (N*(N+1)/2). on entry, it's the block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by CSPTRF, stored as a packed triangular matrix.

on exit, if INFO = 0, it's the (symmetric) inverse of the original matrix, stored as a packed triangular matrix. the j-th column of inv(A) is stored in the array AP like this: if UPLO = 'U', AP(i + (j-1)*j/2) = inv(A)(i,j) for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = inv(A)(i,j) for j<=i<=n.

`IPIV`

IPIV is INTEGER array, dimension (N). it has the details of the interchanges and the block structure of D as determined by CSPTRF.

`WORK`

WORK is COMPLEX array, dimension (N).

`INFO`

INFO is INTEGER. = 0: successful exit < 0: if INFO = -i, the i-th argument had an illegal value

0: if INFO = i, D(i,i) = 0; the matrix is singular and its inverse could not be computed. yikes.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💅 subroutine csptrs 💅

subroutine csptrs (character UPLO, integer N, integer NRHS, complex,
    dimension( * ) AP, integer, dimension( * ) IPIV, complex, dimension(
    ldb, * ) B, integer LDB, integer INFO)

CSPTRS

🎯 Purpose 🎯

so like, CSPTRS solves a system of linear equations A*X = B with a complex symmetric matrix A stored in packed format using the factorization A = U*D*U**T or A = L*D*L**T computed by CSPTRF. periodt.

📋 Parameters 📋

`UPLO`

`N`

N is INTEGER. it's the order of the matrix A. N >= 0.

`NRHS`

NRHS is INTEGER. it's the number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.

`AP`

AP is COMPLEX array, dimension (N*(N+1)/2). it's the block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by CSPTRF, stored as a packed triangular matrix.

`IPIV`

IPIV is INTEGER array, dimension (N). it has the details of the interchanges and the block structure of D as determined by CSPTRF.

`B`

B is COMPLEX array, dimension (LDB,NRHS). on entry, it's the right hand side matrix B. on exit, it's the solution matrix X.

`LDB`

LDB is INTEGER. it's the leading dimension of the array B. LDB >= max(1,N).

`INFO`

INFO is 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.

💅 subroutine cstedc 💅

subroutine cstedc (character COMPZ, integer N, real, dimension( * ) D, real,
    dimension( * ) E, complex, dimension( ldz, * ) Z, integer LDZ, complex,
    dimension( * ) WORK, integer LWORK, real, dimension( * ) RWORK, integer
    LRWORK, integer, dimension( * ) IWORK, integer LIWORK, integer INFO)

CSTEDC

🎯 Purpose 🎯

so like, CSTEDC computes all eigenvalues and, optionally, eigenvectors of a symmetric tridiagonal matrix using the divide and conquer method. the eigenvectors of a full or band complex Hermitian matrix can also be found if CHETRD or CHPTRD or CHBTRD has been used to reduce this matrix to tridiagonal form.

this code makes very mild assumptions about floating point arithmetic. it will work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray X-MP, Cray Y-MP, Cray C-90, or Cray-2. it could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none. see SLAED3 for details. no cap.

📋 Parameters 📋

`COMPZ`

COMPZ is CHARACTER*1 = 'N': Compute eigenvalues only. = 'I': Compute eigenvectors of tridiagonal matrix also. = 'V': Compute eigenvectors of original Hermitian matrix also. On entry, Z contains the unitary matrix used to reduce the original matrix to tridiagonal form.

`N`

N is INTEGER. it's the dimension of the symmetric tridiagonal matrix. N >= 0.

`D`

D is REAL array, dimension (N). on entry, it's the diagonal elements of the tridiagonal matrix. on exit, if INFO = 0, it's the eigenvalues in ascending order.

`E`

E is REAL array, dimension (N-1). on entry, it's the subdiagonal elements of the tridiagonal matrix. on exit, E has been destroyed.

`Z`

Z is COMPLEX array, dimension (LDZ,N). on entry, if COMPZ = 'V', then Z contains the unitary matrix used in the reduction to tridiagonal form. on exit, if INFO = 0, then if COMPZ = 'V', Z contains the orthonormal eigenvectors of the original Hermitian matrix, and if COMPZ = 'I', Z contains the orthonormal eigenvectors of the symmetric tridiagonal matrix. if COMPZ = 'N', then Z is not referenced.

`LDZ`

LDZ is INTEGER. it's the leading dimension of the array Z. LDZ >= 1. if eigenvectors are desired, then LDZ >= max(1,N).

`WORK`

WORK is COMPLEX array, dimension (MAX(1,LWORK)). on exit, if INFO = 0, WORK(1) returns the optimal LWORK.

`LWORK`

LWORK is INTEGER. it's the dimension of the array WORK. if COMPZ = 'N' or 'I', or N <= 1, LWORK must be at least 1. if COMPZ = 'V' and N > 1, LWORK must be at least N*N. note that for COMPZ = 'V', then if N is less than or equal to the minimum divide size, usually 25, then LWORK need only be 1.

if LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA.

`RWORK`

RWORK is REAL array, dimension (MAX(1,LRWORK)). on exit, if INFO = 0, RWORK(1) returns the optimal LRWORK.

`LRWORK`

LRWORK is INTEGER. it's the dimension of the array RWORK. if COMPZ = 'N' or N <= 1, LRWORK must be at least 1. if COMPZ = 'V' and N > 1, LRWORK must be at least 1 + 3*N + 2*N*lg N + 4*N**2, where lg( N ) = smallest integer k such that 2**k >= N. if COMPZ = 'I' and N > 1, LRWORK must be at least 1 + 4*N + 2*N**2. note that for COMPZ = 'I' or 'V', then if N is less than or equal to the minimum divide size, usually 25, then LRWORK need only be max(1,2*(N-1)).

if LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA.

`IWORK`

IWORK is INTEGER array, dimension (MAX(1,LIWORK)). on exit, if INFO = 0, IWORK(1) returns the optimal LIWORK.

`LIWORK`

LIWORK is INTEGER — it's literally the dimension of the array IWORK, bestie.

If COMPZ = 'N' or N <= 1, LIWORK must be at least 1.
If COMPZ = 'V' or N > 1, LIWORK must be at least 6 + 6*N + 5*N*lg N.
If COMPZ = 'I' or N > 1, LIWORK must be at least 3 + 5*N.

Note that for COMPZ = 'I' or 'V', then if N is less than or equal to the minimum divide size, usually 25, then LIWORK need only be 1.

If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. no yelling from XERBLA, we love that for us 💅

`INFO`

INFO is INTEGER

= 0: successful exit. slay ✨
< 0: if INFO = -i, the i-th argument had an illegal value. oops, bad argument energy 💀
> 0: The algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and columns INFO/(N+1) through mod(INFO,N+1). it tried and it did NOT succeed 😭

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🫶 Contributors:

Jeff Rutter, Computer Science Division, University of California at Berkeley, USA

✨ subroutine `cstegr` ✨

subroutine cstegr (character JOBZ, character RANGE, integer N, real,
    dimension( * ) D, real, dimension( * ) E, real VL, real VU, integer IL,
    integer IU, real ABSTOL, integer M, real, dimension( * ) W, complex,
    dimension( ldz, * ) Z, integer LDZ, integer, dimension( * ) ISUPPZ,
    real, dimension( * ) WORK, integer LWORK, integer, dimension( * ) IWORK,
    integer LIWORK, integer INFO)

CSTEGR ✨

🌸 Purpose

CSTEGR computes selected eigenvalues and, optionally, eigenvectors of a real symmetric tridiagonal matrix T. Any such unreduced matrix has a well defined set of pairwise different real eigenvalues, the corresponding real eigenvectors are pairwise orthogonal. math is so real for that tbh

The spectrum may be computed either completely or partially by specifying either an interval (VL,VU] or a range of indices IL:IU for the desired eigenvalues.

CSTEGR is a compatibility wrapper around the improved CSTEMR routine. See SSTEMR for further details.

One important change is that the ABSTOL parameter no longer provides any benefit and hence is no longer used. it's giving retired icon 🫡

Note : CSTEGR and CSTEMR work only on machines which follow IEEE-754 floating-point standard in their handling of infinities and NaNs. Normal execution may create these exceptiona values and hence may abort due to a floating point exception in environments which do not conform to the IEEE-754 standard. not the exceptiona values catching strays 😭

🎀 Parameters

JOBZ — JOBZ is CHARACTER*1
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
RANGE — RANGE is CHARACTER*1
- = 'A': all eigenvalues will be found.
- = 'V': all eigenvalues in the half-open interval (VL,VU] will be found.
- = 'I': the IL-th through IU-th eigenvalues will be found.
N — N is INTEGER. The order of the matrix. N >= 0.
D — D is REAL array, dimension (N). On entry, the N diagonal elements of the tridiagonal matrix T. On exit, D is overwritten. bye bye original data, we hardly knew ye
E — E is REAL array, dimension (N). On entry, the (N-1) subdiagonal elements of the tridiagonal matrix T in elements 1 to N-1 of E. E(N) need not be set on input, but is used internally as workspace. On exit, E is overwritten.
VL — VL is REAL. If RANGE='V', the lower bound of the interval to be searched for eigenvalues. VL < VU. Not referenced if RANGE = 'A' or 'I'. she's only invited to the 'V' party 💅
VU — VU is REAL. If RANGE='V', the upper bound of the interval to be searched for eigenvalues. VL < VU. Not referenced if RANGE = 'A' or 'I'.
IL — IL is INTEGER. If RANGE='I', the index of the smallest eigenvalue to be returned. 1 <= IL <= IU <= N, if N > 0. Not referenced if RANGE = 'A' or 'V'.
IU — IU is INTEGER. If RANGE='I', the index of the largest eigenvalue to be returned. 1 <= IL <= IU <= N, if N > 0. Not referenced if RANGE = 'A' or 'V'.
ABSTOL — ABSTOL is REAL. Unused. Was the absolute error tolerance for the eigenvalues/eigenvectors in previous versions. glow-up so hard she got benched fr 🙈
M — M is INTEGER. The total number of eigenvalues found. 0 <= M <= N. If RANGE = 'A', M = N, and if RANGE = 'I', M = IU-IL+1.
W — W is REAL array, dimension (N). The first M elements contain the selected eigenvalues in ascending order. sorted, organized, main character behavior 👑
Z — Z is COMPLEX array, dimension (LDZ, max(1,M) ). If JOBZ = 'V', and if INFO = 0, then the first M columns of Z contain the orthonormal eigenvectors of the matrix T corresponding to the selected eigenvalues, with the i-th column of Z holding the eigenvector associated with W(i). If JOBZ = 'N', then Z is not referenced. Note: the user must ensure that at least max(1,M) columns are supplied in the array Z; if RANGE = 'V', the exact value of M is not known in advance and an upper bound must be used. Supplying N columns is always safe. when in doubt, give her all the columns 💅
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', then LDZ >= max(1,N).
ISUPPZ — ISUPPZ is INTEGER array, dimension ( 2*max(1,M) ). The support of the eigenvectors in Z, i.e., the indices indicating the nonzero elements in Z. The i-th computed eigenvector is nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ). This is relevant in the case when the matrix is split. ISUPPZ is only accessed when JOBZ is 'V' and N > 0. she only shows up when the vibes are right
WORK — WORK is REAL array, dimension (LWORK). On exit, if INFO = 0, WORK(1) returns the optimal (and minimal) LWORK. peek the first slot for the tea ☕
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= max(1,18*N) if JOBZ = 'V', and LWORK >= max(1,12*N) if JOBZ = 'N'. 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 — IWORK is INTEGER array, dimension (LIWORK). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK.
LIWORK — LIWORK is INTEGER. The dimension of the array IWORK. LIWORK >= max(1,10*N) if the eigenvectors are desired, and LIWORK >= max(1,8*N) if only the eigenvalues are to be computed. If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA.
INFO — INFO is INTEGER. On exit, INFO
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = 1X, internal error in SLARRE, if INFO = 2X, internal error in CLARRV. Here, the digit X = ABS( IINFO ) < 10, where IINFO is the nonzero error code returned by SLARRE or CLARRV, respectively. internal drama, do not perceive 🫣

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🫶 Contributors:

Inderjit Dhillon, IBM Almaden, USA Osni Marques, LBNL/NERSC, USA Christof Voemel, LBNL/NERSC, USA

✨ subroutine `cstein` ✨

subroutine cstein (integer N, real, dimension( * ) D, real, dimension( * )
    E, integer M, real, dimension( * ) W, integer, dimension( * ) IBLOCK,
    integer, dimension( * ) ISPLIT, complex, dimension( ldz, * ) Z, integer
    LDZ, real, dimension( * ) WORK, integer, dimension( * ) IWORK, integer,
    dimension( * ) IFAIL, integer INFO)

CSTEIN

🌸 Purpose

CSTEIN computes the eigenvectors of a real symmetric tridiagonal matrix T corresponding to specified eigenvalues, using inverse iteration. inverse iteration ate and left no crumbs 💅

The maximum number of iterations allowed for each eigenvector is specified by an internal parameter MAXITS (currently set to 5). five tries and then we're done, no cap

Although the eigenvectors are real, they are stored in a complex array, which may be passed to CUNMTR or CUPMTR for back transformation to the eigenvectors of a complex Hermitian matrix which was reduced to tridiagonal form. real math in a complex fit, iconic honestly ✨

🎀 Parameters

N — N is INTEGER. The order of the matrix. N >= 0.
D — D is REAL array, dimension (N). The n diagonal elements of the tridiagonal matrix T.
E — E is REAL array, dimension (N-1). The (n-1) subdiagonal elements of the tridiagonal matrix T, stored in elements 1 to N-1.
M — M is INTEGER. The number of eigenvectors to be found. 0 <= M <= N.
W — W is REAL array, dimension (N). The first M elements of W contain the eigenvalues for which eigenvectors are to be computed. The eigenvalues should be grouped by split-off block and ordered from smallest to largest within the block. ( The output array W from SSTEBZ with ORDER = 'B' is expected here. ) so hand her the SSTEBZ output, she's expecting it specifically
IBLOCK
IBLOCK — IBLOCK is INTEGER array, dimension (N).
- It's the submatrix index situation 💫 — it tells you which block each eigenvalue in W actually belongs to. So IBLOCK(i)=1 if eigenvalue W(i) belongs to the first submatrix from the top, =2 if W(i) belongs to the second submatrix, etc.
- (The output array IBLOCK from SSTEBZ is expected here.)
ISPLIT — ISPLIT is INTEGER array, dimension (N).
- The splitting points, at which T breaks up into submatrices. Slay, the matrix gets chopped.
- The first submatrix consists of rows/columns 1 to ISPLIT( 1 ), the second of rows/columns ISPLIT( 1 )+1 through ISPLIT( 2 ), etc.
- (The output array ISPLIT from SSTEBZ is expected here.)
Z — Z is COMPLEX array, dimension (LDZ, M).
- The computed eigenvectors, periodt. The eigenvector associated with the eigenvalue W(i) is stored in the i-th column of Z.
- Any vector which fails to converge is set to its current iterate after MAXITS iterations.
- The imaginary parts of the eigenvectors are set to zero.
LDZ — LDZ is INTEGER. It's the leading dimension of the array Z. LDZ >= max(1,N).
WORK — WORK is REAL array, dimension (5*N). Just vibing, holding scratch space. 🫶
IWORK — IWORK is INTEGER array, dimension (N). Same energy, integer edition.
IFAIL — IFAIL is INTEGER array, dimension (M).
- On normal exit, all elements of IFAIL are zero. ✨
- If one or more eigenvectors fail to converge after MAXITS iterations, then their indices are stored in array IFAIL. Not the glow-up we wanted, but at least you know which ones flopped. 😭
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, then i eigenvectors failed to converge in MAXITS iterations. Their indices are stored in array IFAIL.

Internal Parameters 💅

MAXITS — INTEGER, default = 5. The maximum number of iterations performed. That's it, that's the whole budget.
EXTRA — INTEGER, default = 2. The number of iterations performed after norm growth criterion is satisfied, should be at least 1.

Author 👑

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

`subroutine cstemr` 🦋

subroutine cstemr (character JOBZ, character RANGE, integer N, real,
    dimension( * ) D, real, dimension( * ) E, real VL, real VU, integer IL,
    integer IU, integer M, real, dimension( * ) W, complex, dimension( ldz,
    * ) Z, integer LDZ, integer NZC, integer, dimension( * ) ISUPPZ, logical
    TRYRAC, real, dimension( * ) WORK, integer LWORK, integer, dimension( *
    ) IWORK, integer LIWORK, integer INFO)

CSTEMR

Purpose:

CSTEMR computes selected eigenvalues and, optionally, eigenvectors of a real symmetric tridiagonal matrix T. Bestie, any such unreduced matrix has a well defined set of pairwise different real eigenvalues, and the corresponding real eigenvectors are pairwise orthogonal. It's giving immaculate structure. ✨

The spectrum may be computed either completely or partially by specifying either an interval (VL,VU] or a range of indices IL:IU for the desired eigenvalues.

Depending on the number of desired eigenvalues, these are computed either by bisection or the dqds algorithm. Numerically orthogonal eigenvectors are computed by the use of various suitable L D L^T factorizations near clusters of close eigenvalues (referred to as RRRs, Relatively Robust Representations — yes the acronym is iconic, no cap). An informal sketch of the algorithm follows. 🧚

For each unreduced block (submatrix) of T,

(a) Compute T - sigma I = L D L^T, so that L and D define all the wanted eigenvalues to high relative accuracy. This means that small relative changes in the entries of D and L cause only small relative changes in the eigenvalues and eigenvectors. The standard (unfactored) representation of the tridiagonal matrix T does not have this property in general.
(b) Compute the eigenvalues to suitable accuracy. If the eigenvectors are desired, the algorithm attains full accuracy of the computed eigenvalues only right before the corresponding vectors have to be computed, see steps c) and d).
(c) For each cluster of close eigenvalues, select a new shift close to the cluster, find a new factorization, and refine the shifted eigenvalues to suitable accuracy.
(d) For each eigenvalue with a large enough relative separation compute the corresponding eigenvector by forming a rank revealing twisted factorization. Go back to (c) for any clusters that remain.

For more details, see:

Inderjit S. Dhillon and Beresford N. Parlett: 'Multiple representations to compute orthogonal eigenvectors of symmetric tridiagonal matrices,' Linear Algebra and its Applications, 387(1), pp. 1-28, August 2004.
Inderjit Dhillon and Beresford Parlett: 'Orthogonal Eigenvectors and Relative Gaps,' SIAM Journal on Matrix Analysis and Applications, Vol. 25, 2004. Also LAPACK Working Note 154.
Inderjit Dhillon: 'A new O(n^2) algorithm for the symmetric tridiagonal eigenvalue/eigenvector problem', Computer Science Division Technical Report No. UCB/CSD-97-971, UC Berkeley, May 1997.

Further Details

CSTEMR works only on machines which follow IEEE-754 floating-point standard in their handling of infinities and NaNs. This permits the use of efficient inner loops avoiding a check for zero divisors.
LAPACK routines can be used to reduce a complex Hermitean matrix to real symmetric tridiagonal form.

(Any complex Hermitean tridiagonal matrix has real values on its diagonal and potentially complex numbers on its off-diagonals. By applying a similarity transform with an appropriate diagonal matrix diag(1,e^{i \phy_1}, ... , e^{i \phy_{n-1}}), the complex Hermitean matrix can be transformed into a real symmetric matrix and complex arithmetic can be entirely avoided.)

While the eigenvectors of the real symmetric tridiagonal matrix are real, the eigenvectors of original complex Hermitean matrix have complex entries in general.

Since LAPACK drivers overwrite the matrix data with the eigenvectors, CSTEMR accepts complex workspace to facilitate interoperability with CUNMTR or CUPMTR.

Parameters

JOBZ — JOBZ is CHARACTER*1
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
RANGE — RANGE is CHARACTER*1
- = 'A': all eigenvalues will be found.
- = 'V': all eigenvalues in the half-open interval (VL,VU] will be found.
- = 'I': the IL-th through IU-th eigenvalues will be found.
N — N is INTEGER. The order of the matrix. N >= 0.
D — D is REAL array, dimension (N).
- On entry, the N diagonal elements of the tridiagonal matrix T.
- On exit, D is overwritten. 🙈
E — E is REAL array, dimension (N).
- On entry, the (N-1) subdiagonal elements of the tridiagonal matrix T in elements 1 to N-1 of E. E(N) need not be set on input, but is used internally as workspace.
- On exit, E is overwritten.
VL — VL is REAL.
- If RANGE='V', the lower bound of the interval to be searched for eigenvalues. VL < VU.
- Not referenced if RANGE = 'A' or 'I'.
VU — VU is REAL.
- If RANGE='V', the upper bound of the interval to be searched for eigenvalues. VL < VU.
- Not referenced if RANGE = 'A' or 'I'.
IL — IL is INTEGER.
- If RANGE='I', the index of the smallest eigenvalue to be returned. 1 <= IL <= IU <= N, if N > 0.
- Not referenced if RANGE = 'A' or 'V'.
IU — IU is INTEGER.
- If RANGE='I', the index of the largest eigenvalue to be returned. 1 <= IL <= IU <= N, if N > 0.
- Not referenced if RANGE = 'A' or 'V'.
M — M is INTEGER. The total number of eigenvalues found. 0 <= M <= N. If RANGE = 'A', M = N, and if RANGE = 'I', M = IU-IL+1.
W — W is REAL array, dimension (N). The first M elements contain the selected eigenvalues in ascending order. Sorted, as they should be. 👑
Z — Z is COMPLEX array, dimension (LDZ, max(1,M) ).
- If JOBZ = 'V', and if INFO = 0, then the first M columns of Z contain the orthonormal eigenvectors of the matrix T corresponding to the selected eigenvalues, with the i-th column of Z holding the eigenvector associated with W(i).
- If JOBZ = 'N', then Z is not referenced.
- Note: the user must ensure that at least max(1,M) columns are supplied in the array Z; if RANGE = 'V', the exact value of M is not known in advance and can be computed with a workspace query by setting NZC = -1, see below.
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', then LDZ >= max(1,N).
NZC — NZC is INTEGER. The number of eigenvectors to be held in the array Z.
- If RANGE = 'A', then NZC >= max(1,N).
- If RANGE = 'V', then NZC >= the number of eigenvalues in (VL,VU].
- If RANGE = 'I', then NZC >= IU-IL+1.
- If NZC = -1, then a workspace query is assumed; the routine calculates the number of columns of the array Z that are needed to hold the eigenvectors. This value is returned as the first entry of the Z array, and no error message related to NZC is issued by XERBLA.
ISUPPZ — okay bestie, this is an INTEGER array, dimension ( 2*max(1,M) ). It's the support of the eigenvectors in Z, aka the indices that show which elements in Z are nonzero. The i-th computed eigenvector is nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ). This matters when the matrix is split. Heads up: ISUPPZ is only accessed when JOBZ is 'V' and N > 0.
TRYRAC — TRYRAC is LOGICAL. If TRYRAC = .TRUE., it means the code should check whether the tridiagonal matrix defines its eigenvalues to high relative accuracy. If it does, the code uses relative-accuracy preserving algorithms that might be (a bit) slower depending on the matrix. If the matrix does not define its eigenvalues to high relative accuracy, the code can use possibly faster algorithms. If TRYRAC = .FALSE., the code is not required to guarantee relatively accurate eigenvalues and can use the fastest possible techniques. On exit, a .TRUE. TRYRAC will be set to .FALSE. if the matrix does not define its eigenvalues to high relative accuracy.
WORK — WORK is REAL array, dimension (LWORK). On exit, if INFO = 0, WORK(1) returns the optimal (and minimal) LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= max(1,18*N) if JOBZ = 'V', and LWORK >= max(1,12*N) if JOBZ = 'N'. 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 — IWORK is INTEGER array, dimension (LIWORK). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK.
LIWORK — LIWORK is INTEGER. The dimension of the array IWORK. LIWORK >= max(1,10*N) if the eigenvectors are desired, and LIWORK >= max(1,8*N) if only the eigenvalues are to be computed. If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA.
INFO — INFO is INTEGER. On exit, INFO:
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = 1X, internal error in SLARRE, if INFO = 2X, internal error in CLARRV. Here, the digit X = ABS( IINFO ) < 10, where IINFO is the nonzero error code returned by SLARRE or CLARRV, respectively.

🌟 Author 🌟

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💖 Contributors: 💖

Beresford Parlett, University of California, Berkeley, USA Jim Demmel, University of California, Berkeley, USA Inderjit Dhillon, University of Texas, Austin, USA Osni Marques, LBNL/NERSC, USA Christof Voemel, University of California, Berkeley, USA

✨ subroutine csteqr ✨

   subroutine csteqr (character COMPZ, integer N, real, dimension( * ) D, real,
       dimension( * ) E, complex, dimension( ldz, * ) Z, integer LDZ, real,
       dimension( * ) WORK, integer INFO)

CSTEQR

🎯 Purpose:

CSTEQR computes all eigenvalues and, optionally, eigenvectors of a symmetric tridiagonal matrix using the implicit QL or QR method. The eigenvectors of a full or band complex Hermitian matrix can also be found if CHETRD or CHPTRD or CHBTRD has been used to reduce this matrix to tridiagonal form.

🎀 Parameters

COMPZ — COMPZ is CHARACTER*1
- = 'N': Compute eigenvalues only.
- = 'V': Compute eigenvalues and eigenvectors of the original Hermitian matrix. On entry, Z must contain the unitary matrix used to reduce the original matrix to tridiagonal form.
- = 'I': Compute eigenvalues and eigenvectors of the tridiagonal matrix. Z is initialized to the identity matrix.
N — N is INTEGER. The order of the matrix. N >= 0.
D — D is REAL array, dimension (N). On entry, the diagonal elements of the tridiagonal matrix. On exit, if INFO = 0, the eigenvalues in ascending order.
E — E is REAL array, dimension (N-1). On entry, the (n-1) subdiagonal elements of the tridiagonal matrix. On exit, E has been destroyed.
Z — Z is COMPLEX array, dimension (LDZ, N). On entry, if COMPZ = 'V', then Z contains the unitary matrix used in the reduction to tridiagonal form. On exit, if INFO = 0, then if COMPZ = 'V', Z contains the orthonormal eigenvectors of the original Hermitian matrix, and if COMPZ = 'I', Z contains the orthonormal eigenvectors of the symmetric tridiagonal matrix. If COMPZ = 'N', then Z is not referenced.
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= 1, and if eigenvectors are desired, then LDZ >= max(1,N).
WORK — WORK is REAL array, dimension (max(1,2*N-2)). If COMPZ = 'N', then WORK is not referenced.
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: the algorithm has failed to find all the eigenvalues in a total of 30*N iterations; if INFO = i, then i elements of E have not converged to zero; on exit, D and E contain the elements of a symmetric tridiagonal matrix which is unitarily similar to the original matrix.

🌟 Author 🌟

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine ctbcon 🌸

   subroutine ctbcon (character NORM, character UPLO, character DIAG, integer
       N, integer KD, complex, dimension( ldab, * ) AB, integer LDAB, real
       RCOND, complex, dimension( * ) WORK, real, dimension( * ) RWORK, integer
       INFO)

CTBCON

🎯 Purpose:

CTBCON estimates the reciprocal of the condition number of a triangular band matrix A, in either the 1-norm or the infinity-norm.

The norm of A is computed and an estimate is obtained for norm(inv(A)), then the reciprocal of the condition number is computed as

RCOND = 1 / ( norm(A) * norm(inv(A)) ).

🎀 Parameters

NORM — NORM is CHARACTER*1. Specifies whether the 1-norm condition number or the infinity-norm condition number is required:
- = '1' or 'O': 1-norm;
- = 'I': Infinity-norm.
UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — DIAG is CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
KD — KD is INTEGER. The number of superdiagonals or subdiagonals of the triangular band matrix A. KD >= 0.
AB — AB is COMPLEX array, dimension (LDAB,N). The upper or lower triangular band matrix A, stored in the first kd+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd). If DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1.
LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
RCOND — RCOND is REAL. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(norm(A) * norm(inv(A))).
WORK — WORK is COMPLEX array, dimension (2*N)
RWORK — RWORK is REAL array, dimension (N)
INFO — INFO is 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.

💜 subroutine ctbrfs 💜

   subroutine ctbrfs (character UPLO, character TRANS, character DIAG, integer
       N, integer KD, integer NRHS, complex, dimension( ldab, * ) AB, integer
       LDAB, complex, dimension( ldb, * ) B, integer LDB, complex, dimension(
       ldx, * ) X, integer LDX, real, dimension( * ) FERR, real, dimension( * )
       BERR, complex, dimension( * ) WORK, real, dimension( * ) RWORK, integer
       INFO)

CTBRFS

🎯 Purpose:

CTBRFS provides error bounds and backward error estimates for the solution to a system of linear equations with a triangular band coefficient matrix.

The solution matrix X must be computed by CTBTRS or some other means before entering this routine. CTBRFS does not do iterative refinement because doing so cannot improve the backward error.

🎀 Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1. Specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — DIAG is CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
KD
KD — INTEGER, bestie. It's the number of superdiagonals or subdiagonals of the triangular band matrix A. Constraint: KD >= 0. 💅
NRHS — INTEGER. The number of right hand sides, aka the number of columns of the matrices B and X. Constraint: NRHS >= 0. slay.
AB — COMPLEX array, dimension (LDAB,N). This is the upper or lower triangular band matrix A, stored in the first kd+1 rows of the array. The j-th column of A lives in the j-th column of the array AB like so:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

And listen — if DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1. iconic behavior honestly.

LDAB — INTEGER. The leading dimension of the array AB. Constraint: LDAB >= KD+1.
B — COMPLEX array, dimension (LDB,NRHS). The right hand side matrix B. periodt.
LDB — INTEGER. The leading dimension of the array B. Constraint: LDB >= max(1,N).
X — COMPLEX array, dimension (LDX,NRHS). The solution matrix X. 🎀
LDX — INTEGER. The leading dimension of the array X. Constraint: LDX >= max(1,N).
FERR — REAL array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), then FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and it is almost always a slight overestimate of the true error. ngl that's pretty trustworthy.
BERR — REAL array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution). 💀
WORK — COMPLEX array, dimension (2*N)
RWORK — REAL array, dimension (N)
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.

🦋 subroutine ctbtrs 🦋

subroutine ctbtrs (character UPLO, character TRANS, character DIAG, integer
    N, integer KD, integer NRHS, complex, dimension( ldab, * ) AB, integer
    LDAB, complex, dimension( ldb, * ) B, integer LDB, integer INFO)

CTBTRS — okay so this one solves stuff, hold on.

✨ Purpose ✨

CTBTRS solves a triangular system of the form

A * X = B,  A**T * X = B,  or  A**H * X = B,

where A is a triangular band matrix of order N, and B is an N-by-NRHS matrix. A check is made to verify that A is nonsingular. (yes bestie, it's checking the vibes to make sure nothing's degenerate 💅)

🌸 Parameters 🌸

UPLO — CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — CHARACTER*1. Specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — INTEGER. The order of the matrix A. Constraint: N >= 0.
KD — INTEGER. The number of superdiagonals or subdiagonals of the triangular band matrix A. Constraint: KD >= 0.
NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. Constraint: NRHS >= 0.
AB — COMPLEX array, dimension (LDAB,N). The upper or lower triangular band matrix A, stored in the first kd+1 rows of AB. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

If DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1.

LDAB — INTEGER. The leading dimension of the array AB. Constraint: LDAB >= KD+1.
B — COMPLEX array, dimension (LDB,NRHS).
- On entry, the right hand side matrix B.
- On exit, if INFO = 0, the solution matrix X.
LDB — INTEGER. The leading dimension of the array B. Constraint: LDB >= max(1,N).
INFO — INTEGER
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🙈
- > 0: if INFO = i, the i-th diagonal element of A is zero, indicating that the matrix is singular and the solutions X have not been computed. bestie the math said no 😭

👑 Author 👑

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

🧚 subroutine ctfsm 🧚

subroutine ctfsm (character TRANSR, character SIDE, character UPLO,
    character TRANS, character DIAG, integer M, integer N, complex ALPHA,
    complex, dimension( 0: * ) A, complex, dimension( 0: ldb-1, 0: * ) B,
    integer LDB)

CTFSM solves a matrix equation (one operand is a triangular matrix in RFP format). ok this one is fancy, stay with me 🫶

✨ Purpose ✨

Level 3 BLAS like routine for A in RFP Format.

CTFSM solves the matrix equation

op( A )*X = alpha*B  or  X*op( A ) = alpha*B

where alpha is a scalar, X and B are m by n matrices, A is a unit, or non-unit, upper or lower triangular matrix and op( A ) is one of

op( A ) = A   or   op( A ) = A**H.

A is in Rectangular Full Packed (RFP) Format.

The matrix X is overwritten on B. (no copy, just vibes on top of vibes ✨)

🌸 Parameters 🌸

TRANSR — CHARACTER*1
- = 'N': The Normal Form of RFP A is stored;
- = 'C': The Conjugate-transpose Form of RFP A is stored.
SIDE — CHARACTER*1. On entry, SIDE specifies whether op( A ) appears on the left or right of X as follows:
- SIDE = 'L' or 'l' → op( A )*X = alpha*B.
- SIDE = 'R' or 'r' → X*op( A ) = alpha*B.

Unchanged on exit.

UPLO — CHARACTER*1. On entry, UPLO specifies whether the RFP matrix A came from an upper or lower triangular matrix as follows:
- UPLO = 'U' or 'u' → RFP A came from an upper triangular matrix
- UPLO = 'L' or 'l' → RFP A came from a lower triangular matrix

Unchanged on exit.

TRANS — CHARACTER*1. On entry, TRANS specifies the form of op( A ) to be used in the matrix multiplication as follows:
- TRANS = 'N' or 'n' → op( A ) = A.
- TRANS = 'C' or 'c' → op( A ) = conjg( A' ).

Unchanged on exit.

DIAG — CHARACTER*1. On entry, DIAG specifies whether or not RFP A is unit triangular as follows:
- DIAG = 'U' or 'u' → A is assumed to be unit triangular.
- DIAG = 'N' or 'n' → A is not assumed to be unit triangular.

Unchanged on exit.

M — INTEGER. On entry, M specifies the number of rows of B. M must be at least zero. Unchanged on exit.
N — INTEGER. On entry, N specifies the number of columns of B. N must be at least zero. Unchanged on exit.
ALPHA — COMPLEX. On entry, ALPHA specifies the scalar alpha. When alpha is zero then A is not referenced and B need not be set before entry. Unchanged on exit.
A — COMPLEX array, dimension (N*(N+1)/2). NT = N*(N+1)/2. On entry, the matrix A in RFP Format. RFP Format is described by TRANSR, UPLO and N as follows: If TRANSR='N' then RFP A is (0:N,0:K-1) when N is even; K=N/2. RFP A is (0:N-1,0:K) when N is odd; K=N/2. If TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: If UPLO = 'U' the RFP A contains the NT elements of upper packed A either in normal or conjugate-transpose Format. If UPLO = 'L' the RFP A contains the NT elements of lower packed A either in normal or conjugate-transpose Format. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and is N when is odd. See the Note below for more details. Unchanged on exit. (yes that's a lot of words, but bestie every one of them matters 💅)
B — COMPLEX array, dimension (LDB,N). Before entry, the leading m by n part of the array B must contain the right-hand side matrix B, and on exit is overwritten by the solution matrix X.
LDB — INTEGER. On entry, LDB specifies the first dimension of B as declared in the calling (sub) program. LDB must be at least max( 1, m ). Unchanged on exit.

👑 Author 👑

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

🌈 Further Details 🌈

We first consider Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

okay so let's keep it moving with the RFP layout when N is even. We're using N = 6 as the moment:

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

🌟 subroutine ctftri 🌟

subroutine ctftri (character TRANSR, character UPLO, character DIAG, integer
    N, complex, dimension( 0: * ) A, integer INFO)

✨ CTFTRI ✨

Purpose

CTFTRI computes the inverse of a triangular matrix A stored in RFP format. This is a Level 3 BLAS version of the algorithm.

Parameters

TRANSR — TRANSR is CHARACTER*1
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'C': The Conjugate-transpose TRANSR of RFP A is stored.
UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — DIAG is CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER
- The order of the matrix A. N >= 0.
A — A is COMPLEX array, dimension ( N*(N+1)/2 );
- On entry, the triangular matrix A in RFP format. RFP format is described by TRANSR, UPLO, and N as follows: If TRANSR = 'N' then RFP A is (0:N,0:k-1) when N is even; k=N/2. RFP A is (0:N-1,0:k) when N is odd; k=N/2. IF TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: If UPLO = 'U' the RFP A contains the nt elements of upper packed A; If UPLO = 'L' the RFP A contains the nt elements of lower packed A. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and N is odd. See the Note below for more details.
- On exit, the (triangular) inverse of the original matrix, in the same storage format.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, A(i,i) is exactly zero. The triangular matrix is singular and its inverse can not be computed.

Author

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

Further Details

We first consider Standard Packed Format when N is even. We give an example where N = 6.

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

🦋 subroutine ctfttp 🦋

subroutine ctfttp (character TRANSR, character UPLO, integer N, complex,
    dimension( 0: * ) ARF, complex, dimension( 0: * ) AP, integer INFO)

✨ CTFTTP ✨

CTFTTP copies a triangular matrix from the rectangular full packed format (TF) to the standard packed format (TP).

Purpose

CTFTTP copies a triangular matrix A from rectangular full packed format (TF) to standard packed format (TP).

Parameters

TRANSR — TRANSR is CHARACTER*1
- = 'N': ARF is in Normal format;
- = 'C': ARF is in Conjugate-transpose format;
UPLO —
UPLO is CHARACTER*1 💖
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N is INTEGER
- bestie this is just the order of the matrix A. And like, N >= 0. that's the vibe check. ✨
ARF is COMPLEX array, dimension ( N*(N+1)/2 )
- On entry, the upper or lower triangular matrix A stored in RFP format. For a further discussion see Notes below. (yes bestie, the Notes. we're getting there. 🦋)
AP is COMPLEX array, dimension ( N*(N+1)/2 )
- On exit, the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
  - if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
  - if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
INFO is 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: 🌈

okay so first we consider Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

 00 01 02 03 04 05       00
    11 12 13 14 15       10 11
       22 23 24 25       20 21 22
          33 34 35       30 31 32 33
             44 45       40 41 42 43 44
                55       50 51 52 53 54 55

       RFP A                   RFP A

                              -- -- --
      03 04 05                33 43 53
                                 -- --
      13 14 15                00 44 54
                                    --
      23 24 25                10 11 55

      33 34 35                20 21 22
      --
      00 44 45                30 31 32
      -- --
      01 11 55                40 41 42
      -- -- --
      02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

         RFP A                   RFP A

   -- -- -- --                -- -- -- -- -- --
   03 13 23 33 00 01 02    33 00 10 20 30 40 50
   -- -- -- -- --                -- -- -- -- --
   04 14 24 34 44 11 12    43 44 11 21 31 41 51
   -- -- -- -- -- --                -- -- -- --
   05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

   AP is Upper                 AP is Lower

 00 01 02 03 04              00
    11 12 13 14              10 11
       22 23 24              20 21 22
          33 34              30 31 32 33
             44              40 41 42 43 44

       RFP A                   RFP A

                                 -- --
      02 03 04                00 33 43
                                    --
      12 13 14                10 11 44

      22 23 24                20 21 22
      --
      00 33 34                30 31 32
      -- --
      01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

🎀 `ctfttr` 🎀

subroutine ctfttr (character TRANSR, character UPLO, integer N, complex,
    dimension( 0: * ) ARF, complex, dimension( 0: lda-1, 0: * ) A, integer
    LDA, integer INFO)

CTFTTR copies a triangular matrix from the rectangular full packed format (TF) to the standard full format (TR). 💅

✨ Purpose: ✨

CTFTTR copies a triangular matrix A from rectangular full packed format (TF) to standard full format (TR). no cap. 🫶

🌸 Parameters 🌸

TRANSR is CHARACTER*1
- = 'N': ARF is in Normal format;
- = 'C': ARF is in Conjugate-transpose format;
UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N is INTEGER
- The order of the matrix A. N >= 0.
ARF is COMPLEX array, dimension ( N*(N+1)/2 )
- On entry, the upper or lower triangular matrix A stored in RFP format. For a further discussion see Notes below.
A is COMPLEX array, dimension ( LDA, N )
- On exit, the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced.
LDA is INTEGER
- The leading dimension of the array A. LDA >= max(1,N). 👑
INFO is 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: 🌈

We first consider Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

 00 01 02 03 04 05       00
    11 12 13 14 15       10 11
       22 23 24 25       20 21 22
          33 34 35       30 31 32 33
             44 45       40 41 42 43 44
                55       50 51 52 53 54 55

       RFP A                   RFP A

                              -- -- --
      03 04 05                33 43 53
                                 -- --
      13 14 15                00 44 54
                                    --
      23 24 25                10 11 55

      33 34 35                20 21 22
      --
      00 44 45                30 31 32
      -- --
      01 11 55                40 41 42
      -- -- --
      02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

         RFP A                   RFP A

   -- -- -- --                -- -- -- -- -- --
   03 13 23 33 00 01 02    33 00 10 20 30 40 50
   -- -- -- -- --                -- -- -- -- --
   04 14 24 34 44 11 12    43 44 11 21 31 41 51
   -- -- -- -- -- --                -- -- -- --
   05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

   AP is Upper                 AP is Lower

 00 01 02 03 04              00
    11 12 13 14              10 11
       22 23 24              20 21 22
          33 34              30 31 32 33
             44              40 41 42 43 44

       RFP A                   RFP A

                                 -- --
      02 03 04                00 33 43
                                    --
      12 13 14                10 11 44

      22 23 24                20 21 22
      --
      00 33 34                30 31 32
      -- --
      01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

   subroutine ctgsen (integer IJOB, logical WANTQ, logical WANTZ, logical,
       dimension( * ) SELECT, integer N, complex, dimension( lda, * ) A,
       integer LDA, complex, dimension( ldb, * ) B, integer LDB, complex,
       dimension( * ) ALPHA, complex, dimension( * ) BETA, complex, dimension(
       ldq, * ) Q, integer LDQ, complex, dimension( ldz, * ) Z, integer LDZ,
       integer M, real PL, real PR, real, dimension( * ) DIF, complex,
       dimension( * ) WORK, integer LWORK, integer, dimension( * ) IWORK,
       integer LIWORK, integer INFO)
       CTGSEN

✨ Purpose ✨

okay so CTGSEN reorders the generalized Schur decomposition of a complex matrix pair (A, B) (in terms of an unitary equivalence transformation Q**H * (A, B) * Z), so that a selected cluster of eigenvalues appears in the leading diagonal blocks of the pair (A,B). The leading columns of Q and Z form unitary bases of the corresponding left and right eigenspaces (deflating subspaces). (A, B) must be in generalized Schur canonical form, that is, A and B are both upper triangular.

CTGSEN also computes the generalized eigenvalues

w(j)= ALPHA(j) / BETA(j)

of the reordered matrix pair (A, B).

Optionally, the routine computes estimates of reciprocal condition numbers for eigenvalues and eigenspaces. These are Difu[(A11,B11), (A22,B22)] and Difl[(A11,B11), (A22,B22)], i.e. the separation(s) between the matrix pairs (A11, B11) and (A22,B22) that correspond to the selected cluster and the eigenvalues outside the cluster, resp., and norms of 'projections' onto left and right eigenspaces w.r.t. the selected cluster in the (1,1)-block.

🌸 Parameters 🌸

IJOB — INTEGER. Specifies whether condition numbers are required for the cluster of eigenvalues (PL and PR) or the deflating subspaces (Difu and Difl):
- =0: Only reorder w.r.t. SELECT. No extras.
- =1: Reciprocal of norms of 'projections' onto left and right eigenspaces w.r.t. the selected cluster (PL and PR).
- =2: Upper bounds on Difu and Difl. F-norm-based estimate (DIF(1:2)).
- =3: Estimate of Difu and Difl. 1-norm-based estimate (DIF(1:2)). About 5 times as expensive as IJOB = 2.
- =4: Compute PL, PR and DIF (i.e. 0, 1 and 2 above): Economic version to get it all.
- =5: Compute PL, PR and DIF (i.e. 0, 1 and 3 above)
WANTQ — LOGICAL. .TRUE. : update the left transformation matrix Q; .FALSE.: do not update Q.
WANTZ — LOGICAL. .TRUE. : update the right transformation matrix Z; .FALSE.: do not update Z.
SELECT — LOGICAL array, dimension (N). SELECT specifies the eigenvalues in the selected cluster. To select an eigenvalue w(j), SELECT(j) must be set to .TRUE..
N — INTEGER. The order of the matrices A and B. N >= 0.
A — COMPLEX array, dimension(LDA,N). On entry, the upper triangular matrix A, in generalized Schur canonical form. On exit, A is overwritten by the reordered matrix A.
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — COMPLEX array, dimension(LDB,N). On entry, the upper triangular matrix B, in generalized Schur canonical form. On exit, B is overwritten by the reordered matrix B.
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
ALPHA — COMPLEX array, dimension (N).
BETA — COMPLEX array, dimension (N). The diagonal elements of A and B, respectively, when the pair (A,B) has been reduced to generalized Schur form. ALPHA(i)/BETA(i) i=1,...,N are the generalized eigenvalues.
Q — COMPLEX array, dimension (LDQ,N). On entry, if WANTQ = .TRUE., Q is an N-by-N matrix. On exit, Q has been postmultiplied by the left unitary transformation matrix which reorder (A, B); The leading M columns of Q form orthonormal bases for the specified pair of left eigenspaces (deflating subspaces). If WANTQ = .FALSE., Q is not referenced.
LDQ — INTEGER. The leading dimension of the array Q. LDQ >= 1. If WANTQ = .TRUE., LDQ >= N.
Z — COMPLEX array, dimension (LDZ,N). On entry, if WANTZ = .TRUE., Z is an N-by-N matrix. On exit, Z has been postmultiplied by the left unitary transformation matrix which reorder (A, B); The leading M columns of Z form orthonormal bases for the specified pair of left eigenspaces (deflating subspaces). If WANTZ = .FALSE., Z is not referenced.
LDZ — INTEGER. The leading dimension of the array Z. LDZ >= 1. If WANTZ = .TRUE., LDZ >= N.
M — INTEGER. The dimension of the specified pair of left and right eigenspaces, (deflating subspaces) 0 <= M <= N.
PL — REAL.
PR — REAL. If IJOB = 1, 4 or 5, PL, PR are lower bounds on the reciprocal of the norm of 'projections' onto left and right eigenspace with respect to the selected cluster. 0 < PL, PR <= 1. If M = 0 or M = N, PL = PR = 1. If IJOB = 0, 2 or 3 PL, PR are not referenced.
DIF — REAL array, dimension (2). If IJOB >= 2, DIF(1:2) store the estimates of Difu and Difl. If IJOB = 2 or 4, DIF(1:2) are F-norm-based upper bounds on Difu and Difl. If IJOB = 3 or 5, DIF(1:2) are 1-norm-based estimates of Difu and Difl, computed using reversed communication with CLACN2. If M = 0 or N, DIF(1:2) = F-norm([A, B]). If IJOB = 0 or 1, DIF is not referenced.
WORK — COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — INTEGER. The dimension of the array WORK. LWORK >= 1. If IJOB = 1, 2 or 4, LWORK >= 2*M*(N-M). If IJOB = 3 or 5, LWORK >= 4*M*(N-M). 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 (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK.
LIWORK — INTEGER. The dimension of the array IWORK. LIWORK >= 1. If IJOB = 1, 2 or 4, LIWORK >= N+2; If IJOB = 3 or 5, LIWORK >= MAX(N+2, 2*M*(N-M)). If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA.
INFO — INTEGER.
- =0: Successful exit.
- <0: If INFO = -i, the i-th argument had an illegal value.
- =1: Reordering of (A, B) failed because the transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is very ill-conditioned. (A, B) may have been partially reordered. If requested, 0 is returned in DIF(*), PL and PR.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 Further Details 🦋

CTGSEN first collects the selected eigenvalues by computing unitary U and W that move them to the top left corner of (A, B). In other words, the selected eigenvalues are the eigenvalues of (A11, B11) in

            U**H*(A, B)*W = (A11 A12) (B11 B12) n1
                            ( 0  A22),( 0  B22) n2
                              n1  n2    n1  n2

where N = n1+n2 and U**H means the conjugate transpose of U. The first n1 columns of U and W span the specified pair of left and right eigenspaces (deflating subspaces) of (A, B).

If (A, B) has been obtained from the generalized real Schur decomposition of a matrix pair (C, D) = Q*(A, B)*Z', then the reordered generalized Schur form of (C, D) is given by

         (C, D) = (Q*U)*(U**H *(A, B)*W)*(Z*W)**H,

and the first n1 columns of Q*U and Z*W span the corresponding deflating subspaces of (C, D) (Q and Z store Q*U and Z*W, resp.).

Note that if the selected eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering.

The reciprocal condition numbers of the left and right eigenspaces spanned by the first n1 columns of U and W (or Q*U and Z*W) may be returned in DIF(1:2), corresponding to Difu and Difl, resp.

The Difu and Difl are defined as:

     Difu[(A11, B11), (A22, B22)] = sigma-min( Zu )
and
     Difl[(A11, B11), (A22, B22)] = Difu[(A22, B22), (A11, B11)],

where sigma-min(Zu) is the smallest singular value of the (2*n1*n2)-by-(2*n1*n2) matrix

     Zu = [ kron(In2, A11)  -kron(A22**H, In1) ]
          [ kron(In2, B11)  -kron(B22**H, In1) ].

Here, Inx is the identity matrix of size nx and A22**H is the conjuguate transpose of A22. kron(X, Y) is the Kronecker product between the matrices X and Y. periodt 💅

When DIF(2) is small, small changes in (A, B) can cause large changes in the deflating subspace. An approximate (asymptotic) bound on the maximum angular error in the computed deflating subspaces is

EPS * norm((A, B)) / DIF(2),

where EPS is the machine precision.

The reciprocal norm of the projectors on the left and right eigenspaces associated with (A11, B11) may be returned in PL and PR. They are computed as follows. First we compute L and R so that P*(A, B)*Q is block diagonal, where

P = ( I -L ) n1           Q = ( I R ) n1
    ( 0  I ) n2    and        ( 0 I ) n2
      n1 n2                    n1 n2

and (L, R) is the solution to the generalized Sylvester equation

A11*R - L*A22 = -A12
B11*R - L*B22 = -B12

Then PL = (F-norm(L)**2+1)**(-1/2) and PR = (F-norm(R)**2+1)**(-1/2). An approximate (asymptotic) bound on the average absolute error of the selected eigenvalues is

EPS * norm((A, B)) / PL.

There are also global error bounds that are valid for perturbations up to a certain restriction: A lower bound (x) on the smallest F-norm(E,F) for which an eigenvalue of (A11, B11) may move and coalesce with an eigenvalue of (A22, B22) under perturbation (E,F), (i.e. (A + E, B + F), is

x = min(Difu,Difl)/((1/(PL*PL)+1/(PR*PR))**(1/2)+2*max(1/PL,1/PR)).

An approximate bound on x can be computed from DIF(1:2), PL and PR.

If y = ( F-norm(E,F) / x) <= 1, the angles between the perturbed (L', R') and unperturbed (L, R) left and right deflating subspaces associated with the selected cluster in the (1,1)-blocks can be bounded as

max-angle(L, L') <= arctan( y * PL / (1 - y * (1 - PL * PL)**(1/2))
max-angle(R, R') <= arctan( y * PR / (1 - y * (1 - PR * PR)**(1/2))

See LAPACK User's Guide section 4.11 or the following references for more information.

Note that if the default method for computing the Frobenius-norm-based estimate DIF is not wanted (see CLATDF), then the parameter IDIFJB (see below) should be changed from 3 to 4 (routine CLATDF (IJOB = 2 will be used)). See CTGSYL for more details.

👑 Contributors: 👑

Shoutout to Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden. icons only 💅

📚 References: 📚

[1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the Generalized Real Schur Form of a Regular Matrix Pair (A, B), in M.S. Moonen et al (eds), Linear Algebra for Large Scale and Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
[2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified Eigenvalues of a Regular Matrix Pair (A, B) and Condition Estimation: Theory, Algorithms and Software, Report UMINF - 94.04, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87. To appear in Numerical Algorithms, 1996.
[3] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software for Solving the Generalized Sylvester Equation and Estimating the Separation between Regular Matrix Pairs, Report UMINF - 93.23, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, December 1993, Revised April 1994, Also as LAPACK working Note 75. To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.

🦋 `subroutine ctgsja` 🦋

   subroutine ctgsja (character JOBU, character JOBV, character JOBQ, integer
       M, integer P, integer N, integer K, integer L, complex, dimension( lda,
       * ) A, integer LDA, complex, dimension( ldb, * ) B, integer LDB, real
       TOLA, real TOLB, real, dimension( * ) ALPHA, real, dimension( * ) BETA,
       complex, dimension( ldu, * ) U, integer LDU, complex, dimension( ldv, *
       ) V, integer LDV, complex, dimension( ldq, * ) Q, integer LDQ, complex,
       dimension( * ) WORK, integer NCYCLE, integer INFO)
       CTGSJA

🎀 Purpose 🎀

CTGSJA computes the generalized singular value decomposition (GSVD) of two complex upper triangular (or trapezoidal) matrices A and B. Slay.

On entry, it is assumed that matrices A and B have the following forms, which may be obtained by the preprocessing subroutine CGGSVP from a general M-by-N matrix A and P-by-N matrix B:

                         N-K-L  K    L
               A =    K ( 0    A12  A13 ) if M-K-L >= 0;
                      L ( 0     0   A23 )
                  M-K-L ( 0     0    0  )

                       N-K-L  K    L
               A =  K ( 0    A12  A13 ) if M-K-L < 0;
                  M-K ( 0     0   A23 )

                       N-K-L  K    L
               B =  L ( 0     0   B13 )
                  P-L ( 0     0    0  )

where the K-by-K matrix A12 and L-by-L matrix B13 are nonsingular upper triangular; A23 is L-by-L upper triangular if M-K-L >= 0, otherwise A23 is (M-K)-by-L upper trapezoidal.

On exit,

                   U**H *A*Q = D1*( 0 R ),    V**H *B*Q = D2*( 0 R ),

where U, V and Q are unitary matrices. R is a nonsingular upper triangular matrix, and D1 and D2 are ``diagonal'' matrices, which are of the following structures:

If M-K-L >= 0,

                                K  L
                   D1 =     K ( I  0 )
                            L ( 0  C )
                        M-K-L ( 0  0 )

                               K  L
                   D2 = L   ( 0  S )
                        P-L ( 0  0 )

                           N-K-L  K    L
              ( 0 R ) = K (  0   R11  R12 ) K
                        L (  0    0   R22 ) L

where

              C = diag( ALPHA(K+1), ... , ALPHA(K+L) ),
              S = diag( BETA(K+1),  ... , BETA(K+L) ),
              C**2 + S**2 = I.

R is stored in A(1:K+L,N-K-L+1:N) on exit.

If M-K-L < 0,

                           K M-K K+L-M
                D1 =   K ( I  0    0   )
                     M-K ( 0  C    0   )

                             K M-K K+L-M
                D2 =   M-K ( 0  S    0   )
                     K+L-M ( 0  0    I   )
                       P-L ( 0  0    0   )

                           N-K-L  K   M-K  K+L-M
            ( 0 R ) =    K ( 0    R11  R12  R13  )
                      M-K ( 0     0   R22  R23  )
                    K+L-M ( 0     0    0   R33  )

where

            C = diag( ALPHA(K+1), ... , ALPHA(M) ),
            S = diag( BETA(K+1),  ... , BETA(M) ),
            C**2 + S**2 = I.

R = ( R11 R12 R13 )
    (  0  R22 R23 )

is stored in A(1:M, N-K-L+1:N) and R33 is stored in B(M-K+1:L,N+M-K-L+1:N) on exit.

The computation of the unitary transformation matrices U, V or Q is optional. These matrices may either be formed explicitly, or they may be postmultiplied into input matrices U1, V1, or Q1.

✨ Parameters ✨

JOBU — JOBU is CHARACTER*1
- = 'U': U must contain a unitary matrix U1 on entry, and the product U1*U is returned;
- = 'I': U is initialized to the unit matrix, and the unitary matrix U is returned;
- = 'N': U is not computed.
JOBV — JOBV is CHARACTER*1
- = 'V': V must contain a unitary matrix V1 on entry, and the product V1*V is returned;
- = 'I': V is initialized to the unit matrix, and the unitary matrix V is returned;
- = 'N': V is not computed.
JOBQ — JOBQ is CHARACTER*1
- = 'Q': Q must contain a unitary matrix Q1 on entry, and the product Q1*Q is returned;
- = 'I': Q is initialized to the unit matrix, and the unitary matrix Q is returned;
- = 'N': Q is not computed.
M — M is INTEGER. The number of rows of the matrix A. M >= 0.
P — P is INTEGER. The number of rows of the matrix B. P >= 0.
N — N is INTEGER. The number of columns of the matrices A and B. N >= 0.
K — K is INTEGER.
L — L is INTEGER. K and L specify the subblocks in the input matrices A and B: A23 = A(K+1:MIN(K+L,M),N-L+1:N) and B13 = B(1:L,,N-L+1:N) of A and B, whose GSVD is going to be computed by CTGSJA. See Further Details.
A — A is COMPLEX array, dimension (LDA,N). On entry, the M-by-N matrix A. On exit, A(N-K+1:N,1:MIN(K+L,M) ) contains the triangular matrix R or part of R. See Purpose for details.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
B — B is COMPLEX array, dimension (LDB,N). On entry, the P-by-N matrix B. On exit, if necessary, B(M-K+1:L,N+M-K-L+1:N) contains a part of R. See Purpose for details.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,P).
TOLA — TOLA is REAL.
TOLB — TOLB is REAL. TOLA and TOLB are the convergence criteria for the Jacobi-Kogbetliantz iteration procedure. Generally, they are the same as used in the preprocessing step, say TOLA = MAX(M,N)*norm(A)*MACHEPS, TOLB = MAX(P,N)*norm(B)*MACHEPS.
ALPHA — ALPHA is REAL array, dimension (N).
BETA — BETA is REAL array, dimension (N). On exit, ALPHA and BETA contain the generalized singular value pairs of A and B; ALPHA(1:K) = 1, BETA(1:K) = 0, and if M-K-L >= 0, ALPHA(K+1:K+L) = diag(C), BETA(K+1:K+L) = diag(S), or if M-K-L < 0, ALPHA(K+1:M)= C, ALPHA(M+1:K+L)= 0, BETA(K+1:M) = S, BETA(M+1:K+L) = 1. Furthermore, if K+L < N, ALPHA(K+L+1:N) = 0, BETA(K+L+1:N) = 0.
U
U — a COMPLEX</> array, dimension (LDU,M). On entry, if JOBU = 'U', then U has to already contain a matrix U1 (usually the unitary matrix that CGGSVP handed back to you, bestie 💅). On exit:
- if JOBU = 'I', U holds the unitary matrix U;
- if JOBU = 'U', U holds the product U1*U. If JOBU = 'N', then U isn't referenced at all — she's not even in the group chat. 🙈
LDU — INTEGER</>. The leading dimension of the array U. LDU >= max(1,M) if JOBU = 'U'; LDU >= 1 otherwise. Respect the leading dimension or perish.
V — a COMPLEX</> array, dimension (LDV,P). On entry, if JOBV = 'V', then V must contain a matrix V1 (again, usually the unitary matrix from CGGSVP ✨). On exit:
- if JOBV = 'I', V contains the unitary matrix V;
- if JOBV = 'V', V contains the product V1*V. If JOBV = 'N', V is not referenced.
LDV — INTEGER</>. The leading dimension of the array V. LDV >= max(1,P) if JOBV = 'V'; LDV >= 1 otherwise.
Q — a COMPLEX</> array, dimension (LDQ,N). On entry, if JOBQ = 'Q', Q must contain a matrix Q1 (you already know the drill — usually from CGGSVP 🎀). On exit:
- if JOBQ = 'I', Q contains the unitary matrix Q;
- if JOBQ = 'Q', Q contains the product Q1*Q. If JOBQ = 'N', Q is not referenced. She said not today. 💀
LDQ — INTEGER</>. The leading dimension of the array Q. LDQ >= max(1,N) if JOBQ = 'Q'; LDQ >= 1 otherwise.
WORK — a COMPLEX</> array, dimension (2*N). Just doing her little job in the background, no notes. 🫶
NCYCLE — INTEGER</>. The number of cycles required for convergence. That's literally it, that's the whole vibe check. ✅
INFO — INTEGER</>. The receipts:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. Somebody passed something cursed.
- = 1: the procedure does not converge after MAXIT cycles. She tried, she really did, but no. 😭

🧠 Internal Parameters 🧠

MAXIT — INTEGER</>. MAXIT specifies the total loops that the iterative procedure may take. If, after MAXIT cycles, the routine fails to converge, we return INFO = 1. That's the deal, that's the contract, no cap.

✍️ Author ✍️

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details 🔍

CTGSJA essentially uses a variant of the Kogbetliantz algorithm to reduce the min(L,M-K)-by-L triangular (or trapezoidal) matrix A23 and the L-by-L matrix B13 to the form:

         U1**H *A13*Q1 = C1*R1; V1**H *B13*Q1 = S1*R1,

where U1, V1 and Q1 are unitary matrices. C1 and S1 are diagonal matrices satisfying

              C1**2 + S1**2 = I,

and R1 is an L-by-L nonsingular upper triangular matrix. Iconic triangular behavior, honestly. 🔥

🦋 CTGSNA 🦋

subroutine ctgsna (character JOB, character HOWMNY, logical, dimension( * ) SELECT, integer N, complex, dimension( lda, * ) A, integer LDA, complex, dimension( ldb, * ) B, integer LDB, complex, dimension( ldvl, * ) VL, integer LDVL, complex, dimension( ldvr, * ) VR, integer LDVR, real, dimension( * ) S, real, dimension( * ) DIF, integer MM, integer M, complex, dimension( * ) WORK, integer LWORK, integer, dimension( * ) IWORK, integer INFO)

🎯 Purpose 🎯

CTGSNA estimates reciprocal condition numbers for specified eigenvalues and/or eigenvectors of a matrix pair (A, B). Bestie, she is literally the vibe-checker for your eigenstuff. 💖

(A, B) must be in generalized Schur canonical form — that is, A and B are both upper triangular. No exceptions, that's the dress code. 👑

📋 Parameters 📋

JOB — CHARACTER*1</>. Specifies whether condition numbers are required for eigenvalues (S) or eigenvectors (DIF):
- = 'E': for eigenvalues only (S);
- = 'V': for eigenvectors only (DIF);
- = 'B': for both eigenvalues and eigenvectors (S and DIF). Both. She's doing both.
HOWMNY — CHARACTER*1</>. How many of them are we doing, bestie:
- = 'A': compute condition numbers for all eigenpairs;
- = 'S': compute condition numbers for selected eigenpairs specified by the array SELECT.
SELECT — LOGICAL</> array, dimension (N). If HOWMNY = 'S', SELECT specifies the eigenpairs for which condition numbers are required. To select condition numbers for the corresponding j-th eigenvalue and/or eigenvector, SELECT(j) must be set to .TRUE.. If HOWMNY = 'A', SELECT is not referenced. She doesn't need your opinion then. 💅
N — INTEGER</>. The order of the square matrix pair (A, B). N >= 0. Zero is allowed, she's flexible. 🦋
A — COMPLEX</> array, dimension (LDA,N). The upper triangular matrix A in the pair (A,B). Triangulated and thriving. ✨
LDA — INTEGER</>. The leading dimension of the array A. LDA >= max(1,N).
B — COMPLEX</> array, dimension (LDB,N). The upper triangular matrix B in the pair (A, B). Her other half, fr fr. 🫶
LDB — INTEGER</>. The leading dimension of the array B. LDB >= max(1,N).
VL — COMPLEX</> array, dimension (LDVL,M). If JOB = 'E' or 'B', VL must contain the left eigenvectors of (A, B), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VL, as returned by CTGEVC. Consecutive columns. Not scattered. Consecutive. If JOB = 'V', VL is not referenced.
LDVL — INTEGER</>. The leading dimension of the array VL. LDVL >= 1; and if JOB = 'E' or 'B', LDVL >= N.
VR — COMPLEX</> array, dimension (LDVR,M). If JOB = 'E' or 'B', VR must contain the right eigenvectors of (A, B), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VR, as returned by CTGEVC. If JOB = 'V', VR is not referenced. Right side, left side, she keeps both sides booked and busy. 💅
LDVR — INTEGER</>. The leading dimension of the array VR. LDVR >= 1; if JOB = 'E' or 'B', LDVR >= N.
S — REAL</> array, dimension (MM). If JOB = 'E' or 'B', this holds the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array. If JOB = 'V', S is not referenced.
DIF — REAL</> array, dimension (MM). If JOB = 'V' or 'B', this holds the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. If the eigenvalues cannot be reordered to compute DIF(j), then DIF(j) is set to 0; this can only occur when the true value would be very small anyway, so don't panic, bestie. For each eigenvalue/vector specified by SELECT, DIF stores a Frobenius norm-based estimate of Difl. If JOB = 'E', DIF is not referenced.
MM — INTEGER</>. The number of elements in the arrays S and DIF. MM >= M. Give her room to work, okay? 🎀
M — INTEGER</>. The number of elements of the arrays S and DIF used to store the specified condition numbers; for each selected eigenvalue one element is used. If HOWMNY = 'A', M is set to N. She's doing the counting for you, you're welcome. ✨
WORK — COMPLEX</> array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. She's telling you how much space she actually wanted. 🫶
LWORK — INTEGER</>. The dimension of the array WORK. LWORK >= max(1,N). If JOB = 'V' or 'B', LWORK >= max(1,2*N*N). That second one is big. Do not skimp. 😭
IWORK — INTEGER</> array, dimension (N+2). If JOB = 'E', IWORK is not referenced. She's off the clock in that case. 💀
INFO — INTEGER</>. The final verdict:
- = 0: Successful exit 🎉
- < 0: If INFO = -i, the i-th argument had an illegal value. Something in the call was not it.

✍️ Author ✍️

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details 🔍

The reciprocal of the condition number of the i-th generalized eigenvalue w = (a, b) is defined as

        S(I) = (|v**HAu|**2 + |v**HBu|**2)**(1/2) / (norm(u)*norm(v))

where u and v are the right and left eigenvectors of (A, B) corresponding to w; |z| denotes the absolute value of the complex number, and norm(u) denotes the 2-norm of the vector u. The pair (a, b) corresponds to an eigenvalue w = a/b (= v**HAu/v**HBu) of the matrix pair (A, B). If both a and b equal zero, then (A,B) is singular and S(I) = -1 is returned. Yes, that's the "she's broken" flag. 🙈

An approximate error bound on the chordal distance between the i-th computed generalized eigenvalue w and the corresponding exact eigenvalue lambda is

        chord(w, lambda) <=   EPS * norm(A, B) / S(I),

where EPS is the machine precision. Tiny EPS, big drama. 💀

The reciprocal of the condition number of the right eigenvector u and left eigenvector v corresponding to the generalized eigenvalue w is defined as follows. Suppose

                         (A, B) = ( a   *  ) ( b  *  )  1
                                  ( 0  A22 ),( 0 B22 )  n-1
                                    1  n-1     1 n-1

Then the reciprocal condition number DIF(I) is

        Difl[(a, b), (A22, B22)]  = sigma-min( Zl )

where sigma-min(Zl) denotes the smallest singular value of

       Zl = [ kron(a, In-1) -kron(1, A22) ]
            [ kron(b, In-1) -kron(1, B22) ].

Here In-1 is the identity matrix of size n-1 and X**H is the conjugate transpose of X. kron(X, Y) is the Kronecker product between the matrices X and Y. Kronecker product my beloved. 🦋

We approximate the smallest singular value of Zl with an upper bound. This is done by CLATDF. (Shoutout to CLATDF, doing the real work behind the scenes. 👑)

An approximate error bound for a computed eigenvector VL(i) or VR(i) is given by

                            EPS * norm(A, B) / DIF(i).

See ref. [2-3] for more details and further references.

👑 Contributors 👑

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden. Absolute legends, no notes. 💖

📚 References 📚

[1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the Generalized Real Schur Form of a Regular Matrix Pair (A, B), in M.S. Moonen et al (eds), Linear Algebra for Large Scale and Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
[2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified Eigenvalues of a Regular Matrix Pair (A, B) and Condition Estimation: Theory, Algorithms and Software, Report UMINF - 94.04, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87. To appear in Numerical Algorithms, 1996.
[3] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software for Solving the Generalized Sylvester Equation and Estimating the Separation between Regular Matrix Pairs, Report UMINF - 93.23, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, December 1993, Revised April 1994, Also as LAPACK Working Note 75. To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.

🌸 subroutine ctpcon 🌸

okay bestie, buckle up, we're doing condition numbers now 💅

subroutine ctpcon (character NORM, character UPLO, character DIAG, integer
    N, complex, dimension( * ) AP, real RCOND, complex, dimension( * ) WORK,
    real, dimension( * ) RWORK, integer INFO)

CTPCON

✨ Purpose ✨

CTPCON estimates the reciprocal of the condition number of a packed triangular matrix A, in either the 1-norm or the infinity-norm. lowkey obsessed with this one 🫶

The norm of A is computed and an estimate is obtained for norm(inv(A)), then the reciprocal of the condition number is computed as

RCOND = 1 / ( norm(A) * norm(inv(A)) ).

🎀 Parameters 🎀

NORM

NORM is CHARACTER*1

Specifies whether the 1-norm condition number or the infinity-norm condition number is required:

= '1' or 'O': 1-norm;
= 'I': Infinity-norm.

UPLO

UPLO is CHARACTER*1

= 'U': A is upper triangular;
= 'L': A is lower triangular.

DIAG

DIAG is CHARACTER*1

= 'N': A is non-unit triangular;
= 'U': A is unit triangular.

N

N is INTEGER

The order of the matrix A. N >= 0.

AP

AP is COMPLEX array, dimension (N*(N+1)/2)

The upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

If DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1.

RCOND

RCOND is REAL

The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(norm(A) * norm(inv(A))).

WORK

WORK is COMPLEX array, dimension (2*N)

RWORK

RWORK is REAL array, dimension (N)

INFO

INFO is 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.

🦋 subroutine ctpmqrt 🦋

subroutine ctpmqrt (character SIDE, character TRANS, integer M, integer N,
    integer K, integer L, integer NB, complex, dimension( ldv, * ) V,
    integer LDV, complex, dimension( ldt, * ) T, integer LDT, complex,
    dimension( lda, * ) A, integer LDA, complex, dimension( ldb, * ) B,
    integer LDB, complex, dimension( * ) WORK, integer INFO)

CTPMQRT

✨ Purpose ✨

CTPMQRT applies a complex orthogonal matrix Q obtained from a 'triangular-pentagonal' complex block reflector H to a general complex matrix C, which consists of two blocks A and B. it's giving very structured, very demure ✨

🎀 Parameters 🎀

SIDE

SIDE is CHARACTER*1

= 'L': apply Q or Q**H from the Left;
= 'R': apply Q or Q**H from the Right.

TRANS

TRANS is CHARACTER*1

= 'N': No transpose, apply Q;
= 'C': Conjugate transpose, apply Q**H.

M

M is INTEGER

The number of rows of the matrix B. M >= 0.

N

N is INTEGER

The number of columns of the matrix B. N >= 0.

K

K is INTEGER

The number of elementary reflectors whose product defines the matrix Q.

L

L is INTEGER

The order of the trapezoidal part of V. K >= L >= 0. See Further Details.

NB

NB is INTEGER

The block size used for the storage of T. K >= NB >= 1. This must be the same value of NB used to generate T in CTPQRT. > bestie do NOT switch up the NB value, it's gotta match fr fr 😭

V

V is COMPLEX array, dimension (LDV,K)

The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CTPQRT in B. See Further Details.

LDV

LDV is INTEGER

The leading dimension of the array V.

If SIDE = 'L', LDV >= max(1,M);
if SIDE = 'R', LDV >= max(1,N).

T

T is COMPLEX array, dimension (LDT,K)

The upper triangular factors of the block reflectors as returned by CTPQRT, stored as a NB-by-K matrix.

LDT

LDT is INTEGER

The leading dimension of the array T. LDT >= NB.

A

A is COMPLEX array, dimension (LDA,N) if SIDE = 'L' or (LDA,K) if SIDE = 'R'

On entry, the K-by-N or M-by-K matrix A. On exit, A is overwritten by the corresponding block of Q*C or Q**H*C or C*Q or C*Q**H. See Further Details.

LDA

LDA is INTEGER

The leading dimension of the array A.

If SIDE = 'L', LDC >= max(1,K);
If SIDE = 'R', LDC >= max(1,M).

B

B is COMPLEX array, dimension (LDB,N)

On entry, the M-by-N matrix B. On exit, B is overwritten by the corresponding block of Q*C or Q**H*C or C*Q or C*Q**H. See Further Details.

LDB

LDB is INTEGER

The leading dimension of the array B. LDB >= max(1,M).

WORK

WORK is COMPLEX array. The dimension of WORK is N*NB if SIDE = 'L', or M*NB if SIDE = 'R'.

INFO

INFO is 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 columns of the pentagonal matrix V contain the elementary reflectors H(1), H(2), ..., H(K); V is composed of a rectangular block V1 and a trapezoidal block V2:

      V = [V1]
          [V2].

The size of the trapezoidal block V2 is determined by the parameter L, where 0 <= L <= K; V2 is upper trapezoidal, consisting of the first L rows of a K-by-K upper triangular matrix. If L=K, V2 is upper triangular; if L=0, there is no trapezoidal block, hence V = V1 is rectangular.

If SIDE = 'L': C = [A] where A is K-by-N, B is M-by-N and V is M-by-K. [B]

If SIDE = 'R': C = [A B] where A is M-by-K, B is M-by-N and V is N-by-K.

The complex orthogonal matrix Q is formed from V and T.

If TRANS='N' and SIDE='L', C is on exit replaced with Q * C.
If TRANS='C' and SIDE='L', C is on exit replaced with Q**H * C.
If TRANS='N' and SIDE='R', C is on exit replaced with C * Q.
If TRANS='C' and SIDE='R', C is on exit replaced with C * Q**H.

💜 subroutine ctpqrt 💜

subroutine ctpqrt (integer M, integer N, integer L, integer NB, complex,
    dimension( lda, * ) A, integer LDA, complex, dimension( ldb, * ) B,
    integer LDB, complex, dimension( ldt, * ) T, integer LDT, complex,
    dimension( * ) WORK, integer INFO)

CTPQRT

✨ Purpose ✨

CTPQRT computes a blocked QR factorization of a complex 'triangular-pentagonal' matrix C, which is composed of a triangular block A and pentagonal block B, using the compact WY representation for Q. the way it decomposes... iconic 💅

🎀 Parameters 🎀

M

M is INTEGER

The number of rows of the matrix B. M >= 0.

N

N is INTEGER

The number of columns of the matrix B, and the order of the triangular matrix A. N >= 0.

L

L is INTEGER

The number of rows of the upper trapezoidal part of B. MIN(M,N) >= L >= 0. See Further Details.

NB

NB is INTEGER

The block size to be used in the blocked QR. N >= NB >= 1.

A

A is COMPLEX array, dimension (LDA,N)

On entry, the upper triangular N-by-N matrix A. On exit, the elements on and above the diagonal of the array contain the upper triangular matrix R.

LDA

LDA is INTEGER

The leading dimension of the array A. LDA >= max(1,N).

B

B is COMPLEX array, dimension (LDB,N)

On entry, the pentagonal M-by-N matrix B. The first M-L rows are rectangular, and the last L rows are upper trapezoidal. On exit, B contains the pentagonal matrix V. See Further Details.

LDB

LDB is INTEGER

The leading dimension of the array B. LDB >= max(1,M).

T

T is COMPLEX array, dimension (LDT,N)

The upper triangular block reflectors stored in compact form as a sequence of upper triangular blocks. See Further Details.

LDT

LDT is INTEGER

The leading dimension of the array T. LDT >= NB.

WORK

WORK is COMPLEX array, dimension (NB*N)

INFO

INFO is 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 💫

okay so bestie, the input matrix C is a (N+M)-by-N matrix

C = [ A ]
    [ B ]

where A is an upper triangular N-by-N matrix, and B is M-by-N pentagonal matrix consisting of a (M-L)-by-N rectangular matrix B1 on top of a L-by-N upper trapezoidal matrix B2:

B = [ B1 ]  <- (M-L)-by-N rectangular
    [ B2 ]  <-     L-by-N upper trapezoidal.

The upper trapezoidal matrix B2 consists of the first L rows of a N-by-N upper triangular matrix, where 0 <= L <= MIN(M,N). If L=0, B is rectangular M-by-N; if M=L=N, B is upper triangular.

The matrix W stores the elementary reflectors H(i) in the i-th column below the diagonal (of A) in the (N+M)-by-N input matrix C

C = [ A ]  <- upper triangular N-by-N
    [ B ]  <- M-by-N pentagonal

so that W can be represented as

W = [ I ]  <- identity, N-by-N
    [ V ]  <- M-by-N, same form as B.

Thus, all of information needed for W is contained on exit in B, which we call V above. Note that V has the same form as B; that is,

V = [ V1 ] <- (M-L)-by-N rectangular
    [ V2 ] <-     L-by-N upper trapezoidal.

The columns of V represent the vectors which define the H(i)'s.

The number of blocks is B = ceiling(N/NB), where each block is of order NB except for the last block, which is of order IB = N - (B-1)*NB. For each of the B blocks, a upper triangular block reflector factor is computed: T1, T2, ..., TB. The NB-by-NB (and IB-by-IB for the last block) T's are stored in the NB-by-N matrix T as

T = [T1 T2 ... TB].

subroutine ctpqrt2 🌟

subroutine ctpqrt2 (integer M, integer N, integer L, complex, dimension(
    lda, * ) A, integer LDA, complex, dimension( ldb, * ) B, integer LDB,
    complex, dimension( ldt, * ) T, integer LDT, integer INFO)

CTPQRT2 computes a QR factorization of a real or complex 'triangular-pentagonal' matrix, which is composed of a triangular block and a pentagonal block, using the compact WY representation for Q.

Purpose ✨

CTPQRT2 computes a QR factorization of a complex 'triangular-pentagonal' matrix C, which is composed of a triangular block A and pentagonal block B, using the compact WY representation for Q.

Parameters 🧮

M — M is INTEGER The total number of rows of the matrix B. M >= 0.
N — N is INTEGER The number of columns of the matrix B, and the order of the triangular matrix A. N >= 0.
L — L is INTEGER The number of rows of the upper trapezoidal part of B. MIN(M,N) >= L >= 0. See Further Details.
A — A is COMPLEX array, dimension (LDA,N) On entry, the upper triangular N-by-N matrix A. On exit, the elements on and above the diagonal of the array contain the upper triangular matrix R.
LDA — LDA is INTEGER The leading dimension of the array A. LDA >= max(1,N).
B — B is COMPLEX array, dimension (LDB,N) On entry, the pentagonal M-by-N matrix B. The first M-L rows are rectangular, and the last L rows are upper trapezoidal. On exit, B contains the pentagonal matrix V. See Further Details.
LDB — LDB is INTEGER The leading dimension of the array B. LDB >= max(1,M).
T — T is COMPLEX array, dimension (LDT,N) The N-by-N upper triangular factor T of the block reflector. See Further Details.
LDT — LDT is INTEGER The leading dimension of the array T. LDT >= max(1,N)
INFO — INFO is 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 🌈

okay so the input matrix C is a (N+M)-by-N matrix

C = [ A ]
    [ B ]

B = [ B1 ]  <- (M-L)-by-N rectangular
    [ B2 ]  <-     L-by-N upper trapezoidal.

The matrix W stores the elementary reflectors H(i) in the i-th column below the diagonal (of A) in the (N+M)-by-N input matrix C

C = [ A ]  <- upper triangular N-by-N
    [ B ]  <- M-by-N pentagonal

so that W can be represented as

W = [ I ]  <- identity, N-by-N
    [ V ]  <- M-by-N, same form as B.

Thus, all of information needed for W is contained on exit in B, which we call V above. Note that V has the same form as B; that is,

V = [ V1 ] <- (M-L)-by-N rectangular
    [ V2 ] <-     L-by-N upper trapezoidal.

The columns of V represent the vectors which define the H(i)'s. The (M+N)-by-(M+N) block reflector H is then given by

H = I - W * T * W**H

where W**H is the conjugate transpose of W and T is the upper triangular factor of the block reflector.

subroutine ctprfs 🎀

subroutine ctprfs (character UPLO, character TRANS, character DIAG, integer
    N, integer NRHS, complex, dimension( * ) AP, complex, dimension( ldb, *
    ) B, integer LDB, complex, dimension( ldx, * ) X, integer LDX, real,
    dimension( * ) FERR, real, dimension( * ) BERR, complex, dimension( * )
    WORK, real, dimension( * ) RWORK, integer INFO)

CTPRFS

Purpose ✨

CTPRFS provides error bounds and backward error estimates for the solution to a system of linear equations with a triangular packed coefficient matrix.

The solution matrix X must be computed by CTPTRS or some other means before entering this routine. CTPRFS does not do iterative refinement because doing so cannot improve the backward error.

Parameters 🧮

UPLO — UPLO is CHARACTER*1 = 'U': A is upper triangular; = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1 Specifies the form of the system of equations: = 'N': A * X = B (No transpose) = 'T': A**T * X = B (Transpose) = 'C': A**H * X = B (Conjugate transpose)
DIAG — DIAG is CHARACTER*1 = 'N': A is non-unit triangular; = 'U': A is unit triangular.
N — N is INTEGER The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2) The upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows: if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n. If DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1.
B — B is COMPLEX array, dimension (LDB,NRHS) The right hand side matrix B.
LDB — LDB is INTEGER The leading dimension of the array B. LDB >= max(1,N).
X — X is COMPLEX array, dimension (LDX,NRHS) The solution matrix X.
LDX — LDX is INTEGER The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is REAL array, dimension (NRHS) The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.
BERR — BERR is REAL array, dimension (NRHS) The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
WORK — WORK is COMPLEX array, dimension (2*N)
RWORK — RWORK is REAL array, dimension (N)
INFO — INFO is 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.

subroutine ctptri 🦋

subroutine ctptri (character UPLO, character DIAG, integer N, complex,
    dimension( * ) AP, integer INFO)

CTPTRI

Purpose ✨

CTPTRI computes the inverse of a complex upper or lower triangular matrix A stored in packed format.

Parameters 🧮

UPLO — UPLO is CHARACTER*1 = 'U': A is upper triangular; = 'L': A is lower triangular.
DIAG — DIAG is CHARACTER*1 = 'N': A is non-unit triangular; = 'U': A is unit triangular.
N — N is INTEGER The order of the matrix A. N >= 0.
AP —
AP — okay so this one is a COMPLEX array, dimension (N*(N+1)/2). On entry it's your upper-or-lower triangular matrix A, stored columnwise in a linear array (yes bestie, all squished into one long line, that's the vibe). The j-th column of A gets stored in the array AP like this:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*((2*n-j)/2) = A(i,j) for j<=i<=n.

See below for further details. On exit, AP is holding the (triangular) inverse of the original matrix, in the exact same packed storage format. iconic, honestly 💖

INFO — INFO is INTEGER, and it's basically the vibe check at the end:
- = 0: successful exit, we ate ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🙈
- > 0: if INFO = i, A(i,i) is exactly zero. The triangular matrix is singular and its inverse can not be computed. like, cannot, do not pass go 💀

🫶 Author 🫶

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details:

A triangular matrix A can be transferred to packed storage using one of the following program segments:

             UPLO = 'U':                      UPLO = 'L':

                   JC = 1                           JC = 1
                   DO 2 J = 1, N                    DO 2 J = 1, N
                      DO 1 I = 1, J                    DO 1 I = J, N
                         AP(JC+I-1) = A(I,J)              AP(JC+I-J) = A(I,J)
                 1    CONTINUE                    1    CONTINUE
                      JC = JC + J                      JC = JC + N - J + 1
                 2 CONTINUE                       2 CONTINUE

💅 `subroutine ctptrs` 💅

subroutine ctptrs (character UPLO, character TRANS, character DIAG, integer
    N, integer NRHS, complex, dimension( * ) AP, complex, dimension( ldb, *
    ) B, integer LDB, integer INFO)

CTPTRS — say it with me, the triangular solve with a packed glow-up ✨

🎀 Purpose:

CTPTRS solves a triangular system of the form

   A * X = B,  A**T * X = B,  or  A**H * X = B,

where A is a triangular matrix of order N stored in packed format, and B is an N-by-NRHS matrix. It also checks that A is nonsingular, because we do not play about singular matrices in this house.

🌸 Parameters

UPLO — UPLO is CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1, specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — DIAG is CHARACTER*1:
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). The upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
B — B is COMPLEX array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, if INFO = 0, the solution matrix X. the glow-up moment fr fr 🦋
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
INFO — INFO is INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭
- > 0: if INFO = i, the i-th diagonal element of A is zero, indicating that the matrix is singular and the solutions X have not been computed. so like, do not trust B after this bestie 💀

🫶 Author 🫶

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 `subroutine ctpttf` 🦋

subroutine ctpttf (character TRANSR, character UPLO, integer N, complex,
    dimension( 0: * ) AP, complex, dimension( 0: * ) ARF, integer INFO)

CTPTTF copies a triangular matrix from the standard packed format (TP) to the rectangular full packed format (TF). a whole format glow-up, no cap ✨

🎀 Purpose:

CTPTTF copies a triangular matrix A from standard packed format (TP) to rectangular full packed format (TF).

🌸 Parameters

TRANSR — TRANSR is CHARACTER*1:
- = 'N': ARF in Normal format is wanted;
- = 'C': ARF in Conjugate-transpose format is wanted.
UPLO — UPLO is CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX array, dimension ( N*(N+1)/2 ). On entry, the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
ARF — ARF is COMPLEX array, dimension ( N*(N+1)/2 ). On exit, the upper or lower triangular matrix A stored in RFP format. For a further discussion see Notes below. 👑
INFO — INFO is 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:

We first consider Standard Packed Format when N is even. We give an example where N = 6.

                 AP is Upper             AP is Lower

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

Let TRANSR = 'N'. RFP holds AP as follows: For UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. The lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper. For UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. The upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower. To denote conjugate we place -- above the element. This covers the case N even and TRANSR = 'N'.

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP as follows: For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper. For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower. To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'.

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

🎀 `subroutine ctpttr` 🎀

subroutine ctpttr (character UPLO, integer N, complex, dimension( * ) AP,
    complex, dimension( lda, * ) A, integer LDA, integer INFO)

CTPTTR copies a triangular matrix from the standard packed format (TP) to the standard full format (TR). unpacking, but make it fashion 💅

🎀 Purpose:

CTPTTR copies a triangular matrix A from standard packed format (TP) to standard full format (TR).

🌸 Parameters

UPLO — UPLO is CHARACTER*1:
- = 'U': A is upper triangular.
- = 'L': A is lower triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP —
AP — bestie, this one is a COMPLEX array, dimension ( N*(N+1)/2 ). 💅

On entry, it's the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A gets stored in AP like this:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

A — also a COMPLEX array, dimension ( LDA, N ).

On exit, this is the triangular matrix A. So: if UPLO = 'U', the leading N-by-N upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced (it's just sitting there, unbothered, not getting a vibe check). If UPLO = 'L', the leading N-by-N lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced. ✨

LDA — an INTEGER. The leading dimension of the array A. So LDA >= max(1,N), no exceptions, fr fr. 🫶
INFO — an INTEGER, and it's basically the group-chat status report:

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

🦋 `ctrcon`

subroutine ctrcon (character NORM, character UPLO, character DIAG, integer
    N, complex, dimension( lda, * ) A, integer LDA, real RCOND, complex,
    dimension( * ) WORK, real, dimension( * ) RWORK, integer INFO)

CTRCON — say hi 👋

💖 Purpose:

CTRCON estimates the reciprocal of the condition number of a triangular matrix A, in either the 1-norm or the infinity-norm. Slay, honestly.

The norm of A is computed and an estimate is obtained for norm(inv(A)), then the reciprocal of the condition number is computed as

RCOND = 1 / ( norm(A) * norm(inv(A)) ).

No cap, that's the whole formula. 🎀

🌸 Parameters

NORM — a CHARACTER*1. It specifies whether the 1-norm condition number or the infinity-norm condition number is required:

= '1' or 'O':  1-norm;
= 'I':         Infinity-norm.

UPLO — a CHARACTER*1:

= 'U':  A is upper triangular;
= 'L':  A is lower triangular.

DIAG — a CHARACTER*1:

= 'N':  A is non-unit triangular;
= 'U':  A is unit triangular.

N — an INTEGER. The order of the matrix A. So N >= 0, okay? 💅
A — a COMPLEX array, dimension (LDA,N). It's the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. And if DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1. Iconic behaviour, honestly. ✨
LDA — an INTEGER. The leading dimension of the array A. LDA >= max(1,N). Periodt.
RCOND — a REAL. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(norm(A) * norm(inv(A))). 💖
WORK — a COMPLEX array, dimension (2*N).
RWORK — a REAL array, dimension (N).
INFO — an 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.

🧚 `ctrevc`

subroutine ctrevc (character SIDE, character HOWMNY, logical, dimension( * )
    SELECT, integer N, complex, dimension( ldt, * ) T, integer LDT, complex,
    dimension( ldvl, * ) VL, integer LDVL, complex, dimension( ldvr, * ) VR,
    integer LDVR, integer MM, integer M, complex, dimension( * ) WORK, real,
    dimension( * ) RWORK, integer INFO)

CTREVC — she's here and she's serving eigenvectors 💅

💜 Purpose:

CTREVC computes some or all of the right and/or left eigenvectors of a complex upper triangular matrix T. Matrices of this type are produced by the Schur factorization of a complex general matrix: A = Q*T*Q**H, as computed by CHSEQR. 🦋

The right eigenvector x and the left eigenvector y of T corresponding to an eigenvalue w are defined by:

             T*x = w*x,     (y**H)*T = w*(y**H)

where y**H denotes the conjugate transpose of the vector y. The eigenvalues are not input to this routine, but are read directly from the diagonal of T. The way she just knows?? 🔥

This routine returns the matrices X and/or Y of right and left eigenvectors of T, or the products Q*X and/or Q*Y, where Q is an input matrix. If Q is the unitary factor that reduces a matrix A to Schur form T, then Q*X and Q*Y are the matrices of right and left eigenvectors of A. So she can do both. Main character energy, obviously. 👑

🌈 Parameters

SIDE — a CHARACTER*1:

= 'R':  compute right eigenvectors only;
= 'L':  compute left eigenvectors only;
= 'B':  compute both right and left eigenvectors.

HOWMNY — a CHARACTER*1:

= 'A':  compute all right and/or left eigenvectors;
= 'B':  compute all right and/or left eigenvectors,
        backtransformed using the matrices supplied in
        VR and/or VL;
= 'S':  compute selected right and/or left eigenvectors,
        as indicated by the logical array SELECT.

SELECT — a LOGICAL array, dimension (N). If HOWMNY = 'S', SELECT specifies the eigenvectors to be computed. The eigenvector corresponding to the j-th eigenvalue is computed if SELECT(j) = .TRUE.. Not referenced if HOWMNY = 'A' or 'B'. 🙈
N — an INTEGER. The order of the matrix T. N >= 0.
T — a COMPLEX array, dimension (LDT,N). The upper triangular matrix T. Heads up bestie: T is modified, but restored on exit. So she's messy but she cleans up after herself. 💅
LDT — an INTEGER. The leading dimension of the array T. LDT >= max(1,N).
VL — a COMPLEX array, dimension (LDVL,MM).

On entry, if SIDE = 'L' or 'B' and HOWMNY = 'B', VL must contain an N-by-N matrix Q (usually the unitary matrix Q of Schur vectors returned by CHSEQR).

On exit, if SIDE = 'L' or 'B', VL contains:

if HOWMNY = 'A', the matrix Y of left eigenvectors of T;
if HOWMNY = 'B', the matrix Q*Y;
if HOWMNY = 'S', the left eigenvectors of T specified by
                 SELECT, stored consecutively in the columns
                 of VL, in the same order as their
                 eigenvalues.

Not referenced if SIDE = 'R'. ✨

LDVL — an INTEGER. The leading dimension of the array VL. LDVL >= 1, and if SIDE = 'L' or 'B', LDVL >= N.
VR — a COMPLEX array, dimension (LDVR,MM).

On entry, if SIDE = 'R' or 'B' and HOWMNY = 'B', VR must contain an N-by-N matrix Q (usually the unitary matrix Q of Schur vectors returned by CHSEQR).

On exit, if SIDE = 'R' or 'B', VR contains:

if HOWMNY = 'A', the matrix X of right eigenvectors of T;
if HOWMNY = 'B', the matrix Q*X;
if HOWMNY = 'S', the right eigenvectors of T specified by
                 SELECT, stored consecutively in the columns
                 of VR, in the same order as their
                 eigenvalues.

Not referenced if SIDE = 'L'. 🦋

LDVR — an INTEGER. The leading dimension of the array VR. LDVR >= 1, and if SIDE = 'R' or 'B'; LDVR >= N.
MM — an INTEGER. The number of columns in the arrays VL and/or VR. MM >= M. 🎀
M — an INTEGER. The number of columns in the arrays VL and/or VR actually used to store the eigenvectors. If HOWMNY = 'A' or 'B', M is set to N. Each selected eigenvector occupies one column. One column per queen, as it should be. 👑
WORK — a COMPLEX array, dimension (2*N).
RWORK — a REAL array, dimension (N).
INFO — an 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 algorithm used in this program is basically backward (forward) substitution, with scaling to make the the code robust against possible overflow. 🫶

Each eigenvector is normalized so that the element of largest magnitude has magnitude 1; here the magnitude of a complex number (x,y) is taken to be |x| + |y|. And that's the tea. 🍓

🌟 `ctrevc3`

subroutine ctrevc3 (character SIDE, character HOWMNY, logical, dimension( *
    ) SELECT, integer N, complex, dimension( ldt, * ) T, integer LDT,
    complex, dimension( ldvl, * ) VL, integer LDVL, complex, dimension(
    ldvr, * ) VR, integer LDVR, integer MM, integer M, complex, dimension( *
    ) WORK, integer LWORK, real, dimension( * ) RWORK, integer LRWORK,
    integer INFO)

CTREVC3 — yes bestie, there's a third one, she's the upgraded model 💅✨

💜 Purpose:

CTREVC3 computes some or all of the right and/or left eigenvectors of a complex upper triangular matrix T. Matrices of this type are produced by the Schur factorization of a complex general matrix: A = Q*T*Q**H, as computed by CHSEQR. Same lore as before, because why mess with perfection. 🦋

The right eigenvector x and the left eigenvector y of T corresponding to an eigenvalue w are defined by:

             T*x = w*x,     (y**H)*T = w*(y**H)

where y**H denotes the conjugate transpose of the vector y. The eigenvalues are not input to this routine, but are read directly from the diagonal of T. 🔥

Okay bestie, this routine hands you back the matrices X and/or Y of right and left eigenvectors of T, or the products Q*X and/or Q*Y, where Q is an input matrix. If Q is the unitary factor that reduces a matrix A to Schur form T, then Q*X and Q*Y are the matrices of right and left eigenvectors of A.

This uses a Level 3 BLAS version of the back transformation. 💅

Parameters ✨

`SIDE`

SIDE is CHARACTER*1

= 'R': compute right eigenvectors only;
= 'L': compute left eigenvectors only;
= 'B': compute both right and left eigenvectors.

`HOWMNY`

HOWMNY is CHARACTER*1

= 'A': compute all right and/or left eigenvectors;
= 'B': compute all right and/or left eigenvectors, backtransformed using the matrices supplied in VR and/or VL;
= 'S': compute selected right and/or left eigenvectors, as indicated by the logical array SELECT.

`SELECT`

SELECT is LOGICAL array, dimension (N)

If HOWMNY = 'S', SELECT specifies the eigenvectors to be computed. The eigenvector corresponding to the j-th eigenvalue is computed if SELECT(j) = .TRUE.. Not referenced if HOWMNY = 'A' or 'B'.

`N`

N is INTEGER

The order of the matrix T. N >= 0.

`T`

T is COMPLEX array, dimension (LDT,N)

The upper triangular matrix T. T is modified, but restored on exit. 😌

`LDT`

LDT is INTEGER

The leading dimension of the array T. LDT >= max(1,N).

`VL`

VL is COMPLEX array, dimension (LDVL,MM)

On entry, if SIDE = 'L' or 'B' and HOWMNY = 'B', VL must contain an N-by-N matrix Q (usually the unitary matrix Q of Schur vectors returned by CHSEQR).

On exit, if SIDE = 'L' or 'B', VL contains:

if HOWMNY = 'A', the matrix Y of left eigenvectors of T;
if HOWMNY = 'B', the matrix Q*Y;
if HOWMNY = 'S', the left eigenvectors of T specified by SELECT, stored consecutively in the columns of VL, in the same order as their eigenvalues.

Not referenced if SIDE = 'R'.

`LDVL`

LDVL is INTEGER

The leading dimension of the array VL. LDVL >= 1, and if SIDE = 'L' or 'B', LDVL >= N.

`VR`

VR is COMPLEX array, dimension (LDVR,MM)

On entry, if SIDE = 'R' or 'B' and HOWMNY = 'B', VR must contain an N-by-N matrix Q (usually the unitary matrix Q of Schur vectors returned by CHSEQR).

On exit, if SIDE = 'R' or 'B', VR contains:

if HOWMNY = 'A', the matrix X of right eigenvectors of T;
if HOWMNY = 'B', the matrix Q*X;
if HOWMNY = 'S', the right eigenvectors of T specified by SELECT, stored consecutively in the columns of VR, in the same order as their eigenvalues.

Not referenced if SIDE = 'L'.

`LDVR`

LDVR is INTEGER

The leading dimension of the array VR. LDVR >= 1, and if SIDE = 'R' or 'B', LDVR >= N.

`MM`

MM is INTEGER

The number of columns in the arrays VL and/or VR. MM >= M.

`M`

M is INTEGER

The number of columns in the arrays VL and/or VR actually used to store the eigenvectors. If HOWMNY = 'A' or 'B', M is set to N. Each selected eigenvector occupies one column.

`WORK`

WORK is COMPLEX array, dimension (MAX(1,LWORK))

`LWORK`

LWORK is INTEGER

The dimension of array WORK. LWORK >= max(1,2*N). For optimum performance, LWORK >= N + 2*N*NB, where NB is the optimal blocksize.

`RWORK`

RWORK is REAL array, dimension (LRWORK)

`LRWORK`

LRWORK is INTEGER

The dimension of array RWORK. LRWORK >= max(1,N).

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the RWORK array, returns this value as the first entry of the RWORK array, and no error message related to LRWORK is issued by XERBLA.

`INFO`

INFO is 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 algorithm used in this program is basically backward (forward) substitution, with scaling to make the code robust against possible overflow.

Each eigenvector is normalized so that the element of largest magnitude has magnitude 1; here the magnitude of a complex number (x,y) is taken to be |x| + |y|.

`subroutine ctrexc` 🌀

subroutine ctrexc (character COMPQ, integer N, complex, dimension( ldt, * ) T, integer LDT, complex, dimension( ldq, * ) Q, integer LDQ, integer IFST, integer ILST, integer INFO)

CTREXC

Purpose:

CTREXC reorders the Schur factorization of a complex matrix A = Q*T*Q**H, so that the diagonal element of T with row index IFST is moved to row ILST.

The Schur form T is reordered by a unitary similarity transformation Z**H*T*Z, and optionally the matrix Q of Schur vectors is updated by postmultiplying it with Z.

Parameters

`COMPQ`

COMPQ is CHARACTER*1

= 'V': update the matrix Q of Schur vectors;
= 'N': do not update Q.

`N`

N is INTEGER

The order of the matrix T. N >= 0. If N == 0 arguments ILST and IFST may be any value.

`T`

T is COMPLEX array, dimension (LDT,N)

On entry, the upper triangular matrix T. On exit, the reordered upper triangular matrix.

`LDT`

LDT is INTEGER

The leading dimension of the array T. LDT >= max(1,N).

`Q`

Q is COMPLEX array, dimension (LDQ,N)

On entry, if COMPQ = 'V', the matrix Q of Schur vectors. On exit, if COMPQ = 'V', Q has been postmultiplied by the unitary transformation matrix Z which reorders T. If COMPQ = 'N', Q is not referenced.

`LDQ`

LDQ is INTEGER

The leading dimension of the array Q. LDQ >= 1, and if COMPQ = 'V', LDQ >= max(1,N).

`IFST`

IFST is INTEGER

`ILST`

ILST is INTEGER

Specify the reordering of the diagonal elements of T: The element with row index IFST is moved to row ILST by a sequence of transpositions between adjacent elements. 1 <= IFST <= N; 1 <= ILST <= N.

`INFO`

INFO is 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.

`subroutine ctrrfs` 💖

subroutine ctrrfs (character UPLO, character TRANS, character DIAG, integer N, integer NRHS, complex, dimension( lda, * ) A, integer LDA, complex, dimension( ldb, * ) B, integer LDB, complex, dimension( ldx, * ) X, integer LDX, real, dimension( * ) FERR, real, dimension( * ) BERR, complex, dimension( * ) WORK, real, dimension( * ) RWORK, integer INFO)

CTRRFS

Purpose:

CTRRFS provides error bounds and backward error estimates for the solution to a system of linear equations with a triangular coefficient matrix.

The solution matrix X must be computed by CTRTRS or some other means before entering this routine. CTRRFS does not do iterative refinement because doing so cannot improve the backward error.

Parameters

`UPLO`

UPLO is CHARACTER*1

= 'U': A is upper triangular;
= 'L': A is lower triangular.

`TRANS`

TRANS is CHARACTER*1

Specifies the form of the system of equations:

= 'N': A * X = B (No transpose)
= 'T': A**T * X = B (Transpose)
= 'C': A**H * X = B (Conjugate transpose)

`DIAG`

DIAG is CHARACTER*1

= 'N': A is non-unit triangular;
= 'U': A is unit triangular.

`N`

N is INTEGER

The order of the matrix A. N >= 0.

`NRHS`

NRHS is INTEGER

The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.

`A`

A is COMPLEX array, dimension (LDA,N)

The triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1.

`LDA`

LDA is INTEGER

The leading dimension of the array A. LDA >= max(1,N).

`B`

B is COMPLEX array, dimension (LDB,NRHS)

The right hand side matrix B.

`LDB`

LDB is INTEGER

The leading dimension of the array B. LDB >= max(1,N).

`X`

X is COMPLEX array, dimension (LDX,NRHS)

The solution matrix X.

`LDX`

LDX — INTEGER, bestie. The leading dimension of the array X. The rule: LDX >= max(1,N).
FERR — REAL array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (that's the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), then FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). This estimate is as reliable as the estimate for RCOND, and it is almost always a slight overestimate of the true error. 💅
BERR — REAL array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) — i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution. She's precise like that. ✨
WORK — COMPLEX array, dimension (2*N). It's the workspace, she works. 💪
RWORK — REAL array, dimension (N). More workspace, but make it real. 🎀
INFO — INTEGER, the vibe check at the end:
- = 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.

Four whole institutions showed up for this. Iconic collaborative energy, no cap. 🫶

🌈 `ctrsen` 🌈

subroutine ctrsen (character JOB, character COMPQ, logical, dimension( * )
    SELECT, integer N, complex, dimension( ldt, * ) T, integer LDT, complex,
    dimension( ldq, * ) Q, integer LDQ, complex, dimension( * ) W, integer
    M, real S, real SEP, complex, dimension( * ) WORK, integer LWORK,
    integer INFO)

CTRSEN — say it with me, bestie. 🦋

✨ Purpose ✨

CTRSEN reorders the Schur factorization of a complex matrix A = Q*T*Q**H, so that a selected cluster of eigenvalues shows up in the leading positions on the diagonal of the upper triangular matrix T, and the leading columns of Q form an orthonormal basis of the corresponding right invariant subspace. She's rearranging the whole party so the VIPs are at the front. 💅

Optionally, the routine computes the reciprocal condition numbers of the cluster of eigenvalues and/or the invariant subspace. Options, options, we love to see it. ✨

🎀 Parameters 🎀

JOB — JOB is CHARACTER*1. Specifies whether condition numbers are required for the cluster of eigenvalues (S) or the invariant subspace (SEP):
- = 'N': none;
- = 'E': for eigenvalues only (S);
- = 'V': for invariant subspace only (SEP);
- = 'B': for both eigenvalues and invariant subspace (S and SEP).
COMPQ — COMPQ is CHARACTER*1.
- = 'V': update the matrix Q of Schur vectors;
- = 'N': do not update Q.
SELECT — SELECT is LOGICAL array, dimension (N). SELECT specifies the eigenvalues in the selected cluster. To select the j-th eigenvalue, SELECT(j) must be set to .TRUE.. Pick your faves, bestie, but you gotta commit.
N — N is INTEGER. The order of the matrix T. N >= 0.
T — T is COMPLEX array, dimension (LDT,N). On entry, the upper triangular matrix T. On exit, T is overwritten by the reordered matrix T, with the selected eigenvalues as the leading diagonal elements. Glow-up on the diagonal, fr fr.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N).
Q — Q is COMPLEX array, dimension (LDQ,N). On entry, if COMPQ = 'V', the matrix Q of Schur vectors. On exit, if COMPQ = 'V', Q has been postmultiplied by the unitary transformation matrix which reorders T; the leading M columns of Q form an orthonormal basis for the specified invariant subspace. If COMPQ = 'N', Q is not referenced. Not referenced means she didn't even look at it, periodt.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= 1; and if COMPQ = 'V', LDQ >= N.
W — W is COMPLEX array, dimension (N). The reordered eigenvalues of T, in the same order as they appear on the diagonal of T. 🌸
M — M is INTEGER. The dimension of the specified invariant subspace. 0 <= M <= N.
S — S is REAL. If JOB = 'E' or 'B', S is a lower bound on the reciprocal condition number for the selected cluster of eigenvalues. S cannot underestimate the true reciprocal condition number by more than a factor of sqrt(N). If M = 0 or N, S = 1. If JOB = 'N' or 'V', S is not referenced.
SEP — SEP is REAL. If JOB = 'V' or 'B', SEP is the estimated reciprocal condition number of the specified invariant subspace. If M = 0 or N, SEP = norm(T). If JOB = 'N' or 'E', SEP is not referenced.
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. Sneaky little first entry, telling you the tea.
LWORK — LWORK is INTEGER. The dimension of the array WORK.
- If JOB = 'N', LWORK >= 1;
- if JOB = 'E', LWORK = max(1,M*(N-M));
- if JOB = 'V' or 'B', LWORK >= max(1,2*M*(N-M)).

INFO — INFO is 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 💜

      CTRSEN first collects the selected eigenvalues by computing a unitary
      transformation Z to move them to the top left corner of T. In other
      words, the selected eigenvalues are the eigenvalues of T11 in:

              Z**H * T * Z = ( T11 T12 ) n1
                             (  0  T22 ) n2
                                n1  n2

      where N = n1+n2. The first
      n1 columns of Z span the specified invariant subspace of T.

Ok so real talk: she's shoving the chosen eigenvalues up into that top-left corner and the rest just vibe in T22. 🦋

      If T has been obtained from the Schur factorization of a matrix
      A = Q*T*Q**H, then the reordered Schur factorization of A is given by
      A = (Q*Z)*(Z**H*T*Z)*(Q*Z)**H, and the first n1 columns of Q*Z span the
      corresponding invariant subspace of A.

      The reciprocal condition number of the average of the eigenvalues of
      T11 may be returned in S. S lies between 0 (very badly conditioned)
      and 1 (very well conditioned). It is computed as follows. First we
      compute R so that

                             P = ( I  R ) n1
                                 ( 0  0 ) n2
                                   n1 n2

      is the projector on the invariant subspace associated with T11.
      R is the solution of the Sylvester equation:

                            T11*R - R*T22 = T12.

      Let F-norm(M) denote the Frobenius-norm of M and 2-norm(M) denote
      the two-norm of M. Then S is computed as the lower bound

                          (1 + F-norm(R)**2)**(-1/2)

      on the reciprocal of 2-norm(P), the true reciprocal condition number.
      S cannot underestimate 1 / 2-norm(P) by more than a factor of
      sqrt(N).

      An approximate error bound for the computed average of the
      eigenvalues of T11 is

                             EPS * norm(T) / S

      where EPS is the machine precision.

S is a scale from 0 (very badly conditioned) to 1 (very well conditioned), and bestie, it will not lowball you by more than a factor of sqrt(N). Trust her. 🫶

      The reciprocal condition number of the right invariant subspace
      spanned by the first n1 columns of Z (or of Q*Z) is returned in SEP.
      SEP is defined as the separation of T11 and T22:

                         sep( T11, T22 ) = sigma-min( C )

      where sigma-min(C) is the smallest singular value of the
      n1*n2-by-n1*n2 matrix

         C  = kprod( I(n2), T11 ) - kprod( transpose(T22), I(n1) )

      I(m) is an m by m identity matrix, and kprod denotes the Kronecker
      product. We estimate sigma-min(C) by the reciprocal of an estimate of
      the 1-norm of inverse(C). The true reciprocal 1-norm of inverse(C)
      cannot differ from sigma-min(C) by more than a factor of sqrt(n1*n2).

      When SEP is small, small changes in T can cause large changes in
      the invariant subspace. An approximate bound on the maximum angular
      error in the computed right invariant subspace is

                          EPS * norm(T) / SEP

Heads up, bestie: when SEP is small, teeny tiny changes in T can cause huge changes in the invariant subspace. That's not a vibe. That's a warning. 😭

🌈 `ctrsna` 🌈

subroutine ctrsna (character JOB, character HOWMNY, logical, dimension( * )
    SELECT, integer N, complex, dimension( ldt, * ) T, integer LDT, complex,
    dimension( ldvl, * ) VL, integer LDVL, complex, dimension( ldvr, * ) VR,
    integer LDVR, real, dimension( * ) S, real, dimension( * ) SEP, integer
    MM, integer M, complex, dimension( ldwork, * ) WORK, integer LDWORK,
    real, dimension( * ) RWORK, integer INFO)

CTRSNA 🧚

✨ Purpose ✨

CTRSNA estimates reciprocal condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix T (or of any matrix Q*T*Q**H with Q unitary). She's here to tell you how shaky things are, and she's honest about it. 💅

🎀 Parameters 🎀

JOB — JOB is CHARACTER*1. Specifies whether condition numbers are required for eigenvalues (S) or eigenvectors (SEP):
- = 'E': for eigenvalues only (S);
- = 'V': for eigenvectors only (SEP);
- = 'B': for both eigenvalues and eigenvectors (S and SEP).
HOWMNY — HOWMNY is CHARACTER*1.
- = 'A': compute condition numbers for all eigenpairs;
- = 'S': compute condition numbers for selected eigenpairs specified by the array SELECT.
SELECT — SELECT is LOGICAL array, dimension (N). If HOWMNY = 'S', SELECT specifies the eigenpairs for which condition numbers are required. To select condition numbers for the j-th eigenpair, SELECT(j) must be set to .TRUE.. If HOWMNY = 'A', SELECT is not referenced. Only relevant when you're being picky, bestie.
N — N is INTEGER. The order of the matrix T. N >= 0.
T — T is COMPLEX array, dimension (LDT,N). The upper triangular matrix T. 🌸
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N).
VL
VL — a COMPLEX array, dimension (LDVL,M). If JOB = 'E' or 'B', VL has to hold the left eigenvectors of T (or of any Q*T*Q**H with Q unitary, we're not picky 💅), matching up with the eigenpairs that HOWMNY and SELECT picked out. Those eigenvectors gotta live in consecutive columns of VL, exactly like CHSEIN or CTREVC handed them back. If JOB = 'V', then bestie… VL is literally not referenced, it's just vibing 🦋
LDVL — LDVL is INTEGER. It's the leading dimension of the VL array. So: LDVL >= 1; and if JOB = 'E' or 'B', then LDVL >= N. No cap.
VR — a COMPLEX array, dimension (LDVR,M). If JOB = 'E' or 'B', VR must contain the right eigenvectors of T (or of any Q*T*Q**H with Q unitary), corresponding to the eigenpairs specified by HOWMNY and SELECT. Store them in consecutive columns of VR, as returned by CHSEIN or CTREVC. If JOB = 'V', VR is not referenced. Periodt. ✨
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= 1; and if JOB = 'E' or 'B', LDVR >= N.
S — S is a REAL array, dimension (MM). If JOB = 'E' or 'B', this is where the reciprocal condition numbers of the selected eigenvalues go, stored in consecutive elements of the array. So listen: S(j), SEP(j), and the j-th columns of VL and VR all correspond to the same eigenpair — but not, like, in general the j-th eigenpair, unless literally all eigenpairs got selected 🙈. If JOB = 'V', S is not referenced.
SEP — SEP is a REAL array, dimension (MM). If JOB = 'V' or 'B', this holds the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. If JOB = 'E', SEP is not referenced.
MM — MM is INTEGER. The number of elements in the arrays S (if JOB = 'E' or 'B') and/or SEP (if JOB = 'V' or 'B'). MM >= M. That's the rule, bestie.
M — M is INTEGER. The number of elements of the arrays S and/or SEP actually used to store the estimated condition numbers. And heads up: if HOWMNY = 'A', then M gets set to N. 🫶
WORK — WORK is a COMPLEX array, dimension (LDWORK,N+6). If JOB = 'E', WORK is not referenced.
LDWORK — LDWORK is INTEGER. The leading dimension of the array WORK. LDWORK >= 1; and if JOB = 'V' or 'B', LDWORK >= N.
RWORK — RWORK is a REAL array, dimension (N). If JOB = 'E', RWORK is not referenced.
INFO — INFO is INTEGER.
- = 0: successful exit, we ate and left no crumbs 🎀
- < 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 reciprocal of the condition number of an eigenvalue lambda is defined as

        S(lambda) = |v**H*u| / (norm(u)*norm(v))

where u and v are the right and left eigenvectors of T corresponding to lambda; v**H denotes the conjugate transpose of v, and norm(u) denotes the Euclidean norm. These reciprocal condition numbers always lie between zero (very badly conditioned 😭) and one (very well conditioned 👑). If n = 1, then S(lambda) is defined to be 1.

An approximate error bound for a computed eigenvalue W(i) is given by

                    EPS * norm(T) / S(i)

where EPS is the machine precision. Yes, that's the whole vibe.

The reciprocal of the condition number of the right eigenvector u corresponding to lambda is defined as follows. Suppose

            T = ( lambda  c  )
                (   0    T22 )

Then the reciprocal condition number is

        SEP( lambda, T22 ) = sigma-min( T22 - lambda*I )

where sigma-min denotes the smallest singular value. We approximate that smallest singular value by the reciprocal of an estimate of the one-norm of the inverse of T22 - lambda*I. And if n = 1, SEP(1) is defined to be abs(T(1,1)). Slay.

An approximate error bound for a computed right eigenvector VR(i) is given by

                    EPS * norm(T) / SEP(i)

subroutine `ctrti2` (character `UPLO`, character `DIAG`, integer `N`, complex, dimension( `lda`, * ) `A`, integer `LDA`, integer `INFO`)

CTRTI2 computes the inverse of a triangular matrix (unblocked algorithm). It's giving baby steps energy but it gets the job done 🧚

Purpose:

 CTRTI2 computes the inverse of a complex upper or lower triangular
 matrix.

 This is the Level 2 BLAS version of the algorithm.

Parameters

UPLO — UPLO is CHARACTER*1. Specifies whether the matrix A is upper or lower triangular.
- = 'U': Upper triangular
- = 'L': Lower triangular
DIAG — DIAG is CHARACTER*1. Specifies whether or not the matrix A is unit triangular.
- = 'N': Non-unit triangular
- = 'U': Unit triangular
N — N is INTEGER. The order of the matrix A. N >= 0.
A — A is COMPLEX array, dimension (LDA,N). On entry, the triangular matrix A. If UPLO = 'U', the leading n by n upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading n by n lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1. On exit, the (triangular) inverse of the original matrix, in the same storage format. ✨
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -k, the k-th argument had an illegal value

Author

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

subroutine `ctrtri` (character `UPLO`, character `DIAG`, integer `N`, complex, dimension( `lda`, * ) `A`, integer `LDA`, integer `INFO`)

CTRTRI — now this one is the glow-up version, bestie 💅

Purpose:

 CTRTRI computes the inverse of a complex upper or lower triangular
 matrix A.

 This is the Level 3 BLAS version of the algorithm.

Parameters

UPLO — UPLO is CHARACTER*1.
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — DIAG is CHARACTER*1.
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
A — A is COMPLEX array, dimension (LDA,N). On entry, the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1. On exit, the (triangular) inverse of the original matrix, in the same storage format. 🌸
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, A(i,i) is exactly zero. The triangular matrix is singular and its inverse can not be computed. 💀

Author

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

subroutine `ctrtrs` (character `UPLO`, character `TRANS`, character `DIAG`, integer `N`, integer `NRHS`, complex, dimension( `lda`, * ) `A`, integer `LDA`, complex, dimension( `ldb`, * ) `B`, integer `LDB`, integer `INFO`)

CTRTRS — solving systems, the main character moment 👑

Purpose:

 CTRTRS solves a triangular system of the form

    A * X = B,  A**T * X = B,  or  A**H * X = B,

 where A is a triangular matrix of order N, and B is an N-by-NRHS
 matrix.  A check is made to verify that A is nonsingular.

Parameters

UPLO — UPLO is CHARACTER*1.
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1. Specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — DIAG is CHARACTER*1.
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
A — A is COMPLEX array, dimension (LDA,N). The triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1. 🦋
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — B is COMPLEX array, dimension (LDB,NRHS).
B — a COMPLEX array, dimension (LDB,NRHS). On entry, this is the right hand side matrix B. On exit, if INFO = 0, it's the solution matrix X. ✨
LDB — INTEGER. The leading dimension of the array B. Constraint: LDB >= max(1,N). 💅
INFO — INTEGER, bestie, and here's the tea:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭
- > 0: if INFO = i, the i-th diagonal element of A is zero, indicating that the matrix is singular and the solutions X have not been computed 💀

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 subroutine `ctrttf` 🦋

subroutine ctrttf (character TRANSR, character UPLO, integer N, complex,
    dimension( 0: lda-1, 0: * ) A, integer LDA, complex, dimension( 0: * )
    ARF, integer INFO)

CTRTTF copies a triangular matrix from the standard full format (TR) to the rectangular full packed format (TF). It's giving glow-up, but for storage layouts 💖

🌸 Purpose 🌸

CTRTTF copies a triangular matrix A from standard full format (TR) to rectangular full packed format (TF).

✨ Parameters ✨

TRANSR — CHARACTER*1
- = 'N': ARF in Normal mode is wanted;
- = 'C': ARF in Conjugate Transpose mode is wanted;
UPLO — CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — INTEGER. The order of the matrix A. Constraint: N >= 0.
A — a COMPLEX array, dimension ( LDA, N ). On entry, the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced.
LDA — INTEGER. The leading dimension of the matrix A. Constraint: LDA >= max(1,N).
ARF — a COMPLEX array, dimension ( N*(N+1)/2 ). On exit, the upper or lower triangular matrix A stored in RFP format. For a further discussion see Notes below. 🫶
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 🌈

We first consider Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

  00 01 02 03 04 05       00
     11 12 13 14 15       10 11
        22 23 24 25       20 21 22
           33 34 35       30 31 32 33
              44 45       40 41 42 43 44
                 55       50 51 52 53 54 55

        RFP A                   RFP A

                               -- -- --
       03 04 05                33 43 53
                                  -- --
       13 14 15                00 44 54
                                     --
       23 24 25                10 11 55

       33 34 35                20 21 22
       --
       00 44 45                30 31 32
       -- --
       01 11 55                40 41 42
       -- -- --
       02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

          RFP A                   RFP A

    -- -- -- --                -- -- -- -- -- --
    03 13 23 33 00 01 02    33 00 10 20 30 40 50
    -- -- -- -- --                -- -- -- -- --
    04 14 24 34 44 11 12    43 44 11 21 31 41 51
    -- -- -- -- -- --                -- -- -- --
    05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

    AP is Upper                 AP is Lower

  00 01 02 03 04              00
     11 12 13 14              10 11
        22 23 24              20 21 22
           33 34              30 31 32 33
              44              40 41 42 43 44

        RFP A                   RFP A

                                  -- --
       02 03 04                00 33 43
                                     --
       12 13 14                10 11 44

       22 23 24                20 21 22
       --
       00 33 34                30 31 32
       -- --
       01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

          RFP A                   RFP A

    -- -- --                   -- -- -- -- -- --
    02 12 22 00 01             00 10 20 30 40 50
    -- -- -- --                   -- -- -- -- --
    03 13 23 33 11             33 11 21 31 41 51
    -- -- -- -- --                   -- -- -- --
    04 14 24 34 44             43 44 22 32 42 52

🎀 subroutine `ctrttp` 🎀

subroutine ctrttp (character UPLO, integer N, complex, dimension( lda, * )
    A, integer LDA, complex, dimension( * ) AP, integer INFO)

CTRTTP copies a triangular matrix from the standard full format (TR) to the standard packed format (TP). Same energy, different layout 💅

🌸 Purpose 🌸

CTRTTP copies a triangular matrix A from full format (TR) to standard packed format (TP).

✨ Parameters ✨

UPLO — CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — INTEGER. The order of the matrices AP and A. Constraint: N >= 0.
A — a COMPLEX array, dimension (LDA,N). On entry, the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced.
LDA — INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,N).
AP — a COMPLEX array, dimension ( N*(N+1)/2 ). On exit, the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
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.

⭐ subroutine `ctzrzf` ⭐

subroutine ctzrzf (integer M, integer N, complex, dimension( lda, * ) A,
    integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK,
    integer LWORK, integer INFO)

CTZRZF — no cap, this one's the moment ✨

🌸 Purpose 🌸

CTZRZF reduces the M-by-N ( M<=N ) complex upper trapezoidal matrix A to upper triangular form by means of unitary transformations.

The upper trapezoidal matrix A is factored as

   A = ( R  0 ) * Z,

where Z is an N-by-N unitary matrix and R is an M-by-M upper triangular matrix.

✨ Parameters ✨

M — INTEGER. The number of rows of the matrix A. Constraint: M >= 0.
N — INTEGER. The number of columns of the matrix A. Constraint: N >= M.
A — a COMPLEX array, dimension (LDA,N). On entry, the leading M-by-N upper trapezoidal part of the array A must contain the matrix to be factorized. On exit, the leading M-by-M upper triangular part of A contains the upper triangular matrix R, and elements M+1 to N of the first M rows of A, with the array TAU, represent the unitary matrix Z as a product of M elementary reflectors. 🦋
LDA — INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,M).
TAU — a COMPLEX array, dimension (M). The scalar factors of the elementary reflectors.
WORK — a COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 👑
LWORK — INTEGER. The dimension of the array WORK. Constraint: LWORK >= max(1,M). For optimum performance LWORK >= M*NB, where NB is the optimal blocksize.

INFO — INFO is INTEGER. = 0: successful exit. < 0: if INFO = -i, the i-th argument had an illegal value. So 0 is slay, negative means one of your args was acting up.

Author 🌟

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

Contributors 💖

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details 🔍

The N-by-N matrix Z can be computed by

Z =  Z(1)*Z(2)* ... *Z(M)

where each N-by-N Z(k) is given by

Z(k) = I - tau(k)*v(k)*v(k)**H

with v(k) is the kth row vector of the M-by-N matrix

V = ( I   A(:,M+1:N) )

I is the M-by-M identity matrix, A(:,M+1:N) is the output stored in A on exit from CTZRZF, and tau(k) is the kth element of the array TAU. It's giving matrix glow-up, fr fr.

`CUNBDB` 💅

subroutine cunbdb (character TRANS, character SIGNS, integer M, integer P,
    integer Q, complex, dimension( ldx11, * ) X11, integer LDX11, complex,
    dimension( ldx12, * ) X12, integer LDX12, complex, dimension( ldx21, * )
    X21, integer LDX21, complex, dimension( ldx22, * ) X22, integer LDX22,
    real, dimension( * ) THETA, real, dimension( * ) PHI, complex,
    dimension( * ) TAUP1, complex, dimension( * ) TAUP2, complex, dimension(
    * ) TAUQ1, complex, dimension( * ) TAUQ2, complex, dimension( * ) WORK,
    integer LWORK, integer INFO)
    CUNBDB

Purpose 🎯

CUNBDB simultaneously bidiagonalizes the blocks of an M-by-M partitioned unitary matrix X:

                                        [ B11 | B12 0  0 ]
            [ X11 | X12 ]   [ P1 |    ] [  0  |  0 -I  0 ] [ Q1 |    ]**H
        X = [-----------] = [---------] [----------------] [---------]   .
            [ X21 | X22 ]   [    | P2 ] [ B21 | B22 0  0 ] [    | Q2 ]
                                        [  0  |  0  0  I ]

X11 is P-by-Q. Q must be no larger than P, M-P, or M-Q. (If this is not the case, then X must be transposed and/or permuted. This can be done in constant time using the TRANS and SIGNS options. See CUNCSD for details.)

The unitary matrices P1, P2, Q1, and Q2 are P-by-P, (M-P)-by-(M-P), Q-by-Q, and (M-Q)-by-(M-Q), respectively. They are represented implicitly by Householder vectors.

B11, B12, B21, and B22 are Q-by-Q bidiagonal matrices represented implicitly by angles THETA, PHI.

Parameters ✨

TRANS — TRANS is CHARACTER. = 'T': X, U1, U2, V1T, and V2T are stored in row-major order; otherwise: X, U1, U2, V1T, and V2T are stored in column-major order.
SIGNS — SIGNS is CHARACTER. = 'O': The lower-left block is made nonpositive (the 'other' convention); otherwise: The upper-right block is made nonpositive (the 'default' convention).
M — M is INTEGER. The number of rows and columns in X.
P — P is INTEGER. The number of rows in X11 and X12. 0 <= P <= M.
Q — Q is INTEGER. The number of columns in X11 and X21. 0 <= Q <= MIN(P,M-P,M-Q).
X11 — X11 is COMPLEX array, dimension (LDX11,Q). On entry, the top-left block of the unitary matrix to be reduced. On exit, the form depends on TRANS:
- If TRANS = 'N', then the columns of tril(X11) specify reflectors for P1, the rows of triu(X11,1) specify reflectors for Q1;
- else TRANS = 'T', and the rows of triu(X11) specify reflectors for P1, the columns of tril(X11,-1) specify reflectors for Q1.
LDX11 — LDX11 is INTEGER. The leading dimension of X11. If TRANS = 'N', then LDX11 >= P; else LDX11 >= Q.
X12 — X12 is COMPLEX array, dimension (LDX12,M-Q). On entry, the top-right block of the unitary matrix to be reduced. On exit, the form depends on TRANS:
- If TRANS = 'N', then the rows of triu(X12) specify the first P reflectors for Q2;
- else TRANS = 'T', and the columns of tril(X12) specify the first P reflectors for Q2.
LDX12 — LDX12 is INTEGER. The leading dimension of X12. If TRANS = 'N', then LDX12 >= P; else LDX11 >= M-Q.
X21 — X21 is COMPLEX array, dimension (LDX21,Q). On entry, the bottom-left block of the unitary matrix to be reduced. On exit, the form depends on TRANS:
- If TRANS = 'N', then the columns of tril(X21) specify reflectors for P2;
- else TRANS = 'T', and the rows of triu(X21) specify reflectors for P2.
LDX21 — LDX21 is INTEGER. The leading dimension of X21. If TRANS = 'N', then LDX21 >= M-P; else LDX21 >= Q.
X22 — X22 is COMPLEX array, dimension (LDX22,M-Q). On entry, the bottom-right block of the unitary matrix to be reduced. On exit, the form depends on TRANS:
- If TRANS = 'N', then the rows of triu(X22(Q+1:M-P,P+1:M-Q)) specify the last M-P-Q reflectors for Q2,
- else TRANS = 'T', and the columns of tril(X22(P+1:M-Q,Q+1:M-P)) specify the last M-P-Q reflectors for P2.
LDX22 — LDX22 is INTEGER. The leading dimension of X22. If TRANS = 'N', then LDX22 >= M-P; else LDX22 >= M-Q.
THETA — THETA is REAL array, dimension (Q). The entries of the bidiagonal blocks B11, B12, B21, B22 can be computed from the angles THETA and PHI. See Further Details.
PHI — PHI is REAL array, dimension (Q-1). The entries of the bidiagonal blocks B11, B12, B21, B22 can be computed from the angles THETA and PHI. See Further Details.
TAUP1 — TAUP1 is COMPLEX array, dimension (P). The scalar factors of the elementary reflectors that define P1.
TAUP2 — TAUP2 is COMPLEX array, dimension (M-P). 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.
TAUQ2 — TAUQ2 is COMPLEX array, dimension (M-Q). The scalar factors of the elementary reflectors that define Q2.
WORK — WORK is COMPLEX array, dimension (LWORK).
LWORK — LWORK is 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 — INFO is 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 bidiagonal blocks B11, B12, B21, and B22 are represented implicitly by angles THETA(1), ..., THETA(Q) and PHI(1), ..., PHI(Q-1). B11 and B21 are upper bidiagonal, while B21 and B22 are lower bidiagonal. 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.

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

References 📚

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

`CUNBDB1` ✨

subroutine cunbdb1 (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)
    CUNBDB1

Purpose 🎯

CUNBDB1 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X with orthonomal columns:

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

X11 is P-by-Q, and X21 is (M-P)-by-Q. Q must be no larger than P, M-P, or M-Q. Routines CUNBDB2, CUNBDB3, and CUNBDB4 handle cases in which 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 Q-by-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. 0 <= P <= M.
Q — Q is INTEGER. The number of columns in X11 and X21. 0 <= Q <= MIN(P,M-P,M-Q).
X11 — X11 is COMPLEX 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. LDX11 >= P.
X21 —
X21 — okay so this is a COMPLEX array, dimension (LDX21,Q). On entry, it's the bottom block of the matrix X that's about to get reduced. On exit, the columns of tril(X21) specify reflectors for P2. 💅
LDX21 — LDX21 is INTEGER. The leading dimension of X21. LDX21 >= M-P. periodt. ✨
THETA — THETA is REAL array, dimension (Q). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details. 🦋
PHI — PHI is REAL array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details. 🌸
TAUP1 — TAUP1 is COMPLEX array, dimension (P). The scalar factors of the elementary reflectors that define P1. 💖
TAUP2 — TAUP2 is COMPLEX array, dimension (M-P). 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). 🎀
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= M-Q. no cap.

INFO — INFO is 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 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.

subroutine cunbdb2

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)

CUNBDB2

Purpose

CUNBDB2 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X with orthonomal columns:

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

X11 is P-by-Q, and X21 is (M-P)-by-Q. P must be no larger than M-P, Q, or M-Q. Routines CUNBDB1, CUNBDB3, and CUNBDB4 handle cases in which 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 P-by-P 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. 0 <= P <= min(M-P,Q,M-Q). 🫶
Q — Q is INTEGER. The number of columns in X11 and X21. 0 <= Q <= M. ✨
X11 — X11 is COMPLEX 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. 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. 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. 🌈
PHI — PHI is REAL array, dimension (Q-1). 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). 💖
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= M-Q.

INFO — INFO is 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

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.

subroutine cunbdb3

subroutine cunbdb3 (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)

CUNBDB3

Purpose

CUNBDB3 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X with orthonomal 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 CUNBDB1, CUNBDB2, and CUNBDB4 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. 🌸

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. 0 <= P <= M. M-P <= min(P,Q,M-Q). ⭐
Q — Q is INTEGER. The number of columns in X11 and X21. 0 <= Q <= M. ✨
X11 — X11 is COMPLEX 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. 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. 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. 🌈
PHI — PHI is REAL array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details. ⭐
TAUP1 — TAUP1 is COMPLEX array, dimension (P). The scalar factors of the elementary reflectors that define P1. 💜
TAUP2 — TAUP2 is COMPLEX array, dimension (M-P). 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). 💖
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= M-Q.

INFO
INFO — INTEGER 💅
- = 0: successful exit, periodt. ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. not slay. 😭

✨ Author ✨

The absolute legends behind this:

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

✨ Further 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.

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

CUNBDB4 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X with orthonomal 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 CUNBDB1, CUNBDB2, and CUNBDB3 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 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 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 — COMPLEX array, dimension (M-Q). The scalar factors of the elementary reflectors that define P1. 🌈
TAUP2 — COMPLEX array, dimension (M-Q). The scalar factors of the elementary reflectors that define P2. ⭐
TAUQ1 — COMPLEX array, dimension (Q). The scalar factors of the elementary reflectors that define Q1. 👑
PHANTOM — 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. 💀
WORK — COMPLEX 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. big yikes. 😭

✨ Author ✨

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

✨ Further 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.

CUNBDB5

   subroutine cunbdb5 (integer M1, integer M2, integer N, complex, dimension(*)
       X1, integer INCX1, complex, dimension(*) X2, integer INCX2, complex,
       dimension(ldq1,*) Q1, integer LDQ1, complex, dimension(ldq2,*) Q2,
       integer LDQ2, complex, dimension(*) WORK, integer LWORK, integer INFO)
       CUNBDB5

Purpose

CUNBDB5 orthogonalizes the column vector

     X = [ X1 ]
         [ X2 ]

with respect to the columns of

     Q = [ Q1 ] .
         [ Q2 ]

The columns of Q must be orthonormal. 💅

If the projection is zero according to Kahan's 'twice is enough' criterion, then some other vector from the orthogonal complement is returned. This vector is chosen in an arbitrary but deterministic way. ✨

Parameters

M1 — INTEGER. The dimension of X1 and the number of rows in Q1. 0 <= M1. 🌸
M2 — INTEGER. The dimension of X2 and the number of rows in Q2. 0 <= M2. 🦋
N — INTEGER. The number of columns in Q1 and Q2. 0 <= N. 🎀
X1 — COMPLEX array, dimension (M1). On entry, the top part of the vector to be orthogonalized. On exit, the top part of the projected vector. 💖
INCX1 — INTEGER. Increment for entries of X1. ✨
X2 — COMPLEX array, dimension (M2). On entry, the bottom part of the vector to be orthogonalized. On exit, the bottom part of the projected vector. 🫶
INCX2 — INTEGER. Increment for entries of X2. 💅
Q1 — COMPLEX array, dimension (LDQ1, N). The top part of the orthonormal basis matrix. 🔥
LDQ1 — INTEGER. The leading dimension of Q1. LDQ1 >= M1. 😭
Q2 — COMPLEX array, dimension (LDQ2, N). The bottom part of the orthonormal basis matrix. 🌈
LDQ2 — INTEGER. The leading dimension of Q2. LDQ2 >= M2. ⭐
WORK — COMPLEX array, dimension (LWORK). 👑
LWORK — INTEGER. The dimension of the array WORK. LWORK >= N. 💀
INFO — INTEGER. 🙈
- = 0: successful exit. ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. oop. 😭

✨ Author ✨

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

CUNBDB6

   subroutine cunbdb6 (integer M1, integer M2, integer N, complex, dimension(*)
       X1, integer INCX1, complex, dimension(*) X2, integer INCX2, complex,
       dimension(ldq1,*) Q1, integer LDQ1, complex, dimension(ldq2,*) Q2,
       integer LDQ2, complex, dimension(*) WORK, integer LWORK, integer INFO)
       CUNBDB6

Purpose

CUNBDB6 orthogonalizes the column vector

     X = [ X1 ]
         [ X2 ]

with respect to the columns of

     Q = [ Q1 ] .
         [ Q2 ]

The Euclidean norm of X must be one and the columns of Q must be orthonormal. The orthogonalized vector will be zero if and only if it lies entirely in the range of Q. 💅

The projection is computed with at most two iterations of the classical Gram-Schmidt algorithm, see

L. Giraud, J. Langou, M. Rozložník. 'On the round-off error analysis of the Gram-Schmidt algorithm with reorthogonalization.' 2002. CERFACS Technical Report No. TR/PA/02/33. URL: https://www.cerfacs.fr/algor/reports/2002/TR_PA_02_33.pdf

Parameters

M1 — INTEGER. The dimension of X1 and the number of rows in Q1. 0 <= M1. 🌸
M2 — INTEGER. The dimension of X2 and the number of rows in Q2. 0 <= M2. 🦋
N — INTEGER. The number of columns in Q1 and Q2. 0 <= N. 🎀
X1 — COMPLEX array, dimension (M1). On entry, the top part of the vector to be orthogonalized. On exit, the top part of the projected vector. 💖
INCX1 — INTEGER. Increment for entries of X1. ✨
X2 — COMPLEX array, dimension (M2). On entry, the bottom part of the vector to be orthogonalized. On exit, the bottom part of the projected vector. 🫶
INCX2 — INTEGER. Increment for entries of X2. 💅
Q1 — COMPLEX array, dimension (LDQ1, N). The top part of the orthonormal basis matrix. 🔥
LDQ1 — INTEGER. The leading dimension of Q1. LDQ1 >= M1. 😭
Q2
Q2 — a COMPLEX array, dimension (LDQ2, N). It's the bottom part of the orthonormal basis matrix. slay 💅
LDQ2 — LDQ2 is INTEGER. It's the leading dimension of Q2, and bestie, LDQ2 >= M2, no cap.
WORK — WORK is a COMPLEX array, dimension (LWORK).
LWORK — LWORK is INTEGER. It's the dimension of the array WORK, and LWORK >= N. that's the vibe check right there ✨
INFO — INFO is INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. like, something you passed in was simply not it 😭

🦋 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

✨ recursive subroutine cuncsd

recursive subroutine cuncsd (character JOBU1, character JOBU2, character
    JOBV1T, character JOBV2T, character TRANS, character SIGNS, integer M,
    integer P, integer Q, complex, dimension( ldx11, * ) X11, integer LDX11,
    complex, dimension( ldx12, * ) X12, integer LDX12, complex, dimension(
    ldx21, * ) X21, integer LDX21, complex, dimension( ldx22,
    * ) X22, integer LDX22, real, dimension( * ) THETA, complex, dimension(
    ldu1, * ) U1, integer LDU1, complex, dimension( ldu2, * ) U2, integer
    LDU2, complex, dimension( ldv1t, * ) V1T, integer LDV1T, complex,
    dimension( ldv2t, * ) V2T, integer LDV2T, complex, dimension( * ) WORK,
    integer LWORK, real, dimension( * ) RWORK, integer LRWORK, integer,
    dimension( * ) IWORK, integer INFO)

CUNCSD 👑

Purpose:

CUNCSD computes the CS decomposition of an M-by-M partitioned unitary matrix X:

                                        [  I  0  0 |  0  0  0 ]
                                        [  0  C  0 |  0 -S  0 ]
            [ X11 | X12 ]   [ U1 |    ] [  0  0  0 |  0  0 -I ] [ V1 |    ]**H
        X = [-----------] = [---------] [---------------------] [---------]   .
            [ X21 | X22 ]   [    | U2 ] [  0  0  0 |  I  0  0 ] [    | V2 ]
                                        [  0  S  0 |  0  C  0 ]
                                        [  0  0  I |  0  0  0 ]

So here's the tea: X11 is P-by-Q. The unitary matrices U1, U2, V1, and V2 are P-by-P, (M-P)-by-(M-P), Q-by-Q, and (M-Q)-by-(M-Q), respectively. And C and S? They're R-by-R nonnegative diagonal matrices satisfying C^2 + S^2 = I, in which R = MIN(P,M-P,Q,M-Q). iconic math fr fr 💖

Parameters

JOBU1 — JOBU1 is CHARACTER:
- = 'Y': U1 is computed;
- otherwise: U1 is not computed.
JOBU2 — JOBU2 is CHARACTER:
- = 'Y': U2 is computed;
- otherwise: U2 is not computed.
JOBV1T — JOBV1T is CHARACTER:
- = 'Y': V1T is computed;
- otherwise: V1T is not computed.
JOBV2T — JOBV2T is CHARACTER:
- = 'Y': V2T is computed;
- otherwise: V2T is not computed.
TRANS — TRANS is CHARACTER:
- = 'T': X, U1, U2, V1T, and V2T are stored in row-major order;
- otherwise: X, U1, U2, V1T, and V2T are stored in column-major order.
SIGNS — SIGNS is CHARACTER:
- = 'O': the lower-left block is made nonpositive (the 'other' convention);
- otherwise: the upper-right block is made nonpositive (the 'default' convention).
M — M is INTEGER. It's the number of rows and columns in X. periodt 💅
P — P is INTEGER. The number of rows in X11 and X12. 0 <= P <= M.
Q — Q is INTEGER. The number of columns in X11 and X21. 0 <= Q <= M.
X11 — X11 is a COMPLEX array, dimension (LDX11,Q). On entry, part of the unitary matrix whose CSD is desired.
LDX11 — LDX11 is INTEGER. The leading dimension of X11. LDX11 >= MAX(1,P).
X12 — X12 is a COMPLEX array, dimension (LDX12,M-Q). On entry, part of the unitary matrix whose CSD is desired.
LDX12 — LDX12 is INTEGER. The leading dimension of X12. LDX12 >= MAX(1,P).
X21 — X21 is a COMPLEX array, dimension (LDX21,Q). On entry, part of the unitary matrix whose CSD is desired.
LDX21 — LDX21 is INTEGER. The leading dimension of X11. LDX21 >= MAX(1,M-P).
X22 — X22 is a COMPLEX array, dimension (LDX22,M-Q). On entry, part of the unitary matrix whose CSD is desired.
LDX22 — LDX22 is INTEGER. The leading dimension of X11. LDX22 >= MAX(1,M-P).
THETA — THETA is a 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 — U1 is a COMPLEX array, dimension (LDU1,P). If JOBU1 = 'Y', U1 contains the P-by-P unitary matrix U1.
LDU1 — LDU1 is INTEGER. The leading dimension of U1. If JOBU1 = 'Y', LDU1 >= MAX(1,P).
U2 — U2 is a COMPLEX array, dimension (LDU2,M-P). If JOBU2 = 'Y', U2 contains the (M-P)-by-(M-P) unitary matrix U2.
LDU2 — LDU2 is INTEGER. The leading dimension of U2. If JOBU2 = 'Y', LDU2 >= MAX(1,M-P).
V1T — V1T is a COMPLEX array, dimension (LDV1T,Q). If JOBV1T = 'Y', V1T contains the Q-by-Q matrix unitary matrix V1**H.
LDV1T — LDV1T is INTEGER. The leading dimension of V1T. If JOBV1T = 'Y', LDV1T >= MAX(1,Q).
V2T — V2T is a COMPLEX array, dimension (LDV2T,M-Q). If JOBV2T = 'Y', V2T contains the (M-Q)-by-(M-Q) unitary matrix V2**H.
LDV2T — LDV2T is INTEGER. The leading dimension of V2T. If JOBV2T = 'Y', LDV2T >= MAX(1,M-Q).
WORK — WORK is a COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 🫶
LWORK — 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.

RWORK — RWORK is a REAL array, dimension MAX(1,LRWORK). On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. 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 — LRWORK is INTEGER. The dimension of the array RWORK.

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the RWORK array, returns this value as the first entry of the work array, and no error message related to LRWORK is issued by XERBLA.

IWORK — IWORK is an INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q)).
INFO — INFO is INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: CBBCSD did not converge. See the description of RWORK above for details. not it, bestie 😭

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.

🌸 subroutine 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:

CUNCSD2BY1 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). the way that math just works? obsessed 💜

Parameters

JOBU1 — JOBU1 is CHARACTER:
- = 'Y': U1 is computed;
- otherwise: U1 is not computed.
JOBU2 — JOBU2 is CHARACTER:
- = 'Y': U2 is computed;
- otherwise: U2 is not computed.
JOBV1T — JOBV1T is CHARACTER:
- = 'Y': V1T is computed;
- otherwise: V1T is not computed.
M — M is INTEGER. The number of rows in X.
P — P is INTEGER. The number of rows in X11. 0 <= P <= M.
Q — Q is INTEGER. The number of columns in X11 and X21. 0 <= Q <= M.
X11 — X11 is a COMPLEX array, dimension (LDX11,Q). On entry, part of the unitary matrix whose CSD is desired.
LDX11 — LDX11 is INTEGER. The leading dimension of X11. LDX11 >= MAX(1,P).
X21

X21 — bestie, X21 is a COMPLEX array, dimension (LDX21,Q). On entry, it’s part of the unitary matrix whose CSD is desired. 💅

LDX21 — LDX21 is INTEGER. The leading dimension of X21. LDX21 >= MAX(1,M-P). no cap.

THETA — 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 — U1 is COMPLEX array, dimension (P). If JOBU1 = 'Y', U1 contains the P-by-P unitary matrix U1. 👑

LDU1 — LDU1 is INTEGER. The leading dimension of U1. If JOBU1 = 'Y', LDU1 >= MAX(1,P). 💖

U2 — U2 is COMPLEX array, dimension (M-P). If JOBU2 = 'Y', U2 contains the (M-P)-by-(M-P) unitary matrix U2. 🦋

LDU2 — LDU2 is INTEGER. The leading dimension of U2. If JOBU2 = 'Y', LDU2 >= MAX(1,M-P). 🌸

V1T — V1T is COMPLEX array, dimension (Q). If JOBV1T = 'Y', V1T contains the Q-by-Q matrix unitary matrix V1**T. 🎀

LDV1T — LDV1T is INTEGER. The leading dimension of V1T. If JOBV1T = 'Y', LDV1T >= MAX(1,Q). 💜

WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 🔥

LWORK — 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 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. 😭

RWORK — RWORK is REAL array, dimension (MAX(1,LRWORK)). On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. 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 — LRWORK is INTEGER. The dimension of the array RWORK.

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 — IWORK is INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q)). 🍓

INFO — INFO is INTEGER.

= 0: successful exit. 🎉
< 0: if INFO = -i, the i-th argument had an illegal value. 🚨
> 0: CBBCSD 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.

subroutine cung2l (integer M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer INFO)

   subroutine cung2l (integer M, integer N, integer K, complex, dimension( lda,
       * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * )
       WORK, integer INFO)

CUNG2L generates all or part of the unitary matrix Q from a QL factorization determined by cgeqlf (unblocked algorithm).

Purpose:

CUNG2L generates an m by n complex matrix Q with orthonormal columns, which is defined as the last n columns of a product of k elementary reflectors of order m

      Q  =  H(k) . . . H(2) H(1)

as returned by CGEQLF.

Parameters

M — M is INTEGER. The number of rows of the matrix Q. M >= 0.
N — N is INTEGER. The number of columns of the matrix Q. M >= N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
A — A is COMPLEX array, dimension (LDA,N). On entry, the (n-k+i)-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGEQLF in the last k columns of its array argument A. On exit, the m-by-n matrix Q. 💅
LDA — LDA is INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEQLF.
WORK — WORK is COMPLEX array, dimension (N).
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument has an illegal value

Author

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

subroutine cung2r (integer M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer INFO)

   subroutine cung2r (integer M, integer N, integer K, complex, dimension( lda,
       * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * )
       WORK, integer INFO)

CUNG2R

Purpose:

CUNG2R generates an m by n complex matrix Q with orthonormal columns, which is defined as the first n columns of a product of k elementary reflectors of order m

      Q  =  H(1) H(2) . . . H(k)

as returned by CGEQRF.

Parameters

M — M is INTEGER. The number of rows of the matrix Q. M >= 0.
N — N is INTEGER. The number of columns of the matrix Q. M >= N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
A — A is COMPLEX array, dimension (LDA,N). On entry, the i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGEQRF in the first k columns of its array argument A. On exit, the m by n matrix Q. ✨
LDA — LDA is INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEQRF.
WORK — WORK is COMPLEX array, dimension (N).
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument has an illegal value

Author

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

subroutine cunghr (integer N, integer ILO, integer IHI, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer LWORK, integer INFO)

   subroutine cunghr (integer N, integer ILO, integer IHI, complex, dimension(
       lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex,
       dimension( * ) WORK, integer LWORK, integer INFO)

CUNGHR

Purpose:

CUNGHR generates a complex unitary matrix Q which is defined as the product of IHI-ILO elementary reflectors of order N, as returned by CGEHRD:

      Q = H(ilo) H(ilo+1) . . . H(ihi-1).

Parameters

N — N is INTEGER. The order of the matrix Q. N >= 0.
ILO — ILO is INTEGER.
IHI — IHI is INTEGER. ILO and IHI must have the same values as in the previous call of CGEHRD. Q is equal to the unit matrix except in the submatrix Q(ilo+1:ihi,ilo+1:ihi). 1 <= ILO <= IHI <= N, if N > 0; ILO=1 and IHI=0, if N=0.
A — A is COMPLEX array, dimension (LDA,N). On entry, the vectors which define the elementary reflectors, as returned by CGEHRD. On exit, the N-by-N unitary matrix Q. 👑
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
TAU — TAU is COMPLEX array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEHRD.
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= IHI-ILO. For optimum performance LWORK >= (IHI-ILO)*NB, where NB is the optimal blocksize.

INFO — INFO is 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.

subroutine cungl2 (integer M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer INFO)

   subroutine cungl2 (integer M, integer N, integer K, complex, dimension( lda,
       * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * )
       WORK, integer INFO)

CUNGL2 generates all or part of the unitary matrix Q from an LQ factorization determined by cgelqf (unblocked algorithm).

Purpose:

CUNGL2 generates an m-by-n complex matrix Q with orthonormal rows, which is defined as the first m rows of a product of k elementary reflectors of order n

      Q  =  H(k)**H . . . H(2)**H H(1)**H

as returned by CGELQF.

Parameters

M — M is INTEGER. The number of rows of the matrix Q. M >= 0.
N — N is INTEGER. The number of columns of the matrix Q. N >= M.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
A —
A — okay bestie, this is a COMPLEX array with dimension (LDA,N). On entry, the i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGELQF in the first k rows of its array argument A. On exit? It's giving the m by n matrix Q. 💅
LDA — INTEGER energy. The first dimension of the array A. LDA >= max(1,M). No cap.
TAU — COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGELQF. Periodt.
WORK — COMPLEX array, dimension (M). She's just here for the vibes.
INFO — INTEGER. = 0: successful exit. < 0: if INFO = -i, the i-th argument has an illegal value. 🚨

Author

Shoutout to the icons who wrote this:

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

subroutine cunglq

subroutine cunglq (integer M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNGLQ

Purpose:

CUNGLQ generates an M-by-N complex matrix Q with orthonormal rows, which is defined as the first M rows of a product of K elementary reflectors of order N

Q  =  H(k)**H . . . H(2)**H H(1)**H

as returned by CGELQF. Slay. ✨

Parameters

M — INTEGER. The number of rows of the matrix Q. M >= 0.
N — INTEGER. The number of columns of the matrix Q. N >= M.
K — INTEGER. The number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
A — COMPLEX array, dimension (LDA,N). On entry, the i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGELQF in the first k rows of its array argument A. On exit, the M-by-N matrix Q. Iconic.
LDA — INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGELQF.
WORK — COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — INTEGER. The dimension of the array WORK. LWORK >= max(1,M). For optimum performance LWORK >= M*NB, where NB is the optimal blocksize. 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 has an illegal value.

Author

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

subroutine cungql

subroutine cungql (integer M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNGQL

Purpose:

CUNGQL generates an M-by-N complex matrix Q with orthonormal columns, which is defined as the last N columns of a product of K elementary reflectors of order M

Q  =  H(k) . . . H(2) H(1)

as returned by CGEQLF. She's serving. 💅

Parameters

M — INTEGER. The number of rows of the matrix Q. M >= 0.
N — INTEGER. The number of columns of the matrix Q. M >= N >= 0.
K — INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
A — COMPLEX array, dimension (LDA,N). On entry, the (n-k+i)-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGEQLF in the last k columns of its array argument A. On exit, the M-by-N matrix Q.
LDA — INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEQLF.
WORK — COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — INTEGER. The dimension of the array WORK. LWORK >= max(1,N). For optimum performance LWORK >= N*NB, where NB is the optimal blocksize. 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 has an illegal value.

Author

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

subroutine cungqr

subroutine cungqr (integer M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNGQR

Purpose:

CUNGQR generates an M-by-N complex matrix Q with orthonormal columns, which is defined as the first N columns of a product of K elementary reflectors of order M

Q  =  H(1) H(2) . . . H(k)

as returned by CGEQRF. No cap, she ate. 🔥

Parameters

M — INTEGER. The number of rows of the matrix Q. M >= 0.
N — INTEGER. The number of columns of the matrix Q. M >= N >= 0.
K — INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
A — COMPLEX array, dimension (LDA,N). On entry, the i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGEQRF in the first k columns of its array argument A. On exit, the M-by-N matrix Q.
LDA — INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEQRF.
WORK — COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — INTEGER. The dimension of the array WORK. LWORK >= max(1,N). For optimum performance LWORK >= N*NB, where NB is the optimal blocksize. 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 has an illegal value.

Author

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

subroutine cungr2

subroutine cungr2 (integer M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer INFO)

CUNGR2 generates all or part of the unitary matrix Q from an RQ factorization determined by cgerqf (unblocked algorithm).

Purpose:

CUNGR2 generates an m by n complex matrix Q with orthonormal rows, which is defined as the last m rows of a product of k elementary reflectors of order n

Q  =  H(1)**H H(2)**H . . . H(k)**H

as returned by CGERQF. She's lowkey unblocked but highkey iconic. 💖

Parameters

M — INTEGER. The number of rows of the matrix Q. M >= 0.
N — INTEGER. The number of columns of the matrix Q. N >= M.
K — INTEGER. The number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
A — COMPLEX array, dimension (LDA,N). On entry, the (m-k+i)-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGERQF in the last k rows of its array argument A. On exit, the m-by-n matrix Q.
LDA — INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGERQF.
WORK — COMPLEX array, dimension (M).
INFO — INTEGER. = 0: successful exit; < 0: if INFO = -i, the i-th argument has an illegal value.

Author

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

subroutine cungrq

subroutine cungrq (integer M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNGRQ

Purpose:

CUNGRQ generates an M-by-N complex matrix Q with orthonormal rows, which is defined as the last M rows of a product of K elementary reflectors of order N

Q  =  H(1)**H H(2)**H . . . H(k)**H

as returned by CGERQF. The main character energy is real. 👑

Parameters

M —
M — M is INTEGER. It's the number of rows of the matrix Q, bestie. So like, M >= 0. 💅
N — N is INTEGER. The number of columns of the matrix Q. Constraint check: N >= M. 👑
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. The vibe check says M >= K >= 0. ✨
A — A is COMPLEX array, dimension (LDA,N). On entry, the (m-k+i)-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGERQF in the last k rows of its array argument A. On exit? It's the M-by-N matrix Q. Glow up fr fr. 🦋
LDA — LDA is INTEGER. The first dimension of the array A. And LDA >= max(1,M), no cap. 🎀
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGERQF. It's giving supporting cast but make it iconic. 💖
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. 🔥
LWORK — LWORK is INTEGER. The dimension of the array WORK. So LWORK >= max(1,M). For optimum performance LWORK >= M*NB, where NB is the optimal blocksize.

And lowkey the important part: 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. Not me getting away with it 😌

INFO — INFO is INTEGER. Here's the tea:
- = 0: successful exit. slay. ✅
- < 0: if INFO = -i, the i-th argument has an illegal value. 🚨

Author 🫶

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

subroutine cungtr 🌸

subroutine cungtr (character UPLO, integer N, complex, dimension( lda, * )
    A, integer LDA, complex, dimension( * ) TAU, complex, dimension( * )
    WORK, integer LWORK, integer INFO)

CUNGTR

Purpose: ✨

CUNGTR generates a complex unitary matrix Q which is defined as the product of n-1 elementary reflectors of order N, as returned by CHETRD:

if UPLO = 'U', Q = H(n-1) . . . H(2) H(1),

if UPLO = 'L', Q = H(1) H(2) . . . H(n-1).

Like, the order literally flips depending on which triangle you picked. Main character behavior fr. 💅

Parameters 🎀

UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangle of A contains elementary reflectors from CHETRD;
- = 'L': Lower triangle of A contains elementary reflectors from CHETRD.
N — N is INTEGER. The order of the matrix Q. N >= 0. 💜
A — A is COMPLEX array, dimension (LDA,N). On entry, the vectors which define the elementary reflectors, as returned by CHETRD. On exit, the N-by-N unitary matrix Q. Transformation era. 🦋
LDA — LDA is INTEGER. The leading dimension of the array A. And LDA >= N. Periodt.
TAU — TAU is COMPLEX array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CHETRD. Not me needing all N-1 of them 😭
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. 🔥
LWORK — LWORK is INTEGER. The dimension of the array WORK. So LWORK >= N-1. For optimum performance LWORK >= (N-1)*NB, where NB is the optimal blocksize.

And 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. Bestie really said "I'll handle it myself" 💅

INFO — INFO is INTEGER. The receipts:
- = 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.

subroutine cungtsqr 🌈

subroutine cungtsqr (integer M, integer N, integer MB, integer NB, complex,
    dimension( lda, * ) A, integer LDA, complex, dimension( ldt, * ) T,
    integer LDT, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNGTSQR

Purpose: ✨

CUNGTSQR generates an M-by-N complex matrix Q_out with orthonormal columns, which are the first N columns of a product of complex unitary matrices of order M which are returned by CLATSQR

Q_out = first_N_columns_of( Q(1)_in * Q(2)_in * ... * Q(k)_in ).

See the documentation for CLATSQR. 👀

Parameters 🎀

M — M is INTEGER. The number of rows of the matrix A. M >= 0. 💖
N — N is INTEGER. The number of columns of the matrix A. M >= N >= 0. 🦋
MB — MB is INTEGER. The row block size used by CLATSQR to return arrays A and T. MB > N.

(Note that if MB > M, then M is used instead of MB as the row block size). 🙈

NB — NB is INTEGER. The column block size used by CLATSQR to return arrays A and T. NB >= 1.

(Note that if NB > N, then N is used instead of NB as the column block size). 🙈

A — A is COMPLEX array, dimension (LDA,N).

On entry:

The elements on and above the diagonal are not accessed. The elements below the diagonal represent the unit lower-trapezoidal blocked matrix V computed by CLATSQR that defines the input matrices Q_in(k) (ones on the diagonal are not stored) (same format as the output A below the diagonal in CLATSQR).

On exit:

The array A contains an M-by-N orthonormal matrix Q_out, i.e the columns of A are orthogonal unit vectors. Orthonormal queen 👑

LDA — LDA is INTEGER. The leading dimension of the array A. And LDA >= max(1,M). 🎀
T — T is COMPLEX array, dimension (LDT, N * NIRB), where

NIRB = Number_of_input_row_blocks
     = MAX( 1, CEIL((M-N)/(MB-N)) )

Let

NICB = Number_of_input_col_blocks
     = CEIL(N/NB)

The upper-triangular block reflectors used to define the input matrices Q_in(k), k=(1:NIRB*NICB). The block reflectors are stored in compact form in NIRB block reflector sequences. Each of NIRB block reflector sequences is stored in a larger NB-by-N column block of T and consists of NICB smaller NB-by-NB upper-triangular column blocks. (same format as the output T in CLATSQR). Compact storage, maximal drama. 💅

LDT — LDT is INTEGER. The leading dimension of the array T. And LDT >= max(1,min(NB1,N)). Yes bestie, that's NB1, exactly like that, I don't make the rules 🫶
WORK — (workspace) COMPLEX array, dimension (MAX(2,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. 🔥
LWORK — LWORK is INTEGER. The dimension of the array WORK. So LWORK >= (M+NB)*N. 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 is INTEGER. The receipts:
- = 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.

Contributors: 🌟

November 2019, Igor Kozachenko, Computer Science Division, University of California, Berkeley

subroutine cungtsqr_row 🌸

subroutine cungtsqr_row (integer M, integer N, integer MB, integer NB,
    complex, dimension( lda, * ) A, integer LDA, complex, dimension( ldt, *
    ) T, integer LDT, complex, dimension( * ) WORK, integer LWORK, integer
    INFO)

CUNGTSQR_ROW

Purpose: ✨

CUNGTSQR_ROW generates an M-by-N complex matrix Q_out with orthonormal columns from the output of CLATSQR. These N orthonormal columns are the first N columns of a product of complex unitary matrices Q(k)_in of order M, which are returned by CLATSQR in a special format.

Q_out = first_N_columns_of( Q(1)_in * Q(2)_in * ... * Q(k)_in ).

The input matrices Q(k)_in are stored in row and column blocks in A. See the documentation of CLATSQR for more details on the format of Q(k)_in, where each Q(k)_in is represented by block Householder transformations. This routine calls an auxiliary routine CLARFB_GETT, where the computation is performed on each individual block. The algorithm first sweeps NB-sized column blocks from the right to left starting in the bottom row block and continues to the top row block (hence _ROW in the routine name). This sweep is in reverse order of the order in which CLATSQR generates the output blocks. Bottom-to-top, right-to-left, chaotic in the best way 💅

Parameters 🎀

M — M is INTEGER. The number of rows of the matrix A. M >= 0. 💖
N — N is INTEGER. The number of columns of the matrix A. M >= N >= 0. 🦋
MB — MB is INTEGER. The row block size used by CLATSQR to return arrays A and T. MB > N.

(Note that if MB > M, then M is used instead of MB as the row block size). 🙈

NB — NB is INTEGER. The column block size used by CLATSQR to return arrays A and T. NB >= 1.

(Note that if NB > N, then N is used instead of NB as the column block size). 🙈

A — A is COMPLEX array, dimension (LDA,N).

On entry:

The elements on and above the diagonal are not used as input. The elements below the diagonal represent the unit lower-trapezoidal blocked matrix V computed by CLATSQR that defines the input matrices Q_in(k) (ones on the diagonal are not stored). See CLATSQR for more details. 👑

On exit:

The array A is holding an M-by-N orthonormal matrix Q_out — like, the columns of A are orthogonal unit vectors, that's the whole vibe. 💜

LDA — LDA is INTEGER. It's the leading dimension of the array A, and bestie, LDA >= max(1,M). No exceptions. 💅
T — T is COMPLEX array, dimension (LDT, N * NIRB) where

NIRB = Number_of_input_row_blocks
     = MAX( 1, CEIL((M-N)/(MB-N)) )

and let

NICB = Number_of_input_col_blocks
     = CEIL(N/NB)

Okay so T is where the upper-triangular block reflectors live — the ones used to define the input matrices Q_in(k), k=(1:NIRB*NICB). The block reflectors are stored in compact form in NIRB block reflector sequences. Each of the NIRB block reflector sequences is stored in a larger NB-by-N column block of T and consists of NICB smaller NB-by-NB upper-triangular column blocks. See CLATSQR for more details on the format of T. 🎀

LDT — LDT is INTEGER. The leading dimension of the array T. And LDT >= max(1,min(NB,N)). Slay.
WORK — (workspace) COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. She's telling you what she wants. 👑
LWORK — The dimension of the array WORK. LWORK >= NBLOCAL * MAX(NBLOCAL,(N-NBLOCAL)), where NBLOCAL=MIN(NB,N). 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 yeah, -1 = "just tell me how much room you need", no yelling. ✨
INFO — INFO is 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.

Contributors:

November 2020, Igor Kozachenko, Computer Science Division, University of California, Berkeley

🌟 subroutine `cunhr_col` 🌟

subroutine cunhr_col (integer M, integer N, integer NB, complex, dimension( lda, * ) A, integer LDA, complex, dimension( ldt, * ) T, integer LDT, complex, dimension( * ) D, integer INFO)

CUNHR_COL

Purpose:

CUNHR_COL takes an M-by-N complex matrix Q_in with orthonormal columns as input, stored in A, and performs Householder Reconstruction (HR), i.e. reconstructs Householder vectors V(i) implicitly representing another M-by-N matrix Q_out, with the property that Q_in = Q_out*S, where S is an N-by-N diagonal matrix with diagonal entries equal to +1 or -1. The Householder vectors (columns V(i) of V) are stored in A on output, and the diagonal entries of S are stored in D. Block reflectors are also returned in T (same output format as CGEQRT). It's giving glow-up but make it linear algebra. 🦋

Parameters

M — M is INTEGER. The number of rows of the matrix A. M >= 0.
N — N is INTEGER. The number of columns of the matrix A. M >= N >= 0. Yes, both bounds, she's specific. 💅
NB — NB is INTEGER. The column block size to be used in the reconstruction of Householder column vector blocks in the array A and corresponding block reflectors in the array T. NB >= 1. (Note that if NB > N, then N is used instead of NB as the column block size.) Not me catching that little caveat, but okay. 🙈
A — A is COMPLEX array, dimension (LDA,N)

On entry:

The array A contains an M-by-N orthonormal matrix Q_in, i.e the columns of A are orthogonal unit vectors.

On exit:

The elements below the diagonal of A represent the unit lower-trapezoidal matrix V of Householder column vectors V(i). The unit diagonal entries of V are not stored (same format as the output below the diagonal in A from CGEQRT). The matrix T and the matrix V stored on output in A implicitly define Q_out.

The elements above the diagonal contain the factor U of the 'modified' LU-decomposition:

   Q_in - ( S ) = V * U
          ( 0 )

where 0 is a (M-N)-by-(M-N) zero matrix. Iconic little formula ngl. 🌸

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
T — T is COMPLEX array, dimension (LDT, N)

Let

NOCB = Number_of_output_col_blocks
     = CEIL(N/NB)

On exit, T(1:NB, 1:N) contains NOCB upper-triangular block reflectors used to define Q_out stored in compact form as a sequence of upper-triangular NB-by-NB column blocks (same format as the output T in CGEQRT). The matrix T and the matrix V stored on output in A implicitly define Q_out.

NOTE: The lower triangles below the upper-triangular blocks will be filled with zeros. See Further Details. 💀 (it's fine, it's on purpose)

LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,min(NB,N)).
D — D is COMPLEX array, dimension min(M,N). The elements can be only plus or minus one.

D(i) is constructed as D(i) = -SIGN(Q_in_i(i,i)), where 1 <= i <= min(M,N), and Q_in_i is Q_in after performing i-1 steps of "modified" Gaussian elimination. See Further Details. ✨

INFO — INFO is INTEGER
- = 0: successful exit 🫶
- < 0: if INFO = -i, the i-th argument had an illegal value 😭

Further Details:

The computed M-by-M unitary factor Q_out is defined implicitly as a product of unitary matrices Q_out(i). Each Q_out(i) is stored in the compact WY-representation format in the corresponding blocks of matrices V (stored in A) and T.

The M-by-N unit lower-trapezoidal matrix V stored in the M-by-N matrix A contains the column vectors V(i) in NB-size column blocks VB(j). For example, VB(1) contains the columns V(1), V(2), ... V(NB).

NOTE: The unit entries on the diagonal of Y are not stored in A. (yes, Y. that's what it says. we don't ask questions. 🙈)

The number of column blocks is

    NOCB = Number_of_output_col_blocks = CEIL(N/NB)

where each block is of order NB except for the last block, which is of order LAST_NB = N - (NOCB-1)*NB.

For example, if M=6, N=5 and NB=2, the matrix V is

    V = (    VB(1),   VB(2), VB(3) ) =

      = (   1                      )
        ( v21    1                 )
        ( v31  v32    1            )
        ( v41  v42  v43   1        )
        ( v51  v52  v53  v54    1  )
        ( v61  v62  v63  v54   v65 )

For each of the column blocks VB(i), an upper-triangular block reflector TB(i) is computed. These blocks are stored as a sequence of upper-triangular column blocks in the NB-by-N matrix T. The size of each TB(i) block is NB-by-NB, except for the last block, whose size is LAST_NB-by-LAST_NB.

For example, if M=6, N=5 and NB=2, the matrix T is

    T  = (    TB(1),    TB(2), TB(3) ) =

       = ( t11  t12  t13  t14   t15  )
         (      t22       t24        )

The M-by-M factor Q_out is given as a product of NOCB unitary M-by-M matrices Q_out(i).

    Q_out = Q_out(1) * Q_out(2) * ... * Q_out(NOCB),

where each matrix Q_out(i) is given by the WY-representation using corresponding blocks from the matrices V and T:

    Q_out(i) = I - VB(i) * TB(i) * (VB(i))**T,

where I is the identity matrix. Here is the formula with matrix dimensions:

 Q(i){M-by-M} = I{M-by-M} -
   VB(i){M-by-INB} * TB(i){INB-by-INB} * (VB(i))**T {INB-by-M},

where INB = NB, except for the last block NOCB for which INB=LAST_NB. 🌈

=====
NOTE:
=====

If Q_in is the result of doing a QR factorization B = Q_in * R_in, then:

B = (Q_out*S) * R_in = Q_out * (S * R_in) = Q_out * R_out.

So if one wants to interpret Q_out as the result of the QR factorization of B, then the corresponding R_out should be equal to R_out = S * R_in, i.e. some rows of R_in should be multiplied by -1. 🎀

For the details of the algorithm, see [1].

[1] 'Reconstructing Householder vectors from tall-skinny QR', G. Ballard, J. Demmel, L. Grigori, M. Jacquelin, H.D. Nguyen, E. Solomonik, J. Parallel Distrib. Comput., vol. 85, pp. 3-31, 2015.

Author

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

Contributors:

November 2019, Igor Kozachenko, Computer Science Division, University of California, Berkeley

🧚 subroutine `cunm22` 🧚

subroutine cunm22 (character SIDE, character TRANS, integer M, integer N, integer N1, integer N2, complex, dimension( ldq, * ) Q, integer LDQ, complex, dimension( ldc, * ) C, integer LDC, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNM22 multiplies a general matrix by a banded unitary matrix.

Purpose

CUNM22 overwrites the general complex M-by-N matrix C with

                 SIDE = 'L'     SIDE = 'R'
 TRANS = 'N':      Q * C          C * Q
 TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix of order NQ, with NQ = M if SIDE = 'L' and NQ = N if SIDE = 'R'. The unitary matrix Q processes a 2-by-2 block structure

        [  Q11  Q12  ]
    Q = [            ]
        [  Q21  Q22  ],

where Q12 is an N1-by-N1 lower triangular matrix and Q21 is an N2-by-N2 upper triangular matrix. Two-by-two block moment fr fr. 🦋

Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose);
- = 'C': apply Q**H (Conjugate transpose). 💅
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N
N — N is INTEGER. the number of columns of the matrix C. And N >= 0, obviously, because a matrix with negative columns is not a vibe. ✨
N1, N2 — N1 is INTEGER, N2 is INTEGER. These two are the dimension of Q12 and Q21, respectively, and both gotta satisfy N1, N2 >= 0. the requirement you cannot skip, and I mean it:
- N1 + N2 = M if SIDE = 'L'
- N1 + N2 = N if SIDE = 'R'
Q — Q is COMPLEX array, dimension (LDQ,M) if SIDE = 'L', or (LDQ,N) if SIDE = 'R'. It's giving "the shape depends on which side you're applying from" 💅
LDQ — LDQ is INTEGER. The leading dimension of the array Q. So: LDQ >= max(1,M) if SIDE = 'L'; LDQ >= max(1,N) if SIDE = 'R'. Respect the leading dimension, bestie, or XERBLA will come for you. 😭
C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. Not a copy, not a peek — overwritten, fr fr.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M). That's the whole rule, no cap. 🧚
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. She's reporting back her optimal size, so thoughtful. 💖
LWORK — LWORK is INTEGER. The dimension of the array WORK. Here's the tea:
- If SIDE = 'L', then LWORK >= max(1,N)
- if SIDE = 'R', then LWORK >= max(1,M)
- For optimum performance, LWORK >= M*N. optimum being the key word — the minimum keeps you legal, this keeps you fast.
- 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. Lowkey a cheat code: ask -1, get the answer, no yelling. 🔥
INFO — INFO is INTEGER
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. Someone did something messy and this is the receipt. 💀

💖 Author 💖

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

🌸 `cunm2l` — the QL one, unblocked and unbothered 🌸

subroutine cunm2l (character SIDE, character TRANS, integer M, integer N,
    integer K, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer INFO)

CUNM2L multiplies a general matrix by the unitary matrix from a QL factorization determined by cgeqlf (unblocked algorithm). Yes bestie, the unblocked version — she's doing it the straightforward way, one reflector at a time. 👑

Purpose:

     CUNM2L overwrites the general complex m-by-n matrix C with

           Q * C  if SIDE = 'L' and TRANS = 'N', or

           Q**H* C  if SIDE = 'L' and TRANS = 'C', or

           C * Q  if SIDE = 'R' and TRANS = 'N', or

           C * Q**H if SIDE = 'R' and TRANS = 'C',

     where Q is a complex unitary matrix defined as the product of k
     elementary reflectors

           Q = H(k) . . . H(2) H(1)

     as returned by CGEQLF. Q is of order m if SIDE = 'L' and of order n
     if SIDE = 'R'.

okay so notice the order of the reflectors here — Q = H(k) . . . H(2) H(1), backwards compared to the QR girlies, because QL factorization builds from the other end. iykyk. ✨

Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. So if SIDE = 'L', then M >= K >= 0; if SIDE = 'R', then N >= K >= 0.
A — A is COMPLEX array, dimension (LDA,K). The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGEQLF in the last k columns of its array argument A. And heads up: A is modified by the routine but restored on exit. She borrows your stuff but she puts it back, we love a considerate queen. 🫶
LDA — LDA is INTEGER. The leading dimension of the array A. If SIDE = 'L', LDA >= max(1,M); if SIDE = 'R', LDA >= max(1,N).
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEQLF. It's the little scalar that makes the reflector reflect. 💅
C — C is COMPLEX array, dimension (LDC,N). On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension (N) if SIDE = 'L', (M) if SIDE = 'R'.
INFO — INFO is INTEGER
- = 0: successful exit ⭐
- < 0: if INFO = -i, the i-th argument had an illegal value. Not me catching an illegal argument 🙈

Author

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

🦋 `cunm2r` — the QR one, and yes she's the mirror image 🦋

subroutine cunm2r (character SIDE, character TRANS, integer M, integer N,
    integer K, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer INFO)

CUNM2R multiplies a general matrix by the unitary matrix from a QR factorization determined by cgeqrf (unblocked algorithm). Same energy as her sister cunm2l, different factorization, different vibe check. 🌈

Purpose:

     CUNM2R overwrites the general complex m-by-n matrix C with

           Q * C  if SIDE = 'L' and TRANS = 'N', or

           Q**H* C  if SIDE = 'L' and TRANS = 'C', or

           C * Q  if SIDE = 'R' and TRANS = 'N', or

           C * Q**H if SIDE = 'R' and TRANS = 'C',

     where Q is a complex unitary matrix defined as the product of k
     elementary reflectors

           Q = H(1) H(2) . . . H(k)

     as returned by CGEQRF. Q is of order m if SIDE = 'L' and of order n
     if SIDE = 'R'.

see how it's Q = H(1) H(2) . . . H(k) this time? forwards. That's the QR way. The way that she flipped the whole order from cunm2l... iconic. 👑

Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX array, dimension (LDA,K). The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGEQRF in the first k columns of its array argument A. And same deal as before: A is modified by the routine but restored on exit. 🫶
LDA — LDA is INTEGER. The leading dimension of the array A. If SIDE = 'L', LDA >= max(1,M); if SIDE = 'R', LDA >= max(1,N).
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEQRF.
C — C is COMPLEX array, dimension (LDC,N). On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension (N) if SIDE = 'L', (M) if SIDE = 'R'.
INFO — INFO is 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.

🎀 `cunmbr` — bidiagonal era, she does it ALL 🎀

subroutine cunmbr (character VECT, character SIDE, character TRANS, integer
    M, integer N, integer K, complex, dimension( lda, * ) A, integer LDA,
    complex, dimension( * ) TAU, complex, dimension( ldc, * ) C, integer
    LDC, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNMBR

Purpose:

okay so this one has two whole modes, depending on whether you're the Q girlie or the P girlie. If VECT = 'Q', CUNMBR overwrites the general complex M-by-N matrix C with:

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

If VECT = 'P', CUNMBR overwrites the general complex M-by-N matrix C with:

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      P * C          C * P
TRANS = 'C':      P**H * C       C * P**H

Here Q and P**H are the unitary matrices determined by CGEBRD when reducing a complex matrix A to bidiagonal form: A = Q * B * P**H. Q and P**H are defined as products of elementary reflectors H(i) and G(i) respectively. 💖

Let nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. Thus nq is the order of the unitary matrix Q or P**H that is applied.

If VECT = 'Q', A is assumed to have been an NQ-by-K matrix:

if nq >= k, Q = H(1) H(2) . . . H(k);
if nq < k, Q = H(1) H(2) . . . H(nq-1).

If VECT = 'P', A is assumed to have been a K-by-NQ matrix:

if k < nq, P = G(1) G(2) . . . G(k);
if k >= nq, P = G(1) G(2) . . . G(nq-1).

Not the length of the product being conditional on nq... she's flexible like that. 💅

Parameters

VECT — VECT is CHARACTER*1
- = 'Q': apply Q or Q**H;
- = 'P': apply P or P**H.
SIDE — SIDE is CHARACTER*1
- = 'L': apply Q, Q**H, P or P**H from the Left;
- = 'R': apply Q, Q**H, P or P**H from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': No transpose, apply Q or P;
- = 'C': Conjugate transpose, apply Q**H or P**H.
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — hold that thought bestie, K's whole deal is up next 🫶

K

K is INTEGER.

if VECT = 'Q', it's the number of columns in the original matrix that got reduced by CGEBRD. 💫
if VECT = 'P', it's the number of rows in the original matrix that got reduced by CGEBRD.

And it's always K >= 0, no negativity allowed bestie. ✋

A

A is COMPLEX array, and its dimension depends on which vibe you picked:

(LDA,min(nq,K)) if VECT = 'Q'
(LDA,nq)        if VECT = 'P'

These are the vectors that define the elementary reflectors H(i) and G(i), and like… their products are literally what determine the matrices Q and P, exactly as returned by CGEBRD. 🦋

LDA

LDA is INTEGER — the leading dimension of the array A.

if VECT = 'Q', then LDA >= max(1,nq);
if VECT = 'P', then LDA >= max(1,min(nq,K)).

TAU

TAU is COMPLEX array, dimension (min(nq,K)).

TAU(i) has to contain the scalar factor of the elementary reflector H(i) or G(i) — whichever one is out here determining Q or P — as returned by CGEBRD in the array argument TAUQ or TAUP. 👑

C

C is COMPLEX array, dimension (LDC,N).

On entry? It's the M-by-N matrix C. On exit? Bestie it gets overwritten by Q*C or Q**H*C or C*Q**H or C*Q or P*C or P**H*C or C*P or C*P**H. That's eight whole possibilities, she's flexible like that. 💅

LDC

LDC is INTEGER — the leading dimension of the array C, and LDC >= max(1,M). Periodt.

WORK

WORK is COMPLEX array, dimension (MAX(1,LWORK)).

On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. She's giving helpful. ✨

LWORK

LWORK is INTEGER — the dimension of the array WORK.

if SIDE = 'L', then LWORK >= max(1,N);
if SIDE = 'R', then LWORK >= max(1,M);
if N = 0 or M = 0, then LWORK >= 1.

For optimum performance (and honestly, why would you settle for less), LWORK >= max(1,N*NB) if SIDE = 'L', and LWORK >= max(1,M*NB) if SIDE = 'R', where NB is the optimal blocksize. And heads up: (NB = 0 if M = 0 or N = 0.) — the blocksize simply does not exist in that case, no cap. 💀

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 like, it's just peeking, not touching. 🙈

INFO

INFO is 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.

🫶 `cunmhr`

subroutine cunmhr (character SIDE, character TRANS, integer M, integer N,
    integer ILO, integer IHI, complex, dimension( lda, * ) A, integer LDA,
    complex, dimension( * ) TAU, complex, dimension( ldc, * ) C, integer
    LDC, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNMHR — yes that's her name, say it with your chest. 💜

Purpose:

CUNMHR overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix of order nq, with nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. And Q is defined as the product of IHI-ILO elementary reflectors, as returned by CGEHRD:

Q = H(ilo) H(ilo+1) . . . H(ihi-1).

Iconic behaviour, honestly. 🔥

Parameters

SIDE

SIDE is CHARACTER*1.

= 'L': apply Q or Q**H from the Left;
= 'R': apply Q or Q**H from the Right.

TRANS

TRANS is CHARACTER*1.

= 'N': apply Q (No transpose)
= 'C': apply Q**H (Conjugate transpose)

M

M is INTEGER — the number of rows of the matrix C. And M >= 0, always.

N

N is INTEGER — the number of columns of the matrix C. And N >= 0, always.

ILO

ILO is INTEGER.

IHI

IHI is INTEGER.

ILO and IHI must have the same values as in the previous call of CGEHRD. No switching it up on her. 🚫

Q is equal to the unit matrix except in the submatrix Q(ilo+1:ihi,ilo+1:ihi).

if SIDE = 'L', then 1 <= ILO <= IHI <= M, if M > 0, and ILO = 1 and IHI = 0, if M = 0;
if SIDE = 'R', then 1 <= ILO <= IHI <= N, if N > 0, and ILO = 1 and IHI = 0, if N = 0.

A

A is COMPLEX array, dimension

(LDA,M) if SIDE = 'L'
(LDA,N) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by CGEHRD. She's the blueprint fr fr. 🎀

LDA

LDA is INTEGER — the leading dimension of the array A. LDA >= max(1,M) if SIDE = 'L'; LDA >= max(1,N) if SIDE = 'R'.

TAU

TAU is COMPLEX array, dimension

(M-1) if SIDE = 'L'
(N-1) if SIDE = 'R'

TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEHRD.

C

C is COMPLEX array, dimension (LDC,N).

On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. Choose your fighter. ✨

LDC

LDC is INTEGER — the leading dimension of the array C, and LDC >= max(1,M).

WORK

WORK is COMPLEX array, dimension (MAX(1,LWORK)).

On exit, if INFO = 0, WORK(1) returns the optimal LWORK. So helpful of her.

LWORK

LWORK is INTEGER — the dimension of the array WORK.

if SIDE = 'L', then LWORK >= max(1,N);
if SIDE = 'R', then LWORK >= max(1,M).

For optimum performance, LWORK >= N*NB if SIDE = 'L', and LWORK >= M*NB if SIDE = 'R', where NB is the optimal blocksize. Bestie the blocksize is doing the heavy lifting, respect her. 👑

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

🧚 `cunml2`

subroutine cunml2 (character SIDE, character TRANS, integer M, integer N,
    integer K, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer INFO)

CUNML2 multiplies a general matrix by the unitary matrix from a LQ factorization determined by cgelqf (unblocked algorithm). Yes she's the unblocked one — small but mighty, lowkey the blueprint. 💖

Purpose:

CUNML2 overwrites the general complex m-by-n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**H* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**H if SIDE = 'R' and TRANS = 'C',

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(k)**H . . . H(2)**H H(1)**H

as returned by CGELQF. And Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. Slay. ✨

Parameters

SIDE

SIDE is CHARACTER*1.

= 'L': apply Q or Q**H from the Left
= 'R': apply Q or Q**H from the Right

TRANS

TRANS is CHARACTER*1.

= 'N': apply Q (No transpose)
= 'C': apply Q**H (Conjugate transpose)

M

M is INTEGER — the number of rows of the matrix C. M >= 0.

N

N is INTEGER — the number of columns of the matrix C. N >= 0.

K

K is INTEGER — the number of elementary reflectors whose product defines the matrix Q.

if SIDE = 'L', then M >= K >= 0;
if SIDE = 'R', then N >= K >= 0.

A

A is COMPLEX array, dimension

(LDA,M) if SIDE = 'L',
(LDA,N) if SIDE = 'R'

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGELQF in the first k rows of its array argument A.

And listen — A is modified by the routine but restored on exit. She borrows it, does her thing, puts it back exactly how she found it. Respect. 🫶

LDA

LDA is INTEGER — the leading dimension of the array A. LDA >= max(1,K).

TAU

TAU is COMPLEX array, dimension (K).

TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGELQF.

C

C is COMPLEX array, dimension (LDC,N).

On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. 💅

LDC

LDC is INTEGER — the leading dimension of the array C. LDC >= max(1,M).

WORK

WORK is COMPLEX array, dimension

(N) if SIDE = 'L',
(M) if SIDE = 'R'

INFO

INFO is 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.

🦋 `cunmlq`

subroutine cunmlq (character SIDE, character TRANS, integer M, integer N,
    integer K, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNMLQ — the blocked queen herself, main character energy fr. 👑

Purpose:

CUNMLQ overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(k)**H . . . H(2)**H H(1)**H

as returned by CGELQF. And Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. No cap. ✨

Parameters

SIDE

SIDE is CHARACTER*1.

= 'L': apply Q or Q**H from the Left;
= 'R': apply Q or Q**H from the Right.

TRANS

TRANS — it's CHARACTER*1, bestie, and it decides everything 💅
- = 'N': no transpose, so you apply Q;
- = 'C': conjugate transpose, so you apply Q**H.
M — M is INTEGER. The number of rows of the matrix C. Constraint: M >= 0. can't be negative, periodt
N — N is INTEGER. The number of columns of the matrix C. Also N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. rules of the road:
- If SIDE = 'L', then M >= K >= 0;
- if SIDE = 'R', then N >= K >= 0.
A — A is COMPLEX array, dimension:

                                          (LDA,M) if SIDE = 'L',
                                          (LDA,N) if SIDE = 'R'

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGELQF in the first k rows of its array argument A. it's literally just handing you the reflectors pre-made ✨

LDA — LDA is INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,K). don't you dare go smaller
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGELQF. CGELQF already did the math, just pass it along 🫶
C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. your original C? gone. replaced. iconic behavior honestly 💀
LDC — LDC is INTEGER. The leading dimension of the array C. Constraint: LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. little peek at what you should've asked for 👀
LWORK — LWORK is INTEGER. The dimension of the array WORK.
- If SIDE = 'L', then LWORK >= max(1,N);
- if SIDE = 'R', then LWORK >= max(1,M).

For good performance, LWORK should generally be larger. yes bigger is better here, no notes

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 is INTEGER
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. something you passed was illegal, girl, check yourself

Author 🫶

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine cunmql 🌸

subroutine cunmql (character SIDE, character TRANS, integer M, integer N,
    integer K, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNMQL

✨ Purpose ✨

CUNMQL overwrites the general complex M-by-N matrix C with:

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix defined as the product of k elementary reflectors:

      Q = H(k) . . . H(2) H(1)

as returned by CGEQLF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. 💜

🎀 Parameters 🎀

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': no transpose, apply Q;
- = 'C': conjugate transpose, apply Q**H.
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q.
- If SIDE = 'L', M >= K >= 0;
- if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX array, dimension (LDA,K). The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGEQLF in the last k columns of its array argument A. last, not first, don't mix it up bestie ⚠️
LDA — LDA is INTEGER. The leading dimension of the array A.
- If SIDE = 'L', LDA >= max(1,M);
- if SIDE = 'R', LDA >= max(1,N).
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEQLF.
C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. again: your C gets completely rewritten, no cap 💅
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK.
- If SIDE = 'L', LWORK >= max(1,N);
- if SIDE = 'R', LWORK >= max(1,M).

For good performance, LWORK should generally be larger.

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

💖 subroutine cunmqr 💖

subroutine cunmqr (character SIDE, character TRANS, integer M, integer N,
    integer K, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNMQR

✨ Purpose ✨

CUNMQR overwrites the general complex M-by-N matrix C with:

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix defined as the product of k elementary reflectors:

      Q = H(1) H(2) . . . H(k)

as returned by CGEQRF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. 💜

🎀 Parameters 🎀

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': no transpose, apply Q;
- = 'C': conjugate transpose, apply Q**H.
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q.
- If SIDE = 'L', M >= K >= 0;
- if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX array, dimension (LDA,K). The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGEQRF in the first k columns of its array argument A. first columns this time! opposite energy from CUNMQL, stay woke 👑
LDA — LDA is INTEGER. The leading dimension of the array A.
- If SIDE = 'L', LDA >= max(1,M);
- if SIDE = 'R', LDA >= max(1,N).
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGEQRF.
C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. same deal, same rewrite, same drama 💅
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK.
- If SIDE = 'L', LWORK >= max(1,N);
- if SIDE = 'R', LWORK >= max(1,M).

For good performance, LWORK should generally be larger.

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

🦋 subroutine cunmr2 🦋

subroutine cunmr2 (character SIDE, character TRANS, integer M, integer N,
    integer K, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer INFO)

CUNMR2 multiplies a general matrix by the unitary matrix from a RQ factorization determined by cgerqf (unblocked algorithm). unblocked, so it's the cute simple version 🍓

✨ Purpose ✨

CUNMR2 overwrites the general complex m-by-n matrix C with:

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**H* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**H if SIDE = 'R' and TRANS = 'C',

where Q is a complex unitary matrix defined as the product of k elementary reflectors:

      Q = H(1)**H H(2)**H . . . H(k)**H

as returned by CGERQF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. 💜

🎀 Parameters 🎀

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M
M — M is INTEGER, and it's the number of rows of the matrix C. Bestie, M >= 0, always. 💅
N — N is INTEGER, the number of columns of the matrix C. Also N >= 0. no negative dimensions in this house ✨
K — K is INTEGER, the number of elementary reflectors whose product defines the matrix Q. And the vibes have conditions, okurr:
- if SIDE = 'L', then M >= K >= 0;
- if SIDE = 'R', then N >= K >= 0.
A — A is a COMPLEX array, dimension:
- (LDA,M) if SIDE = 'L',
- (LDA,N) if SIDE = 'R'.

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGERQF in the last k rows of its array argument A. And listen — A is modified by the routine but restored on exit. It's giving polite guest energy, it touches your stuff and then puts it back. 🫶

LDA — LDA is INTEGER, the leading dimension of the array A. LDA >= max(1,K). That's a hard requirement, don't play. 💀
TAU — TAU is a COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGERQF. 🎀
C — C is a COMPLEX array, dimension (LDC,N). On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. overwritten!! like it's gone-gone, so don't come crying later. 😭
LDC — LDC is INTEGER, the leading dimension of the array C. LDC >= max(1,M). 👑
WORK — WORK is a COMPLEX array, dimension:
- (N) if SIDE = 'L',
- (M) if SIDE = 'R'.
INFO — INFO is INTEGER, and it's the little status report bestie:
- = 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.

✨ subroutine `cunmr3` ✨

subroutine cunmr3 (character SIDE, character TRANS, integer M, integer N,
    integer K, integer L, complex, dimension( lda, * ) A, integer LDA,
    complex, dimension( * ) TAU, complex, dimension( ldc, * ) C, integer
    LDC, complex, dimension( * ) WORK, integer INFO)

CUNMR3 multiplies a general matrix by the unitary matrix from a RZ factorization determined by ctzrzf (unblocked algorithm). unblocked, so she's doing it the honest way, one reflector at a time 🧚

Purpose:

CUNMR3 overwrites the general complex m by n matrix C with:

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**H* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**H if SIDE = 'R' and TRANS = 'C',

where Q is a complex unitary matrix defined as the product of k elementary reflectors:

      Q = H(1) H(2) . . . H(k)

as returned by CTZRZF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. order matters, she's not ambiguous 💖

Parameters

SIDE — SIDE is CHARACTER*1:
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1:
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER. The number of rows of the matrix C. M >= 0. ✨
N — N is INTEGER. The number of columns of the matrix C. N >= 0. ✨
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q.
- If SIDE = 'L', M >= K >= 0;
- if SIDE = 'R', N >= K >= 0.
L — L is INTEGER. The number of columns of the matrix A containing the meaningful part of the Householder reflectors.
- If SIDE = 'L', M >= L >= 0, if SIDE = 'R', N >= L >= 0.
A — A is COMPLEX array, dimension:
- (LDA,M) if SIDE = 'L',
- (LDA,N) if SIDE = 'R'.

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CTZRZF in the last k rows of its array argument A. A is modified by the routine but restored on exit. again with the restore, so thoughtful 🫶

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,K). 📏
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CTZRZF. 🎀
C — C is COMPLEX array, dimension (LDC,N). On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. she's taking the wheel on C, no takebacks 😭
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M). 👑
WORK — WORK is COMPLEX array, dimension:
- (N) if SIDE = 'L',
- (M) if SIDE = 'R'.
INFO — INFO is 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.

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA 💜

Further Details:

and literally nothing else is written here in the source, bestie — the section is just… vibes and silence. moving on. 🌸

✨ subroutine `cunmrq` ✨

subroutine cunmrq (character SIDE, character TRANS, integer M, integer N,
    integer K, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNMRQ — yes that's the whole name, she doesn't need a subtitle. 💅

Purpose:

CUNMRQ overwrites the general complex M-by-N matrix C with:

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix defined as the product of k elementary reflectors:

      Q = H(1)**H H(2)**H . . . H(k)**H

as returned by CGERQF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. note the **H on every single reflector, she is NOT playing 🔥

Parameters

SIDE — SIDE is CHARACTER*1:
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — TRANS is CHARACTER*1:
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M — M is INTEGER. The number of rows of the matrix C. M >= 0. ✨
N — N is INTEGER. The number of columns of the matrix C. N >= 0. ✨
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q.
- If SIDE = 'L', M >= K >= 0;
- if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX array, dimension:
- (LDA,M) if SIDE = 'L',
- (LDA,N) if SIDE = 'R'.

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGERQF in the last k rows of its array argument A. (no "restored on exit" note here, so heads up — read the source before you assume anything, bestie) 🙈

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,K). 📏
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGERQF. 🎀
C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. again, overwritten, say goodbye to the original C 💀
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M). 👑
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. she's a gossip, she tells you the optimal size on the way out ✨
LWORK — LWORK is INTEGER. The dimension of the array WORK.
- If SIDE = 'L', LWORK >= max(1,N);
- if SIDE = 'R', LWORK >= max(1,M).
- For good performance, LWORK should generally be larger. like, bigger is better, performance-wise, that's the whole note 💅

INFO — INFO is 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.

✨ subroutine `cunmrz` ✨

subroutine cunmrz (character SIDE, character TRANS, integer M, integer N,
    integer K, integer L, complex, dimension( lda, * ) A, integer LDA,
    complex, dimension( * ) TAU, complex, dimension( ldc, * ) C, integer
    LDC, complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNMRZ — main character, no notes. 👑

Purpose:

CUNMRZ overwrites the general complex M-by-N matrix C with:

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix defined as the product of k elementary reflectors:

      Q = H(1) H(2) . . . H(k)

as returned by CTZRZF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. 🌈

Parameters

SIDE — SIDE is CHARACTER*1:
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — TRANS is CHARACTER*1:
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M — M is INTEGER. The number of rows of the matrix C. M >= 0. ✨
N — N is INTEGER. The number of columns of the matrix C. N >= 0. ✨
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q.
- If SIDE = 'L', M >= K >= 0;
- if SIDE = 'R', N >= K >= 0.
L — L is INTEGER. The number of columns of the matrix A containing the meaningful part of the Householder reflectors.
- If SIDE = 'L', M >= L >= 0, if SIDE = 'R', N >= L >= 0.
A
A — bestie, this is a COMPLEX array and its dimension is shape-shifting depending on SIDE:
- (LDA,M) if SIDE = 'L'
- (LDA,N) if SIDE = 'R'

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CTZRZF in the last k rows of its array argument A. And heads up 👀 — A is modified by the routine but restored on exit.

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,K). 💅
TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CTZRZF. ✨
C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. She's getting a glow-up, no cap. 🔥
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 🌸
LWORK — LWORK is INTEGER. The dimension of the array WORK.
- If SIDE = 'L', LWORK >= max(1,N);
- if SIDE = 'R', LWORK >= max(1,M).

For good performance, LWORK should generally be larger. (Like, treat her. She deserves it. 💖)

INFO — INFO is 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.

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details:

okay so the original page literally just drops this heading and then dips 💀 — there's nothing under it. That's the whole thing. Moving on, bestie.

subroutine `cunmtr`

subroutine cunmtr (character SIDE, character UPLO, character TRANS, integer
    M, integer N, complex, dimension( lda, * ) A, integer LDA, complex,
    dimension( * ) TAU, complex, dimension( ldc, * ) C, integer LDC,
    complex, dimension( * ) WORK, integer LWORK, integer INFO)

CUNMTR

Purpose:

CUNMTR overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix of order nq, with nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. Q is defined as the product of nq-1 elementary reflectors, as returned by CHETRD:

if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);
if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).

Parameters

SIDE — SIDE is CHARACTER*1.
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangle of A contains elementary reflectors from CHETRD;
- = 'L': Lower triangle of A contains elementary reflectors from CHETRD.
TRANS — TRANS is CHARACTER*1.
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
A — A is COMPLEX array, dimension
- (LDA,M) if SIDE = 'L'
- (LDA,N) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by CHETRD. 🦋

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M) if SIDE = 'L'; LDA >= max(1,N) if SIDE = 'R'.
TAU — TAU is COMPLEX array, dimension
- (M-1) if SIDE = 'L'
- (N-1) if SIDE = 'R'

TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CHETRD.

C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK.
- If SIDE = 'L', LWORK >= max(1,N);
- if SIDE = 'R', LWORK >= max(1,M).

For optimum performance LWORK >= N*NB if SIDE = 'L', and LWORK >=M*NB if SIDE = 'R', where NB is the optimal blocksize. 👑

INFO — INFO is 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.

subroutine `cupgtr`

subroutine cupgtr (character UPLO, integer N, complex, dimension( * ) AP,
    complex, dimension( * ) TAU, complex, dimension( ldq, * ) Q, integer
    LDQ, complex, dimension( * ) WORK, integer INFO)

CUPGTR

Purpose:

CUPGTR generates a complex unitary matrix Q which is defined as the product of n-1 elementary reflectors H(i) of order n, as returned by CHPTRD using packed storage:

if UPLO = 'U', Q = H(n-1) . . . H(2) H(1),
if UPLO = 'L', Q = H(1) H(2) . . . H(n-1).

Parameters

UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangular packed storage used in previous call to CHPTRD;
- = 'L': Lower triangular packed storage used in previous call to CHPTRD.
N — N is INTEGER. The order of the matrix Q. N >= 0.
AP — AP is COMPLEX array, dimension (N*(N+1)/2). The vectors which define the elementary reflectors, as returned by CHPTRD. 💜
TAU — TAU is COMPLEX array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CHPTRD.
Q — Q is COMPLEX array, dimension (LDQ,N). The N-by-N unitary matrix Q. Iconic, honestly. ✨
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,N).
WORK — WORK is COMPLEX array, dimension (N-1).
INFO — INFO is 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.

subroutine `cupmtr`

subroutine cupmtr (character SIDE, character UPLO, character TRANS, integer
    M, integer N, complex, dimension( * ) AP, complex, dimension( * ) TAU,
    complex, dimension( ldc, * ) C, integer LDC, complex, dimension( * )
    WORK, integer INFO)

CUPMTR

Purpose:

CUPMTR overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);
if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).

Parameters

SIDE — SIDE is CHARACTER*1.
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangular packed storage used in previous call to CHPTRD;
- = 'L': Lower triangular packed storage used in previous call to CHPTRD.
TRANS — TRANS is CHARACTER*1.
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
AP — AP is COMPLEX array, dimension
- (M*(M+1)/2) if SIDE = 'L'
- (N*(N+1)/2) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by CHPTRD. AP is modified by the routine but restored on exit. 🙈

TAU — TAU is COMPLEX array, dimension (M-1) if SIDE = 'L' or (N-1) if SIDE = 'R'. TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CHPTRD.
C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX array, dimension
- (N) if SIDE = 'L'
- (M) if SIDE = 'R'
INFO — INFO is 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.

🦋 `dorm22` 🦋

okay so real-talk, this one is the double precision girly 💅

subroutine dorm22 (character SIDE, character TRANS, integer M, integer N,
    integer N1, integer N2, double precision, dimension( ldq, * ) Q, integer
    LDQ, double precision, dimension( ldc, * ) C, integer LDC, double
    precision, dimension( * ) WORK, integer LWORK, integer INFO)

DORM22 multiplies a general matrix by a banded orthogonal matrix. no cap. 🔥

✨ Purpose ✨

DORM22 overwrites the general real M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'T':      Q**T * C       C * Q**T

where Q is a real orthogonal matrix of order NQ, with NQ = M if SIDE = 'L' and NQ = N if SIDE = 'R'.

The orthogonal matrix Q processes a 2-by-2 block structure

       [  Q11  Q12  ]
   Q = [            ]
       [  Q21  Q22  ],

where Q12 is an N1-by-N1 lower triangular matrix and Q21 is an N2-by-N2 upper triangular matrix. it's giving very structured, very blocky, obsessed. 🧚

💖 Parameters 💖

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**T from the Left;
- = 'R': apply Q or Q**T from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose);
- = 'C': apply Q**T (Conjugate transpose).
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
N1, N2 — both INTEGER. The dimension of Q12 and Q21, respectively. N1, N2 >= 0. The following requirement must be satisfied: N1 + N2 = M if SIDE = 'L' and N1 + N2 = N if SIDE = 'R'.
Q — Q is DOUBLE PRECISION array, dimension (LDQ,M) if SIDE = 'L', (LDQ,N) if SIDE = 'R'.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,M) if SIDE = 'L'; LDQ >= max(1,N) if SIDE = 'R'.
C — C is DOUBLE PRECISION array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**T*C or C*Q**T or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is DOUBLE PRECISION array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M). For optimum performance LWORK >= M*N.

INFO — INFO is 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.

🌈 `sorm22` 🌈

same energy, single precision this time, real ones only 💜

subroutine sorm22 (character SIDE, character TRANS, integer M, integer N,
    integer N1, integer N2, real, dimension( ldq, * ) Q, integer LDQ, real,
    dimension( ldc, * ) C, integer LDC, real, dimension( * ) WORK, integer
    LWORK, integer INFO)

SORM22 multiplies a general matrix by a banded orthogonal matrix. periodt. ✨

✨ Purpose ✨

SORM22 overwrites the general real M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'T':      Q**T * C       C * Q**T

where Q is a real orthogonal matrix of order NQ, with NQ = M if SIDE = 'L' and NQ = N if SIDE = 'R'.

The orthogonal matrix Q processes a 2-by-2 block structure

       [  Q11  Q12  ]
   Q = [            ]
       [  Q21  Q22  ],

where Q12 is an N1-by-N1 lower triangular matrix and Q21 is an N2-by-N2 upper triangular matrix.

💖 Parameters 💖

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**T from the Left;
- = 'R': apply Q or Q**T from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose);
- = 'C': apply Q**T (Conjugate transpose).
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
N1, N2 — both INTEGER. The dimension of Q12 and Q21, respectively. N1, N2 >= 0. The following requirement must be satisfied: N1 + N2 = M if SIDE = 'L' and N1 + N2 = N if SIDE = 'R'.
Q — Q is REAL array, dimension (LDQ,M) if SIDE = 'L', (LDQ,N) if SIDE = 'R'.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,M) if SIDE = 'L'; LDQ >= max(1,N) if SIDE = 'R'.
C — C is REAL array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**T*C or C*Q**T or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M). For optimum performance LWORK >= M*N.

INFO — INFO is 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.

🎀 `zunm22` 🎀

and now the complex*16 queen of the family 👑 note bestie: the transpose got upgraded to a conjugate transpose, so everything is Q**H now, not Q**T. slay. 💅

subroutine zunm22 (character SIDE, character TRANS, integer M, integer N,
    integer N1, integer N2, complex*16, dimension( ldq, * ) Q, integer LDQ,
    complex*16, dimension( ldc, * ) C, integer LDC, complex*16, dimension( *
    ) WORK, integer LWORK, integer INFO)

ZUNM22 multiplies a general matrix by a banded unitary matrix. 💖

✨ Purpose ✨

ZUNM22 overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix of order NQ, with NQ = M if SIDE = 'L' and NQ = N if SIDE = 'R'.

The unitary matrix Q processes a 2-by-2 block structure

       [  Q11  Q12  ]
   Q = [            ]
       [  Q21  Q22  ],

where Q12 is an N1-by-N1 lower triangular matrix and Q21 is an N2-by-N2 upper triangular matrix.

💖 Parameters 💖

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose);
- = 'C': apply Q**H (Conjugate transpose).
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
N1, N2 — both INTEGER. The dimension of Q12 and Q21, respectively. N1, N2 >= 0. The following requirement must be satisfied: N1 + N2 = M if SIDE = 'L' and N1 + N2 = N if SIDE = 'R'.
Q — Q is COMPLEX*16 array, dimension (LDQ,M) if SIDE = 'L', (LDQ,N) if SIDE = 'R'.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,M) if SIDE = 'L'; LDQ >= max(1,N) if SIDE = 'R'.
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M). For optimum performance LWORK >= M*N.

INFO — INFO is 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.

✍️ Author ✍️

Generated automatically by Doxygen for LAPACK from the source code.

okay bestie that's the whole thing, we made it to part 57 of 57 and honestly? main character energy the entire way through. 🫶💖

this page is from LAPACK Version 3.11.0, dated Sun Nov 27 2022, and it's filed under complexOTHERcomputational(3). stan a stable release. 🌸✨🎀

📦 where this page comes from

debian bookworm: liblapack-doc 3.11.0-2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

complexOTHERcomputational(3)

✨ NAME ✨

✨ SYNOPSIS ✨

🫶 Functions 🫶

cbbcsd — CBBCSD

cbdsqr — CBDSQR

cgghd3 — CGGHD3

cgghrd — CGGHRD

cggqrf — CGGQRF

cggrqf — CGGRQF

cggsvp3 — CGGSVP3

cgsvj0 — CGSVJ0

cgsvj1 — CGSVJ1

chbgst — CHBGST

chbtrd — CHBTRD

chetrd_hb2st — CHETRD_HB2ST

chfrk — CHFRK

chpcon — CHPCON

chpgst — CHPGST

chprfs — CHPRFS

chptrd — CHPTRD

chptrf — CHPTRF

chptri — CHPTRI

chptrs — CHPTRS

chsein — CHSEIN

chseqr — CHSEQR

cla_lin_berr — CLA_LIN_BERR

cla_wwaddw — CLA_WWADDW

claed0 — CLAED0

claed7 — CLAED7

claed8 — CLAED8

clals0 — CLALS0

clalsa — CLALSA

clalsd — CLALSD

clanhf — CLANHF

clarscl2 — CLARSCL2

clarz — CLARZ

clarzb — CLARZB

clarzt — CLARZT

clascl2 — CLASCL2

clatrz — CLATRZ

cpbcon — CPBCON

cpbequ — CPBEQU

cpbrfs — CPBRFS

cpbstf — CPBSTF

cpbtf2 — CPBTF2

cpbtrf — CPBTRF

cpbtrs — CPBTRS

cpftrf — CPFTRF

cpftri — CPFTRI

cpftrs — CPFTRS

cppcon — CPPCON

cppequ — CPPEQU

cpprfs — CPPRFS

cpptrf — CPPTRF

cpptri — CPPTRI

cpptrs — CPPTRS

cpstf2 — CPSTF2

cpstrf — CPSTRF

cspcon — CSPCON

csprfs — CSPRFS

csptrf — CSPTRF

csptri — CSPTRI

csptrs — CSPTRS

cstedc — CSTEDC

cstegr — CSTEGR

cstein — CSTEIN

cstemr — CSTEMR

csteqr — CSTEQR

ctbcon — CTBCON

ctbrfs — CTBRFS

ctbtrs — CTBTRS

ctfsm — CTFSM

ctftri — CTFTRI

ctfttp — CTFTTP

ctfttr — CTFTTR

ctgsen — CTGSEN

ctgsja — CTGSJA

ctgsna — CTGSNA

ctpcon — CTPCON

`cbbcsd` — CBBCSD

`cbdsqr` — CBDSQR

`cgghd3` — CGGHD3

`cgghrd` — CGGHRD

`cggqrf` — CGGQRF

`cggrqf` — CGGRQF

`cggsvp3` — CGGSVP3

`cgsvj0` — CGSVJ0

`cgsvj1` — CGSVJ1

`chbgst` — CHBGST

`chbtrd` — CHBTRD

`chetrd_hb2st` — CHETRD_HB2ST

`chfrk` — CHFRK

`chpcon` — CHPCON

`chpgst` — CHPGST

`chprfs` — CHPRFS

`chptrd` — CHPTRD

`chptrf` — CHPTRF

`chptri` — CHPTRI

`chptrs` — CHPTRS

`chsein` — CHSEIN

`chseqr` — CHSEQR

`cla_lin_berr` — CLA_LIN_BERR

`cla_wwaddw` — CLA_WWADDW

`claed0` — CLAED0

`claed7` — CLAED7

`claed8` — CLAED8

`clals0` — CLALS0

`clalsa` — CLALSA

`clalsd` — CLALSD

`clanhf` — CLANHF

`clarscl2` — CLARSCL2

`clarz` — CLARZ

`clarzb` — CLARZB

`clarzt` — CLARZT

`clascl2` — CLASCL2

`clatrz` — CLATRZ

`cpbcon` — CPBCON

`cpbequ` — CPBEQU

`cpbrfs` — CPBRFS

`cpbstf` — CPBSTF

`cpbtf2` — CPBTF2

`cpbtrf` — CPBTRF

`cpbtrs` — CPBTRS

`cpftrf` — CPFTRF

`cpftri` — CPFTRI

`cpftrs` — CPFTRS

`cppcon` — CPPCON

`cppequ` — CPPEQU

`cpprfs` — CPPRFS

`cpptrf` — CPPTRF

`cpptri` — CPPTRI

`cpptrs` — CPPTRS

`cpstf2` — CPSTF2

`cpstrf` — CPSTRF

`cspcon` — CSPCON

`csprfs` — CSPRFS

`csptrf` — CSPTRF

`csptri` — CSPTRI

`csptrs` — CSPTRS

`cstedc` — CSTEDC

`cstegr` — CSTEGR

`cstein` — CSTEIN

`cstemr` — CSTEMR

`csteqr` — CSTEQR

`ctbcon` — CTBCON

`ctbrfs` — CTBRFS

`ctbtrs` — CTBTRS

`ctfsm` — CTFSM

`ctftri` — CTFTRI

`ctfttp` — CTFTTP

`ctfttr` — CTFTTR

`ctgsen` — CTGSEN

`ctgsja` — CTGSJA

`ctgsna` — CTGSNA

`ctpcon` — CTPCON

`ctpmqrt` — CTPMQRT

`ctpqrt` — CTPQRT

`ctpqrt2` — CTPQRT2

`ctprfs` — CTPRFS