realOTHERcomputational(3)

📦

version 3.11.0 · 2 versions

3.11.0 · debian bookworm (latest)
3.10.0 · ubuntu jammy

okay so bestie, welcome to realOTHERcomputational(3) from the LAPACK manual ✨ this one is short and sweet, and it is literally serving exactly what it says 💅

✨ NAME ✨

realOTHERcomputational — real

✨ SYNOPSIS ✨

okay bestie, this is the full roster 💖 — every single function this page is handing you. no skipping, no "lol I'll just read the first three", we're doing all of them. signatures are copied character for character so you can trust them, fr fr. 🫶

🌸 Functions 🌸

subroutine sbbcsd (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, WORK, LWORK, INFO) — SBBCSD
subroutine sgghd3 (COMPQ, COMPZ, N, ILO, IHI, A, LDA, B, LDB, Q, LDQ, Z, LDZ, WORK, LWORK, INFO) — SGGHD3
subroutine sgghrd (COMPQ, COMPZ, N, ILO, IHI, A, LDA, B, LDB, Q, LDQ, Z, LDZ, INFO) — SGGHRD
subroutine sggqrf (N, M, P, A, LDA, TAUA, B, LDB, TAUB, WORK, LWORK, INFO) — SGGQRF
subroutine sggrqf (M, P, N, A, LDA, TAUA, B, LDB, TAUB, WORK, LWORK, INFO) — SGGRQF
subroutine sggsvp3 (JOBU, JOBV, JOBQ, M, P, N, A, LDA, B, LDB, TOLA, TOLB, K, L, U, LDU, V, LDV, Q, LDQ, IWORK, TAU, WORK, LWORK, INFO) — SGGSVP3
subroutine sgsvj0 (JOBV, M, N, A, LDA, D, SVA, MV, V, LDV, EPS, SFMIN, TOL, NSWEEP, WORK, LWORK, INFO) — SGSVJ0, aka the pre-processor for the routine sgesvj. 💅
subroutine sgsvj1 (JOBV, M, N, N1, A, LDA, D, SVA, MV, V, LDV, EPS, SFMIN, TOL, NSWEEP, WORK, LWORK, INFO) — SGSVJ1, pre-processor for the routine sgesvj, and it applies Jacobi rotations targeting only particular pivots. picky queen behavior, we love it.
subroutine shsein (SIDE, EIGSRC, INITV, SELECT, N, H, LDH, WR, WI, VL, LDVL, VR, LDVR, MM, M, WORK, IFAILL, IFAILR, INFO) — SHSEIN
subroutine shseqr (JOB, COMPZ, N, ILO, IHI, H, LDH, WR, WI, Z, LDZ, WORK, LWORK, INFO) — SHSEQR
subroutine sla_lin_berr (N, NZ, NRHS, RES, AYB, BERR) — SLA_LIN_BERR computes a component-wise relative backward error. ✨
subroutine sla_wwaddw (N, X, Y, W) — SLA_WWADDW adds a vector into a doubled-single vector.
subroutine slals0 (ICOMPQ, NL, NR, SQRE, NRHS, B, LDB, BX, LDBX, PERM, GIVPTR, GIVCOL, LDGCOL, GIVNUM, LDGNUM, POLES, DIFL, DIFR, Z, K, C, S, WORK, INFO) — SLALS0 applies back multiplying factors in solving the least squares problem using divide and conquer SVD approach. used by sgelsd. 🦋
subroutine slalsa (ICOMPQ, SMLSIZ, N, NRHS, B, LDB, BX, LDBX, U, LDU, VT, K, DIFL, DIFR, Z, POLES, GIVPTR, GIVCOL, LDGCOL, PERM, GIVNUM, C, S, WORK, IWORK, INFO) — SLALSA computes the SVD of the coefficient matrix in compact form. used by sgelsd. 💜
subroutine slalsd (UPLO, SMLSIZ, N, NRHS, D, E, B, LDB, RCOND, RANK, WORK, IWORK, INFO) — SLALSD uses the singular value decomposition of A to solve the least squares problem.
real function slansf (NORM, TRANSR, UPLO, N, A, WORK) — SLANSF
subroutine slarscl2 (M, N, D, X, LDX) — SLARSCL2 performs reciprocal diagonal scaling on a matrix.
subroutine slarz (SIDE, M, N, L, V, INCV, TAU, C, LDC, WORK) — SLARZ applies an elementary reflector (as returned by stzrzf) to a general matrix.
subroutine slarzb (SIDE, TRANS, DIRECT, STOREV, M, N, K, L, V, LDV, T, LDT, C, LDC, WORK, LDWORK) — SLARZB applies a block reflector or its transpose to a general matrix.
subroutine slarzt (DIRECT, STOREV, N, K, V, LDV, TAU, T, LDT) — SLARZT forms the triangular factor T of a block reflector H = I - vtvH. 🎀
subroutine slascl2 (M, N, D, X, LDX) — SLASCL2 performs diagonal scaling on a matrix.
subroutine slatrz (M, N, L, A, LDA, TAU, WORK) — SLATRZ factors an upper trapezoidal matrix by means of orthogonal transformations.
subroutine sopgtr (UPLO, N, AP, TAU, Q, LDQ, WORK, INFO) — SOPGTR
subroutine sopmtr (SIDE, UPLO, TRANS, M, N, AP, TAU, C, LDC, WORK, INFO) — SOPMTR
subroutine sorbdb (TRANS, SIGNS, M, P, Q, X11, LDX11, X12, LDX12, X21, LDX21, X22, LDX22, THETA, PHI, TAUP1, TAUP2, TAUQ1, TAUQ2, WORK, LWORK, INFO) — SORBDB
subroutine sorbdb1 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — SORBDB1
subroutine sorbdb2 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — SORBDB2
subroutine sorbdb3 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — SORBDB3
subroutine sorbdb4 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, PHANTOM, WORK, LWORK, INFO) — SORBDB4. yes bestie there is a PHANTOM argument, it's giving haunted 👻
subroutine sorbdb5 (M1, M2, N, X1, INCX1, X2, INCX2, Q1, LDQ1, Q2, LDQ2, WORK, LWORK, INFO) — SORBDB5
subroutine sorbdb6 (M1, M2, N, X1, INCX1, X2, INCX2, Q1, LDQ1, Q2, LDQ2, WORK, LWORK, INFO) — SORBDB6
recursive subroutine sorcsd (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, IWORK, INFO) — SORCSD, and yeah she's recursive, she contains multitudes 💅
subroutine sorcsd2by1 (JOBU1, JOBU2, JOBV1T, M, P, Q, X11, LDX11, X21, LDX21, THETA, U1, LDU1, U2, LDU2, V1T, LDV1T, WORK, LWORK, IWORK, INFO) — SORCSD2BY1
subroutine sorg2l (M, N, K, A, LDA, TAU, WORK, INFO) — SORG2L generates all or part of the orthogonal matrix Q from a QL factorization determined by sgeqlf (unblocked algorithm).
subroutine sorg2r (M, N, K, A, LDA, TAU, WORK, INFO) — SORG2R generates all or part of the orthogonal matrix Q from a QR factorization determined by sgeqrf (unblocked algorithm).
subroutine sorghr (N, ILO, IHI, A, LDA, TAU, WORK, LWORK, INFO) — SORGHR
subroutine sorgl2 (M, N, K, A, LDA, TAU, WORK, INFO) — SORGL2
subroutine sorglq (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — SORGLQ
subroutine sorgql (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — SORGQL
subroutine sorgqr (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — SORGQR
subroutine sorgr2 (M, N, K, A, LDA, TAU, WORK, INFO) — SORGR2 generates all or part of the orthogonal matrix Q from an RQ factorization determined by sgerqf (unblocked algorithm).
subroutine sorgrq (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — SORGRQ
subroutine sorgtr (UPLO, N, A, LDA, TAU, WORK, LWORK, INFO) — SORGTR
subroutine sorm2l (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — SORM2L multiplies a general matrix by the orthogonal matrix from a QL factorization determined by sgeqlf (unblocked algorithm).
subroutine sorm2r (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — SORM2R multiplies a general matrix by the orthogonal matrix from a QR factorization determined by sgeqrf (unblocked algorithm).
subroutine sormbr (VECT, SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — SORMBR
subroutine sormhr (SIDE, TRANS, M, N, ILO, IHI, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — SORMHR
subroutine sorml2 (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — SORML2 multiplies a general matrix by the orthogonal matrix from a LQ factorization determined by sgelqf (unblocked algorithm).
subroutine sormlq (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — SORMLQ
subroutine sormql (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — SORMQL
subroutine sormqr (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — SORMQR
subroutine sormr2 (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — SORMR2 multiplies a general matrix by the orthogonal matrix from a RQ factorization determined by sgerqf (unblocked algorithm).
subroutine sormr3 (SIDE, TRANS, M, N, K, L, A, LDA, TAU, C, LDC, WORK, INFO) — SORMR3 multiplies a general matrix by the orthogonal matrix from a RZ factorization determined by stzrzf (unblocked algorithm).
subroutine sormrq (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — SORMRQ
subroutine sormrz (SIDE, TRANS, M, N, K, L, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — SORMRZ
subroutine sormtr (SIDE, UPLO, TRANS, M, N, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — SORMTR

okay we're pivoting from the sor* girlies into the sp* girlies and I need you to stay with me, the naming gets so specific 🍓

subroutine spbcon (UPLO, N, KD, AB, LDAB, ANORM, RCOND, WORK, IWORK, INFO) — SPBCON
subroutine spbequ (UPLO, N, KD, AB, LDAB, S, SCOND, AMAX, INFO) — SPBEQU
subroutine spbrfs (UPLO, N, KD, NRHS, AB, LDAB, AFB, LDAFB, B, LDB, X, LDX, FERR, BERR, WORK, IWORK, INFO) — SPBRFS
subroutine spbstf (UPLO, N, KD, AB, LDAB, INFO) — SPBSTF
subroutine spbtf2 (UPLO, N, KD, AB, LDAB, INFO) — SPBTF2 computes the Cholesky factorization of a symmetric/Hermitian positive definite band matrix (unblocked algorithm). 💖
subroutine spbtrf (UPLO, N, KD, AB, LDAB, INFO) — SPBTRF
subroutine spbtrs (UPLO, N, KD, NRHS, AB, LDAB, B, LDB, INFO) — SPBTRS
subroutine spftrf (TRANSR, UPLO, N, A, INFO) — SPFTRF
subroutine spftri (TRANSR, UPLO, N, A, INFO) — SPFTRI
subroutine spftrs (TRANSR, UPLO, N, NRHS, A, B, LDB, INFO) — SPFTRS
subroutine sppcon (UPLO, N, AP, ANORM, RCOND, WORK, IWORK, INFO) — SPPCON
subroutine sppequ (UPLO, N, AP, S, SCOND, AMAX, INFO) — SPPEQU
subroutine spprfs (UPLO, N, NRHS, AP, AFP, B, LDB, X, LDX, FERR, BERR, WORK, IWORK, INFO) — SPPRFS
subroutine spptrf (UPLO, N, AP, INFO) — SPPTRF
subroutine spptri (UPLO, N, AP, INFO) — SPPTRI
subroutine spptrs (UPLO, N, NRHS, AP, B, LDB, INFO) — SPPTRS
subroutine spstf2 (UPLO, N, A, LDA, PIV, RANK, TOL, WORK, INFO) — SPSTF2 computes the Cholesky factorization with complete pivoting of a real symmetric positive semidefinite matrix. ✨
subroutine spstrf (UPLO, N, A, LDA, PIV, RANK, TOL, WORK, INFO) — SPSTRF computes the Cholesky factorization with complete pivoting of a real symmetric positive semidefinite matrix. ✨ (yes bestie, same energy as spstf2, they're sisters)
subroutine ssbgst (VECT, UPLO, N, KA, KB, AB, LDAB, BB, LDBB, X, LDX, WORK, INFO) — SSBGST
subroutine ssbtrd (VECT, UPLO, N, KD, AB, LDAB, D, E, Q, LDQ, WORK, INFO) — SSBTRD
subroutine ssfrk (TRANSR, UPLO, TRANS, N, K, ALPHA, A, LDA, BETA, C) — SSFRK performs a symmetric rank-k operation for matrix in RFP format. 🔥
subroutine sspcon (UPLO, N, AP, IPIV, ANORM, RCOND, WORK, IWORK, INFO) — SSPCON
subroutine sspgst (ITYPE, UPLO, N, AP, BP, INFO) — SSPGST
subroutine ssprfs (UPLO, N, NRHS, AP, AFP, IPIV, B, LDB, X, LDX, FERR, BERR, WORK, IWORK, INFO) — SSPRFS
subroutine ssptrd (UPLO, N, AP, D, E, TAU, INFO) — SSPTRD
subroutine ssptrf (UPLO, N, AP, IPIV, INFO) — SSPTRF
subroutine ssptri (UPLO, N, AP, IPIV, WORK, INFO) — SSPTRI
subroutine ssptrs (UPLO, N, NRHS, AP, IPIV, B, LDB, INFO) — SSPTRS
subroutine sstegr (JOBZ, RANGE, N, D, E, VL, VU, IL, IU, ABSTOL, M, W, Z, LDZ, ISUPPZ, WORK, LWORK, IWORK, LIWORK, INFO) — SSTEGR
subroutine sstein (N, D, E, M, W, IBLOCK, ISPLIT, Z, LDZ, WORK, IWORK, IFAIL, INFO) — SSTEIN

and that's the whole function lineup for this part bestie, every last one accounted for 🫶💖 there's more coming so don't go anywhere, we're not even close to done ✨

subroutine sstemr (JOBZ, RANGE, N, D, E, VL, VU, IL, IU, M, W, Z, LDZ, NZC, ISUPPZ, TRYRAC, WORK, LWORK, IWORK, LIWORK, INFO) — SSTEMR 💅
subroutine stbcon (NORM, UPLO, DIAG, N, KD, AB, LDAB, RCOND, WORK, IWORK, INFO) — STBCON ✨
subroutine stbrfs (UPLO, TRANS, DIAG, N, KD, NRHS, AB, LDAB, B, LDB, X, LDX, FERR, BERR, WORK, IWORK, INFO) — STBRFS 🎀
subroutine stbtrs (UPLO, TRANS, DIAG, N, KD, NRHS, AB, LDAB, B, LDB, INFO) — STBTRS 🦋
subroutine stfsm (TRANSR, SIDE, UPLO, TRANS, DIAG, M, N, ALPHA, A, B, LDB) — STFSM solves a matrix equation (one operand is a triangular matrix in RFP format). 🔥
subroutine stftri (TRANSR, UPLO, DIAG, N, A, INFO) — STFTRI 🌸
subroutine stfttp (TRANSR, UPLO, N, ARF, AP, INFO) — STFTTP copies a triangular matrix from the rectangular full packed format (TF) to the standard packed format (TP). 💖
subroutine stfttr (TRANSR, UPLO, N, ARF, A, LDA, INFO) — STFTTR copies a triangular matrix from the rectangular full packed format (TF) to the standard full format (TR). 💅
subroutine stgsen (IJOB, WANTQ, WANTZ, SELECT, N, A, LDA, B, LDB, ALPHAR, ALPHAI, BETA, Q, LDQ, Z, LDZ, M, PL, PR, DIF, WORK, LWORK, IWORK, LIWORK, INFO) — STGSEN 👑
subroutine stgsja (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) — STGSJA 🌈
subroutine stgsna (JOB, HOWMNY, SELECT, N, A, LDA, B, LDB, VL, LDVL, VR, LDVR, S, DIF, MM, M, WORK, LWORK, IWORK, INFO) — STGSNA ⭐
subroutine stpcon (NORM, UPLO, DIAG, N, AP, RCOND, WORK, IWORK, INFO) — STPCON 💀
subroutine stpmqrt (SIDE, TRANS, M, N, K, L, NB, V, LDV, T, LDT, A, LDA, B, LDB, WORK, INFO) — STPMQRT 🙈
subroutine stpqrt (M, N, L, NB, A, LDA, B, LDB, T, LDT, WORK, INFO) — STPQRT 🍓
subroutine stpqrt2 (M, N, L, A, LDA, B, LDB, T, LDT, INFO) — STPQRT2 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. 🧚
subroutine stprfs (UPLO, TRANS, DIAG, N, NRHS, AP, B, LDB, X, LDX, FERR, BERR, WORK, IWORK, INFO) — STPRFS 💜
subroutine stptri (UPLO, DIAG, N, AP, INFO) — STPTRI ✨
subroutine stptrs (UPLO, TRANS, DIAG, N, NRHS, AP, B, LDB, INFO) — STPTRS 💖
subroutine stpttf (TRANSR, UPLO, N, AP, ARF, INFO) — STPTTF copies a triangular matrix from the standard packed format (TP) to the rectangular full packed format (TF). 🎀
subroutine stpttr (UPLO, N, AP, A, LDA, INFO) — STPTTR copies a triangular matrix from the standard packed format (TP) to the standard full format (TR). 🦋
subroutine strcon (NORM, UPLO, DIAG, N, A, LDA, RCOND, WORK, IWORK, INFO) — STRCON 🌸
subroutine strevc (SIDE, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, MM, M, WORK, INFO) — STREVC 🔥
subroutine strevc3 (SIDE, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, MM, M, WORK, LWORK, INFO) — STREVC3 💅
subroutine strexc (COMPQ, N, T, LDT, Q, LDQ, IFST, ILST, WORK, INFO) — STREXC 👑
subroutine strrfs (UPLO, TRANS, DIAG, N, NRHS, A, LDA, B, LDB, X, LDX, FERR, BERR, WORK, IWORK, INFO) — STRRFS 🌈
subroutine strsen (JOB, COMPQ, SELECT, N, T, LDT, Q, LDQ, WR, WI, M, S, SEP, WORK, LWORK, IWORK, LIWORK, INFO) — STRSEN ⭐
subroutine strsna (JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, S, SEP, MM, M, WORK, LDWORK, IWORK, INFO) — STRSNA 💀
subroutine strti2 (UPLO, DIAG, N, A, LDA, INFO) — STRTI2 computes the inverse of a triangular matrix (unblocked algorithm). 🙈
subroutine strtri (UPLO, DIAG, N, A, LDA, INFO) — STRTRI 🍓
subroutine strtrs (UPLO, TRANS, DIAG, N, NRHS, A, LDA, B, LDB, INFO) — STRTRS 🧚
subroutine strttf (TRANSR, UPLO, N, A, LDA, ARF, INFO) — STRTTF copies a triangular matrix from the standard full format (TR) to the rectangular full packed format (TF). 💜
subroutine strttp (UPLO, N, A, LDA, AP, INFO) — STRTTP copies a triangular matrix from the standard full format (TR) to the standard packed format (TP). ✨
subroutine stzrzf (M, N, A, LDA, TAU, WORK, LWORK, INFO) — STZRZF 💖

💖 Detailed Description 💖

okay so bestie, this whole page is the group of real other Computational routines. no cap. 🫶

🌸 Function Documentation 🌸

🦋 subroutine sbbcsd (...) 🦋

subroutine sbbcsd (character JOBU1, character JOBU2, character JOBV1T,
    character JOBV2T, character TRANS, integer M, integer P, integer Q,
    real, dimension( * ) THETA, real, dimension( * ) PHI, real, dimension(
    ldu1, * ) U1, integer LDU1, real, dimension( ldu2, * ) U2, integer LDU2,
    real, dimension( ldv1t, * ) V1T, integer LDV1T, real, 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( * ) WORK, integer
    LWORK, integer INFO)

SBBCSD

Purpose:

okay so SBBCSD computes the CS decomposition of an orthogonal matrix in bidiagonal-block form, and the vibe is literally this:

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

                          [  C | -S  0  0 ]
              [ U1 |    ] [  0 |  0 -I  0 ] [ V1 |    ]**T
            = [---------] [---------------] [---------]   .
              [    | 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 must be no larger than P, M-P, or M-Q. (If Q is not the smallest index, then X must be transposed and/or permuted. This can be done in constant time using the TRANS and SIGNS options. See SORCSD for details.) ✨

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

The orthogonal 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.
- = 'Y': U1 is updated;
- otherwise: U1 is not updated.
JOBU2 — JOBU2 is CHARACTER.
- = 'Y': U2 is updated;
- otherwise: U2 is not updated.
JOBV1T — JOBV1T is CHARACTER.
- = 'Y': V1T is updated;
- otherwise: V1T is not updated.
JOBV2T — JOBV2T is CHARACTER.
- = 'Y': V2T is updated;
- otherwise: V2T is not updated.
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.
M — M is INTEGER. The number of rows and columns in X, the orthogonal 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 is REAL array, dimension (Q-1). The angles PHI(1),...,PHI(Q-1) that, along with THETA(1),...,THETA(Q), define the matrix in bidiagonal-block form.
U1 — U1 is REAL 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 ]. 💖
LDU1 — LDU1 is INTEGER. The leading dimension of the array U1, LDU1 >= MAX(1,P).
U2 — U2 is REAL 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 ]. 🦋
LDU2 — LDU2 is INTEGER. The leading dimension of the array U2, LDU2 >= MAX(1,M-P).
V1T — V1T is REAL array, dimension (LDV1T,Q). On entry, a Q-by-Q matrix. On exit, V1T is premultiplied by the transpose of the right singular vector matrix common to [ B11 ; 0 ] and [ B21 ; 0 ]. 🌸
LDV1T — LDV1T is INTEGER. The leading dimension of the array V1T, LDV1T >= MAX(1,Q).
V2T — V2T is REAL array, dimension (LDV2T,M-Q). On entry, an (M-Q)-by-(M-Q) matrix. On exit, V2T is premultiplied by the transpose of the right singular vector matrix common to [ B12 0 0 ; 0 -I 0 ] and [ B22 0 0 ; 0 0 I ]. 🔥
LDV2T — LDV2T is INTEGER. The leading dimension of the array V2T, LDV2T >= MAX(1,M-Q).
B11D — B11D is REAL array, dimension (Q). When SBBCSD converges, B11D contains the cosines of THETA(1), ..., THETA(Q). If SBBCSD fails to converge, then B11D contains the diagonal of the partially reduced top-left block. 💅
B11E — B11E is REAL array, dimension (Q-1). When SBBCSD converges, B11E contains zeros. If SBBCSD fails to converge, then B11E contains the superdiagonal of the partially reduced top-left block. ✨
B12D — B12D is REAL array, dimension (Q). When SBBCSD converges, B12D contains the negative sines of THETA(1), ..., THETA(Q). If SBBCSD fails to converge, then B12D contains the diagonal of the partially reduced top-right block. 🎀
B12E — B12E is REAL array, dimension (Q-1). When SBBCSD converges, B12E contains zeros. If SBBCSD fails to converge, then B12E contains the subdiagonal of the partially reduced top-right block. 🦋
B21D
B21D — REAL array, dimension (Q)

Once SBBCSD actually converges 💖, B21D is holding the negative sines of THETA(1), ..., THETA(Q). But if SBBCSD taps out and fails to converge, B21D is instead stuck with the diagonal of the partially reduced bottom-left block. not the glow-up we wanted 😭

B21E — REAL array, dimension (Q-1)

When SBBCSD converges, B21E is literally all zeros ✨. If SBBCSD fails to converge, B21E holds the subdiagonal of the partially reduced bottom-left block instead.

B22D — REAL array, dimension (Q)

Same deal, bottom-right edition: on convergence, B22D contains the negative sines of THETA(1), ..., THETA(Q). If SBBCSD doesn't converge, it's holding the diagonal of the partially reduced bottom-right block. 💅

B22E — REAL array, dimension (Q-1)

Converged? B22E is zeros, periodt. Not converged? Then B22E contains the subdiagonal of the partially reduced bottom-right block. 🦋

WORK — REAL array, dimension (MAX(1,LWORK))

On exit, if INFO = 0, then WORK(1) hands you back the optimal LWORK. cute little receipt 🧾

LWORK — INTEGER

This is the dimension of the array WORK. LWORK >= MAX(1,8*Q).

And bestie, listen: if LWORK = -1, then a workspace query is assumed 👀 — the routine only calculates the optimal size of the WORK array, returns that value as the first entry of the work array, and XERBLA will not throw an error message about LWORK. it's giving "just asking, not committing" 🙈

INFO — INTEGER
- = 0: successful exit. we ate. 🔥
- < 0: if INFO = -i, the i-th argument had an illegal value. 🚩
- > 0: if SBBCSD did not converge, INFO specifies the number of nonzero entries in PHI, and B11D, B11E, etc., contain the partially reduced matrix. the situation is not giving.

🧠 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) get rounded to 0 or PI/2 whenever they're within TOLMUL*EPS of either bound. vibe check on the boundaries, basically. 🌈

📚 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 `sgghd3` 🌸

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

SGGHD3

✨ Purpose ✨

SGGHD3 reduces a pair of real matrices (A,B) to generalized upper Hessenberg form using orthogonal 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 orthogonal matrix Q to the left side of the equation. iconic behavior 💅

This subroutine simultaneously reduces A to a Hessenberg matrix H:

Q**T*A*Z = H

and transforms B to another upper triangular matrix T:

Q**T*B*Z = T

in order to reduce the problem to its standard form

H*y = lambda*T*y

where y = Z**T*x. slay. 💖

The orthogonal 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**T = (Q1*Q) * H * (Z1*Z)**T

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

If Q1 is the orthogonal matrix from the QR factorization of B in the original equation A*x = lambda*B*x, then SGGHD3 reduces the original problem to generalized Hessenberg form. 🦋

This is a blocked variant of SGGHRD, using matrix-matrix multiplications for parts of the computation to enhance performance. performance queen 👑

🎀 Parameters 🎀

COMPQ — CHARACTER*1
- = 'N': do not compute Q;
- = 'I': Q is initialized to the unit matrix, and the orthogonal matrix Q is returned;
- = 'V': Q must contain an orthogonal matrix Q1 on entry, and the product Q1*Q is returned.
COMPZ — CHARACTER*1
- = 'N': do not compute Z;
- = 'I': Z is initialized to the unit matrix, and the orthogonal matrix Z is returned;
- = 'V': Z must contain an orthogonal 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 SGGBAL; 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 — REAL 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. 💀 gone, reduced to atoms.

LDA — INTEGER

The leading dimension of the array A. LDA >= max(1,N).

B — REAL array, dimension (LDB, N)

On entry, the N-by-N upper triangular matrix B. On exit, the upper triangular matrix T = Q**T 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 — REAL array, dimension (LDQ, N)

On entry, if COMPQ = 'V', the orthogonal matrix Q1, typically from the QR factorization of B. On exit, if COMPQ='I', the orthogonal 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 — REAL array, dimension (LDZ, N)

On entry, if COMPZ = 'V', the orthogonal matrix Z1. On exit, if COMPZ='I', the orthogonal 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 — REAL 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. just peeking, no strings attached 💅

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). the lore is real 📖

🌈 subroutine `sgghrd` 🌈

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

SGGHRD

✨ Purpose ✨

SGGHRD reduces a pair of real matrices (A,B) to generalized upper Hessenberg form using orthogonal 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 orthogonal matrix Q to the left side of the equation.

This subroutine simultaneously reduces A to a Hessenberg matrix H:

Q**T*A*Z = H

and transforms B to another upper triangular matrix T:

Q**T*B*Z = T

in order to reduce the problem to its standard form

H*y = lambda*T*y

where y = Z**T*x. 🦋

The orthogonal 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**T = (Q1*Q) * H * (Z1*Z)**T

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

If Q1 is the orthogonal matrix from the QR factorization of B in the original equation A*x = lambda*B*x, then SGGHRD reduces the original problem to generalized Hessenberg form. no cap 💖

🎀 Parameters 🎀

COMPQ — CHARACTER*1
- = 'N': do not compute Q;
- = 'I': Q is initialized to the unit matrix, and the orthogonal matrix Q is returned;
- = 'V': Q must contain an orthogonal matrix Q1 on entry, and the product Q1*Q is returned.
COMPZ — CHARACTER*1
- = 'N': do not compute Z;
- = 'I': Z is initialized to the unit matrix, and the orthogonal matrix Z is returned;
- = 'V': Z must contain an orthogonal matrix Z1 on entry, and the product Z1*Z is returned.

N

Okay bestie, N is an INTEGER — it's the order of the matrices A and B. You know the rule: N >= 0. 💅

ILO

ILO is an INTEGER. That's it, that's the whole vibe. 🎀

IHI

IHI is an INTEGER.

So like, ILO and IHI mark the rows and columns of A that are getting reduced. It's assumed that A is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N. Usually you get ILO and IHI from a previous call to SGGBAL; if not, just set them to 1 and N respectively. And the rules are: 1 <= ILO <= IHI <= N, if N > 0; and ILO=1 and IHI=0, if N=0. Periodt. ✨

A

A is a REAL array, dimension (LDA, N).

On entry, it's 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. So like, glow-up but make it Hessenberg. 🔥

LDA

LDA is an INTEGER. It's the leading dimension of the array A. You need LDA >= max(1,N). No cap. 💯

B

B is a REAL array, dimension (LDB, N).

On entry, it's the N-by-N upper triangular matrix B. On exit, it's the upper triangular matrix T = Q**T B Z. The elements below the diagonal are set to zero. Slay. 👑

LDB

LDB is an INTEGER. The leading dimension of the array B. LDB >= max(1,N). You got this. 🫶

Q

Q is a REAL array, dimension (LDQ, N).

On entry, if COMPQ = 'V', it's the orthogonal matrix Q1, typically from the QR factorization of B. On exit, if COMPQ='I', it's the orthogonal matrix Q, and if COMPQ = 'V', it's the product Q1*Q. Not referenced if COMPQ='N'. So if you're not using it, it's just there vibing. 💅

LDQ

LDQ is an INTEGER. The leading dimension of the array Q. LDQ >= N if COMPQ='V' or 'I'; LDQ >= 1 otherwise. Simple as that. ✨

Z

Z is a REAL array, dimension (LDZ, N).

On entry, if COMPZ = 'V', it's the orthogonal matrix Z1. On exit, if COMPZ='I', it's the orthogonal matrix Z, and if COMPZ = 'V', it's the product Z1*Z. Not referenced if COMPZ='N'. Iconic. 🌸

LDZ

LDZ is an INTEGER. The leading dimension of the array Z. LDZ >= N if COMPZ='V' or 'I'; LDZ >= 1 otherwise. That's the tea. 🍓

INFO

INFO is an INTEGER.

= 0: successful exit. We love to see it. 🎉
< 0: if INFO = -i, the i-th argument had an illegal value. Oops. 😭

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

SGGQRF

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

Purpose:

SGGQRF 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 orthogonal matrix, Z is a P-by-P orthogonal 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**T*(inv(T)*R)

where inv(B) denotes the inverse of the matrix B, and Z**T denotes the transpose of the matrix Z. 💖

Parameters

N

N is an INTEGER. The number of rows of the matrices A and B. N >= 0. 💅

M

M is an INTEGER. The number of columns of the matrix A. M >= 0. ✨

P

P is an INTEGER. The number of columns of the matrix B. P >= 0. 🎀

A

A is a REAL array, dimension (LDA,M).

On entry, it's 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, with the array TAUA, represent the orthogonal matrix Q as a product of min(N,M) elementary reflectors (see Further Details). So it's giving matrix glow-up. 🔥

LDA

LDA is an INTEGER. The leading dimension of the array A. LDA >= max(1,N). You know the vibe. 💯

TAUA

TAUA is a REAL array, dimension (min(N,M)).

The scalar factors of the elementary reflectors which represent the orthogonal matrix Q (see Further Details). Tiny but mighty. 🦋

B

B is a REAL array, dimension (LDB,P).

On entry, it's 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 orthogonal matrix Z as a product of elementary reflectors (see Further Details). So many matrices, so little time. 😭

LDB

LDB is an INTEGER. The leading dimension of the array B. LDB >= max(1,N). Simple. 🌸

TAUB

TAUB is a REAL array, dimension (min(N,P)).

The scalar factors of the elementary reflectors which represent the orthogonal matrix Z (see Further Details). Slay. 👑

WORK

WORK is a REAL array, dimension (MAX(1,LWORK)).

On exit, if INFO = 0, WORK(1) returns the optimal LWORK. So it's like a little note to future you. 📝

LWORK

LWORK is an 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 SORMQR.

INFO

INFO is 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 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**T

where taua is a real scalar, and v is a real 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 SORGQR. To use Q to update another matrix, use LAPACK subroutine SORMQR.

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**T

where taub is a real scalar, and v is a real 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 SORGRQ. To use Z to update another matrix, use LAPACK subroutine SORMRQ.

SGGRQF

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

Purpose:

SGGRQF 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 orthogonal matrix, Z is a P-by-P orthogonal 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**T

where inv(B) denotes the inverse of the matrix B, and Z**T denotes the transpose of the matrix Z. 💖

Parameters

M

M is an INTEGER. The number of rows of the matrix A. M >= 0. 💅

P

P is an INTEGER. The number of rows of the matrix B. P >= 0. ✨

N

N is an INTEGER. The number of columns of the matrices A and B. N >= 0. 🎀

A

A is a REAL array, dimension (LDA,N).

On entry, it's 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 orthogonal matrix Q as a product of elementary reflectors (see Further Details). So it's giving matrix makeover. 🔥

LDA

LDA is an INTEGER. The leading dimension of the array A. LDA >= max(1,M). You know the drill. 💯

TAUA

TAUA — a REAL array, dimension (min(M,N)). These are the scalar factors of the elementary reflectors that build the orthogonal matrix Q — peep Further Details for the whole tea. 💅
B — a REAL array, dimension (LDB,N).
- On entry: the P-by-N matrix B, bestie.
- On exit: the elements on and above the diagonal hold the min(P,N)-by-N upper trapezoidal matrix T (and T is straight-up upper triangular when P >= N); the elements below the diagonal, together with the array TAUB, represent the orthogonal matrix Z as a product of elementary reflectors (again, Further Details has the receipts 📖).
LDB — an INTEGER. It's the leading dimension of the array B. Rule: LDB >= max(1,P). No exceptions, no cap. 🚫🧢
TAUB — a REAL array, dimension (min(P,N)). The scalar factors of the elementary reflectors that represent the orthogonal matrix Z (see Further Details).
WORK — a REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) hands you back the optimal LWORK. ✨
LWORK — an INTEGER. It's the dimension of the array WORK. You need LWORK >= max(1,N,M,P).
- For peak performance you want 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 SORMRQ.
- If LWORK = -1, then it's a workspace query moment — the routine only calculates the optimal size of the WORK array, returns that value as the first entry of the WORK array, and XERBLA will not come for you about LWORK. 🕵️‍♀️
INFO — an INTEGER.
- = 0: successful exit, we ate. 🎉
- < 0: if INF0= -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(m,n).

Each H(i) has the form

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

where taua is a real scalar, and v is a real 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 SORGRQ.

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

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**T

where taub is a real scalar, and v is a real 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 SORGQR.

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

🦋 subroutine `sggsvp3`

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

SGGSVP3

Purpose:

SGGSVP3 computes orthogonal matrices U, V and Q such that

                   N-K-L  K    L
 U**T*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**T*B*Q =   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. K+L = the effective numerical rank of the (M+P)-by-N matrix (A**T,B**T)**T.

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

Parameters

JOBU — a CHARACTER*1.
- = 'U': orthogonal matrix U is computed;
- = 'N': U is not computed.
JOBV — a CHARACTER*1.
- = 'V': orthogonal matrix V is computed;
- = 'N': V is not computed.
JOBQ — a CHARACTER*1.
- = 'Q': orthogonal matrix Q is computed;
- = 'N': Q is not computed.
M — an INTEGER. The number of rows of the matrix A. M >= 0.
P — an INTEGER. The number of rows of the matrix B. P >= 0.
N — an INTEGER. The number of columns of the matrices A and B. N >= 0.
A — a REAL 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 — an INTEGER. The leading dimension of the array A. LDA >= max(1,M).
B — a REAL 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 — an INTEGER. The leading dimension of the array B. LDB >= max(1,P).
TOLA — a REAL.
TOLB — a REAL.
- TOLA and TOLB are the thresholds that determine the effective numerical rank of matrix B and a subblock of A. Generally they're 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. 👀

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

SGGSVP3 replaces the deprecated subroutine SGGSVP. ⚠️ (yes bestie, deprecated — say your goodbyes 🫶)

🦋 subroutine `sgsvj0`

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

SGSVJ0 pre-processor for the routine sgesvj. 🧚

Purpose:

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

Parameters

JOBV — 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.
M — an INTEGER. The number of rows of the input matrix A. M >= 0.
N — an INTEGER. The number of columns of the input matrix A. M >= N >= 0.
A —
A — A is REAL array, dimension (LDA,N)

On entry: an 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 D, TOL and NSWEEP.) it's giving glow-up, fr fr ✨

LDA — LDA is INTEGER

The leading dimension of the array A. LDA >= max(1,M). 👑

D — D is REAL 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 A, TOL and NSWEEP.)

SVA — SVA is 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).

MV — MV is 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. bestie is simply not invited 💅

V — V is REAL 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.

LDV — LDV is INTEGER

The leading dimension of the array V, LDV >= 1.

If JOBV = 'V', LDV >= N.

If JOBV = 'A', LDV >= MV.

EPS — EPS is REAL

EPS = SLAMCH('Epsilon') ⭐

SFMIN — SFMIN is REAL

SFMIN = SLAMCH('Safe Minimum')

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

NSWEEP — NSWEEP is INTEGER

NSWEEP is the number of sweeps of Jacobi rotations to be performed.

WORK — WORK is REAL array, dimension (LWORK)
LWORK — LWORK is INTEGER

LWORK is the dimension of WORK. LWORK >= M. 🫶

INFO — INFO is INTEGER

= 0: successful exit.

< 0: if INFO = -i, then the i-th argument had an illegal value 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

SGSVJ0 is used just to enable SGESVJ to call a simplified version of itself to work on a submatrix of the original matrix. iconic behaviour honestly ✨

Contributors:

Zlatko Drmac (Zagreb, Croatia) and Kresimir Veselic (Hagen, Germany) 🌈

Bugs, Examples and Comments:

Please report all bugs and send interesting test examples and comments to drmac@math.hr. Thank you. 🥺 (yes bestie, an actual email, in an actual manpage, we love to see it)

🧚 subroutine sgsvj1 🧚

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

SGSVJ1 pre-processor for the routine sgesvj, applies Jacobi rotations targeting only particular pivots. 👑

Purpose:

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

Further Details

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

Parameters

JOBV — JOBV is 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 — M is INTEGER

The number of rows of the input matrix A. M >= 0.

N — N is INTEGER

The number of columns of the input matrix A. M >= N >= 0. 🌸

N1 — N1 is INTEGER

N1 specifies the 2 x 2 block partition, the first N1 columns are rotated 'against' the remaining N-N1 columns of A.

A — A is REAL 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.)

LDA — LDA is INTEGER

The leading dimension of the array A. LDA >= max(1,M).

D — D is REAL 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.

(See the descriptions of N1, A, TOL and NSWEEP.)

SVA — SVA is 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). 🦋

MV — MV is 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.

V — V is REAL 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. not referenced = not perceived 💀

LDV — LDV is INTEGER

The leading dimension of the array V, LDV >= 1.

If JOBV = 'V', LDV >= N.

If JOBV = 'A', LDV >= MV.

EPS — EPS is REAL

EPS = SLAMCH('Epsilon')

SFMIN — SFMIN is REAL

SFMIN = SLAMCH('Safe Minimum') ⭐

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

NSWEEP — NSWEEP is INTEGER

NSWEEP is the number of sweeps of Jacobi rotations to be performed.

WORK — WORK is REAL array, dimension (LWORK)
LWORK — LWORK is INTEGER

LWORK is the dimension of WORK. LWORK >= M. 🫶

INFO — INFO is INTEGER

= 0: successful exit.

< 0: if INFO = -i, then the i-th argument had an illegal value 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors:

Zlatko Drmac (Zagreb, Croatia) and Kresimir Veselic (Hagen, Germany) 🌈

🦋 subroutine shsein 🦋

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

SHSEIN

Purpose:

SHSEIN uses inverse iteration to find specified right and/or left eigenvectors of a real upper Hessenberg matrix H. 👑✨

okay bestie, real talk: the right eigenvector x and the left eigenvector y of the matrix H for an eigenvalue w are defined by this iconic little equation:

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

and y**h is just the conjugate transpose of the vector y. periodt. 💅

Parameters ✨

SIDE — it's a CHARACTER*1, so one character, okay?
- 'R': compute right eigenvectors only;
- 'L': compute left eigenvectors only;
- 'B': compute both right and left eigenvectors.
EIGSRC — also CHARACTER*1. Specifies the source of eigenvalues supplied in (WR,WI):
- 'Q': the eigenvalues were found using SHSEQR; so if H has zero subdiagonal elements, and is therefore 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 lets SHSEIN do inverse iteration on just one diagonal block. slay.
- 'N': no assumptions are made about the correspondence between eigenvalues and diagonal blocks. In this case, SHSEIN must always perform inverse iteration using the whole matrix H. no shortcuts.
INITV — CHARACTER*1:
- 'N': no initial vectors are supplied;
- 'U': user-supplied initial vectors are stored in the arrays VL and/or VR.
SELECT — LOGICAL array, dimension (N). Specifies the eigenvectors to be computed. To select the real eigenvector corresponding to real eigenvalue WR(j), SELECT(j) must be set to .TRUE.. To select the complex eigenvector corresponding to complex eigenvalue (WR(j),WI(j)), with complex conjugate (WR(j+1),WI(j+1)), either SELECT(j) or SELECT(j+1) or both must be set to .TRUE.; then on exit SELECT(j) is .TRUE. and SELECT(j+1) is .FALSE.. the way it flips on exit? iconic.
N — INTEGER. The order of the matrix H. N >= 0.
H — REAL array, dimension (LDH,N). The upper Hessenberg matrix H. If a NaN is detected in H, the routine will return with INFO=-6. so don't be sneaky with NaNs, bestie.
LDH — INTEGER. The leading dimension of the array H. LDH >= max(1,N).
WR — REAL array, dimension (N).
WI — REAL array, dimension (N).
- On entry, the real and imaginary parts of the eigenvalues of H; a complex conjugate pair of eigenvalues must be stored in consecutive elements of WR and WI.
- On exit, WR may have been altered since close eigenvalues are perturbed slightly in searching for independent eigenvectors.
VL — REAL 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(s) 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. A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part and the second the imaginary part.
- If SIDE = 'R', VL is not referenced.
LDVL — INTEGER. The leading dimension of the array VL. LDVL >= max(1,N) if SIDE = 'L' or 'B'; LDVL >= 1 otherwise.
VR — REAL 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(s) 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. A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part and the second the imaginary part.
- If SIDE = 'L', VR is not referenced.
LDVR — INTEGER. The leading dimension of the array VR. LDVR >= max(1,N) if SIDE = 'R' or 'B'; LDVR >= 1 otherwise.
MM — INTEGER. The number of columns in the arrays VL and/or VR. MM >= M.
M — INTEGER. The number of columns in the arrays VL and/or VR required to store the eigenvectors; each selected real eigenvector occupies one column and each selected complex eigenvector occupies two columns.
WORK — REAL array, dimension ((N+2)*N).
IFAIL — INTEGER array, dimension (MM). If SIDE = 'L' or 'B', IFAIL(i) = j > 0 if the left eigenvector in the i-th column of VL (corresponding to the eigenvalue w(j)) failed to converge; IFAIL(i) = 0 if the eigenvector converged satisfactorily. If the i-th and (i+1)th columns of VL hold a complex eigenvector, then IFAIL(i) and IFAIL(i+1) are set to the same value. If SIDE = 'R', IFAIL is not referenced.
IFAILR — 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 the i-th and (i+1)th columns of VR hold a complex eigenvector, then IFAILR(i) and IFAILR(i+1) are set to the same value. If SIDE = 'L', IFAILR is not referenced.
INFO — 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 IFAIL and IFAILR for further details.

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

subroutine shseqr (character JOB, character COMPZ, integer N, integer ILO,
     integer IHI, real, dimension( ldh, * ) H, integer LDH, real, dimension(
     * ) WR, real, dimension( * ) WI, real, dimension( ldz, * ) Z, integer
     LDZ, real, dimension( * ) WORK, integer LWORK, integer INFO)

SHSEQR 🦋

Purpose

SHSEQR computes the eigenvalues of a Hessenberg matrix H and, optionally, the matrices T and Z from the Schur decomposition H = Z T Z**T, where T is an upper quasi-triangular matrix (the Schur form), and Z is the orthogonal matrix of Schur vectors.

Optionally Z may be postmultiplied into an input orthogonal matrix Q so that this routine can give the Schur factorization of a matrix A which has been reduced to the Hessenberg form H by the orthogonal matrix Q: A = Q*H*Q**T = (QZ)*T*(QZ)**T.

Parameters 🌸

JOB — CHARACTER*1:
- 'E': compute eigenvalues only;
- 'S': compute eigenvalues and the Schur form T.
COMPZ — 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 an orthogonal matrix Q on entry, and the product Q*Z is returned.
N — INTEGER. The order of the matrix H. N >= 0.
ILO — INTEGER.
IHI — INTEGER.

It is 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 SGEBAL, and then passed to ZGEHRD when the matrix output by SGEBAL is reduced to Hessenberg form. Otherwise ILO and IHI should be set to 1 and N respectively. If N > 0, then 1 <= ILO <= IHI <= N. If N = 0, then ILO = 1 and IHI = 0.

H — REAL array, dimension (LDH,N).
- On entry, the upper Hessenberg matrix H.
- On exit, if INFO = 0 and JOB = 'S', then H contains the upper quasi-triangular matrix T from the Schur decomposition (the Schur form); 2-by-2 diagonal blocks (corresponding to complex conjugate pairs of eigenvalues) are returned in standard form, with H(i,i) = H(i+1,i+1) and H(i+1,i)*H(i,i+1) < 0. 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 SHSEQR, this subroutine may explicitly H(i,j) = 0 for i > j and j = 1, 2, ... ILO-1 or j = IHI+1, IHI+2, ... N.
LDH — INTEGER. The leading dimension of the array H. LDH >= max(1,N).
WR — REAL array, dimension (N).
WI — REAL array, dimension (N).

...the real and imaginary parts, respectively, of the computed eigenvalues, bestie. 💖 And listen, if two eigenvalues come out as a complex conjugate pair, they get stored in consecutive elements of WR and WI — like the i-th and (i+1)-th — with WI(i) > 0 and WI(i+1) < 0. If JOB = 'S', the eigenvalues are stored in the same order as on the diagonal of the Schur form</bad> returned in H, with WR(i) = H(i,i) and, if H(i:i+1,i:i+1) is a 2-by-2 diagonal block, WI(i) = sqrt(-H(i+1,i)*H(i,i+1)) and WI(i+1) = -WI(i). no cap, that's literally the whole thing. 🦋

`Z` 💜

Z is REAL array, dimension (LDZ,N).

If COMPZ = 'N', Z is not referenced at all — she's off the clock. 💀
If COMPZ = 'I', on entry Z need not be set, and on exit, if INFO = 0, Z contains the orthogonal 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 orthogonal matrix generated by SORGHR after the call to SGEHRD which formed the Hessenberg matrix H. (The output value of Z when INFO > 0 is given under the description of INFO below — so like, keep scrolling, it's down there. 👀)

`LDZ` 🎀

LDZ is INTEGER.

It's the leading dimension of the array Z. If COMPZ = 'I' or COMPZ = 'V', then LDZ >= MAX(1,N). Otherwise, LDZ >= 1. that's the vibe check, periodt. ✨

`WORK` 🫶

WORK is REAL array, dimension (LWORK).

On exit, if INFO = 0, WORK(1) returns an estimate of the optimal value for LWORK. she's doing a little fortune-telling for you, iconic. 🔮

`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 SHSEQR does a workspace query. In this case, SHSEQR 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, SHSEQR failed to compute all of the eigenvalues. Elements 1:ilo-1 and i+1:n of WR and WI 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 an orthogonal matrix. The final value of H is upper Hessenberg and quasi-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 orthogonal 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 orthogonal matrix in (*) (regardless of the value of JOB).

If INFO > 0 and COMPZ = 'N', then Z is not accessed. she's literally untouched. 💀

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. absolute legends fr fr. 💜

Further Details 🌸

Default values supplied by:

ILAENV(ISPEC,'SHSEQR',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. like, tune her to your setup, bestie. ✨

ISPEC=12: The SLAHQR vs SLAQR0 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      ...but less    ... the
                                or equal to ...      than        default is

                                     1               30          NS =   2(+)
                                    30               60          NS =   4(+)
                                    60              150          NS =  10(+)
                                   150              590          NS =  **
                                   590             3000          NS =  64
                                  3000             6000          NS = 128
                                  6000             infinity      NS = 256

(+) By default some or all matrices of this order are passed to the implicit double shift routine SLAHQR 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.

subroutine `sla_lin_berr` 🦋

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

SLA_LIN_BERR computes a component-wise relative backward error. slay. 💅

Purpose:

SLA_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 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 REAL 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 sla_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 `sla_wwaddw` 🧚

subroutine sla_wwaddw (integer N, real, dimension( * ) X, real, dimension( *
) Y, real, dimension( * ) W)

SLA_WWADDW adds a vector into a doubled-single vector. obsessed. 🫶

Purpose:

SLA_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 REAL array, dimension (N). The first part of the doubled-single accumulation vector.
Y — Y is REAL array, dimension (N). The second part of the doubled-single accumulation vector.
W — W is REAL array, dimension (N). The vector to be added.

Author 👑

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

✨ subroutine `slals0` ✨

subroutine slals0 (integer ICOMPQ, integer NL, integer NR, integer SQRE,
    integer NRHS, real, dimension( ldb, * ) B, integer LDB, real, 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( * )
    WORK, integer INFO)

SLALS0 applies back multiplying factors in solving the least squares problem using divide and conquer SVD approach. Used by sgelsd. bestie it's giving "the cleanup crew of the SVD world" 💅

🎯 Purpose

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

So for the left singular vector matrix, there's three (3!) types of orthogonal matrices in the mix, and yes we're listing them all:

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

And for the right singular vector matrix, it's four (4!) types of orthogonal matrices, she's high maintenance fr fr:

(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 REAL 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. glow up moment ✨
LDB — LDB is INTEGER. The leading dimension of B. LDB must be at least max(1,MAX( M, N )).
BX — BX is REAL 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 is INTEGER array, dimension ( LDGCOL, 2 ). Each pair of numbers indicates a pair of rows/columns involved in a Givens rotation.
LDGCOL — LDGCOL is INTEGER. The leading dimension of GIVCOL, must be at least N.
GIVNUM — GIVNUM is REAL array, dimension ( LDGNUM, 2 ). Each number indicates the C or S value used in the corresponding Givens rotation.
LDGNUM — LDGNUM is INTEGER. The leading dimension of arrays DIFR, POLES and GIVNUM, must be at least K.
POLES — POLES is REAL array, dimension ( LDGNUM, 2 ). On entry, POLES(1:K, 1) contains the new singular values obtained from solving the secular equation, and POLES(1:K, 2) is an array containing the poles in the secular equation.
DIFL — DIFL is REAL array, dimension ( K ). On entry, DIFL(I) is the distance between I-th updated (undeflated) singular value and the I-th (undeflated) old singular value.
DIFR — DIFR is REAL array, dimension ( LDGNUM, 2 ). On entry, DIFR(I, 1) contains the distances between 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 — Z is REAL array, dimension ( K ). Contain the components of the deflation-adjusted updating row vector.
K — K is INTEGER. Contains the dimension of the non-deflated matrix, this is the order of the related secular equation. 1 <= K <= N.
C — C is REAL. C contains 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. S contains garbage if SQRE = 0 and the S-value of a Givens rotation related to the right null space if SQRE = 1.

Not me flagging that C and S literally contain garbage when SQRE = 0 😭 that is what the docs say, bestie, don't come for me, that's just the vibe of the null space.

WORK — WORK is REAL array, dimension ( K ).
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 `slalsa` 🦋

subroutine slalsa (integer ICOMPQ, integer SMLSIZ, integer N, integer NRHS,
    real, dimension( ldb, * ) B, integer LDB, real, 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( * ) WORK, integer,
    dimension( * ) IWORK, integer INFO)

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

🎯 Purpose

SLALSA is an intermediate step in solving the least squares problem by computing the SVD of the coefficient matrix in compact form — and yes, the singular vectors are computed as products of simple orthogonal matrices, no cap. (The original spells it "itermediate" and "orthorgonal" but we understood the assignment, bestie 💅)

So like: if ICOMPQ = 0, SLALSA applies the inverse of the left singular vector matrix of an upper bidiagonal matrix to the right hand side; and if ICOMPQ = 1, SLALSA applies the right singular vector matrix to the right hand side. The singular vector matrices were generated in compact form by SLALSA. It's giving "I made this and now I'm applying it," main character energy fr.

🌸 Parameters

ICOMPQ — ICOMPQ is INTEGER. Specifies whether the left or the right singular vector matrix is involved.
- = 0: Left singular vector matrix
- = 1: Right singular vector matrix
SMLSIZ — SMLSIZ is INTEGER. The maximum size of the subproblems 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 REAL 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 in the calling subprogram. LDB must be at least max(1,MAX( M, N )).
BX — BX is REAL array, dimension ( LDBX, NRHS ). On exit, 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**T 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) record 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 — it's an 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 — 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 — INTEGER, LDGCOL = > N. The leading dimension of arrays GIVCOL and PERM. 📐
PERM — INTEGER array, dimension ( LDGCOL, NLVL ). On entry, PERM(*, I) records permutations done on the I-th level of the computation tree. 🔄
GIVNUM — 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 — 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 — 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. 🆂
WORK — REAL array, dimension (N) 💪
IWORK — INTEGER array, dimension (3*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.

🌟 Contributors:

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

✨ `subroutine slalsd` ✨

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

SLALSD uses the singular value decomposition of A to solve the least squares problem. 💅

🎯 Purpose

SLALSD uses the singular value decomposition of A to solve the least squares problem of finding X to minimize 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. ✨

The singular values of A smaller than RCOND times the largest singular value are treated as zero in solving the least squares problem; in this case a minimum norm solution is returned. The actual singular values are returned in D in ascending order. 🔥

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 XMP, Cray YMP, Cray C 90, or Cray 2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none. 💀

📋 Parameters

UPLO — CHARACTER*1
- = 'U': D and E define an upper bidiagonal matrix. ⬆️
- = 'L': D and E define a lower bidiagonal matrix. ⬇️
SMLSIZ — INTEGER
- The maximum size of the subproblems at the bottom of the computation tree. 🌳
N — INTEGER
- The dimension of the bidiagonal matrix. N >= 0. 📏
NRHS — INTEGER
- The number of columns of B. NRHS must be at least 1. 🔢
D — 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. 💎
E — REAL array, dimension (N-1)
- Contains the super-diagonal entries of the bidiagonal matrix. On exit, E has been destroyed. 💥
B — REAL array, dimension (LDB,NRHS)
- On input, B contains the right hand sides of the least squares problem. On output, B contains the solution X. 🅱️
LDB — INTEGER
- The leading dimension of B in the calling subprogram. LDB must be at least max(1,N). 📐
RCOND — 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 — INTEGER
- The number of singular values of A greater than RCOND times the largest singular value. 🏆
WORK — REAL array, dimension at least (9*N + 2*N*SMLSIZ + 8*N*NLVL + N*NRHS + (SMLSIZ+1)**2), where NLVL = max(0, INT(log_2 (N/(SMLSIZ+1))) + 1). 🛠️
IWORK — INTEGER array, dimension at least (3*N*NLVL + 11*N) 🧰
INFO — INTEGER
- = 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 slansf` 🌸

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

SLANSF

🎯 Purpose

SLANSF returns the value of the one norm, or the Frobenius norm, or the infinity norm, or the element of largest absolute value of a real symmetric matrix A in RFP format. 👑

📤 Returns

               SLANSF = ( 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 — CHARACTER*1
- Specifies the value to be returned in SLANSF as described above. 🎯
TRANSR — CHARACTER*1
- Specifies whether the RFP format of A is normal or transposed format.
- = 'N': RFP format is Normal; 🔄
- = 'T': RFP format is Transpose. 🔃
UPLO — CHARACTER*1
- On entry, UPLO specifies whether the RFP matrix A came from an upper or lower triangular matrix as follows:
- = 'U': RFP A came from an upper triangular matrix; ⬆️
- = 'L': RFP A came from a lower triangular matrix. ⬇️
N — INTEGER
- The order of the matrix A. N >= 0. When N = 0, SLANSF is set to zero. 0️⃣
A — REAL array, dimension ( N*(N+1)/2 );
- On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') part of the symmetric matrix A stored in RFP format. See the 'Notes' below for more details. Unchanged on exit. 📝
WORK — REAL array, dimension (MAX(1,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:

We first consider Rectangular Full Packed (RFP) 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 the 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 the transpose of the last three columns of AP lower. 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 = 'T'. RFP A in both UPLO cases is just the 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 then consider Rectangular Full Packed (RFP) Format when N is odd. We give an example where N = 5.

okay so picture the packed array AP doing its little layout moment — upper on the left, lower on the right, and yeah it's giving ✨triangle✨:

                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

Now hold TRANSR = 'N' in your head, bestie. RFP holds AP like this:

For UPLO = 'U' the upper trapezoid A(0:4,0:2) is made of the last three columns of AP upper, and the lower triangle A(3:4,0:1) is made of the transpose of the first two columns of AP upper.
For UPLO = 'L' the lower trapezoid A(0:4,0:2) is made of the first three columns of AP lower, and the upper triangle A(0:1,1:2) is made of the transpose of the last two columns of AP lower.
This covers the case N odd and TRANSR = 'N'. noted, no cap 💅

So the RFP A looks like this:

                    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 flip the vibe: let TRANSR = 'T'. RFP A in both UPLO cases is just the 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 slarscl2 (integer M, integer N, real, dimension( * ) D, real, dimension( ldx, * ) X, integer LDX)`

SLARSCL2 does reciprocal diagonal scaling on a matrix, and honestly? humble but essential 🫶

Purpose

It performs a reciprocal diagonal scaling on a matrix:

  x <-- inv(D) * x

where the diagonal matrix D is stored as a vector. (iykyk — the vector is the diagonal.)

Eventually to be replaced by BLAS_sge_diag_scale in the new BLAS standard. so like, it's on its way out, but it's still here serving looks 💜

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 REAL array, dimension (LDX,N). On entry, the matrix X to be scaled by D. On exit, the scaled matrix. glow up complete ✨
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 slarz (character SIDE, integer M, integer N, integer L, real, dimension( * ) V, integer INCV, real TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * ) WORK)`

SLARZ applies an elementary reflector (as returned by stzrzf) to a general matrix. iconic behaviour, fr fr 🌈

Purpose

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

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

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

If tau = 0, then H is taken to be the unit matrix. (nothing to see here, it's just identity, periodt)

H is a product of k elementary reflectors as returned by STZRZF.

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 REAL array, dimension (1+(L-1)*abs(INCV)). The vector v in the representation of H as returned by STZRZF. V is not used if TAU = 0.
INCV — INCV is INTEGER. The increment between elements of v. INCV <> 0. zero is not the move here, bestie
TAU — TAU is REAL. The value tau in the representation of H.
C — C is REAL 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'. overwritten!! say bye to your old C 😭
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is REAL 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:

…and that's literally it, there's nothing under this heading 💀 carry on.

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

SLARZB applies a block reflector or its transpose to a general matrix. block reflector? more like block baddie 👑

Purpose

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

Currently, only STOREV = 'R' and DIRECT = 'B' are supported. so don't come at it with anything else, it will not eat that 💀

Parameters

SIDE — SIDE is CHARACTER*1.
- = 'L': apply H or H**T from the Left
- = 'R': apply H or H**T from the Right
TRANS — TRANS is CHARACTER*1.
- = 'N': apply H (No transpose)
- = 'C': apply H**T (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 REAL 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 REAL 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 REAL array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by H*C or H**T*C or C*H or C*H**T. pick your fighter, it depends on SIDE and TRANS 👑
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is REAL 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:

again — literally nothing lives under this heading, bestie. moving on 💜

🎀 `subroutine slarzt (character DIRECT, character STOREV, integer N, integer K, real, dimension( ldv, * ) V, integer LDV, real, dimension( * ) TAU, real, dimension( ldt, * ) T, integer LDT)`

SLARZT forms the triangular factor T of a block reflector H = I - vtvH. yes that's the whole header, no I'm not editing it 🫶

Purpose

SLARZT forms the triangular factor T of a real 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**T

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**T * T * V

Currently, only STOREV = 'R' and DIRECT = 'B' are supported. everything else is a ✨no✨ for now

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 REAL array, dimension (LDV,K) if STOREV = 'C', or (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 — TAU is a REAL array, dimension (K). Every TAU(i) has to hold the scalar factor of the elementary reflector H(i). That's its whole job bestie, don't skip it 💅
T — T is a REAL array, dimension (LDT,K). It's the k by k triangular factor T of the block reflector. If DIRECT = 'F', then T is upper triangular; if DIRECT = 'B', then T is lower triangular. The rest of the array is just… not used, sitting there, minding its own business 🙈
LDT — LDT is INTEGER. It's the leading dimension of the array T, and LDT >= K. no cap.

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 shape of the matrix V and the way the vectors defining the H(i) get stored? Best illustrated with an example, and the example is n = 5 and k = 3. The elements equal to 1 are not stored — those array elements get modified but restored on exit. And the rest of the array? Not used. periodt.

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

                                                         ______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

             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 )

`subroutine slascl2` 💖

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

SLASCL2 performs diagonal scaling on a matrix. iconic behaviour honestly.

Purpose: 🎯

SLASCL2 performs a diagonal scaling on a matrix:

  x <-- D * x

where the diagonal matrix D is stored as a vector.

Eventually to be replaced by BLAS_sge_diag_scale in the new BLAS standard. So like… enjoy it while it lasts bestie 💀

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 a REAL array, length M. It's the diagonal matrix D, stored as a vector of length M. lowkey elegant.
X — X is a REAL array, dimension (LDX,N). On entry, it's the matrix X to be scaled by D. On exit, it's the scaled matrix. glow up 🦋
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 slatrz` 🎀

subroutine slatrz (integer M, integer N, integer L, real, dimension( lda, *
    ) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK)

SLATRZ factors an upper trapezoidal matrix by means of orthogonal transformations. very demure, very orthogonal ✨

Purpose: 🎯

SLATRZ factors the M-by-(M+L) real upper trapezoidal matrix [ A1 A2 ] = [ A(1:M,1:M) A(1:M,N-L+1:N) ] as ( R 0 ) * Z, by means of orthogonal transformations. Z is an (M+L)-by-(M+L) orthogonal matrix and, R and A1 are M-by-M upper triangular matrices. fr fr.

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 a REAL 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 orthogonal matrix Z as a product of M elementary reflectors. she contains multitudes 💅
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
TAU — TAU is a REAL array, dimension (M). The scalar factors of the elementary reflectors.
WORK — WORK is a REAL 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: ✨

So 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 )**T,   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. no pressure or anything 😭

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 sopgtr` 🌸

subroutine sopgtr (character UPLO, integer N, real, dimension( * ) AP, real,
    dimension( * ) TAU, real, dimension( ldq, * ) Q, integer LDQ, real,
    dimension( * ) WORK, integer INFO)

SOPGTR 👑

Purpose: 🎯

SOPGTR generates a real orthogonal matrix Q which is defined as the product of n-1 elementary reflectors H(i) of order n, as returned by SSPTRD 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).

the way that it just… builds Q from scratch? obsessed. 🫶

Parameters

UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangular packed storage used in previous call to SSPTRD;
- = 'L': Lower triangular packed storage used in previous call to SSPTRD.
N — N is INTEGER. The order of the matrix Q. N >= 0.
AP — AP is a REAL array, dimension (N*(N+1)/2). The vectors which define the elementary reflectors, as returned by SSPTRD.
TAU — TAU is a REAL array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SSPTRD.
Q — Q is a REAL array, dimension (LDQ,N). The N-by-N orthogonal matrix Q. main character energy honestly 👑
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,N).
WORK — WORK is a REAL 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 sopmtr` 🦋

subroutine sopmtr (character SIDE, character UPLO, character TRANS, integer
    M, integer N, real, dimension( * ) AP, real, dimension( * ) TAU, real,
    dimension( ldc, * ) C, integer LDC, real, dimension( * ) WORK, integer
    INFO)

SOPMTR 💜

Purpose: 🎯

SOPMTR 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'. Q is defined as the product of nq-1 elementary reflectors, as returned by SSPTRD using packed storage:

if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);

if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).

it's giving "apply Q from whichever side you want" and honestly? slay.

Parameters

SIDE — SIDE is CHARACTER*1.
- = 'L': apply Q or Q**T from the Left;
- = 'R': apply Q or Q**T from the Right.
UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangular packed storage used in previous call to SSPTRD;
- = 'L': Lower triangular packed storage used in previous call to SSPTRD.
TRANS — TRANS is CHARACTER*1.
- = 'N': No transpose, apply Q;
- = 'T': Transpose, apply Q**T.
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 a REAL 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 SSPTRD. AP is modified by the routine but restored on exit. so don't panic bestie, it comes back 🙈

TAU — TAU is a REAL 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 SSPTRD.
C — C is a 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. she's been through a lot, honestly 😭
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK
WORK — REAL array, dimension (N) if SIDE = 'L', or (M) if SIDE = 'R'. That's the whole vibe. 💅
INFO — INTEGER, and it's giving receipt energy:
- = 0: successful exit, we ate and left no crumbs 🎉
- < 0: if INFO = -i, then the i-th argument had an illegal value 💀 (something you handed over was Not It)

Author ✍️

Like, the actual legends behind this:

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

✨ `sorbdb` ✨

subroutine sorbdb (character TRANS, character SIGNS, integer M, integer P,
    integer Q, real, dimension( ldx11, * ) X11, integer LDX11, real,
    dimension( ldx12, * ) X12, integer LDX12, real, dimension( ldx21, * )
    X21, integer LDX21, real, dimension( ldx22, * ) X22, integer LDX22,
    real, dimension( * ) THETA, real, dimension( * ) PHI, real, dimension( *
    ) TAUP1, real, dimension( * ) TAUP2, real, dimension( * ) TAUQ1, real,
    dimension( * ) TAUQ2, real, dimension( * ) WORK, integer LWORK, integer
    INFO)

SORBDB, my beloved. 🎀

🎯 Purpose

Okay so SORBDB simultaneously bidiagonalizes the blocks of an M-by-M partitioned orthogonal matrix X. The way it just… does that. Iconic behavior, no cap:

                                        [ B11 | B12 0  0 ]
            [ X11 | X12 ]   [ P1 |    ] [  0  |  0 -I  0 ] [ Q1 |    ]**T
        X = [-----------] = [---------] [----------------] [---------]   .
            [ X21 | X22 ]   [    | P2 ] [ B21 | B22 0  0 ] [    | Q2 ]
                                        [  0  |  0  0  I ]

X11 is P-by-Q. And here's the rule bestie, listen up: Q must be no larger than P, M-P, or M-Q. (If that's 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 SORCSD for details.) Slay, but also: respect the constraint. 🙏

The orthogonal 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. They're shy, they don't show up directly, iykyk. 🙈

B11, B12, B21, and B22 are Q-by-Q bidiagonal matrices represented implicitly by angles THETA, PHI.

🧾 Parameters

TRANS — CHARACTER, and it decides the whole storage vibe:
- = '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 — CHARACTER, choosing your convention era:
- = 'O': the lower-left block is made nonpositive (the 'other' convention);
- otherwise: the upper-right block is made nonpositive (the 'default' convention).
M — INTEGER. The number of rows and columns in X. It's the moment. 👑
P — INTEGER. The number of rows in X11 and X12. 0 <= P <= M.
Q — INTEGER. The number of columns in X11 and X21. 0 <= Q <= MIN(P,M-P,M-Q). (The min-of-three situation. It's giving main character, honestly.)
X11 — REAL array, dimension (LDX11,Q). On entry, the top-left block of the orthogonal 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 — INTEGER. The leading dimension of X11. If TRANS = 'N', then LDX11 >= P; else LDX11 >= Q. ✨
X12 — REAL array, dimension (LDX12,M-Q). On entry, the top-right block of the orthogonal 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 — INTEGER. The leading dimension of X12. If TRANS = 'N', then LDX12 >= P; else LDX11 >= M-Q.

Not me noticing it says LDX11 in that last clause instead of LDX12 😭 but bestie, we reproduce the source faithfully here, typos and all. We don't "fix" the ancestors. 💅

X21 — REAL array, dimension (LDX21,Q). On entry, the bottom-left block of the orthogonal 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 — INTEGER. The leading dimension of X21. If TRANS = 'N', then LDX21 >= M-P; else LDX21 >= Q.
X22 — REAL array, dimension (LDX22,M-Q). On entry, the bottom-right block of the orthogonal 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 — INTEGER. The leading dimension of X22. If TRANS = 'N', then LDX22 >= M-P; else LDX22 >= M-Q.
THETA — 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 — 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. (Yes, Q-1. She's one shorter. She's built different.)
TAUP1 — REAL array, dimension (P). The scalar factors of the elementary reflectors that define P1.
TAUP2 — REAL array, dimension (M-P). The scalar factors of the elementary reflectors that define P2.
TAUQ1 — REAL array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
TAUQ2 — REAL array, dimension (M-Q). The scalar factors of the elementary reflectors that define Q2.
WORK — REAL array, dimension (LWORK).
LWORK — INTEGER. The dimension of the array WORK. LWORK >= M-Q.

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 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 SORCSD for details.

P1, P2, Q1, and Q2 are represented as products of elementary reflectors. See SORCSD for details on generating P1, P2, Q1, and Q2 using SORGQR and SORGLQ.

📚 References:

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

✨ `sorbdb1` ✨

subroutine sorbdb1 (integer M, integer P, integer Q, real,
    dimension(ldx11,*) X11, integer LDX11, real, dimension(ldx21,*) X21,
    integer LDX21, real, dimension(*) THETA, real, dimension(*) PHI, real,
    dimension(*) TAUP1, real, dimension(*) TAUP2, real, dimension(*) TAUQ1,
    real, dimension(*) WORK, integer LWORK, integer INFO)

SORBDB1 💖

🎯 Purpose

SORBDB1 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X with orthonomal columns. Tall. Skinny. Serving silhouette, honestly:

                                       [ 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 SORBDB2, SORBDB3, and SORBDB4 handle cases in which Q is not the minimum dimension. (So if Q isn't the smallest one in the room, go bother the other siblings. 👯)

The orthogonal matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), and (M-Q)-by-(M-Q), respectively. They are represented implicitly by Householder vectors.

B11 and B12 are Q-by-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 <= MIN(P,M-P,M-Q). ✨
X11 — REAL array, dimension (LDX11,Q). On entry, the top block of the matrix X to be reduced. On exit, the columns of tril(X11) specify reflectors for P1 and the rows of triu(X11,1) specify reflectors for Q1.
LDX11 — INTEGER. The leading dimension of X11. LDX11 >= P.
X21 — REAL array, dimension (LDX21,Q). On entry, the bottom block of the matrix X to be reduced. On exit, the columns of tril(X21) specify reflectors for P2.
LDX21 — INTEGER. The leading dimension of X21. LDX21 >= M-P.
THETA — REAL array, dimension (Q). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
PHI — REAL array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details. 🫶
TAUP1
TAUP1 — TAUP1 is REAL array, dimension (P) — these are the scalar factors of the elementary reflectors that define P1. 💅
TAUP2 — TAUP2 is REAL array, dimension (M-P) — the scalar factors of the elementary reflectors that define P2.
TAUQ1 — TAUQ1 is REAL array, dimension (Q) — the scalar factors of the elementary reflectors that define Q1.
WORK — WORK is REAL array, dimension (LWORK). It's the workspace bestie, it holds stuff so you don't have to.
LWORK — LWORK is INTEGER — the dimension of the array WORK. So like, LWORK >= M-Q, no negotiating on that one.

If LWORK = -1, then a workspace query is assumed 👀 — the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. So it's a lil peek, not a real run, iykyk.

INFO — INFO is INTEGER, and here's the vibe check:
- = 0: successful exit. slay 💖
- < 0: if INFO = -i, the i-th argument had an illegal value. 😭

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

✨ Further Details ✨

The upper-bidiagonal blocks B11, B21 are represented implicitly by angles THETA(1), ..., THETA(Q) and PHI(1), ..., PHI(Q-1). Every entry in each bidiagonal band is a product of a sine or cosine of a THETA with a sine or cosine of a PHI. See [1] or SORCSD for details. 🦋

P1, P2, and Q1 are represented as products of elementary reflectors. See SORCSD2BY1 for details on generating P1, P2, and Q1 using SORGQR and SORGLQ. Periodt. 💅

🌈 References 🌈

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

🧚 subroutine `sorbdb2` — SORBDB2

subroutine sorbdb2 (integer M, integer P, integer Q, real,
    dimension(ldx11,*) X11, integer LDX11, real, dimension(ldx21,*) X21,
    integer LDX21, real, dimension(*) THETA, real, dimension(*) PHI, real,
    dimension(*) TAUP1, real, dimension(*) TAUP2, real, dimension(*) TAUQ1,
    real, dimension(*) WORK, integer LWORK, integer INFO)

✨ Purpose ✨

SORBDB2 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. So P must be no larger than M-P, Q, or M-Q. Routines SORBDB1, SORBDB3, and SORBDB4 handle cases in which P is not the minimum dimension. (Squad goals, they all cover for each other. 🫶)

The orthogonal matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), and (M-Q)-by-(M-Q), respectively. They are represented implicitly by Householder vectors. 👑

B11 and B12 are 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. So 0 <= P <= min(M-P,Q,M-Q).
Q — Q is INTEGER. The number of columns in X11 and X21. And 0 <= Q <= M.
X11 — X11 is REAL array, dimension (LDX11,Q). On entry, the top block of the matrix X to be reduced. On exit, the columns of tril(X11) specify reflectors for P1 and the rows of triu(X11,1) specify reflectors for Q1. It literally transforms on you, main character energy. ✨
LDX11 — LDX11 is INTEGER. The leading dimension of X11. LDX11 >= P.
X21 — X21 is REAL array, dimension (LDX21,Q). On entry, the bottom block of the matrix X to be reduced. On exit, the columns of tril(X21) specify reflectors for P2.
LDX21 — 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 REAL array, dimension (P-1). The scalar factors of the elementary reflectors that define P1.
TAUP2 — TAUP2 is REAL array, dimension (Q). The scalar factors of the elementary reflectors that define P2. (Yes bestie, dimension (Q) here — don't come for me, that's what it says. 💀)
TAUQ1 — TAUQ1 is REAL array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
WORK — WORK is REAL 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 ✨

P1, P2, and Q1 are represented as products of elementary reflectors. See SORCSD2BY1 for details on generating P1, P2, and Q1 using SORGQR and SORGLQ.

🌈 References 🌈

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

🦋 subroutine `sorbdb3` — SORBDB3

subroutine sorbdb3 (integer M, integer P, integer Q, real,
    dimension(ldx11,*) X11, integer LDX11, real, dimension(ldx21,*) X21,
    integer LDX21, real, dimension(*) THETA, real, dimension(*) PHI, real,
    dimension(*) TAUP1, real, dimension(*) TAUP2, real, dimension(*) TAUQ1,
    real, dimension(*) WORK, integer LWORK, integer INFO)

✨ Purpose ✨

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

The orthogonal matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), and (M-Q)-by-(M-Q), respectively. They are represented implicitly by Householder vectors.

B11 and B12 are (M-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. So 0 <= P <= M. And also 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 REAL array, dimension (LDX11,Q). On entry, the top block of the matrix X to be reduced. On exit, the columns of tril(X11) specify reflectors for P1 and the rows of triu(X11,1) specify reflectors for Q1.
LDX11 — LDX11 is INTEGER. The leading dimension of X11. LDX11 >= P.
X21 — X21 is REAL array, dimension (LDX21,Q). On entry, the bottom block of the matrix X to be reduced. On exit, the columns of tril(X21) specify reflectors for P2.
LDX21 — 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 REAL array, dimension (P). The scalar factors of the elementary reflectors that define P1.
TAUP2 — TAUP2 is REAL array, dimension (M-P). The scalar factors of the elementary reflectors that define P2.
TAUQ1 — TAUQ1 is REAL array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
WORK — WORK is REAL 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 ✨

P1, P2, and Q1 are represented as products of elementary reflectors. See SORCSD2BY1 for details on generating P1, P2, and Q1 using SORGQR and SORGLQ.

References:

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

subroutine `sorbdb4`

subroutine sorbdb4 (integer M, integer P, integer Q, real,
    dimension(ldx11,*) X11, integer LDX11, real, dimension(ldx21,*) X21,
    integer LDX21, real, dimension(*) THETA, real, dimension(*) PHI, real,
    dimension(*) TAUP1, real, dimension(*) TAUP2, real, dimension(*) TAUQ1,
    real, dimension(*) PHANTOM, real, dimension(*) WORK, integer LWORK,
    integer INFO)

SORBDB4 💖

Purpose

okay so SORBDB4 is out here bidiagonalizing the blocks of a tall and skinny matrix X that has orthonormal columns, all at the same time, bestie:

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

X11 is P-by-Q, and X21 is (M-P)-by-Q. And the vibe check here is real: M-Q must be no larger than P, M-P, or Q. If that's not your situation, no worries — routines SORBDB1, SORBDB2, and SORBDB3 handle the cases where M-Q is not the minimum dimension. ✨

The orthogonal matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), and (M-Q)-by-(M-Q), respectively. They don't show up all loud and explicit, no — they're represented implicitly by Householder vectors. sneakyyy 🫶

And B11 and B12 are (M-Q)-by-(M-Q) bidiagonal matrices, also represented implicitly, this time by the angles THETA and PHI. iconic. 💅

Parameters

M — INTEGER. The number of rows X11 plus the number of rows in X21. 🧮
P — INTEGER. The number of rows in X11. 0 <= P <= M.
Q — INTEGER. The number of columns in X11 and X21. 0 <= Q <= M and M-Q <= min(P,M-P,Q).
X11 — REAL array, dimension (LDX11,Q). On entry, the top block of the matrix X to be reduced. On exit, the columns of tril(X11) specify reflectors for P1 and the rows of triu(X11,1) specify reflectors for Q1. she's doing double duty, periodt 💖
LDX11 — INTEGER. The leading dimension of X11. LDX11 >= P.
X21 — REAL array, dimension (LDX21,Q). On entry, the bottom block of the matrix X to be reduced. On exit, the columns of tril(X21) specify reflectors for P2.
LDX21 — INTEGER. The leading dimension of X21. LDX21 >= M-P.
THETA — REAL array, dimension (Q). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details. 🔍
PHI — REAL array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details. 🔍
TAUP1 — REAL array, dimension (M-Q). The scalar factors of the elementary reflectors that define P1.
TAUP2 — REAL array, dimension (M-Q). The scalar factors of the elementary reflectors that define P2.
TAUQ1 — REAL array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
PHANTOM — REAL array, dimension (M). The routine computes an M-by-1 column vector Y that is orthogonal to the columns of [ X11; X21 ]. PHANTOM(1:P) and PHANTOM(P+1:M) contain Householder vectors for Y(1:P) and Y(P+1:M), respectively. spooky name, very on brand 👻
WORK — REAL array, dimension (LWORK).
LWORK — INTEGER. The dimension of the array WORK. LWORK >= M-Q.
- If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. 💅
INFO — INTEGER
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

The upper-bidiagonal blocks B11, B21 are represented implicitly by angles THETA(1), ..., THETA(Q) and PHI(1), ..., PHI(Q-1). Every single entry in each bidiagonal band is a product of a sine or cosine of a THETA with a sine or cosine of a PHI. like… it's giving trig collab 🌸 See [1] or SORCSD for details.

P1, P2, and Q1 are represented as products of elementary reflectors. See SORCSD2BY1 for details on generating P1, P2, and Q1 using SORGQR and SORGLQ. 🎀

References:

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

subroutine `sorbdb5`

subroutine sorbdb5 (integer M1, integer M2, integer N, real, dimension(*)
    X1, integer INCX1, real, dimension(*) X2, integer INCX2, real,
    dimension(ldq1,*) Q1, integer LDQ1, real, dimension(ldq2,*) Q2, integer
    LDQ2, real, dimension(*) WORK, integer LWORK, integer INFO)

SORBDB5 🦋

Purpose

SORBDB5 orthogonalizes the column vector

     X = [ X1 ]
         [ X2 ]

with respect to the columns of

     Q = [ Q1 ] .
         [ Q2 ]

The columns of Q must be orthonormal — non-negotiable bestie, that's the whole point ✨

And here's the fun part: if the projection comes out as zero according to Kahan's 'twice is enough' criterion, then some other vector from the orthogonal complement is returned. Which one? It's chosen in an arbitrary but deterministic way. so like, it's random but it's not random. iykyk 💀

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 — REAL 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 — REAL 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 — REAL array, dimension (LDQ1, N). The top part of the orthonormal basis matrix.
LDQ1 — INTEGER. The leading dimension of Q1. LDQ1 >= M1.
Q2 — REAL array, dimension (LDQ2, N). The bottom part of the orthonormal basis matrix.
LDQ2 — INTEGER. The leading dimension of Q2. LDQ2 >= M2.
WORK — REAL 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.

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

subroutine `sorbdb6`

subroutine sorbdb6 (integer M1, integer M2, integer N, real, dimension(*)
    X1, integer INCX1, real, dimension(*) X2, integer INCX2, real,
    dimension(ldq1,*) Q1, integer LDQ1, real, dimension(ldq2,*) Q2, integer
    LDQ2, real, dimension(*) WORK, integer LWORK, integer INFO)

SORBDB6 🌈

Purpose

SORBDB6 orthogonalizes the column vector

     X = [ X1 ]
         [ X2 ]

with respect to the columns of

     Q = [ Q1 ] .
         [ Q2 ]

okay so the rules are different here, listen up 🫶 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. no cap.

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 — REAL 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 — REAL 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 — REAL array, dimension (LDQ1, N). The top part of the orthonormal basis matrix.
LDQ1 — INTEGER. The leading dimension of Q1. LDQ1 >= M1.
Q2 — REAL array, dimension (LDQ2, N). The bottom part of the orthonormal basis matrix.
LDQ2 — INTEGER. The leading dimension of Q2. LDQ2 >= M2.
WORK — REAL 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.

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 subroutine `sorcsd` — the full CS decomposition, main character energy 🌈

recursive subroutine sorcsd (character JOBU1, character JOBU2, character
    JOBV1T, character JOBV2T, character TRANS, character SIGNS, integer M,
    integer P, integer Q, real, dimension( ldx11, * ) X11, integer LDX11,
    real, dimension( ldx12, * ) X12, integer LDX12, real, dimension( ldx21,
    * ) X21, integer LDX21, real, dimension( ldx22,
    * ) X22, integer LDX22, real, dimension( * ) THETA, real, dimension(
    ldu1, * ) U1, integer LDU1, real, dimension( ldu2, * ) U2, integer LDU2,
    real, dimension( ldv1t, * ) V1T, integer LDV1T, real, dimension( ldv2t,
    * ) V2T, integer LDV2T, real, dimension( * ) WORK, integer LWORK,
    integer, dimension( * ) IWORK, integer INFO)

Purpose:

okay so SORCSD computes the CS decomposition of an M-by-M partitioned orthogonal matrix X. and bestie, when I say partitioned I mean it, look at this glow-up:

                                     [  I  0  0 |  0  0  0 ]
                                     [  0  C  0 |  0 -S  0 ]
     [ X11 | X12 ]   [ U1 |    ] [  0  0  0 |  0  0 -I ] [ V1 |    ]**T
 X = [-----------] = [---------] [---------------------] [---------]   .
     [ X21 | X22 ]   [    | U2 ] [  0  0  0 |  I  0  0 ] [    | V2 ]
                                     [  0  S  0 |  0  C  0 ]
                                     [  0  0  I |  0  0  0 ]

X11 is P-by-Q. The orthogonal 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. 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). ✨ like, they literally complement each other, it's giving soulmate behavior ✨

✨ Parameters ✨

JOBU1 — JOBU1 is CHARACTER. = 'Y' → U1 is computed 🫶. otherwise → U1 is not computed, and that's a choice bestie.
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. lowkey the whole layout of your data hinges on this one letter 💀
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). two conventions, one character, no pressure 💅
M — M is INTEGER. the number of rows and columns in X. it's a square, she's balanced, we love her.
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 REAL array, dimension (LDX11,Q)`. on entry, part of the orthogonal matrix whose CSD is desired. she's a fragment of the moment, ok?
LDX11 — LDX11 is INTEGER. the leading dimension of X11. LDX11 >= MAX(1,P).
X12 — X12 is REAL array, dimension (LDX12,M-Q)`. on entry, part of the orthogonal matrix whose CSD is desired.
LDX12 — LDX12 is INTEGER. the leading dimension of X12. LDX12 >= MAX(1,P).
X21 — X21 is REAL array, dimension (LDX21,Q)`. on entry, part of the orthogonal matrix whose CSD is desired.
LDX21 — LDX21 is INTEGER. the leading dimension of X11 (yes that's literally what the docs say, i'm just the messenger 🧚). LDX21 >= MAX(1,M-P).
X22 — X22 is REAL array, dimension (LDX22,M-Q)`. on entry, part of the orthogonal matrix whose CSD is desired.
LDX22 — LDX22 is INTEGER. the leading dimension of X11 (again, doc's words not mine 🧚). LDX22 >= MAX(1,M-P).
THETA — THETA is REAL array, dimension (R)</cyan>, in which <yellow>R = MIN(P,M-P,Q,M-Q)`. then:

C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) ) and
S = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ).

U1 — U1 is REAL array, dimension (LDU1,P)</cyan>. if JOBU1 = 'Y', U1contains the P-by-P orthogonal matrixU1`. 🫶
LDU1 — LDU1 is INTEGER. the leading dimension of U1. if JOBU1 = 'Y', LDU1 >= MAX(1,P).
U2 — U2 is REAL array, dimension (LDU2,M-P)</cyan>. if JOBU2 = 'Y', U2contains the (M-P)-by-(M-P) orthogonal matrixU2`. 🫶
LDU2 — LDU2 is INTEGER. the leading dimension of U2. if JOBU2 = 'Y', LDU2 >= MAX(1,M-P).
V1T — V1T is REAL array, dimension (LDV1T,Q)</cyan>. if JOBV1T = 'Y', V1Tcontains the Q-by-Q matrix orthogonal matrixV1**T`. (yes, "matrix orthogonal matrix", we stan a queen who contains multitudes 💅)
LDV1T — LDV1T is INTEGER. the leading dimension of V1T. if JOBV1T = 'Y', LDV1T >= MAX(1,Q).
V2T — V2T is REAL array, dimension (LDV2T,M-Q)</cyan>. if JOBV2T = 'Y', V2Tcontains the (M-Q)-by-(M-Q) orthogonal matrixV2**T`. 🫶
LDV2T — LDV2T is INTEGER. the leading dimension of V2T. if JOBV2T = 'Y', LDV2T >= MAX(1,M-Q).
WORK — WORK is REAL array, dimension (MAX(1,LWORK))</cyan>. on exit, if INFO = 0, <mint>WORK(1)returns the optimalLWORK</mint>. if INFO > 0on exit,WORK(2:R)contains the valuesPHI(1), ..., PHI(R-1)that, together withTHETA(1), ..., THETA(R), define the matrix in intermediate bidiagonal-block form remaining after nonconvergence. INFOspecifies the number of nonzeroPHI`'s. 😭 so if it didn't converge, the leftovers are all still in there, it's giving unread group chat
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. 🎀 classic "just tell me how much room you need" move.

IWORK — IWORK is INTEGER array, dimension (M-MIN(P, M-P, Q, M-Q))`
INFO — INFO is INTEGER. receipts:
- = 0: successful exit. slay. ✨
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: SBBCSD did not converge. see the description of WORK above for details. 💀

📚 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 `sorcsd2by1` — the 2-by-1 block version, she's more compact and she knows it 🌸

subroutine sorcsd2by1 (character JOBU1, character JOBU2, character JOBV1T,
    integer M, integer P, integer Q, real, dimension(ldx11,*) X11, integer
    LDX11, real, dimension(ldx21,*) X21, integer LDX21, real, dimension(*)
    THETA, real, dimension(ldu1,*) U1, integer LDU1, real, dimension(ldu2,*)
    U2, integer LDU2, real, dimension(ldv1t,*) V1T, integer LDV1T, real,
    dimension(*) WORK, integer LWORK, integer, dimension(*) IWORK, integer
    INFO)

Purpose:

SORCSD2BY1 computes the CS decomposition of an M-by-Q matrix X with orthonormal columns that has been partitioned into a 2-by-1 block structure:

                                        [  I1 0  0 ]
                                        [  0  C  0 ]
                  [ X11 ]   [ U1 |    ] [  0  0  0 ]
              X = [-----] = [---------] [----------] V1**T .
                  [ X21 ]   [    | U2 ] [  0  0  0 ]
                                        [  0  S  0 ]
                                        [  0  0  I2]

X11 is P-by-Q. The orthogonal matrices U1, U2, and V1 are P-by-P, (M-P)-by-(M-P), and Q-by-Q, respectively. C and S are R-by-R nonnegative diagonal matrices satisfying C^2 + S^2 = I, in which R = MIN(P,M-P,Q,M-Q). I1 is a K1-by-K1 identity matrix and I2 is a K2-by-K2 identity matrix, where K1 = MAX(Q+P-M,0), K2 = MAX(Q-P,0). two little identity babies tucked into the corners, iconic 👑

✨ 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 REAL array, dimension (LDX11,Q)`. on entry, part of the orthogonal matrix whose CSD is desired.
LDX11 — LDX11 is INTEGER. the leading dimension of X11. LDX11 >= MAX(1,P).
X21 — X21 is REAL array, dimension (LDX21,Q)`. on entry, part of the orthogonal matrix whose CSD is desired.
LDX21 — LDX21 is INTEGER. the leading dimension of X21. LDX21 >= MAX(1,M-P).
THETA — THETA is REAL array, dimension (R)</cyan>, in which <yellow>R = MIN(P,M-P,Q,M-Q)`. then:

C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) ) and
S = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ).

U1 — U1 is REAL array, dimension (P)</cyan>. if JOBU1 = 'Y', U1contains the P-by-P orthogonal matrixU1`. 🫶
LDU1 — LDU1 is INTEGER. the leading dimension of U1. if JOBU1 = 'Y', LDU1 >= MAX(1,P).
U2 — U2 is REAL array, dimension (M-P)</cyan>. if JOBU2 = 'Y', U2contains the (M-P)-by-(M-P) orthogonal matrixU2`. 🫶
LDU2 — LDU2 is INTEGER. the leading dimension of U2. if JOBU2 = 'Y', LDU2 >= MAX(1,M-P).
V1T — V1T is REAL array, dimension (Q)</cyan>. if JOBV1T = 'Y', V1Tcontains the Q-by-Q matrix orthogonal matrixV1**T`. (she said it again 💅)
LDV1T — LDV1T is INTEGER. the leading dimension of V1T. if JOBV1T = 'Y', LDV1T >= MAX(1,Q).
WORK — hold that thought bestie, WORK's whole deal is right up next…

okay bestie, we're still deep in the parameter tea for the routine from before, and ngl WORK is doing the absolute most 💅

WORK — it's a REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. If INFO > 0 on exit, WORK(2:R) contains the values PHI(1), ..., PHI(R-1) that, together with THETA(1), ..., THETA(R), define the matrix in intermediate bidiagonal-block form remaining after nonconvergence. INFO specifies the number of nonzero PHI's. 😭
LWORK — is an 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. ✨
IWORK — is an INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q)). 👑
INFO — is an INTEGER.
- = 0: successful exit. 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. 💀
- > 0: SBBCSD did not converge. See the description of WORK above for details. 🚨

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 sorg2l (integer M, integer N, integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK, integer INFO)` ✨

SORG2L generates all or part of the orthogonal matrix Q from a QL factorization determined by sgeqlf (unblocked algorithm).

Purpose 🎀

SORG2L generates an m by n real 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 SGEQLF.

Parameters 💅

M — is an INTEGER. The number of rows of the matrix Q. M >= 0. 🌟
N — is an INTEGER. The number of columns of the matrix Q. M >= N >= 0. 🌈
K — is an INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0. 🔥
A — is a REAL 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 SGEQLF in the last k columns of its array argument A. On exit, the m by n matrix Q. 🦋
LDA — is an INTEGER. The first dimension of the array A. LDA >= max(1,M). 💖
TAU — is a REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEQLF. 🌸
WORK — is a REAL array, dimension (N). 🧚
INFO — is an 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 sorg2r (integer M, integer N, integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK, integer INFO)` ✨

SORG2R generates all or part of the orthogonal matrix Q from a QR factorization determined by sgeqrf (unblocked algorithm).

Purpose 🎀

SORG2R generates an m by n real 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 SGEQRF.

Parameters 💅

M — is an INTEGER. The number of rows of the matrix Q. M >= 0. 🌟
N — is an INTEGER. The number of columns of the matrix Q. M >= N >= 0. 🌈
K — is an INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0. 🔥
A — is a REAL 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 SGEQRF in the first k columns of its array argument A. On exit, the m-by-n matrix Q. 🦋
LDA — is an INTEGER. The first dimension of the array A. LDA >= max(1,M). 💖
TAU — is a REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEQRF. 🌸
WORK — is a REAL array, dimension (N). 🧚
INFO — is an 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 sorghr (integer N, integer ILO, integer IHI, real, dimension( lda, * ) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK, integer LWORK, integer INFO)` ✨

SORGHR

Purpose 🎀

SORGHR generates a real orthogonal matrix Q which is defined as the product of IHI-ILO elementary reflectors of order N, as returned by SGEHRD:

Q = H(ilo) H(ilo+1) . . . H(ihi-1).

Parameters 💅

N — is an INTEGER. The order of the matrix Q. N >= 0. 🌟
ILO — is an INTEGER. 💫
IHI — is an INTEGER. ILO and IHI must have the same values as in the previous call of SGEHRD. 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 — is a REAL array, dimension (LDA,N). On entry, the vectors which define the elementary reflectors, as returned by SGEHRD. On exit, the N-by-N orthogonal matrix Q. 🦋
LDA — is an INTEGER. The leading dimension of the array A. LDA >= max(1,N). 💖
TAU — is a REAL array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEHRD. 🌸
WORK — is a REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 🧚
LWORK — is an INTEGER. The dimension of the array WORK. LWORK >= IHI-ILO. For optimum performance LWORK >= (IHI-ILO)*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 — is 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.

`subroutine sorgl2 (integer M, integer N, integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK, integer INFO)` ✨

SORGL2

Purpose 🎀

SORGL2 generates an m by n real 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(2) H(1)

as returned by SGELQF.

Parameters 💅

M — is an INTEGER. The number of rows of the matrix Q. M >= 0. 🌟
N — is an INTEGER. The number of columns of the matrix Q. N >= M. 🌈
K — is an INTEGER. The number of elementary reflectors whose product defines the matrix Q. M >= K >= 0. 🔥
A — is a REAL 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 SGELQF in the first k rows of its array argument A. On exit, the m-by-n matrix Q. 🦋
LDA — is an INTEGER. The first dimension of the array A. LDA >= max(1,M). 💖
TAU — is a REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGELQF. 🌸
WORK — is a REAL array, dimension (M). 🧚
INFO — is an 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 sorglq (integer M, integer N, integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK, integer LWORK, integer INFO)` ✨

SORGLQ

Purpose 🎀

SORGLQ generates an M-by-N real 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(2) H(1)

as returned by SGELQF.

Parameters 💅

M — is an INTEGER. The number of rows of the matrix Q. M >= 0. 🌟
N — is an INTEGER. The number of columns of the matrix Q. N >= M. 🌈
K — is an INTEGER. The number of elementary reflectors whose product defines the matrix Q. M >= K >= 0. 🔥
A — is a REAL 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 SGELQF in the first k rows of its array argument A. On exit, the M-by-N matrix Q. 🦋
LDA — is an INTEGER. The first dimension of the array A. LDA >= max(1,M). 💖
TAU —
TAU — REAL array, dimension (K). TAU(i) has to hold the scalar factor of the elementary reflector H(i), exactly how SGELQF handed it back to you. No improvising bestie 💖
WORK — REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. It's literally telling you what it wants 🫶
LWORK — INTEGER, the dimension of the array WORK. LWORK >= max(1,M). For optimum performance LWORK >= M*NB, where NB is the optimal blocksize ✨

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.

`sorgql` 🌸

subroutine sorgql (integer M, integer N, integer K, real, dimension( lda, *
) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK,
integer LWORK, integer INFO)

SORGQL — the icon, the moment 💅

Purpose:

SORGQL generates an M-by-N real 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 SGEQLF.

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 — REAL 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 SGEQLF in the last k columns of its array argument A. On exit, the M-by-N matrix Q. glow up ✨
LDA — INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEQLF.
WORK — REAL 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.

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.

`sorgqr` 🦋

subroutine sorgqr (integer M, integer N, integer K, real, dimension( lda, *
) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK,
integer LWORK, integer INFO)

SORGQR — yes she's related to SORGQL, they're sisters, don't compare them 🙈

Purpose:

SORGQR generates an M-by-N real 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 SGEQRF.

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 — REAL 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 SGEQRF in the first k columns of its array argument A. On exit, the M-by-N matrix Q. periodt 💅
LDA — INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEQRF.
WORK — REAL 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.

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.

`sorgr2` 🍓

subroutine sorgr2 (integer M, integer N, integer K, real, dimension( lda, *
) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK,
integer INFO)

SORGR2 generates all or part of the orthogonal matrix Q from an RQ factorization determined by sgerqf (unblocked algorithm). the unblocked one. the lowkey one. the one that just works 🧚

Purpose:

SORGR2 generates an m by n real 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(2) . . . H(k)

as returned by SGERQF.

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 — REAL 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 SGERQF in the last k rows of its array argument A. On exit, the m by n matrix Q. rows not columns, keep up bestie 🫶
LDA — INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGERQF.
WORK — REAL 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.

`sorgrq` 💜

subroutine sorgrq (integer M, integer N, integer K, real, dimension( lda, *
) A, integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK,
integer LWORK, integer INFO)

SORGRQ — the blocked version of the above, she's got a LWORK and everything 👑

Purpose:

SORGRQ generates an M-by-N real 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(2) . . . H(k)

as returned by SGERQF.

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 — REAL 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 SGERQF 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 — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGERQF.
WORK — REAL 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.

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.

`sorgtr` 🌈

subroutine sorgtr (character UPLO, integer N, real, dimension( lda, * ) A,
integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK,
integer LWORK, integer INFO)

SORGTR — different energy entirely, she takes a UPLO and she's serving tridiagonal realness 💅

Purpose:

SORGTR generates a real orthogonal matrix Q which is defined as the product of n-1 elementary reflectors of order N, as returned by SSYTRD:

if UPLO = 'U', Q = H(n-1) . . . H(2) H(1),

if UPLO = 'L', Q = H(1) H(2) . . . H(n-1).

UPLO — a CHARACTER*1, and it's literally telling us which triangle of A is holding the elementary reflectors 💅
- 'U': Upper triangle of A contains elementary reflectors from SSYTRD;
- 'L': Lower triangle of A contains elementary reflectors from SSYTRD.
N — INTEGER, the order of the matrix Q. Bestie, N >= 0. No negative orders, we don't do that here. ✨
A — a REAL array, dimension (LDA,N).
- On entry: the vectors which define the elementary reflectors, as returned by SSYTRD.
- On exit: the N-by-N orthogonal matrix Q. She transforms. 👑
LDA — INTEGER, the leading dimension of the array A. LDA >= max(1,N). Respect the leading dimension or the whole thing falls apart, fr fr.
TAU — a REAL array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SSYTRD. Like, it has to must, okay? 😤
WORK — a REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. She's telling you what she wants 🫶
LWORK — INTEGER, the dimension of the array WORK. LWORK >= max(1,N-1).
- For optimum performance, LWORK >= (N-1)*NB, where NB is the optimal blocksize. (Yes, she has a whole optimal blocksize. Main character energy. 🌟)
- 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, -1 is a vibe check, not an error. 🧚
INFO — INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. Somebody messed up. It happens. 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

`sorm2l` — the icon herself 💖

subroutine sorm2l (character SIDE, character TRANS, integer M, integer N,
    integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( *
    ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * )
    WORK, integer INFO)

SORM2L multiplies a general matrix by the orthogonal matrix from a QL factorization determined by sgeqlf (unblocked algorithm). Okay so she's the unblocked one. Lowkey humble, highkey essential. ✨

Purpose:

SORM2L overwrites the general real m by n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**T * C  if SIDE = 'L' and TRANS = 'T', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**T if SIDE = 'R' and TRANS = 'T',

where Q is a real orthogonal matrix defined as the product of k elementary reflectors

      Q = H(k) . . . H(2) H(1)

as returned by SGEQLF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. So the order of Q depends entirely on which side she's coming from. It's giving ambidextrous. 🦋

Parameters

SIDE — CHARACTER*1.
- 'L': apply Q or Q**T from the Left
- 'R': apply Q or Q**T from the Right
TRANS — CHARACTER*1.
- 'N': apply Q (No transpose)
- 'T': apply Q**T (Transpose)
M — INTEGER, the number of rows of the matrix C. M >= 0.
N — INTEGER, the number of columns of the matrix C. N >= 0.
K — 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 REAL 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 SGEQLF in the last k columns of its array argument A. A is modified by the routine but restored on exit. So like, she borrows it, changes it, and then puts it back exactly how she found it. A respectful queen. 👑
LDA — INTEGER, the leading dimension of the array A.
- If SIDE = 'L', LDA >= max(1,M);
- if SIDE = 'R', LDA >= max(1,N).
TAU — a REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEQLF.
C — a 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. She took over. Periodt. 💅
LDC — INTEGER, the leading dimension of the array C. LDC >= max(1,M).
WORK — a REAL array, dimension

                                          (N) if SIDE = 'L',
                                          (M) if SIDE = 'R'

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.

`sorm2r` — same energy, different factorization 🌸

subroutine sorm2r (character SIDE, character TRANS, integer M, integer N,
    integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( *
    ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * )
    WORK, integer INFO)

SORM2R multiplies a general matrix by the orthogonal matrix from a QR factorization determined by sgeqrf (unblocked algorithm). She's sorm2l's sister but QR-coded. No cap. 💜

Purpose:

SORM2R overwrites the general real m by n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**T* C  if SIDE = 'L' and TRANS = 'T', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**T if SIDE = 'R' and TRANS = 'T',

where Q is a real orthogonal matrix defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by SGEQRF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. Notice the order is H(1) H(2) . . . H(k) here — not reversed like in sorm2l. The way these two are cousins and not twins. 😭

Parameters

SIDE — CHARACTER*1.
- 'L': apply Q or Q**T from the Left
- 'R': apply Q or Q**T from the Right
TRANS — CHARACTER*1.
- 'N': apply Q (No transpose)
- 'T': apply Q**T (Transpose)
M — INTEGER, the number of rows of the matrix C. M >= 0.
N — INTEGER, the number of columns of the matrix C. N >= 0.
K — 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 REAL 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 SGEQRF in the first k columns of its array argument A. A is modified by the routine but restored on exit. First k columns this time, not last k. Keep up bestie, I know. 🙈
LDA — INTEGER, the leading dimension of the array A.
- If SIDE = 'L', LDA >= max(1,M);
- if SIDE = 'R', LDA >= max(1,N).
TAU — a REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEQRF.
C — a 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 — INTEGER, the leading dimension of the array C. LDC >= max(1,M).
WORK — a REAL array, dimension

                                          (N) if SIDE = 'L',
                                          (M) if SIDE = 'R'

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.

`sormbr` — the bidiagonal girlie 🦋

subroutine sormbr (character VECT, character SIDE, character TRANS, integer
    M, integer N, integer K, real, dimension( lda, * ) A, integer LDA, real,
    dimension( * ) TAU, real, dimension( ldc, * ) C, integer LDC, real,
    dimension( * ) WORK, integer LWORK, integer INFO)

SORMBR

Purpose:

If VECT = 'Q', SORMBR 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

If VECT = 'P', SORMBR overwrites the general real M-by-N matrix C with

                        SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      P * C          C * P
TRANS = 'T':      P**T * C       C * P**T

Here Q and P**T are the orthogonal matrices determined by SGEBRD when reducing a real matrix A to bidiagonal form: A = Q * B * P**T. Q and P**T are defined as products of elementary reflectors H(i) and G(i) respectively. Two reflectors, two families, one routine. It's giving overachiever and we love her for it. 🌈

Let nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. Thus nq is the order of the orthogonal matrix Q or P**T 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).

See how the inequalities flip between the two? Yeah. Read it twice. I had to. 💀

Parameters

VECT — CHARACTER*1.
- 'Q': apply Q or Q**T;
- 'P': apply P or P**T.
SIDE — CHARACTER*1.
- 'L': apply Q, Q**T, P or P**T from the Left;
- 'R': apply Q, Q**T, P or P**T from the Right.
TRANS — CHARACTER*1.
- 'N': No transpose, apply Q or P;
- 'T': Transpose, apply Q**T or P**T.
M — INTEGER, the number of rows of the matrix C. M >= 0.
N — INTEGER, the number of columns of the matrix C. N >= 0.
K — INTEGER.
- If VECT = 'Q', the number of columns in the original matrix reduced by SGEBRD.
- If VECT = 'P', the number of rows in the original matrix reduced by SGEBRD.
- K >= 0.
A
A — REAL array, dimension

(LDA,min(nq,K)) if VECT = 'Q'
(LDA,nq)        if VECT = 'P'

bestie these are the vectors that define the elementary reflectors H(i) and G(i), and their products are literally what build the matrices Q and P 💅 — exactly as handed back by SGEBRD.

LDA — 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 — REAL array, dimension (min(nq,K)). TAU(i) has to contain the scalar factor of the elementary reflector H(i) or G(i) that determines Q or P, as returned by SGEBRD in the array argument TAUQ or TAUP. no cap 🌸
C — REAL array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C gets overwritten by Q*C or Q**T*C or C*Q**T or C*Q or P*C or P**T*C or C*P or C*P**T. she's a main character and she gets replaced 💀
LDC — INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. ✨
LWORK — 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.

okay so if LWORK = -1, 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. iconic behaviour honestly.

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 sormhr ✨

subroutine sormhr (character SIDE, character TRANS, integer M, integer N,
    integer ILO, integer IHI, real, dimension( lda, * ) A, integer LDA,
    real, dimension( * ) TAU, real, dimension( ldc, * ) C, integer LDC,
    real, dimension( * ) WORK, integer LWORK, integer INFO)

SORMHR — okay bestie, this one 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'. And Q is defined as the product of IHI-ILO elementary reflectors, as returned by SGEHRD:

Q = H(ilo) H(ilo+1) . . . H(ihi-1).

🎀 Parameters 🎀

SIDE — CHARACTER*1.
- = 'L': apply Q or Q**T from the Left;
- = 'R': apply Q or Q**T from the Right.
TRANS — CHARACTER*1.
- = 'N': No transpose, apply Q;
- = 'T': Transpose, apply Q**T.
M — INTEGER. The number of rows of the matrix C. M >= 0.
N — INTEGER. The number of columns of the matrix C. N >= 0.
ILO — INTEGER.
IHI — INTEGER.

ILO and IHI must have the same values as in the previous call of SGEHRD 👀 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 — REAL array, dimension

(LDA,M) if SIDE = 'L'
(LDA,N) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by SGEHRD. 💜

LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,M) if SIDE = 'L'; LDA >= max(1,N) if SIDE = 'R'.
TAU — REAL 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 SGEHRD. periodt ✨

C — 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 — INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — REAL 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 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.

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.

🦋 subroutine sorml2 🦋

subroutine sorml2 (character SIDE, character TRANS, integer M, integer N,
    integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( *
    ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * )
    WORK, integer INFO)

SORML2 multiplies a general matrix by the orthogonal matrix from a LQ factorization determined by sgelqf — it's the unblocked algorithm btw, so like, the lil baby version 🥺

Purpose:

SORML2 overwrites the general real m by n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**T* C  if SIDE = 'L' and TRANS = 'T', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**T if SIDE = 'R' and TRANS = 'T',

where Q is a real orthogonal matrix defined as the product of k elementary reflectors

      Q = H(k) . . . H(2) H(1)

as returned by SGELQF. And Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. ✨

💖 Parameters 💖

SIDE — CHARACTER*1.
- = 'L': apply Q or Q**T from the Left
- = 'R': apply Q or Q**T from the Right
TRANS — CHARACTER*1.
- = 'N': apply Q (No transpose)
- = 'T': apply Q**T (Transpose)
M — INTEGER. The number of rows of the matrix C. M >= 0.
N — INTEGER. The number of columns of the matrix C. N >= 0.
K — 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 — REAL 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 SGELQF in the first k rows of its array argument A.

🫢 okay so listen — A is modified by the routine but restored on exit. so she's changed but she comes back, no worries bestie.

LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,K).
TAU — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGELQF. 💜
C — 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 — INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — REAL array, dimension

(N) if SIDE = 'L',
(M) if SIDE = 'R'

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 sormlq 👑

subroutine sormlq (character SIDE, character TRANS, integer M, integer N,
    integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( *
    ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * )
    WORK, integer LWORK, integer INFO)

SORMLQ — okay so this one 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 defined as the product of k elementary reflectors

      Q = H(k) . . . H(2) H(1)

as returned by SGELQF. And Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. slay 💅

🍓 Parameters 🍓

SIDE — CHARACTER*1.
- = 'L': apply Q or Q**T from the Left;
- = 'R': apply Q or Q**T from the Right.
TRANS — CHARACTER*1.
- = 'N': No transpose, apply Q;
- = 'T': Transpose, apply Q**T.
M — INTEGER. The number of rows of the matrix C. M >= 0.
N — INTEGER. The number of columns of the matrix C. N >= 0.
K

…and we're right back in the parameter tea, bestie, no recap needed 💖

K — 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 — REAL 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 SGELQF in the first k rows of its array argument A. (Row, not column, okay? don't come for me, that's just how this one lives. 👑)

LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,K).
TAU — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGELQF.
C — 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. 😭 (your original C is gone gone, it's giving makeover)
LDC — INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — REAL 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 SIDE = 'L', LWORK >= max(1,N);
- if SIDE = 'R', LWORK >= max(1,M).
- For good performance, LWORK should generally be larger. (fr fr, bigger is better here, don't be stingy ✨)

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 sormql

subroutine sormql (character SIDE, character TRANS, integer M, integer N,
    integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( *
    ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * )
    WORK, integer LWORK, integer INFO)

SORMQL

✨ Purpose

SORMQL 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 defined as the product of k elementary reflectors

      Q = H(k) . . . H(2) H(1)

as returned by SGEQLF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'.

Notice the order bestie: H(k) . . . H(2) H(1) — it's the QL vibe, reflectors stacked from the back. The QR one down below goes the other way. iykyk 💅

🌸 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': No transpose, apply Q;
- = 'T': Transpose, apply Q**T.
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 REAL 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 SGEQLF in the last k columns of its array argument A. (last columns this time, not first — the QL plot twist 🎀)
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 REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEQLF.
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 good performance, LWORK should generally be larger.

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 sormqr

subroutine sormqr (character SIDE, character TRANS, integer M, integer N,
    integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( *
    ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * )
    WORK, integer LWORK, integer INFO)

SORMQR

✨ Purpose

SORMQR 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 defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by SGEQRF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'.

See? H(1) H(2) . . . H(k) — front to back, the classic QR order. This is the one everyone meets first and honestly it ate. 🔥

🌸 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': No transpose, apply Q;
- = 'T': Transpose, apply Q**T.
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 REAL 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 SGEQRF in the first k columns of its array argument A.
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 REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGEQRF.
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 good performance, LWORK should generally be larger.

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 sormr2

subroutine sormr2 (character SIDE, character TRANS, integer M, integer N,
    integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( *
    ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * )
    WORK, integer INFO)

SORMR2 multiplies a general matrix by the orthogonal matrix from a RQ factorization determined by sgerqf (unblocked algorithm).

✨ Purpose

SORMR2 overwrites the general real m by n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**T* C  if SIDE = 'L' and TRANS = 'T', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**T if SIDE = 'R' and TRANS = 'T',

where Q is a real orthogonal matrix defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by SGERQF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'.

Heads up bestie: this one is the unblocked algorithm — the small, simple, no-frills sibling. It does the job, it just doesn't do it with the fancy blocked trickery. 🫶

🌸 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)
- = 'T': apply Q' (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 — REAL 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 SGERQF in the last k rows of its array argument A. Bestie, A gets modified by the routine but restored on exit, so it comes back to you untouched 💅
LDA — INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,K). Don't fumble this one 🙈
TAU — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGERQF. The receipts from the factorization, basically ✨
C — 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. Your baby is getting replaced, no cap 😭
LDC — INTEGER. The leading dimension of the array C. Constraint: LDC >= max(1,M).
WORK — REAL array, dimension (N) if SIDE = 'L', (M) if SIDE = 'R'. Just a lil scratchpad 🎀
INFO — INTEGER.
- = 0: successful exit, we ate 🔥
- < 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.

🦋 `sormr3` 🦋

subroutine sormr3 (character SIDE, character TRANS, integer M, integer N,
    integer K, integer L, real, dimension( lda, * ) A, integer LDA, real,
    dimension( * ) TAU, real, dimension( ldc, * ) C, integer LDC, real,
    dimension( * ) WORK, integer INFO)

SORMR3 multiplies a general matrix by the orthogonal matrix from a RZ factorization determined by stzrzf (unblocked algorithm).

Purpose:

SORMR3 overwrites the general real m by n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**T* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**T if SIDE = 'R' and TRANS = 'C',

where Q is a real orthogonal matrix defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by STZRZF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. Like, the whole reflectors-to-Q pipeline, iykyk 💜

Parameters:

SIDE — CHARACTER*1.
- = 'L': apply Q or Q**T from the Left
- = 'R': apply Q or Q**T from the Right
TRANS — CHARACTER*1.
- = 'N': apply Q (No transpose)
- = 'T': apply Q**T (Transpose)
M — INTEGER. The number of rows of the matrix C. Constraint: M >= 0.
N — INTEGER. The number of columns of the matrix C. Constraint: N >= 0.
K — 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 — 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 — REAL 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 STZRZF in the last k rows of its array argument A. A is modified by the routine but restored on exit 🌸
LDA — INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,K).
TAU — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by STZRZF.
C — 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. Bestie it's gone, it's giving transformation 💫
LDC — INTEGER. The leading dimension of the array C. Constraint: LDC >= max(1,M).
WORK — REAL array, dimension (N) if SIDE = 'L', (M) if SIDE = 'R'.
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.

🌟 Contributors:

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

💫 Further Details:

(this section is literally just vibes — nothing listed here)

🎀 `sormrq` 🎀

subroutine sormrq (character SIDE, character TRANS, integer M, integer N,
    integer K, real, dimension( lda, * ) A, integer LDA, real, dimension( *
    ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * )
    WORK, integer LWORK, integer INFO)

SORMRQ — yes that's genuinely the whole description, iconic minimalism 💅

Purpose:

SORMRQ 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 defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by SGERQF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. Look at that lil table, she's serving organization 🦋

Parameters:

SIDE — CHARACTER*1.
- = 'L': apply Q or Q**T from the Left;
- = 'R': apply Q or Q**T from the Right.
TRANS — CHARACTER*1.
- = 'N': No transpose, apply Q;
- = 'T': Transpose, apply Q**T.
M — INTEGER. The number of rows of the matrix C. Constraint: M >= 0.
N — INTEGER. The number of columns of the matrix C. Constraint: N >= 0.
K — 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 — REAL 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 SGERQF in the last k rows of its array argument A. Note: no "restored on exit" here, so peek accordingly 👀
LDA — INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,K).
TAU — REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGERQF.
C — 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 — INTEGER. The leading dimension of the array C. Constraint: LDC >= max(1,M).
WORK — REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. She's self-reporting, main character energy ✨
LWORK — 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. Bigger scratchpad, smoother ride, fr fr.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. So -1 is not a mistake, it's a question 🎀

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.

🌈 `sormrz` 🌈

subroutine sormrz (character SIDE, character TRANS, integer M, integer N,
    integer K, integer L, real, dimension( lda, * ) A, integer LDA, real,
    dimension( * ) TAU, real, dimension( ldc, * ) C, integer LDC, real,
    dimension( * ) WORK, integer LWORK, integer INFO)

SORMRZ

Purpose:

SORMRZ 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 defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by STZRZF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. Same shape as her sister sormrq but the reflectors come from STZRZF — sibling energy 💜

Parameters:

SIDE — CHARACTER*1.
- = 'L': apply Q or Q**T from the Left;
- = 'R': apply Q or Q**T from the Right.
TRANS — CHARACTER*1.
- = 'N': No transpose, apply Q;
- = 'T': Transpose, apply Q**T.
M — INTEGER. The number of rows of the matrix C. Constraint: M >= 0.
N — INTEGER. The number of columns of the matrix C. Constraint: N >= 0.
K — 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 — 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 — REAL 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 STZRZF in the last k rows of its array argument A. A is modified by the routine but restored on exit 🌸
LDA — INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,K).
TAU — TAU is REAL array, dimension (K). Bestie listen — TAU(i) has to contain the scalar factor of the elementary reflector H(i), exactly as it came back from STZRZF. ✨
C — C is REAL array, dimension (LDC,N). On entry: the M-by-N matrix C, the whole main character. 💅 On exit: C gets overwritten by Q*C or Q**H*C or C*Q**H or C*Q. No takebacks, she's changed now. 🦋
LDC — LDC is INTEGER. The leading dimension of the array C. Rule of the house: LDC >= max(1,M). 📏
WORK — WORK is REAL 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.
- If SIDE = 'L', LWORK >= max(1,N).
- If SIDE = 'R', LWORK >= max(1,M).
- For good performance, LWORK should generally be larger. Like, go big, she deserves it. ✨

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.

