/home/abui...a_2stage.f(3)

👑 /home/abui...a_2stage.f(3) — Library Functions Manual 🦋

okay so bestie, this is a page from the Library Functions Manual, and it's about one (1) very specific file. The star of the show is:

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/ssysv_aa_2stage.f

yes that's the whole path, no I'm not shortening it, she's long and she's iconic 💅

---

✨ NAME ✨

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/ssysv_aa_2stage.f

like literally that's it, that's the name, she's a whole file path and she knows it 🎀

---

🌸 SYNOPSIS 🌸

Functions/Subroutines

subroutine SSYSV_AA_2STAGE (uplo, n, nrhs, a, lda, tb, ltb, ipiv, ipiv2,
    b, ldb, work, lwork, info)
     SSYSV_AA_2STAGE computes the solution to system of linear equations
    A * X = B for SY matrices

---

💜 Function/Subroutine Documentation 💜

subroutine SSYSV_AA_2STAGE (character uplo, integer n, integer nrhs, real,
    dimension( lda, * ) a, integer lda, real, dimension( * ) tb, integer
    ltb, integer, dimension( * ) ipiv, integer, dimension( * ) ipiv2, real,
    dimension( ldb, * ) b, integer ldb, real, dimension( * ) work, integer
    lwork, integer info)

SSYSV_AA_2STAGE computes the solution to system of linear equations A * X = B for SY matrices 🫶

🎯 Purpose

so here's the vibe check on what she actually does 👇

!>
!> SSYSV_AA_2STAGE computes the solution to a real system of
!> linear equations
!>    A * X = B,
!> where A is an N-by-N symmetric matrix and X and B are N-by-NRHS
!> matrices.
!>
!> Aasen's 2-stage algorithm is used to factor A as
!>    A = U**T * T * U,  if UPLO = 'U', or
!>    A = L * T * L**T,  if UPLO = 'L',
!> where U (or L) is a product of permutation and unit upper (lower)
!> triangular matrices, and T is symmetric and band. The matrix T is
!> then LU-factored with partial pivoting. The factored form of A
!> is then used to solve the system of equations A * X = B.
!>
!> This is the blocked version of the algorithm, calling Level 3 BLAS.
!>

highkey that last line is the glow-up — blocked version, calling Level 3 BLAS. she's not doing this one element at a time, bestie, she's doing it in blocks 🔥

---

🌈 Parameters 🌈

okay bestie this is the part where you actually read, no skimming 🙈

🍓 UPLO

!>          UPLO is CHARACTER*1
!>          = 'U':  Upper triangle of A is stored;
!>          = 'L':  Lower triangle of A is stored.
!>

pick a side, babe: 'U' for upper triangle, 'L' for lower 💫

🍓 N

!>          N is INTEGER
!>          The order of the matrix A.  N >= 0.
!>

the order of matrix A, and she's gotta be N >= 0.

🍓 NRHS

!>          NRHS is INTEGER
!>          The number of right hand sides, i.e., the number of columns
!>          of the matrix B.  NRHS >= 0.
!>

number of right hand sides = the number of columns of B, with NRHS >= 0.

🍓 A

!>          A is 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, L is stored below (or above) the subdiagonal blocks,
!>          when UPLO  is 'L' (or 'U').
!>

so on entry she's your symmetric matrix; only the triangle you picked gets used and the other half is literally not referenced (she's ignoring it, periodt). on exit, L is stored below (or above) the subdiagonal blocks, when UPLO is 'L' (or 'U').

🍓 LDA

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

leading dimension of A, and LDA >= max(1,N) — don't try it 💀

🍓 TB

!>          TB is REAL array, dimension (LTB)
!>          On exit, details of the LU factorization of the band matrix.
!>

on exit she holds the details of the LU factorization of the band matrix ✨

🍓 LTB

!>          LTB is INTEGER
!>          The size of the array TB. LTB >= 4*N, internally
!>          used to select NB such that LTB >= (3*NB+1)*N.
!>
!>          If LTB = -1, then a workspace query is assumed; the
!>          routine only calculates the optimal size of LTB,
!>          returns this value as the first entry of TB, and
!>          no error message related to LTB is issued by XERBLA.
!>

size of the TB array — LTB >= 4*N, and she's internally used to select NB such that LTB >= (3*NB+1)*N. and yes: if LTB = -1 it's a workspace query, she only calculates the optimal size of LTB, returns it as the first entry of TB, and XERBLA stays quiet about LTB — no error message, we don't do that here 🤫

🍓 IPIV

!>          IPIV is INTEGER array, dimension (N)
!>          On exit, it contains the details of the interchanges, i.e.,
!>          the row and column k of A were interchanged with the
!>          row and column IPIV(k).
!>

on exit: the interchange receipts 🧾 row and column k of A were interchanged with row and column IPIV(k).

🍓 IPIV2

!>          IPIV2 is INTEGER array, dimension (N)
!>          On exit, it contains the details of the interchanges, i.e.,
!>          the row and column k of T were interchanged with the
!>          row and column IPIV(k).
!>

same energy but for T. (and yeah, the doc literally says IPIV(k) right there in the IPIV2 bit — I'm not touching it, iykyk 👀)

🍓 B

!>          B is REAL array, dimension (LDB,NRHS)
!>          On entry, the right hand side matrix B.
!>          On exit, the solution matrix X.
!>

comes in as the right hand side matrix B, leaves as the solution matrix X — main character transformation 💅

🍓 LDB

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

LDB >= max(1,N), no cap.

🍓 WORK

!>          WORK is REAL workspace of size LWORK
!>

REAL workspace, size LWORK. that's the whole note, she's chill 🧚

🍓 LWORK

!>          LWORK is INTEGER
!>          The size of WORK. LWORK >= N, internally used to select NB
!>          such that LWORK >= N*NB.
!>
!>          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.
!>

size of WORK, with LWORK >= N, internally used to select NB such that LWORK >= N*NB. and if LWORK = -1? workspace query time 🦋 she only calculates the optimal size of the WORK array, returns that 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.
!>          > 0:  if INFO = i, band LU factorization failed on i-th column
!>

the final verdict ⭐

• = 0 — successful exit, slay 🎉
• < 0 — if INFO = -i, the i-th argument had an illegal value 🚨
• > 0 — if INFO = i, band LU factorization failed on i-th column 💀

---

🎀 Author 🎀

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

look at that group project actually working out 👑 four whole institutions, no drama.

Definition at line 184 of file ssysv_aa_2stage.f.

---

🦋 Author (again, but Doxygen this time) 🦋

Generated automatically by Doxygen for LAPACK from the source code. so nobody hand-wrote this one, a robot did it and honestly? she ate 🤖✨

---

ngl bestie if you made it this far you know this routine better than most people who use it. read the parameters again before you call her, fr fr 🙏

---

signing off with LAPACK Version 3.12.0, dated with that same /home/abui...a_2stage.f(3) footer energy — mwah, go compile something gorgeous 💖