🫶 Contributors:

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

🌸 Further Details:

`subroutine sormtr (character SIDE, character UPLO, character TRANS, integer M, integer N, real, dimension( lda, * ) A, integer LDA, real, dimension( * ) TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * ) WORK, integer LWORK, integer INFO)`

SORMTR

🎯 Purpose:

SORMTR 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'. Q is defined as the product of nq-1 elementary reflectors, as returned by SSYTRD:

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**T from the Left;
- = 'R': apply Q or Q**T from the Right. Pick a side, any side.
UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangle of A contains elementary reflectors from SSYTRD;
- = 'L': Lower triangle of A contains elementary reflectors from SSYTRD.
TRANS — TRANS is CHARACTER*1.
- = 'N': No transpose, apply Q;
- = 'T': Transpose, apply Q**T. 🔄
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 REAL array, dimension

                                     (LDA,M) if SIDE = 'L'
                                     (LDA,N) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by SSYTRD. 🦋

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 REAL 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 SSYTRD. ✨

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. She's been through something, okay. 💅
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 >= N*NB if SIDE = 'L', and LWORK >= M*NB if SIDE = 'R', where NB is the optimal blocksize. Optimum performance, we love to see it. 🔥

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 spbcon (character UPLO, integer N, integer KD, real, dimension( ldab, * ) AB, integer LDAB, real ANORM, real RCOND, real, dimension( * ) WORK, integer, dimension( * ) IWORK, integer INFO)`

SPBCON

🎯 Purpose:

SPBCON estimates the reciprocal of the condition number (in the 1-norm) of a real symmetric positive definite band matrix using the Cholesky factorization A = U**T*U or A = L*L**T computed by SPBTRF.

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

🌈 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 subdiagonals if UPLO = 'L'. KD >= 0. 📏
AB — AB is REAL array, dimension (LDAB,N). The triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T 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 symmetric 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 REAL array, dimension (3*N).
IWORK — IWORK is INTEGER 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 spbequ (character UPLO, integer N, integer KD, real, dimension( ldab, * ) AB, integer LDAB, real, dimension( * ) S, real SCOND, real AMAX, integer INFO)`

SPBEQU

🎯 Purpose:

SPBEQU computes row and column scalings intended to equilibrate a symmetric positive definite band matrix A and reduce its condition number (with respect to the two-norm). S is the star of this show. 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 REAL array, dimension (LDAB,N). The upper or lower triangle of the symmetric 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. Lowkey leave her alone at that point.
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 `spbrfs` ✨

subroutine spbrfs (character UPLO, integer N, integer KD, integer NRHS,
    real, dimension( ldab, * ) AB, integer LDAB, real, dimension( ldafb, * )
    AFB, integer LDAFB, real, dimension( ldb, * ) B, integer LDB, real,
    dimension( ldx, * ) X, integer LDX, real, dimension( * ) FERR, real,
    dimension( * ) BERR, real, dimension( * ) WORK, integer, dimension( * )
    IWORK, integer INFO)
SPBRFS

Purpose: bestie. SPBRFS takes your already-computed solution to a linear system and makes it better. 🫶 It's out here improving the computed solution to a system of linear equations when the coefficient matrix is symmetric positive definite and banded, and it also hands you error bounds and backward error estimates for the solution. It's giving glow-up, but for matrices. 💅

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. (Zero is allowed, she's not judging. 👑)
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 REAL array, dimension (LDAB,N)
- The upper or lower triangle of the symmetric 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 REAL array, dimension (LDAFB,N)
- The triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T of the band matrix A as computed by SPBTRF, in the same storage format as A (see AB). It's literally the same vibe, different array. ✨
LDAFB — LDAFB is INTEGER
- The leading dimension of the array AFB. LDAFB >= KD+1.
B — B is REAL array, dimension (LDB,NRHS)
- The right hand side matrix B. She's the main character of the equation, ngl.
LDB — LDB is INTEGER
- The leading dimension of the array B. LDB >= max(1,N).
X — X is REAL array, dimension (LDX,NRHS)
- On entry, the solution matrix X, as computed by SPBTRS.
- On exit, the improved solution matrix X. Upgrade era. 🦋
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 REAL array, dimension (3*N)
- Just workspace. Let her cook. 🍓
IWORK — IWORK is INTEGER array, dimension (N)
- More workspace, but make it integer.
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 `spbstf` ✨

subroutine spbstf (character UPLO, integer N, integer KD, real, dimension(
    ldab, * ) AB, integer LDAB, integer INFO)
SPBSTF

Purpose: SPBSTF computes a split Cholesky factorization of a real symmetric positive definite band matrix A. 😤

This routine is designed to be used in conjunction with SSBGST.

The factorization has the form A = S**T*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 REAL array, dimension (LDAB,N)
- On entry, the upper or lower triangle of the symmetric 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**T*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. Not positive definite?? Bestie the whole routine just stopped talking to you. 💀

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  s64  s75
 *   a12  a23  a34  a45  a56  a67   *   s12  s23  s34  s54  s65  s76
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  s23  s34  s54  s65  s76   *
a31  a42  a53  a64  a64   *    *   s13  s24  s53  s64  s75   *    *

Array elements marked * are not used by the routine. (They're just standing there, being decorative. 🎀)

✨ subroutine `spbtf2` ✨

subroutine spbtf2 (character UPLO, integer N, integer KD, real, dimension(
    ldab, * ) AB, integer LDAB, integer INFO)

SPBTF2 computes the Cholesky factorization of a symmetric/Hermitian positive definite band matrix (unblocked algorithm).

Purpose: 🌈

SPBTF2 computes the Cholesky factorization of a real symmetric positive definite band matrix A.

The factorization has the form

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

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

This is the unblocked version of the algorithm, calling Level 2 BLAS. Lowkey the simpler sibling, but she gets the job done. 💪

Parameters 🌸

UPLO — 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
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 REAL array, dimension (LDAB,N)
- On entry, the upper or lower triangle of the symmetric 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**T*U or A = L*L**T 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. Girl, that minor said "not today." 😭

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   *    *

Array elements marked * are not used by the routine. they're literally just vibing there, untouched, unemployed 💅

subroutine `spbtrf`

SPBTRF

Purpose:

Bestie, it's Cholesky time ✨ SPBTRF computes the Cholesky factorization of a real symmetric positive definite band matrix A.

The factorization has the form

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

where U is an upper triangular matrix and L is lower triangular. iconic behaviour, no notes.

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 REAL array, dimension (LDAB,N)
- On entry, the upper or lower triangle of the symmetric 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**T*U or A = L*L**T of the band matrix A, in the same storage format as A. it really said "same energy, same format" 💖
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 leading minor of order i is not positive definite, and the factorization could not be completed. not her failing, the matrix was just not that girl 😭

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   *    *

Array elements marked * are not used by the routine. still unemployed, still unbothered 🦋

Contributors:

Peter Mayes and Giuseppe Radicati, IBM ECSEC, Rome, March 23, 1989. legends, honestly 👑

subroutine `spbtrs`

SPBTRS

Purpose:

okay so you already did the hard part, now we solve 💅 SPBTRS solves a system of linear equations A*X = B with a symmetric positive definite band matrix A using the Cholesky factorization A = U**T*U or A = L*L**T computed by SPBTRF.

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 subdiagonals if UPLO = 'L'. KD >= 0.
NRHS — NRHS is INTEGER
- The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AB — AB is REAL array, dimension (LDAB,N)
- The triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T 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.
B — B is REAL array, dimension (LDB,NRHS)
- On entry, the right hand side matrix B.
- On exit, the solution matrix X. glow up moment ✨ she came in as B and left as X
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.

subroutine `spftrf`

SPFTRF

Purpose:

SPFTRF computes the Cholesky factorization of a real symmetric positive definite matrix A.

The factorization has the form

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

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

This is the block version of the algorithm, calling Level 3 BLAS. yes she's fancy, yes she's fast, we love a block algorithm 🫶

Parameters

TRANSR — TRANSR is CHARACTER*1
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'T': The 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.
A — A is REAL array, dimension ( N*(N+1)/2 );
- On entry, the symmetric 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 = 'T' then RFP is the 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 = 'T'. When TRANSR is 'N' the LDA is N+1 when N is even and N is odd. See the Note below for more details. yes that's a lot of words, read it twice, it's fine, you got this 💜
- On exit, if INFO = 0, the factor U or L from the Cholesky factorization RFP A = U**T*U or RFP A = L*L**T.
INFO — 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. she tried, the matrix said no 💀

Author

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

Further Details:

We first consider Rectangular Full Packed (RFP) 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 the 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 the transpose of the last three columns of AP lower.

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 = 'T'. RFP A in both UPLO cases is just the 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 then consider Rectangular Full Packed (RFP) 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 the 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 the transpose of the last two columns of AP lower.

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

okay so now let TRANSR = 'T' bestie 💖 and honestly in both UPLO cases, RFP A is just the transpose of RFP A from above. so you literally get this:

                    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

and that's the whole vibe check for that one, no cap ✨

✨ `spftri` ✨

subroutine spftri (character TRANSR, character UPLO, integer N, real,
    dimension( 0: * ) A, integer INFO)

SPFTRI 🫶

Purpose

SPFTRI computes the inverse of a real (symmetric) positive definite matrix A using the Cholesky factorization A = U**T*U or A = L*L**T computed by SPFTRF. like it literally just undoes the factorization, bestie 🔥

Parameters

TRANSR — TRANSR is CHARACTER*1.
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'T': The 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 REAL array, dimension ( N*(N+1)/2 ).

On entry, the symmetric 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 = 'T' then RFP is the 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 = 'T'. 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 symmetric inverse of the original matrix, in the same storage format. slay 💅

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.

okay so that > 0 case? that's the 💀 moment. a zero on the diagonal of your factor means there's literally no inverse to give you. not a vibe.

Author

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

Further Details

So first we consider Rectangular Full Packed (RFP) Format when N is even. here's the 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 = 'T'. RFP A in both UPLO cases is just the 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 then consider Rectangular Full Packed (RFP) Format when N is odd. the example here is 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 the 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 the transpose of the last two columns of AP lower. 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 = 'T'. RFP A in both UPLO cases is just the 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

✨ `spftrs` ✨

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

SPFTRS 👑

Purpose

SPFTRS solves a system of linear equations A*X = B with a symmetric positive definite matrix A using the Cholesky factorization A = U**T*U or A = L*L**T computed by SPFTRF. like it's giving solve-the-whole-system energy 💜

Parameters

TRANSR — TRANSR is CHARACTER*1.
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'T': The 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 REAL 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**T, as computed by SPFTRF. See note below for more details about RFP A.
B — B is REAL array, dimension (LDB,NRHS).
- On entry, the right hand side matrix B.
- On exit, the solution matrix X. it literally swaps itself out, main character behaviour honestly 💅
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

okay so first we consider Rectangular Full Packed (RFP) Format when N is even. here's the 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 = 'T'. RFP A in both UPLO cases is just the 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 then consider Rectangular Full Packed (RFP) Format when N is odd. we're doing N = 5 this time 🎀

   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 = 'T'. RFP A in both UPLO cases is just the 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

and that's where we're at, bestie — more coming, don't go anywhere 🫶

subroutine `sppcon`

subroutine sppcon (character UPLO, integer N, real, dimension( * ) AP, real
    ANORM, real RCOND, real, dimension( * ) WORK, integer, dimension( * )
    IWORK, integer INFO)

SPPCON — okay so this one is the vibe-check function for your matrix. It looks at how ✨unwell✨ your problem is numerically.

Purpose

Bestie, SPPCON estimates the reciprocal of the condition number (in the 1-norm) of a real symmetric positive definite packed matrix, using the Cholesky factorization A = U**T*U or A = L*L**T that SPPTRF already computed for you. 💅

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

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

So like, tiny RCOND = your matrix is shaking. 🌸

Parameters

UPLO — CHARACTER*1, pick your lane:
- = 'U': upper triangle of A is stored;
- = 'L': lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0. ✨
AP — REAL array, dimension (N*(N+1)/2). The triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T, 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 — REAL. The 1-norm (or infinity-norm) of the symmetric matrix A. 👑
RCOND — 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 — REAL array, dimension (3*N).
IWORK — INTEGER 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 `sppequ`

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

SPPEQU — this one is literally the glow-up routine. It rescales your matrix so it behaves. 🦋

Purpose

SPPEQU computes row and column scalings intended to equilibrate a symmetric 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. Periodt. 💅

Parameters

UPLO — CHARACTER*1:
- = 'U': upper triangle of A is stored;
- = 'L': lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0.
AP — REAL 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)*(2n-j)/2) = A(i,j) for j<=i<=n.
S — REAL array, dimension (N). If INFO = 0, S contains the scale factors for A. ✨
SCOND — 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 — 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 — 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 `spprfs`

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

SPPRFS — the "actually, let's make that answer better" routine. 💖

Purpose

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

Parameters

UPLO — CHARACTER*1:
- = 'U': upper triangle of A is stored;
- = 'L': lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0.
NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AP — REAL 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)*(2n-j)/2) = A(i,j) for j<=i<=n.
AFP — REAL array, dimension (N*(N+1)/2). The triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T, as computed by SPPTRF/CPPTRF, packed columnwise in a linear array in the same format as A (see AP). 👑
B — REAL array, dimension (LDB,NRHS). The right hand side matrix B.
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
X — REAL array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by SPPTRS. On exit, the improved solution matrix X. ✨
LDX — INTEGER. The leading dimension of the array X. 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), 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 — 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 — REAL array, dimension (3*N).
IWORK — INTEGER array, dimension (N).
INFO — 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 `spptrf`

subroutine spptrf (character UPLO, integer N, real, dimension( * ) AP,
    integer INFO)

SPPTRF — the main character of the packed-Cholesky universe. 🌈

Purpose

SPPTRF computes the Cholesky factorization of a real symmetric positive definite matrix A stored in packed format. ✨

The factorization has the form

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

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

Parameters

UPLO — CHARACTER*1:
- = 'U': upper triangle of A is stored;
- = 'L': lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0.
AP — REAL 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.

See below for further details. 👀

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

INFO — 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 me when the leading minor isn't positive definite — bestie the matrix said no. 😭

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 symmetric matrix A:

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

Packed storage of the upper triangle of A:

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

subroutine `spptri`

subroutine spptri (character UPLO, integer N, real, dimension( * ) AP,
    integer INFO)

SPPTRI — flip that matrix, invert it, slay. 🧚

Purpose

SPPTRI computes the inverse of a real symmetric positive definite matrix A using the Cholesky factorization A = U**T*U or A = L*L**T computed by SPPTRF. 💖

Parameters

UPLO
UPLO — a CHARACTER*1 that tells us which triangle of the factor is chilling in AP:
- = 'U': Upper triangular factor is stored in AP;
- = 'L': Lower triangular factor is stored in AP.
N — INTEGER, the order of the matrix A. Rule: N >= 0. ✨
AP — REAL array, dimension (N*(N+1)/2). On entry, bestie, it's the triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T, packed columnwise as a linear array. The j-th column of U or L is stored in the array AP like this:

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.

On exit? It gets overwritten — the upper or lower triangle of the (symmetric) inverse of A lands right where the input factor U or L used to be. 💅

INFO — INTEGER, the vibe check:
- = 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.

🧚 `spptrs`

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

SPPTRS

Purpose

SPPTRS solves a system of linear equations A*X = B with a symmetric positive definite matrix A in packed storage using the Cholesky factorization A = U**T*U or A = L*L**T computed by SPPTRF. It's giving "solve the thing, no drama" ✨

Parameters

UPLO — CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — INTEGER, the order of the matrix A. N >= 0.
NRHS — INTEGER, the number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AP — REAL array, dimension (N*(N+1)/2). The triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T, 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.

B — REAL array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, the solution matrix X. glow-up moment fr fr 🦋
LDB — INTEGER, the leading dimension of the array B. LDB >= max(1,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.

🌸 `spstf2`

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

SPSTF2 computes the Cholesky factorization with complete pivoting of a real symmetric positive semidefinite matrix.

Purpose

SPSTF2 computes the Cholesky factorization with complete pivoting of a real symmetric positive semidefinite matrix A. 💖

The factorization has the form

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

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

Heads up bestie: this algorithm does not attempt to check that A is positive semidefinite. 🙈 Also, this version of the algorithm calls level 2 BLAS.

Parameters

UPLO — CHARACTER*1. Specifies whether the upper or lower triangular part of the symmetric matrix A is stored.
- = 'U': Upper triangular
- = 'L': Lower triangular
N — INTEGER, the order of the matrix A. N >= 0.
A — REAL 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.

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

PIV — INTEGER array, dimension (N). PIV is such that the nonzero entries are P( PIV(K), K ) = 1.
RANK — INTEGER. The rank of A given by the number of steps the algorithm completed. 👑
TOL — 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.
LDA — INTEGER, the leading dimension of the array A. LDA >= max(1,N).
WORK — REAL array, dimension (2*N). Work space. 🛠️
INFO — INTEGER
- < 0: If INFO = -K, the K-th argument had an illegal value,
- = 0: algorithm completed successfully, and
- > 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.

🎀 `spstrf`

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

SPSTRF computes the Cholesky factorization with complete pivoting of a real symmetric positive semidefinite matrix.

Purpose

SPSTRF computes the Cholesky factorization with complete pivoting of a real symmetric positive semidefinite matrix A. 💜

The factorization has the form

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

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

Same energy as before, bestie: this algorithm does not attempt to check that A is positive semidefinite. The difference? This version of the algorithm calls level 3 BLAS. 🔥

Parameters

UPLO — CHARACTER*1. Specifies whether the upper or lower triangular part of the symmetric matrix A is stored.
- = 'U': Upper triangular
- = 'L': Lower triangular
N — INTEGER, the order of the matrix A. N >= 0.
A — REAL 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.

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

LDA — INTEGER, the leading dimension of the array A. LDA >= max(1,N).
PIV — INTEGER array, dimension (N). PIV is such that the nonzero entries are P( PIV(K), K ) = 1.
RANK — INTEGER. The rank of A given by the number of steps the algorithm completed.
TOL — 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.
WORK — REAL array, dimension (2*N). Work space. 🧰
INFO — INTEGER
- < 0: If INFO = -K, the K-th argument had an illegal value,
- = 0: algorithm completed successfully, and
- > 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.

🦋 `ssbgst`

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

SSBGST

Purpose

SSBGST reduces a real symmetric-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**T*S by SPBSTF, using a split Cholesky factorization. A is overwritten by C = X**T*A*X, where X = S**(-1)*Q and Q is an orthogonal matrix chosen to preserve the bandwidth of A. no cap, that's the whole glow-up ✨

Parameters

VECT — CHARACTER*1
- = 'N': do not form the transformation matrix X;
- = 'V': form X.
UPLO — CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — INTEGER, the order of the matrices A and B. N >= 0.
KA — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KA >= 0.
KB —
KB — KB is INTEGER. It's the number of superdiagonals of the matrix B when UPLO = 'U', or the number of subdiagonals when UPLO = 'L'. And the rule is KA >= KB >= 0 — no negotiating, bestie. 💅
AB — AB is REAL array, dimension (LDAB,N).

On entry: the upper or lower triangle of the symmetric band matrix A, vibing 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 like this:

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**T*A*X, stored in the same format as A. ✨

LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KA+1. That's the bare minimum, don't test it. 🫶
BB — BB is REAL array, dimension (LDBB,N). It's the banded factor S from the split Cholesky factorization of B, exactly as SPBSTF handed it back, stored in the first KB+1 rows of the array.
LDBB — LDBB is INTEGER. The leading dimension of the array BB. LDBB >= KB+1.
X — X is REAL array, dimension (LDX,N). If VECT = 'V', it's the n-by-n matrix X. If VECT = 'N', then bestie, the array X is literally not referenced. Ignored. Ghosted. 💀
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,N) if VECT = 'V'; LDX >= 1 otherwise.
WORK — WORK is REAL array, dimension (2*N).
INFO — INFO is INTEGER.
- = 0: successful exit, we ate. 👑
- < 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 `ssbtrd` 🦋

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

SSBTRD

✨ Purpose ✨

SSBTRD reduces a real symmetric band matrix A to symmetric tridiagonal form T by an orthogonal similarity transformation: Q**T * A * Q = T. Slay. That's the whole glow-up. 💖

🌈 Parameters 🌈

VECT — VECT is CHARACTER*1.
- = 'N': do not form Q;
- = 'V': form Q;
- = 'U': update a matrix X, by forming X*Q.
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 REAL array, dimension (LDAB,N).

On entry: the upper or lower triangle of the symmetric 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 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).

On exit: the diagonal elements of AB get 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') get overwritten by the off-diagonal elements of T; and the rest of AB? Overwritten by values generated during the reduction. It's giving transformation era. 🦋

LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
D — D is REAL array, dimension (N). The diagonal elements of the tridiagonal matrix T. The main character elements, honestly.
E — E is 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 — Q is REAL 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. No pressure. 🙈

On exit:

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

LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= 1, and LDQ >= N if VECT = 'V' or 'U'.
WORK — WORK is REAL array, dimension (N).
INFO — INFO is INTEGER.
- = 0: successful exit. We love to see it. 💖
- < 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. Iconic behaviour, honestly. 👑

🧚 subroutine `ssfrk` 🧚

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

SSFRK

✨ Purpose ✨

Level 3 BLAS like routine for C in RFP Format.

SSFRK performs one of the symmetric rank--k operations

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

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

where alpha and beta are real scalars, C is an n--by--n symmetric matrix and A is an n--by--k matrix in the first case and a k--by--n matrix in the second case. Pick your fighter, bestie. 💅

🌈 Parameters 🌈

TRANSR — TRANSR is CHARACTER*1.
- = 'N': The Normal Form of RFP A is stored;
- = 'T': The 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**T + beta*C.
TRANS = 'T' or 't': C := alpha*A**T*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 = 'T' or 't', 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 REAL 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 REAL array, dimension (NT), NT = N*(N+1)/2. On entry, the symmetric matrix C in RFP Format. RFP Format is described by TRANSR, UPLO and N. iykyk. 🎀

🌸 Author 🌸

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

🍓 subroutine `sspcon` 🍓

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

SSPCON

✨ Purpose ✨

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

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))). It's giving "how close to a disaster are we" energy, and honestly? Respect. 😭

🌈 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.
AP — AP is REAL 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 SSPTRF, 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 SSPTRF.
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 REAL array, dimension (2*N).
IWORK — IWORK is INTEGER array, dimension (N) 🫶
INFO — INFO is INTEGER = 0: successful exit, bestie, we made it ✨ < 0: if INFO = -i, then the i-th argument had an illegal value 💀 (somebody passed you a bad argument, not me)

Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine `sspgst` — SSPGST

subroutine sspgst (integer ITYPE, character UPLO, integer N, real,
    dimension( * ) AP, real, dimension( * ) BP, integer INFO)

Purpose 💫

SSPGST reduces a real symmetric-definite generalized eigenproblem to standard form, using packed storage. it's giving glow-up transformation 🦋

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

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**T or L**T*A*L.

B must have been previously factorized as U**T*U or L*L**T by SPPTRF. no cap, you gotta do that first 🙈

Parameters 🎀

ITYPE — ITYPE is INTEGER = 1: compute inv(U**T)*A*inv(U) or inv(L)*A*inv(L**T); = 2 or 3: compute U*A*U**T or L**T*A*L.
UPLO — UPLO is CHARACTER*1 = 'U': Upper triangle of A is stored and B is factored as U**T*U; = 'L': Lower triangle of A is stored and B is factored as L*L**T.
N — N is INTEGER. The order of the matrices A and B. N >= 0. 💅
AP — AP is REAL 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, if INFO = 0, the transformed matrix, stored in the same format as A. ✨

BP — BP is REAL 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 SPPTRF.
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 `ssprfs` — SSPRFS

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

Purpose 💫

SSPRFS 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. it's the glow-up pass, the refinement era 🧚

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 REAL 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.
AFP — AFP is REAL 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 SSPTRF, 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 SSPTRF.
B — B is REAL 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 REAL array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by SSPTRS. 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. lowkey generous of it 💅
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 REAL array, dimension (3*N)
IWORK — IWORK is INTEGER 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 `ssptrd` — SSPTRD

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

Purpose 💫

SSPTRD reduces a real symmetric matrix A stored in packed form to symmetric tridiagonal form T by an orthogonal similarity transformation: Q**T * A * Q = T. it's giving main character transformation arc 👑

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 REAL 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)*(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 orthogonal 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 orthogonal 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 REAL 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**T

where tau is a real scalar, and v is a real 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**T

where tau is a real scalar, and v is a real 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 `ssptrf` — SSPTRF

subroutine ssptrf (character UPLO, integer N, real, dimension( * ) AP,
    integer, dimension( * ) IPIV, integer INFO)

Purpose 💫

SSPTRF computes the factorization of a real 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. periodt. 🎀

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 — (the breakdown continues, bestie, we're still mid-parameter list… stay tuned 💅)
AP — okay bestie, AP is a REAL array with dimension (N*(N+1)/2). On entry, it’s the upper or lower triangle of the symmetric matrix A, packed columnwise in a linear array. The j-th column of A lives in AP like this:
- if UPLO = 'U', then AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', then 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 are stored as a packed triangular matrix overwriting A (see below for further details, no cap).

IPIV — it’s an 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 — 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. bestie, that’s a yikes 💀

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

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 ssptri ... 👑

subroutine ssptri (character UPLO, integer N, real, dimension( * ) AP,
    integer, dimension( * ) IPIV, real, dimension( * ) WORK, integer INFO)
    SSPTRI

Purpose: 🌸

SSPTRI computes the inverse of a real symmetric indefinite matrix A in packed storage using the factorization A = U*D*U**T or A = L*D*L**T computed by SSPTRF.

Parameters 🎀

UPLO — 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 — INTEGER. The order of the matrix A. N >= 0.
AP — REAL 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 SSPTRF, stored as a packed triangular matrix.

On exit, if INFO = 0, 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 as follows:

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 — INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by SSPTRF.
WORK — REAL array, dimension (N).
INFO — 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. oof 💀

Author ✨

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

subroutine ssptrs ... 🦋

subroutine ssptrs (character UPLO, integer N, integer NRHS, real, dimension(
    * ) AP, integer, dimension( * ) IPIV, real, dimension( ldb, * ) B,
    integer LDB, integer INFO)
    SSPTRS

Purpose: 🌈

SSPTRS solves a system of linear equations A*X = B with a real symmetric matrix A stored in packed format using the factorization A = U*D*U**T or A = L*D*L**T computed by SSPTRF.

Parameters 💖

UPLO — 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 — INTEGER. The order of the matrix A. N >= 0.
NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AP — REAL 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 SSPTRF, stored as a packed triangular matrix.
IPIV — INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by SSPTRF.
B — REAL array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, the solution matrix X.
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,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 sstegr ... 👑

subroutine sstegr (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, real,
    dimension( ldz, * ) Z, integer LDZ, integer, dimension( * ) ISUPPZ,
    real, dimension( * ) WORK, integer LWORK, integer, dimension( * ) IWORK,
    integer LIWORK, integer INFO)
    SSTEGR

Purpose: 🧚

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

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.

SSTEGR is a compatibility wrapper around the improved SSTEMR 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.

Note : SSTEGR and SSTEMR 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.

Parameters 💜

JOBZ — CHARACTER*1.
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
RANGE — 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 — INTEGER. The order of the matrix. N >= 0.
D — REAL array, dimension (N). On entry, the N diagonal elements of the tridiagonal matrix T. On exit, D is overwritten.
E — 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 — 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 — 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 — 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 — 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.

bestie this one’s a ghost, fr 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.
Z — Z is REAL 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.
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 ( 2max(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.
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 SLARRV. Here, the digit X = ABS( IINFO ) < 10, where IINFO is the nonzero error code returned by SLARRE or SLARRV, respectively.

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 sstein (integer N, real, dimension( * ) D, real, dimension( * )
E, integer M, real, dimension( * ) W, integer, dimension( * ) IBLOCK,
integer, dimension( * ) ISPLIT, real, dimension( ldz, * ) Z, integer
LDZ, real, dimension( * ) WORK, integer, dimension( * ) IWORK, integer,
dimension( * ) IFAIL, integer INFO)

SSTEIN 💅

Purpose:

SSTEIN computes the eigenvectors of a real symmetric tridiagonal matrix T corresponding to specified eigenvalues, using inverse iteration.

The maximum number of iterations allowed for each eigenvector is specified by an internal parameter MAXITS (currently set to 5).

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, 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. )
IBLOCK — IBLOCK is INTEGER array, dimension (N) The submatrix indices associated with the corresponding eigenvalues in W; 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. 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 REAL array, dimension (LDZ, M) The computed eigenvectors. 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.
LDZ — LDZ is INTEGER The leading dimension of the array Z. LDZ >= max(1,N).
WORK — WORK is REAL array, dimension (5N)*
IWORK — IWORK is INTEGER array, dimension (N)
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.
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.
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 sstemr (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, real, dimension( ldz, * )
Z, integer LDZ, integer NZC, integer, dimension( * ) ISUPPZ, logical
TRYRAC, real, dimension( * ) WORK, integer LWORK, integer, dimension( *
) IWORK, integer LIWORK, integer INFO)

SSTEMR 🌟

Purpose:

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

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

ok bestie if you want the receipts, here's the whole academic bibliography — actual papers, no vibe-based sourcing 💅

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 ✨

1. SSTEMR 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. 🧚

no cap, if your machine is weird about infinities and NaNs, this routine is simply not the moment. it's giving "IEEE-754 girlies only" 💀

🎀 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. ⭐
Z — Z is REAL 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 — 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.
TRYRAC — TRYRAC is LOGICAL. If TRYRAC = .TRUE., indicates that the code should check whether the tridiagonal matrix defines its eigenvalues to high relative accuracy. If so, 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 uses 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 SLARRV. Here, the digit X = ABS( IINFO ) < 10, where IINFO is the nonzero error code returned by SLARRE or SLARRV, 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 stbcon 👑

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

STBCON

✨ Purpose: ✨

STBCON 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)) ).

basically it's asking "how sketchy is this matrix" and answering with a number between, like, tiny and not-tiny 💀

🎀 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 REAL 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 REAL array, dimension (3*N)
IWORK — IWORK is INTEGER 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 `stbrfs` ✨

okay bestie, here's the whole vibe signature, no notes:

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

STBRFS

💖 Purpose 💖

STBRFS hands you error bounds and backward error estimates for the solution of a linear system whose coefficient matrix is a triangular band matrix. it's giving "how wrong am i actually" energy and honestly we love that for us 💅

heads up though: the solution matrix X has to be computed by STBTRS or literally any other means before you walk in here. this routine is not out here doing the work for you, it's doing the vibe check afterwards. and no, STBRFS does not do iterative refinement — because doing that cannot improve the backward error. the math said no and we respect the math 🫶

🎀 Parameters 🎀

UPLO — UPLO is CHARACTER*1, and it tells us which way A is leaning:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1. it specifies the form of the system of equations, so like, which shape are we solving:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose = 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. periodt.
KD — KD is INTEGER. the number of superdiagonals or subdiagonals of the triangular band matrix A. 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 REAL array, dimension (LDAB,N). it's 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).

and 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.
B — B is REAL array, dimension (LDB,NRHS). it's the right hand side matrix B. that's it, that's the whole job 🍓
LDB — LDB is INTEGER. the leading dimension of the array B. LDB >= max(1,N).
X — X is REAL array, dimension (LDX,NRHS). the solution matrix X. (you brought this one yourself, remember?)
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 tea: the estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. so it's a hater sometimes but a reliable hater.
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 REAL array, dimension (3*N).
IWORK — IWORK is INTEGER array, dimension (N).
INFO — INFO is INTEGER:
- = 0: successful exit. slay ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. not slay.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine `stbtrs` 🌸

signature drop, verbatim, we don't edit the queen's handwriting:

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

STBTRS

💖 Purpose 💖

STBTRS actually solves a triangular system of the form

   A * X = B  or  A**T * X = B,

where A is a triangular band matrix of order N, and B is an N-by-NRHS matrix. and because it's a girlboss with trust issues, a check is made to verify that A is nonsingular. if A is out here being singular, bestie, we're not pretending. 🙈

🎀 Parameters 🎀

UPLO — UPLO is CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1. it specifies the form the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose = 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 is INTEGER. the number of superdiagonals or subdiagonals of the triangular band matrix A. KD >= 0.
NRHS — NRHS is INTEGER. the number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AB — AB is REAL 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).

also: 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.
B — B is REAL array, dimension (LDB,NRHS). the glow-up spot right here: on entry, the right hand side matrix B. on exit, if INFO = 0, the solution matrix X. same array, whole new identity. main character energy 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. do not touch that X, bestie, it's empty. 😭

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 subroutine `stfsm` 🦋

STFSM solves a matrix equation (one operand is a triangular matrix in RFP format).

here's the signature, character for character, don't come for me:

subroutine stfsm (character TRANSR, character SIDE, character UPLO,
    character TRANS, character DIAG, integer M, integer N, real ALPHA, real,
    dimension( 0: * ) A, real, dimension( 0: ldb-1, 0: * ) B, integer LDB)

💖 Purpose 💖

Level 3 BLAS like routine for A in RFP Format.

STFSM 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**T.

A is in Rectangular Full Packed (RFP) Format. iykyk.

and the kicker: the matrix X is overwritten on B. she doesn't make a copy, she becomes the answer. iconic behavior honestly 🎀

🎀 Parameters 🎀

TRANSR — TRANSR is CHARACTER*1:
- = 'N': The Normal Form of RFP A is stored;
- = 'T': The Transpose Form of RFP A is stored.
SIDE — SIDE is 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 — UPLO is 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 — TRANS is 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 = 'T' or 't': op( A ) = A'.

Unchanged on exit.

DIAG — DIAG is 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 — M is INTEGER. on entry, M specifies the number of rows of B. M must be at least zero. Unchanged on exit.
N — N is INTEGER. on entry, N specifies the number of columns of B. N must be at least zero. Unchanged on exit.
ALPHA — ALPHA is REAL. on entry, ALPHA specifies the scalar alpha. cute shortcut alert: when alpha is zero then A is not referenced and B need not be set before entry. Unchanged on exit.
A —
A — a REAL array, dimension (NT), where NT = N*(N+1)/2. On entry, this is the matrix A in RFP Format. RFP Format is described by TRANSR, UPLO and N like this: if TRANSR='N' then RFP A is (0:N,0:K-1) when N is even, and K=N/2. RFP A is (0:N-1,0:K) when N is odd, K=N/2. If TRANSR = 'T' then RFP is the transpose of RFP A as defined when TRANSR = 'N'. What's actually inside RFP A is defined by UPLO as follows: if UPLO = 'U' the RFP A contains the NT elements of upper packed A, either in normal or transpose Format. If UPLO = 'L' the RFP A contains the NT elements of lower packed A, either in normal or transpose Format. The LDA of RFP A is (N+1)/2 when TRANSR = 'T'. When TRANSR is 'N' the LDA is N+1 when N is even and is N when is odd. Peep the Note below for more deets, bestie. Unchanged on exit. 💖
B — a REAL 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 it gets overwritten by the solution matrix X. She's not coming back the same, ok? 💅
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 🔍

Okay so first we consider Rectangular Full Packed (RFP) Format when N is even. Example time — let's say 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 the 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 the transpose of the last three columns of AP lower. 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 = 'T'. RFP A in both UPLO cases is just the transpose of RFP A above. So 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 then consider Rectangular Full Packed (RFP) 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

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 the 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 the transpose of the last two columns of AP lower. 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 = 'T'. RFP A in both UPLO cases is just the 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 `stftri` ✨

subroutine stftri (character TRANSR, character UPLO, character DIAG, integer
    N, real, dimension( 0: * ) A, integer INFO)

STFTRI 💖

🎯 Purpose 🎯

STFTRI computes the inverse of a triangular matrix A stored in RFP format.

This is a Level 3 BLAS version of the algorithm. Slay. 💅

🧾 Parameters 🧾

TRANSR — CHARACTER*1. = 'N': the Normal TRANSR of RFP A is stored; = 'T': the Transpose TRANSR of RFP A is stored.
UPLO — CHARACTER*1. = 'U': A is upper triangular; = 'L': A is lower triangular.
DIAG — CHARACTER*1. = 'N': A is non-unit triangular; = 'U': A is unit triangular.
N — INTEGER. The order of the matrix A. N >= 0.
A — REAL array, dimension (NT); NT=N*(N+1)/2. On entry, the triangular factor of a Hermitian Positive Definite 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 = 'T' then RFP is the 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 = 'T'. 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 — 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.

Bestie. If you get INFO > 0 it's giving singular matrix — A(i,i) is exactly zero and that inverse is not computable. No cap. 😭

👑 Author 👑

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

🔍 Further Details 🔍

We first consider Rectangular Full Packed (RFP) 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 = 'T'. RFP A in both UPLO cases is just the 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 then consider Rectangular Full Packed (RFP) 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 = 'T'. RFP A in both UPLO cases is just the 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 `stfttp` ✨

subroutine stfttp (character TRANSR, character UPLO, integer N, real,
    dimension( 0: * ) ARF, real, dimension( 0: * ) AP, integer INFO)

STFTTP copies a triangular matrix from the rectangular full packed format (TF) to the standard packed format (TP). 💖

🎯 Purpose 🎯

STFTTP copies a triangular matrix A from rectangular full packed format (TF) to standard packed format (TP). Iconic behaviour honestly. ✨

🧾 Parameters 🧾

TRANSR
TRANSR — CHARACTER*1, and it's literally just telling you which flavour of packing ARF is serving 💅
- = 'N': ARF is in Normal format;
- = 'T': ARF is in Transpose format;
UPLO — also CHARACTER*1, bestie, it picks a side 🫶
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — N is INTEGER. It's the order of the matrix A, and N >= 0, no exceptions periodt.
ARF — ARF is REAL array, dimension ( N*(N+1)/2 ). On entry this is holding the upper or lower triangular matrix A stored in RFP format. For the full tea on that, see the Notes below 🍵✨
AP — AP is REAL array, dimension ( N*(N+1)/2 ). On exit this is your upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A lives 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)*(2n-j)/2) = A(i,j) for j<=i<=n.
INFO — INFO is 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.

🧠 Further Details:

Okay so first, Rectangular Full Packed (RFP) Format when N is even. Here's the example with N = 6 👇

             We first consider Rectangular Full Packed (RFP) 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
             the 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
             the transpose of the last three columns of AP lower.
             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 = 'T'. RFP A in both UPLO cases is just the
             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

Then we do Rectangular Full Packed (RFP) Format when N is odd 🌸 example with N = 5:

             We then consider Rectangular Full Packed (RFP) 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
             the 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
             the transpose of the last two columns of AP lower.
             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 = 'T'. RFP A in both UPLO cases is just the
             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 `stfttr`

subroutine stfttr (character TRANSR, character UPLO, integer N, real,
    dimension( 0: * ) ARF, real, dimension( 0: lda-1, 0: * ) A, integer LDA,
    integer INFO)

STFTTR copies a triangular matrix from the rectangular full packed format (TF) to the standard full format (TR).

✨ Purpose:

STFTTR copies a triangular matrix A from rectangular full packed format (TF) to standard full format (TR).

🎀 Parameters

TRANSR — CHARACTER*1, same energy as before 💫
- = 'N': ARF is in Normal format;
- = 'T': ARF is in Transpose format.
UPLO — CHARACTER*1, pick your side bestie 🫶
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — N is INTEGER. The order of the matrices ARF and A. N >= 0, always.
ARF — ARF is REAL array, dimension (N*(N+1)/2). On entry, the upper (if UPLO = 'U') or lower (if UPLO = 'L') matrix A in RFP format. See the 'Notes' below for more details 👀
A — A is REAL 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 — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
INFO — INFO is INTEGER, the final vibe check 😌
- = 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:

Starting with Rectangular Full Packed (RFP) Format when N is even — example with N = 6 👇

             We first consider Rectangular Full Packed (RFP) 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
             the 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
             the transpose of the last three columns of AP lower.
             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 = 'T'. RFP A in both UPLO cases is just the
             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

And now Rectangular Full Packed (RFP) Format when N is odd — example with N = 5 🌸

             We then consider Rectangular Full Packed (RFP) 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
             the 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
             the transpose of the last two columns of AP lower.
             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 = 'T'. RFP A in both UPLO cases is just the
             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 `stgsen`

subroutine stgsen (integer IJOB, logical WANTQ, logical WANTZ, logical,
    dimension( * ) SELECT, integer N, real, dimension( lda, * ) A, integer
    LDA, real, dimension( ldb, * ) B, integer LDB, real, dimension( * )
    ALPHAR, real, dimension( * ) ALPHAI, real, dimension( * ) BETA, real,
    dimension( ldq, * ) Q, integer LDQ, real, dimension( ldz, * ) Z, integer
    LDZ, integer M, real PL, real PR, real, dimension( * ) DIF, real,
    dimension( * ) WORK, integer LWORK, integer, dimension( * ) IWORK,
    integer LIWORK, integer INFO)

STGSEN 🔥

🎯 Purpose:

okay so what does it actually do, bestie 👀

STGSEN reorders the generalized real Schur decomposition of a real matrix pair <code>(A, B)</code> — think of it like the orthonormal equivalence transformation <code>QT * (A, B) * Z</code> — so that a selected cluster of eigenvalues shows up in the leading diagonal blocks of the upper quasi-triangular matrix A and the upper triangular B. The leading columns of Q and Z form orthonormal bases of the corresponding left and right eigenspaces (aka deflating subspaces). Bestie, (A, B) **has to be in generalized real Schur canonical form (as returned by SGGES), meaning A is block upper triangular with 1-by-1 and 2-by-2 diagonal blocks, and B is upper triangular. No exceptions, fr fr.

STGSEN also computes the generalized eigenvalues

            w(j) = (ALPHAR(j) + i*ALPHAI(j))/BETA(j)

of the reordered matrix pair (A, B). 💅

Optionally, STGSEN computes the estimates of reciprocal condition numbers for eigenvalues and eigenspaces. Those 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, respectively, plus the norms of 'projections' onto the left and right eigenspaces with respect to the selected cluster in the (1,1)-block. ✨

Parameters 🎀

IJOB — IJOB is INTEGER. It 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. Bare minimum, lowkey iconic.
- =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. 💀 that's a lot of math.
- =4: Compute PL, PR and DIF (i.e. 0, 1 and 2 above): economic version to get it all. Bestie this is the "I want everything but make it affordable" option.
- =5: Compute PL, PR and DIF (i.e. 0, 1 and 3 above)
WANTQ — WANTQ is LOGICAL.
- .TRUE. : update the left transformation matrix Q;
- .FALSE.: do not update Q.
WANTZ — WANTZ is LOGICAL.
- .TRUE. : update the right transformation matrix Z;
- .FALSE.: do not update Z.
SELECT — SELECT is LOGICAL array, dimension (N). SELECT specifies the eigenvalues in the selected cluster. To select a real eigenvalue w(j), SELECT(j) must be set to .TRUE.. To select a complex conjugate pair of eigenvalues w(j) and w(j+1), corresponding to a 2-by-2 diagonal block, either SELECT(j) or SELECT(j+1) or both must be set to .TRUE. — a complex conjugate pair of eigenvalues must be either both included in the cluster or both excluded. No splitting up the couple, they're a package deal. 🫶
N — N is INTEGER. The order of the matrices A and B. N >= 0.
A — A is REAL array, dimension (LDA,N). On entry, the upper quasi-triangular matrix A, with (A, B) in generalized real Schur canonical form. On exit, A is overwritten by the reordered matrix A. She's changed, but it's a glow up. ✨
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — B is REAL array, dimension (LDB,N). On entry, the upper triangular matrix B, with (A, B) in generalized real Schur canonical form. On exit, B is overwritten by the reordered matrix B.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
ALPHAR — ALPHAR is REAL array, dimension (N)
ALPHAI — ALPHAI is REAL array, dimension (N)
BETA — BETA is REAL array, dimension (N)

On exit, (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will be the generalized eigenvalues. ALPHAR(j) + ALPHAI(j)*i and BETA(j),j=1,...,N are the diagonals of the complex Schur form (S,T) that would result if the 2-by-2 diagonal blocks of the real generalized Schur form of (A,B) were further reduced to triangular form using complex unitary transformations. If ALPHAI(j) is zero, then the j-th eigenvalue is real; if positive, then the j-th and (j+1)-st eigenvalues are a complex conjugate pair, with ALPHAI(j+1) negative. 🦋

Q — Q is REAL 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 orthogonal 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. (She's not even in the group chat. 🙈)
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= 1; and if WANTQ = .TRUE., LDQ >= N.
Z — Z is REAL 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 orthogonal 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 — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= 1; If WANTZ = .TRUE., LDZ >= N.
M — M is INTEGER. The dimension of the specified pair of left and right eigenspaces (deflating subspaces). 0 <= M <= N.
PL — PL is REAL
PR — PR is REAL

If IJOB = 1, 4 or 5, PL, PR are lower bounds on the reciprocal of the norm of 'projections' onto left and right eigenspaces 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 and PR are not referenced. 👑

DIF — DIF is 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. If M = 0 or N, DIF(1:2) = F-norm([A, B]). If IJOB = 0 or 1, DIF is not referenced.
WORK — WORK is REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. The little receipt at the front, iykyk. 🧾
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= 4*N+16. If IJOB = 1, 2 or 4, LWORK >= MAX(4*N+16, 2*M*(N-M)). If IJOB = 3 or 5, LWORK >= MAX(4*N+16, 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 — IWORK is INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK.
LIWORK — LIWORK is INTEGER. The dimension of the array IWORK. LIWORK >= 1. If IJOB = 1, 2 or 4, LIWORK >= N+6. If IJOB = 3 or 5, LIWORK >= MAX(2*M*(N-M), N+6).

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.
- =0: Successful exit. Slay. 🎉
- <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. 💀 proceed with caution bestie.

Author 🌸

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details: 🔥

STGSEN first collects the selected eigenvalues by computing orthogonal 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**T*(A, B)*W = (A11 A12) (B11 B12) n1
                                         ( 0  A22),( 0  B22) n2
                                           n1  n2    n1  n2

where N = n1+n2 and U**T means the 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**T, then the reordered generalized real Schur form of (C, D) is given by

                      (C, D) = (Q*U)*(U**T*(A, B)*W)*(Z*W)**T,

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.). It's giving very "pass the transformation along the group chat" energy. 💅

Note that if the selected eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering. ⚠️ Not a bug, just the math being dramatic.

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

and Zu is literally just this whole block situation, bestie:

                  Zu = [ kron(In2, A11)  -kron(A22**T, In1) ]
                       [ kron(In2, B11)  -kron(B22**T, In1) ].

Here, Inx is the identity matrix of size nx and A22**T is the transpose of A22. kron(X, Y) is the Kronecker product between the matrices X and Y. Yes, Kronecker. Iconic name, iconic math. 🎀

When DIF(2) is small, small changes in (A, B) can cause large changes in the deflating subspace. Like, one tiny nudge and the whole vibe shifts. 💀 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. No cap.

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 which 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 SLATDF), then the parameter IDIFJB (see below) should be changed from 3 to 4 (routine SLATDF (IJOB = 2 will be used)). See STGSYL for more details.

✨ Contributors ✨

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden. Absolute legends, honestly. 👑

✨ 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 `stgsja` 🌈

subroutine stgsja (character JOBU, character JOBV, character JOBQ, integer
    M, integer P, integer N, integer K, integer L, real, dimension( lda, * )
    A, integer LDA, real, dimension( ldb, * ) B, integer LDB, real TOLA,
    real TOLB, real, dimension( * ) ALPHA, real, dimension( * ) BETA, real,
    dimension( ldu, * ) U, integer LDU, real, dimension( ldv, * ) V, integer
    LDV, real, dimension( ldq, * ) Q, integer LDQ, real, dimension( * )
    WORK, integer NCYCLE, integer INFO)

STGSJA

✨ Purpose ✨

STGSJA computes the generalized singular value decomposition (GSVD) of two real upper triangular (or trapezoidal) matrices A and B. It's giving decomposition but make it generalized. 💅

On entry, it is assumed that matrices A and B have the following forms, which may be obtained by the preprocessing subroutine SGGSVP 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**T *A*Q = D1*( 0 R ),    V**T *B*Q = D2*( 0 R ),

where U, V and Q are orthogonal 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 ) is stored in A(1:M, N-K-L+1:N) and R33 is stored
    (  0  R22 R23 )
in B(M-K+1:L,N+M-K-L+1:N) on exit.

The computation of the orthogonal 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. Your choice, bestie, live your truth. 🦋

✨ Parameters ✨

JOBU — JOBU is CHARACTER*1
- = 'U': U must contain an orthogonal matrix U1 on entry, and the product U1*U is returned;
- = 'I': U is initialized to the unit matrix, and the orthogonal matrix U is returned;
- = 'N': U is not computed.
JOBV — JOBV is CHARACTER*1
- = 'V': V must contain an orthogonal matrix V1 on entry, and the product V1*V is returned;
- = 'I': V is initialized to the unit matrix, and the orthogonal matrix V is returned;
- = 'N': V is not computed.
JOBQ — JOBQ is CHARACTER*1
- = 'Q': Q must contain an orthogonal matrix Q1 on entry, and the product Q1*Q is returned;
- = 'I': Q is initialized to the unit matrix, and the orthogonal 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 STGSJA. See Further Details.

A — A is REAL 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 REAL 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 and
BETA(K+L+1:N)  = 0.

U
U — it's a REAL array, dimension (LDU,M). So on entry, if JOBU = 'U', bestie, U has to contain a matrix U1 (usually the orthogonal matrix that SGGSVP handed back). On exit? If JOBU = 'I', then U contains the orthogonal matrix U. If JOBU = 'U', U contains the product U1*U. And if JOBU = 'N', then U is literally not referenced, she's off the clock. 💅
LDU — LDU is INTEGER, the leading dimension of the array U. So LDU >= max(1,M) if JOBU = 'U'; LDU >= 1 otherwise. No cap. 🫶
V — V is REAL array, dimension (LDV,P). On entry, if JOBV = 'V', then V must contain a matrix V1 (usually the orthogonal matrix returned by SGGSVP). On exit, if JOBV = 'I', V contains the orthogonal matrix V; if JOBV = 'V', V contains the product V1*V. If JOBV = 'N', V is not referenced. periodt.
LDV — LDV is INTEGER, the leading dimension of the array V. LDV >= max(1,P) if JOBV = 'V'; LDV >= 1 otherwise. ✨
Q — Q is REAL array, dimension (LDQ,N). On entry, if JOBQ = 'Q', Q must contain a matrix Q1 (usually the orthogonal matrix returned by SGGSVP). On exit, if JOBQ = 'I', Q contains the orthogonal matrix Q; if JOBQ = 'Q', Q contains the product Q1*Q. If JOBQ = 'N', Q is not referenced. iconic behaviour honestly. 💖
LDQ — LDQ is INTEGER, the leading dimension of the array Q. LDQ >= max(1,N) if JOBQ = 'Q'; LDQ >= 1 otherwise.
WORK — WORK is REAL array, dimension (2*N).
NCYCLE — NCYCLE is INTEGER. It's the number of cycles required for convergence. Like, how many laps she needed to lock in. 🏃‍♀️
INFO — INFO is INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value.
- = 1: the procedure does not converge after MAXIT cycles. 😭

🌈 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, no negotiating. 💀

🎀 Author 🎀

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

🦋 Further Details: 🦋

STGSJA essentially uses a variant of Kogbetliantz algorithm to reduce min(L,M-K)-by-L triangular (or trapezoidal) matrix A23 and L-by-L matrix B13 to the form:

          U1**T *A13*Q1 = C1*R1; V1**T *B13*Q1 = S1*R1,

where U1, V1 and Q1 are orthogonal matrix, and Z**T is the transpose of Z. C1 and S1 are diagonal matrices satisfying

               C1**2 + S1**2 = I,

and R1 is an L-by-L nonsingular upper triangular matrix.

🌸 subroutine stgsna 🌸

subroutine stgsna (character JOB, character HOWMNY, logical, dimension( * )
    SELECT, integer N, real, dimension( lda, * ) A, integer LDA, real,
    dimension( ldb, * ) B, integer LDB, real, dimension( ldvl, * ) VL,
    integer LDVL, real, dimension( ldvr, * ) VR, integer LDVR, real,
    dimension( * ) S, real, dimension( * ) DIF, integer MM, integer M, real,
    dimension( * ) WORK, integer LWORK, integer, dimension( * ) IWORK,
    integer INFO)

STGSNA — say hi bestie 👋

💜 Purpose: 💜

STGSNA estimates reciprocal condition numbers for specified eigenvalues and/or eigenvectors of a matrix pair (A, B) in generalized real Schur canonical form (or of any matrix pair (Q*A*Z**T, Q*B*Z**T) with orthogonal matrices Q and Z, where Z**T denotes the transpose of Z.

(A, B) must be in generalized real Schur form (as returned by SGGES), i.e. A is block upper triangular with 1-by-1 and 2-by-2 diagonal blocks. B is upper triangular. no cap. 👑

✨ Parameters ✨

JOB — JOB is 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 is giving main character energy. 💅
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 eigenpair corresponding to a real eigenvalue w(j), SELECT(j) must be set to .TRUE.. To select condition numbers corresponding to a complex conjugate pair of eigenvalues w(j) and w(j+1), either SELECT(j) or SELECT(j+1) or both, must be set to .TRUE.. If HOWMNY = 'A', SELECT is not referenced. she's simply not in the group chat for that one. 🙈
N — N is INTEGER. The order of the square matrix pair (A, B). N >= 0.
A — A is REAL array, dimension (LDA,N). The upper quasi-triangular matrix A in the pair (A,B).
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — B is REAL array, dimension (LDB,N). The upper triangular matrix B in the pair (A,B).
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
VL — VL is REAL array, dimension (LDVL,M). If JOB = 'E' or 'B', VL must contain 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 STGEVC. If JOB = 'V', VL is not referenced. 💜
LDVL — LDVL is INTEGER. The leading dimension of the array VL. LDVL >= 1. If JOB = 'E' or 'B', LDVL >= N.
VR — VR is REAL array, dimension (LDVR,M). If JOB = 'E' or 'B', VR must contain right eigenvectors of (A, B), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns ov VR, as returned by STGEVC. If JOB = 'V', VR is not referenced. (yes bestie, the original really says "columns ov VR" — we keep it, we don't fix it, that's the rule 🫶)
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= 1. If JOB = 'E' or 'B', LDVR >= N.
S — S is REAL array, dimension (MM). If JOB = 'E' or 'B', the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array. For a complex conjugate pair of eigenvalues two consecutive elements of S are set to the same value. Thus S(j), DIF(j), and the j-th columns of VL and VR all correspond to the same eigenpair (but not in general the j-th eigenpair, unless all eigenpairs are selected). If JOB = 'V', S is not referenced. ⭐
DIF — DIF is REAL array, dimension (MM). If JOB = 'V' or 'B', the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. For a complex eigenvector two consecutive elements of DIF are set to the same value. If the eigenvalues cannot be reordered to compute DIF(j), DIF(j) is set to 0; this can only occur when the true value would be very small anyway. If JOB = 'E', DIF is not referenced.
MM — MM is INTEGER. The number of elements in the arrays S and DIF. MM >= M.
M — M is INTEGER. The number of elements of the arrays S and DIF used to store the specified condition numbers; for each selected real eigenvalue one element is used, and for each selected complex conjugate pair of eigenvalues, two elements are used. If HOWMNY = 'A', M is set to N.
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. LWORK >= max(1,N). If JOB = 'V' or 'B' LWORK >= 2*N*(N+2)+16.

IWORK — IWORK is INTEGER array, dimension (N + 6). If JOB = 'E', IWORK is not referenced.
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 reciprocal of the condition number of a generalized eigenvalue w = (a, b) is defined as

      S(w) = (|u**TAv|**2 + |u**TBv|**2)**(1/2) / (norm(u)*norm(v))

where u and v are the left and right 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 (= u**TAv/u**TBv) of the matrix pair (A, B). If both a and b equal zero, then (A B) is singular and S(I) = -1 is returned. 😭

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.

The reciprocal of the condition number DIF(i) of right eigenvector u and left eigenvector v corresponding to the generalized eigenvalue w is defined as follows:

a) If the i-th eigenvalue w = (a,b) is real

Suppose U and V are orthogonal transformations such that

so yeah, back to the math, bestie. we were saying:

                         U**T*(A, B)*V  = (S, T) = ( a   *  ) ( b  *  )  1
                                                   ( 0  S22 ),( 0 T22 )  n-1
                                                     1  n-1     1 n-1

Then the reciprocal condition number DIF(i) is

                           Difl((a, b), (S22, T22)) = sigma-min( Zl ),

where sigma-min(Zl) denotes the smallest singular value of the 2(n-1)-by-2(n-1) matrix

                    Zl = [ kron(a, In-1)  -kron(1, S22) ]
                         [ kron(b, In-1)  -kron(1, T22) ] .

Here In-1 is the identity matrix of size n-1. kron(X, Y) is the Kronecker product between the matrices X and Y. iykyk. ✨

Note that if the default method for computing DIF(i) is wanted (see SLATDF), then the parameter DIFDRI (see below) should be changed from 3 to 4 (routine SLATDF(IJOB = 2 will be used)). See STGSYL for more details. no cap.

b) If the i-th and (i+1)-th eigenvalues are complex conjugate pair, bestie,

Suppose U and V are orthogonal transformations such that

                         U**T*(A, B)*V = (S, T) = ( S11  *   ) ( T11  *  )  2
                                                  ( 0    S22 ),( 0    T22) n-2
                                                    2    n-2     2    n-2

and (S11, T11) corresponds to the complex conjugate eigenvalue pair (w, conjg(w)). There exist unitary matrices U1 and V1 such that

                  U1**T*S11*V1 = ( s11 s12 ) and U1**T*T11*V1 = ( t11 t12 )
                                 (  0  s22 )                    (  0  t22 )

where the generalized eigenvalues w = s11/t11 and conjg(w) = s22/t22.

Then the reciprocal condition number DIF(i) is bounded by

                    min( d1, max( 1, |real(s11)/real(s22)| )*d2 )

where, d1 = Difl((s11, t11), (s22, t22)) = sigma-min(Z1), where Z1 is the complex 2-by-2 matrix

                         Z1 =  [ s11  -s22 ]
                               [ t11  -t22 ],

This is done by computing (using real arithmetic) the roots of the characteristical polynomial det(Z1**T * Z1 - lambda I), where Z1**T denotes the transpose of Z1 and det(X) denotes the determinant of X. slay. 💅

and d2 is an upper bound on Difl((S11, T11), (S22, T22)), i.e. an upper bound on sigma-min(Z2), where Z2 is (2n-2)-by-(2n-2)

                         Z2 = [ kron(S11**T, In-2)  -kron(I2, S22) ]
                              [ kron(T11**T, In-2)  -kron(I2, T22) ]

Note that if the default method for computing DIF is wanted (see SLATDF), then the parameter DIFDRI (see below) should be changed from 3 to 4 (routine SLATDF(IJOB = 2 will be used)). See STGSYL for more details. periodt.

For each eigenvalue/vector specified by SELECT, DIF stores a Frobenius norm-based estimate of Difl.

An approximate error bound for the i-th 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.

References: 📚

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.
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.
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 stpcon (character NORM, character UPLO, character DIAG, integer N, real, dimension( * ) AP, real RCOND, real, dimension( * ) WORK, integer, dimension( * ) IWORK, integer INFO) 🌸

STPCON

Purpose:

STPCON estimates the reciprocal of the condition number of a packed triangular 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)) ).

it's giving condition number energy, bestie. 💅

Parameters

okay so the params, no skips:

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 — is CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — is CHARACTER*1:
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — is INTEGER. The order of the matrix A. N >= 0.
AP — is REAL 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 — is REAL. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(norm(A) * norm(inv(A))).
WORK — is REAL array, dimension (3*N).
IWORK — is INTEGER array, dimension (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.

🌟 subroutine stpmqrt (character SIDE, character TRANS, integer M, integer N, integer K, integer L, integer NB, real, dimension( ldv, * ) V, integer LDV, real, dimension( ldt, * ) T, integer LDT, real, dimension( lda, * ) A, integer LDA, real, dimension( ldb, * ) B, integer LDB, real, dimension( * ) WORK, integer INFO) 🌟

STPMQRT

Purpose:

STPMQRT applies a real orthogonal matrix Q obtained from a 'triangular-pentagonal' real block reflector H to a general real matrix C, which consists of two blocks A and B. it's giving triangular-pentagonal realness. ✨

Parameters

SIDE — is CHARACTER*1:
- = 'L': apply Q or Q^T from the Left;
- = 'R': apply Q or Q^T from the Right.
TRANS — is CHARACTER*1:
- = 'N': No transpose, apply Q;
- = 'T': Transpose, apply Q^T.
M — is INTEGER. The number of rows of the matrix B. M >= 0.
N — is INTEGER. The number of columns of the matrix B. N >= 0.
K — is INTEGER. The number of elementary reflectors whose product defines the matrix Q.
L — is INTEGER. The order of the trapezoidal part of V. K >= L >= 0. See Further Details.
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.
V — is REAL 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 — is INTEGER. The leading dimension of the array V.
- If SIDE = 'L', LDV >= max(1,M);
- if SIDE = 'R', LDV >= max(1,N).
T — is REAL array, dimension (LDT,K). The upper triangular factors of the block reflectors as returned by CTPQRT, stored as a NB-by-K matrix.
LDT — is INTEGER. The leading dimension of the array T. LDT >= NB.
A — is REAL 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^T*C or C*Q or C*Q^T. See Further Details.
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 — is REAL 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^T*C or C*Q or C*Q^T. See Further Details.
LDB — is INTEGER. The leading dimension of the array B. LDB >= max(1,M).
WORK — is REAL array. The dimension of WORK is N*NB if SIDE = 'L', or M*NB if SIDE = 'R'.
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].

okay so the size of the trapezoidal block V2 is fully decided by the parameter L, where 0 <= L <= K. And V2 is upper trapezoidal, meaning it's literally the first L rows of a K-by-K upper triangular matrix. If L=K, then V2 is upper triangular, slay. If L=0, there's no trapezoidal block at all, which means V = V1 is just plain rectangular. no cap. 💅

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 real 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='T' and SIDE='L', C is on exit replaced with Q^T * C.
If TRANS='N' and SIDE='R', C is on exit replaced with C * Q.
If TRANS='T' and SIDE='R', C is on exit replaced with C * Q^T.

🌸 `subroutine stpqrt` (STPQRT)

subroutine stpqrt (integer M, integer N, integer L, integer NB, real,
    dimension( lda, * ) A, integer LDA, real, dimension( ldb, * ) B, integer
    LDB, real, dimension( ldt, * ) T, integer LDT, real, dimension( * )
    WORK, integer INFO)

STPQRT ✨

🎯 Purpose

STPQRT computes a blocked QR factorization of a real '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 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 REAL 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 REAL 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 REAL 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 REAL array, dimension (NB*N).
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. rude, but okay

✍️ Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details

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 an 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 stpqrt2` (STPQRT2)

subroutine stpqrt2 (integer M, integer N, integer L, real, dimension( lda, * )
    A, integer LDA, real, dimension( ldb, * ) B, integer LDB, real,
    dimension( ldt, * ) T, integer LDT, integer INFO)

STPQRT2 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

STPQRT2 computes a QR factorization of a real '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 REAL 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 REAL 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 REAL 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. same energy as before ngl

✍️ Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details

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 stprfs` (STPRFS)

subroutine stprfs (character UPLO, character TRANS, character DIAG, integer
    N, integer NRHS, real, dimension( * ) AP, real, dimension( ldb, * ) B,
    integer LDB, real, dimension( ldx, * ) X, integer LDX, real, dimension(
    * ) FERR, real, dimension( * ) BERR, real, dimension( * ) WORK, integer,
    dimension( * ) IWORK, integer INFO)

STPRFS 🌸

🎯 Purpose

STPRFS 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 STPTRS or some other means before entering this routine. STPRFS does not do iterative refinement because doing so cannot improve the backward error. so like, don't ask it to, it literally can't help. 😭

📋 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 = 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 — NRHS is INTEGER. bestie this is just how many right hand sides you got, i.e. the number of columns of the matrices B and X. and it's gotta be NRHS >= 0, no negativity allowed 💅
AP — AP is REAL array, dimension (N*(N+1)/2). it's the upper or lower triangular matrix A, packed columnwise into one lil linear array. here's the tea on how the j-th column of A lives inside AP:
- if UPLO = 'U', then AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', then AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.

and if DIAG = 'U', the diagonal elements of A are not referenced and are just assumed to be 1. so don't even bother storing them, she's unit, she's built different ✨

B — B is REAL array, dimension (LDB,NRHS). it's the right hand side matrix B. the moment. the icon 🫶
LDB — LDB is INTEGER. the leading dimension of the array B. rule of law: LDB >= max(1,N). periodt.
X — X is REAL array, dimension (LDX,NRHS). the solution matrix X, aka the answer we been waiting for 💖
LDX — LDX is INTEGER. the leading dimension of the array X. also gotta obey LDX >= max(1,N), no exceptions queen 👑
FERR — FERR is 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). so 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). and the estimate is exactly as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. lowkey generous, highkey 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. she's measuring how close to perfection we got 💯
WORK — WORK is REAL array, dimension (3*N). scratch space bestie, don't touch 🎀
IWORK — IWORK is INTEGER array, dimension (N). more scratch space, integer flavored.
INFO — INFO is INTEGER. the vibe check at the end:
- = 0: successful exit, we ate 🔥
- < 0: if INFO = -i, the i-th argument had an illegal value. somebody messed up the input, not me 💀

👑 Author

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

🌸 `subroutine stptri (character UPLO, character DIAG, integer N, real, dimension( * ) AP, integer INFO)`

STPTRI

Purpose:

STPTRI computes the inverse of a real upper or lower triangular matrix A stored in packed format. she flips the whole thing inside out and hands it back, same packaging, brand new energy ✨

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. and N >= 0, always.
AP — AP is REAL array, dimension (N*(N+1)/2). on entry, it's the upper or lower triangular matrix A, stored 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.

see below for further details bestie, there's a whole tutorial 💅

on exit, AP holds the (triangular) inverse of the original matrix, in the same packed storage format. glow up complete 🦋

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. that's a hard no, can't invert what has no inverse 😭

👑 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 stptrs (character UPLO, character TRANS, character DIAG, integer N, integer NRHS, real, dimension( * ) AP, real, dimension( ldb, * ) B, integer LDB, integer INFO)`

STPTRS

Purpose:

STPTRS solves a triangular system of the form

A * X = B  or  A**T * X = B,

where A is a triangular matrix of order N stored in packed format, and B is an N-by-NRHS matrix. and yes, a check is made to verify 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 = 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 REAL 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 REAL array, dimension (LDB,NRHS). on entry, it's the right hand side matrix B. on exit, if INFO = 0, it's the solution matrix X. character development 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. we simply did not compute them. no solution for you 💀

👑 Author

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

🎀 `subroutine stpttf (character TRANSR, character UPLO, integer N, real, dimension( 0: * ) AP, real, dimension( 0: * ) ARF, integer INFO)`

STPTTF

STPTTF copies a triangular matrix from the standard packed format (TP) to the rectangular full packed format (TF). it's a whole format migration, she's moving apartments and keeping every single element 🌸

Purpose:

STPTTF 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;
- = 'T': 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 REAL 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 REAL 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. and bestie you will want to see the Notes, they're giving diagram 💅
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 first we consider Rectangular Full Packed (RFP) 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 the 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 the transpose of the last three columns of AP lower.

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 = 'T'. RFP A in both UPLO cases is just the 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 then consider Rectangular Full Packed (RFP) 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

okay so let TRANSR = 'N' and RFP holds AP like this, bestie: for UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper, and the lower triangle A(3:4,0:1) consists of the 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, and the upper triangle A(0:1,1:2) consists of the transpose of the last two columns of AP lower. 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 = 'T'. RFP A in both UPLO cases is just the 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 `stpttr` 🌸

subroutine stpttr (character UPLO, integer N, real, dimension( * ) AP, real,
    dimension( lda, * ) A, integer LDA, integer INFO)

STPTTR copies a triangular matrix from the standard packed format (TP) to the standard full format (TR). it unpacks the tea, no cap. 💅

✨ Purpose

STPTTR 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 is REAL 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.
A — A is REAL array, dimension ( LDA, N ). On exit, 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 — 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.

💖 Author

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

🔥 subroutine `strcon` 🔥

subroutine strcon (character NORM, character UPLO, character DIAG, integer
    N, real, dimension( lda, * ) A, integer LDA, real RCOND, real,
    dimension( * ) WORK, integer, dimension( * ) IWORK, integer INFO)

STRCON. it's giving condition-number math and honestly it ate. 🫶

✨ Purpose

STRCON estimates the reciprocal of the condition number of a triangular 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.
A — A is REAL 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).
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 REAL array, dimension (3*N).
IWORK — IWORK is INTEGER 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 `strevc` 👑

subroutine strevc (character SIDE, character HOWMNY, logical, dimension( * )
    SELECT, integer N, real, dimension( ldt, * ) T, integer LDT, real,
    dimension( ldvl, * ) VL, integer LDVL, real, dimension( ldvr, * ) VR,
    integer LDVR, integer MM, integer M, real, dimension( * ) WORK, integer
    INFO)

STREVC. main character energy, bestie. 💀✨

✨ Purpose

STREVC computes some or all of the right and/or left eigenvectors of a real upper quasi-triangular matrix T. Matrices of this type are produced by the Schur factorization of a real general matrix: A = Q*T*Q**T, as computed by SHSEQR.

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 y. The eigenvalues are not input to this routine, but are read directly from the diagonal blocks of T.

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 orthogonal 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. iconic tbh. 🌈

🎀 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 by the matrices 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. If w(j) is a real eigenvalue, the corresponding real eigenvector is computed if SELECT(j) is .TRUE.. If w(j) and w(j+1) are the real and imaginary parts of a complex eigenvalue, the corresponding complex eigenvector is computed if either SELECT(j) or SELECT(j+1) is .TRUE., and on exit SELECT(j) is set to .TRUE. and SELECT(j+1) is set to .FALSE.. Not referenced if HOWMNY = 'A' or 'B'.
N — N is INTEGER. The order of the matrix T. N >= 0.
T — T is REAL array, dimension (LDT,N). The upper quasi-triangular matrix T in Schur canonical form.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N).
VL — VL is REAL 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 orthogonal matrix Q of Schur vectors returned by SHSEQR). 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. A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part, and the second the imaginary part. 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 — REAL array, dimension (LDVR,MM). On entry, if SIDE = 'R' or 'B' and HOWMNY = 'B', then VR has to already contain an N-by-N matrix Q (usually the orthogonal matrix Q of Schur vectors that SHSEQR handed back 💫). 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 that SELECT picked out, stored consecutively in the columns of VR, in the same order as their eigenvalues.

A complex eigenvector that matches a complex eigenvalue gets stored in two consecutive columns — first column is the real part, second column is the imaginary part. And it is not referenced if SIDE = 'L', so don't worry about it then bestie 🫶.

LDVR — INTEGER. The leading dimension of the array VR. LDVR >= 1, and if SIDE = 'R' or 'B', then LDVR >= N.
MM — INTEGER. The number of columns in the arrays VL and/or VR. MM >= M.
M — INTEGER. The number of columns in the arrays VL and/or VR that are actually used to store the eigenvectors. If HOWMNY = 'A' or 'B', M is set to N. Each selected real eigenvector takes up one column, and each selected complex eigenvector takes up two columns. 💅
WORK — REAL array, dimension (3*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.

Further Details 🔥

The algorithm used in this program is basically backward (forward) substitution, with scaling to make the code robust against possible overflow. Ngl, that scaling is doing the lord's work.

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|. Periodt. 💖

🌈 STREVC3 🌈

subroutine strevc3 (character SIDE, character HOWMNY, logical, dimension( *
    ) SELECT, integer N, real, dimension( ldt, * ) T, integer LDT, real,
    dimension( ldvl, * ) VL, integer LDVL, real, dimension( ldvr, * ) VR,
    integer LDVR, integer MM, integer M, real, dimension( * ) WORK, integer
    LWORK, integer INFO)

STREVC3 — okay so this one is the Level 3 BLAS glow-up of the whole vibe, and we are obsessed. 💅✨

Purpose 🦋

STREVC3 computes some or all of the right and/or left eigenvectors of a real upper quasi-triangular matrix T. Matrices of this type are produced by the Schur factorization of a real general matrix: A = Q*T*Q**T, as computed by SHSEQR.

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

T*x = w*x,     (y**T)*T = w*(y**T)

where y**T denotes the transpose of the vector y. The eigenvalues are not input to this routine — they're read directly from the diagonal blocks of T. Slay, self-sufficient king 👑.

And the flex? This uses a Level 3 BLAS version of the back transformation. Main character energy fr fr. 🔥

Parameters 🌟

SIDE — CHARACTER*1. = 'R': compute right eigenvectors only; = 'L': compute left eigenvectors only; = 'B': compute both right and left eigenvectors.
HOWMNY — CHARACTER*1. = 'A': compute all right and/or left eigenvectors; = 'B': compute all right and/or left eigenvectors, backtransformed by the matrices in VR and/or VL; = 'S': compute selected right and/or left eigenvectors, as indicated by the logical array SELECT.
SELECT — LOGICAL array, dimension (N). If HOWMNY = 'S', SELECT specifies the eigenvectors to be computed. If w(j) is a real eigenvalue, the corresponding real eigenvector is computed if SELECT(j) is .TRUE.. If w(j) and w(j+1) are the real and imaginary parts of a complex eigenvalue, the corresponding complex eigenvector is computed if either SELECT(j) or SELECT(j+1) is .TRUE., and on exit SELECT(j) is set to .TRUE. and SELECT(j+1) is set to .FALSE.. Not referenced if HOWMNY = 'A' or 'B'. 💫
N — INTEGER. The order of the matrix T. N >= 0.
T — REAL array, dimension (LDT,N). The upper quasi-triangular matrix T in Schur canonical form.
LDT — INTEGER. The leading dimension of the array T. LDT >= max(1,N).
VL — REAL 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 orthogonal matrix Q of Schur vectors returned by SHSEQR). 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.

A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part, and the second the imaginary part. Not referenced if SIDE = 'R'. 🎀

LDVL — INTEGER. The leading dimension of the array VL. LDVL >= 1, and if SIDE = 'L' or 'B', LDVL >= N.
VR — REAL 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 orthogonal matrix Q of Schur vectors returned by SHSEQR). 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.

A complex eigenvector corresponding to a complex eigenvalue is stored in two consecutive columns, the first holding the real part and the second the imaginary part. Not referenced if SIDE = 'L'. 🦋

LDVR — INTEGER. The leading dimension of the array VR. LDVR >= 1, and if SIDE = 'R' or 'B', LDVR >= N.
MM — INTEGER. The number of columns in the arrays VL and/or VR. MM >= M.
M — 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 real eigenvector occupies one column and each selected complex eigenvector occupies two columns.
WORK — REAL array, dimension (MAX(1,LWORK)).
LWORK — INTEGER. The dimension of array WORK. LWORK >= max(1,3*N). For optimum performance, LWORK >= N + 2*N*NB, where NB is the optimal blocksize. (Yes bestie, we love a performance tip 💅.)

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. Sneaky little shortcut, we stan.

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

🧚 STREXC 🧚

subroutine strexc (character COMPQ, integer N, real, dimension( ldt, * ) T,
    integer LDT, real, dimension( ldq, * ) Q, integer LDQ, integer IFST,
    integer ILST, real, dimension( * ) WORK, integer INFO)

STREXC — the reorder-the-Schur-form girlie. 🎀

Purpose 👑

STREXC reorders the real Schur factorization of a real matrix A = Q*T*Q**T, so that the diagonal block of T with row index IFST is moved to row ILST.

The real Schur form T is reordered by an orthogonal similarity transformation Z**T*T*Z, and optionally the matrix Q of Schur vectors is updated by postmultiplying it with Z.

T must be in Schur canonical form (as returned by SHSEQR), that is, block upper triangular with 1-by-1 and 2-by-2 diagonal blocks; each 2-by-2 diagonal block has its diagonal elements equal and its off-diagonal elements of opposite sign. So specific, so iconic. 💅

Parameters 🌸

COMPQ — CHARACTER*1. = 'V': update the matrix Q of Schur vectors; = 'N': do not update Q.
N — INTEGER. The order of the matrix T. N >= 0. If N == 0, arguments ILST and IFST may be any value. (Free pass, no judgement 🫶.)
T — REAL array, dimension (LDT,N). On entry, the upper quasi-triangular matrix T, in Schur canonical form. On exit, the reordered upper quasi-triangular matrix, again in Schur canonical form.
LDT — INTEGER. The leading dimension of the array T. LDT >= max(1,N).
Q —
Q — Q is REAL array, dimension (LDQ,N). On entry, if COMPQ = 'V', this is the matrix Q of Schur vectors 💅. On exit, if COMPQ = 'V', Q has been postmultiplied by the orthogonal transformation matrix Z which reorders T. If COMPQ = 'N', Q is literally not referenced, bestie, she's off the clock 🙈.
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.

These two specify the reordering of the diagonal blocks of T 👑. The block with row index IFST is moved to row ILST, by a sequence of transpositions between adjacent blocks. On exit, if IFST pointed on entry to the second row of a 2-by-2 block, it is changed to point to the first row; ILST always points to the first row of the block in its final position (which may differ from its input value by +1 or -1). 1 <= IFST <= N; 1 <= ILST <= N.

WORK — WORK is REAL array, dimension (N).
INFO — INFO is INTEGER.
- = 0: successful exit 🌈
- < 0: if INFO = -i, the i-th argument had an illegal value 🚨
- = 1: two adjacent blocks were too close to swap (the problem is very ill-conditioned); T may have been partially reordered, and ILST points to the first row of the current position of the block being moved 💀

Author 🫶

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

`subroutine strrfs` 🦋

subroutine strrfs (character UPLO, character TRANS, character DIAG, integer
    N, integer NRHS, real, dimension( lda, * ) A, integer LDA, real,
    dimension( ldb, * ) B, integer LDB, real, dimension( ldx, * ) X, integer
    LDX, real, dimension( * ) FERR, real, dimension( * ) BERR, real,
    dimension( * ) WORK, integer, dimension( * ) IWORK, integer INFO)

STRRFS 💖

Purpose ✨

STRRFS provides error bounds and backward error estimates for the solution to a system of linear equations with a triangular coefficient matrix, no cap 🎀.

The solution matrix X must be computed by STRTRS or some other means before entering this routine. STRRFS does not do iterative refinement because doing so cannot improve the backward error. Like, it's just not the move, periodt.

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 = 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 REAL 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 REAL 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 REAL 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 REAL array, dimension (3*N).
IWORK — IWORK is INTEGER 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 strsen` 🧚

subroutine strsen (character JOB, character COMPQ, logical, dimension( * )
    SELECT, integer N, real, dimension( ldt, * ) T, integer LDT, real,
    dimension( ldq, * ) Q, integer LDQ, real, dimension( * ) WR, real,
    dimension( * ) WI, integer M, real S, real SEP, real, dimension( * )
    WORK, integer LWORK, integer, dimension( * ) IWORK, integer LIWORK,
    integer INFO)

STRSEN ⭐

Purpose ✨

STRSEN reorders the real Schur factorization of a real matrix A = Q*T*Q**T, so that a selected cluster of eigenvalues appears in the leading diagonal blocks of the upper quasi-triangular matrix T, and the leading columns of Q form an orthonormal basis of the corresponding right invariant subspace. Iconic behaviour honestly 💅.

Optionally the routine computes the reciprocal condition numbers of the cluster of eigenvalues and/or the invariant subspace, if you're feeling fancy.

T must be in Schur canonical form (as returned by SHSEQR), that is, block upper triangular with 1-by-1 and 2-by-2 diagonal blocks; each 2-by-2 diagonal block has its diagonal elements equal and its off-diagonal elements of opposite sign. That's the vibe check it has to pass, fr fr.

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 a real eigenvalue w(j), SELECT(j) must be set to .TRUE.. To select a complex conjugate pair of eigenvalues w(j) and w(j+1), corresponding to a 2-by-2 diagonal block, either SELECT(j) or SELECT(j+1) or both must be set to .TRUE.; a complex conjugate pair of eigenvalues must be either both included in the cluster or both excluded. No splitting them up, they're a package deal 😭🫶.
N — N is INTEGER. The order of the matrix T. N >= 0.
T — T is REAL array, dimension (LDT,N). On entry, the upper quasi-triangular matrix T, in Schur canonical form. On exit, T is overwritten by the reordered matrix T, again in Schur canonical form, with the selected eigenvalues in the leading diagonal blocks 👑.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N).
Q — Q is REAL 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 orthogonal 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 🙈.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= 1; and if COMPQ = 'V', LDQ >= N.
WR — WR is REAL array, dimension (N).
WI — WI is REAL array, dimension (N).

The real and imaginary parts, respectively, of the reordered eigenvalues of T. The eigenvalues are stored in the same order as on the diagonal of T, with WR(i) = T(i,i) and, if T(i:i+1,i:i+1) is a 2-by-2 diagonal block, WI(i) > 0 and WI(i+1) = -WI(i). Note that if a complex eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering 💀 — she's been through something, okay?

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 — 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. Pick your size wisely, bestie:
- If JOB = 'N', LWORK >= max(1,N);
- if JOB = 'E', LWORK >= max(1,M*(N-M));
- if JOB = 'V' or 'B', LWORK >= max(1,2*M*(N-M)).

IWORK — IWORK is INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. 🦋
LIWORK — LIWORK is INTEGER. The dimension of the array IWORK. More size rules, no cap:
- If JOB = 'N' or 'E', LIWORK >= 1;
- if JOB = 'V' or 'B', LIWORK >= max(1,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 — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- = 1: reordering of T failed because some eigenvalues are too close to separate (the problem is very ill-conditioned); T may have been partially reordered, and WR and WI contain the eigenvalues in the same order as in T; S and SEP (if requested) are set to zero. 💀

Author 💖

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

Further Details 🧚

STRSEN first collects the selected eigenvalues by computing an orthogonal 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**T * T * Z = ( T11 T12 ) n1
               (  0  T22 ) n2
                  n1  n2

where N = n1+n2 and Z**T means the transpose of Z. The first n1 columns of Z span the specified invariant subspace of T. Slay.

If T has been obtained from the real Schur factorization of a matrix A = Q*T*Q**T, then the reordered real Schur factorization of A is given by A = (Q*Z)*(Z**T*T*Z)*(Q*Z)**T, and the first n1 columns of Q*Z span the corresponding invariant subspace of A. Periodt.

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). No cap.

An approximate error bound for the computed average of the eigenvalues of T11 is

                                    EPS * norm(T) / S

where EPS is the machine precision. 💅

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

STRSNA 💅

   subroutine strsna (character JOB, character HOWMNY, logical, dimension( * )
       SELECT, integer N, real, dimension( ldt, * ) T, integer LDT, real,
       dimension( ldvl, * ) VL, integer LDVL, real, dimension( ldvr, * ) VR,
       integer LDVR, real, dimension( * ) S, real, dimension( * ) SEP, integer
       MM, integer M, real, dimension( ldwork, * ) WORK, integer LDWORK,
       integer, dimension( * ) IWORK, integer INFO)
       STRSNA

Purpose 🌸

STRSNA estimates reciprocal condition numbers for specified eigenvalues and/or right eigenvectors of a real upper quasi-triangular matrix T (or of any matrix Q*T*Q**T with Q orthogonal).

Parameters 🎀

JOB — JOB is CHARACTER*1. Specifies whether condition numbers are required for eigenvalues (S) or eigenvectors (SEP). Choose your fighter:
- = '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 eigenpair corresponding to a real eigenvalue w(j), SELECT(j) must be set to .TRUE.. To select condition numbers corresponding to a complex conjugate pair of eigenvalues w(j) and w(j+1), either SELECT(j) or SELECT(j+1) or both, must be set to .TRUE.. If HOWMNY = 'A', SELECT is not referenced. 🙈
N — N is INTEGER. The order of the matrix T. N >= 0.
T — T is REAL array, dimension (LDT,N). The upper quasi-triangular matrix T, in Schur canonical form.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N).
VL — VL is REAL array, dimension (LDVL,M). If JOB = 'E' or 'B', VL must contain left eigenvectors of T (or of any Q*T*Q**T with Q orthogonal), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VL, as returned by SHSEIN or STREVC. If JOB = 'V', VL is not referenced.
LDVL — LDVL is INTEGER. The leading dimension of the array VL. LDVL >= 1; and if JOB = 'E' or 'B', LDVL >= N.
VR — VR is REAL array, dimension (LDVR,M). If JOB = 'E' or 'B', VR must contain right eigenvectors of T (or of any Q*T*Q**T with Q orthogonal), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VR, as returned by SHSEIN or STREVC. If JOB = 'V', VR is not referenced.
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= 1; and if JOB = 'E' or 'B', LDVR >= N.
S — S is REAL array, dimension (MM). If JOB = 'E' or 'B', the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array. For a complex conjugate pair of eigenvalues two consecutive elements of S are set to the same value. Thus S(j), SEP(j), and the j-th columns of VL and VR all correspond to the same eigenpair (but not in general the j-th eigenpair, unless all eigenpairs are selected). If JOB = 'V', S is not referenced.
SEP — SEP is REAL array, dimension (MM). If JOB = 'V' or 'B', the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. For a complex eigenvector two consecutive elements of SEP are set to the same value. If the eigenvalues cannot be reordered to compute SEP(j), SEP(j) is set to 0; this can only occur when the true value would be very small anyway. 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.
M — M is INTEGER. The number of elements of the arrays S and/or SEP actually used to store the estimated condition numbers. If HOWMNY = 'A', M is set to N.
WORK — WORK is REAL 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.
IWORK — IWORK is INTEGER array, dimension (2*(N-1)). If JOB = 'E', IWORK is not referenced.
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 reciprocal of the condition number of an eigenvalue lambda is defined as

S(lambda) = |v**T*u| / (norm(u)*norm(v))

where u and v are the right and left eigenvectors of T corresponding to lambda; v**T denotes the 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, 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.

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 the smallest singular value by the reciprocal of an estimate of the one-norm of the inverse of T22 - lambda*I. If n = 1, SEP(1) is defined to be abs(T(1,1)).

An approximate error bound for a computed right eigenvector VR(i) is given by

EPS * norm(T) / SEP(i)

🦋 subroutine `strti2` 🦋

subroutine strti2 (character UPLO, character DIAG, integer N, real,
    dimension( lda, * ) A, integer LDA, integer INFO)

STRTI2 computes the inverse of a triangular matrix (unblocked algorithm). 🫶

🌸 Purpose 🌸

STRTI2 computes the inverse of a real 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 REAL 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 `strtri` 🧚

subroutine strtri (character UPLO, character DIAG, integer N, real,
    dimension( lda, * ) A, integer LDA, integer INFO)

STRTRI 💖

🌸 Purpose 🌸

STRTRI computes the inverse of a real 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 REAL 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.

🚨 bestie listen — if you get INFO > 0, that matrix is singular and there is no inverse to compute. no cap.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🍓 subroutine `strtrs` 🍓

subroutine strtrs (character UPLO, character TRANS, character DIAG, integer
    N, integer NRHS, real, dimension( lda, * ) A, integer LDA, real,
    dimension( ldb, * ) B, integer LDB, integer INFO)

STRTRS 🫶

🌸 Purpose 🌸

STRTRS solves a triangular system of the form

A * X = B  or  A**T * 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 = 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 REAL 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 REAL array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, if INFO = 0, the solution matrix X. ✨
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.

💀 INFO > 0 means a zero showed up on the diagonal, the matrix is singular, and the solutions X were never computed. not a single one. so don't go reading X like it's real.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 subroutine `strttf` 🌈

subroutine strttf (character TRANSR, character UPLO, integer N, real,
    dimension( 0: lda-1, 0: * ) A, integer LDA, real, dimension( 0: * ) ARF,
    integer INFO)

STRTTF copies a triangular matrix from the standard full format (TR) to the rectangular full packed format (TF). 🦋

🌸 Purpose 🌸

STRTTF copies a triangular matrix A from standard full format (TR) to rectangular full packed format (TF) . 💅

🎀 Parameters 🎀

TRANSR — TRANSR is CHARACTER*1.
- = 'N': ARF in Normal form is wanted;
- = 'T': ARF in Transpose form is wanted.
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 REAL 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 — LDA is INTEGER. The leading dimension of the matrix A. LDA >= max(1,N).
ARF — ARF is REAL array, dimension (NT). NT=N*(N+1)/2. On exit, the triangular matrix A in RFP format. ✨
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 Rectangular Full Packed (RFP) 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

okay so continuing the RFP format saga, bestie—we're literally in the middle of the layout tea and it's giving matrix realness. 💅

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

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 the 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 the transpose of the last three columns of AP lower.

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 = 'T'. RFP A in both UPLO cases is just the 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 then consider Rectangular Full Packed (RFP) 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 the 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 the transpose of the last two columns of AP lower.

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 = 'T'. RFP A in both UPLO cases is just the 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 strttp` ✨

subroutine strttp (character UPLO, integer N, real, dimension( lda, * ) A,
       integer LDA, real, dimension( * ) AP, integer INFO)

STRTTP copies a triangular matrix from the standard full format (TR) to the standard packed format (TP). It's literally the format glow-up. ✨

🎀 Purpose 🎀

STRTTP copies a triangular matrix A from full format (TR) to standard packed format (TP).

🌸 Parameters 🌸

UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular.
- = 'L': A is lower triangular.
N — N is INTEGER The order of the matrices AP and A. N >= 0.
A — A is REAL array, dimension (LDA,N) On exit, 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 — LDA is INTEGER The leading dimension of the array A. LDA >= max(1,N).
AP — AP is REAL 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 — 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 stzrzf` ✨

subroutine stzrzf (integer M, integer N, real, dimension( lda, * ) A,
       integer LDA, real, dimension( * ) TAU, real, dimension( * ) WORK,
       integer LWORK, integer INFO)

STZRZF — no cap, this one reduces the M-by-N ( M<=N ) real upper trapezoidal matrix A to upper triangular form by means of orthogonal transformations. It's giving factorization fantasy. 💖

🎀 Purpose 🎀

STZRZF reduces the M-by-N ( M<=N ) real upper trapezoidal matrix A to upper triangular form by means of orthogonal transformations.

The upper trapezoidal matrix A is factored as

A = ( R  0 ) * Z,

where Z is an N-by-N orthogonal matrix and R is an M-by-M upper triangular matrix.

🌸 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 >= M.
A — A is REAL 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 orthogonal 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 REAL array, dimension (M) The scalar factors of the elementary reflectors.
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. 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

👑 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)**T

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 STZRZF, and tau(k) is the kth element of the array TAU.

👑 Author 👑

Generated automatically by Doxygen for LAPACK from the source code.

And that's the tea, bestie! This was LAPACK version 3.11.0, dated Sun Nov 27 2022, for realOTHERcomputational(3). Stay slay! 💅✨

📦 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

realOTHERcomputational(3)

✨ NAME ✨

✨ SYNOPSIS ✨

🌸 Functions 🌸

💖 Detailed Description 💖

🌸 Function Documentation 🌸

🦋 subroutine sbbcsd (...) 🦋

🧠 Internal Parameters 🧠

📚 References 📚

👑 Author 👑

🌸 subroutine sgghd3 🌸

✨ Purpose ✨

🎀 Parameters 🎀

👑 Author 👑

💜 Further Details 💜

🌈 subroutine sgghrd 🌈

✨ Purpose ✨

🎀 Parameters 🎀

N

ILO

IHI

A

LDA

B

LDB

Q

LDQ

Z

LDZ

INFO

Author

Further Details:

SGGQRF

Purpose:

Parameters

N

M

P

A

LDA

TAUA

B

LDB

TAUB

WORK

LWORK

INFO

Author

Further Details:

SGGRQF

Purpose:

Parameters

M

P

N

A

LDA

TAUA

👑 Author

🌟 Further Details

🦋 subroutine sggsvp3

👑 Author

🌟 Further Details

🦋 subroutine sgsvj0

Author

Further Details:

Contributors:

Bugs, Examples and Comments:

🧚 subroutine sgsvj1 🧚

Purpose:

Further Details

Parameters

Author

Contributors:

🦋 subroutine shsein 🦋

Purpose:

Parameters ✨

Author 👑

Further Details 💖

SHSEQR 🦋

🌸 subroutine `sgghd3` 🌸

🌈 subroutine `sgghrd` 🌈

🦋 subroutine `sggsvp3`

🦋 subroutine `sgsvj0`

`Z` 💜

`LDZ` 🎀

`WORK` 🫶

`LWORK` 🔥

`INFO` 😭

subroutine `sla_lin_berr` 🦋

subroutine `sla_wwaddw` 🧚

✨ subroutine `slals0` ✨

🦋 subroutine `slalsa` 🦋

✨ `subroutine slalsd` ✨

🌸 `real function slansf` 🌸

💖 `subroutine slarscl2 (integer M, integer N, real, dimension( * ) D, real, dimension( ldx, * ) X, integer LDX)`

🌸 `subroutine slarz (character SIDE, integer M, integer N, integer L, real, dimension( * ) V, integer INCV, real TAU, real, dimension( ldc, * ) C, integer LDC, real, dimension( * ) WORK)`

🎀 `subroutine slarzt (character DIRECT, character STOREV, integer N, integer K, real, dimension( ldv, * ) V, integer LDV, real, dimension( * ) TAU, real, dimension( ldt, * ) T, integer LDT)`

`subroutine slascl2` 💖

`subroutine slatrz` 🎀