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

📦 version 3.12.0, in opensuse-leap 16.0

🌸 /home/abui...hef_rook.f(3) — Library Functions Manual 🌸

okay bestie, buckle up — this one's a <pink>LAPACK</pink> page from the Library Functions Manual, and it's literally all about one little workhorse subroutine. it's giving "behind the scenes icon" energy 💅

The whole file lives at this absolute unit of a path, so let's get it out of the way:

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

no cap, that's the NAME section. that's it. that's the name. 😭

✨ SYNOPSIS ✨

Functions/Subroutines:

subroutine CLAHEF_ROOK (uplo, n, nb, kb, a, lda, ipiv, w, ldw, info)

🦋 Function/Subroutine Documentation 🦋

subroutine CLAHEF_ROOK (character uplo, integer n, integer nb, integer kb,
    complex, dimension( lda, * ) a, integer lda, integer, dimension( * )
    ipiv, complex, dimension( ldw, * ) w, integer ldw, integer info)

💖 Purpose 💖

ok so here's the vibe, straight from the source:

!>
!> CLAHEF_ROOK computes a partial factorization of a complex Hermitian
!> matrix A using the bounded Bunch-Kaufman () diagonal pivoting
!> method. The partial factorization has the form:
!>
!> A  =  ( I  U12 ) ( A11  0  ) (  I      0     )  if UPLO = 'U', or:
!>       ( 0  U22 ) (  0   D  ) ( U12**H U22**H )
!>
!> A  =  ( L11  0 ) (  D   0  ) ( L11**H L21**H )  if UPLO = 'L'
!>       ( L21  I ) (  0  A22 ) (  0      I     )
!>
!> where the order of D is at most NB. The actual order is returned in
!> the argument KB, and is either NB or NB-1, or N if N <= NB.
!> Note that U**H denotes the conjugate transpose of U.
!>
!> CLAHEF_ROOK is an auxiliary routine called by CHETRF_ROOK. It uses
!> blocked code (calling Level 3 BLAS) to update the submatrix
!> A11 (if UPLO = 'U') or A22 (if UPLO = 'L').
!>

so yeah — it's the little helper that <hotpink>CHETRF_ROOK</hotpink> calls in, it only factors some of the columns (a partial factorization, hence "partial"), and the order of D is at most NB, with the real number handed back to you in KB. like, KB is either NB or NB-1, or N if N <= NB. and reminder: U**H is the conjugate transpose of U, iykyk 🧚

🎀 Parameters 🎀

UPLO

!>          UPLO is CHARACTER*1
!>          Specifies whether the upper or lower triangular part of the
!>          Hermitian matrix A is stored:
!>          = 'U':  Upper triangular
!>          = 'L':  Lower triangular

UPLO is a CHARACTER*1 and it picks which triangle of the Hermitian matrix A you're actually storing — 'U' for upper triangular, 'L' for lower triangular. pick your fighter 💅

N

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

N is an INTEGER, the order of the matrix A, and it has to satisfy N >= 0.

NB

!>          NB is INTEGER
!>          The maximum number of columns of the matrix A that should be
!>          factored.  NB should be at least 2 to allow for 2-by-2 pivot
!>          blocks.

NB is an INTEGER — the max number of columns of A that should get factored. and listen: NB should be at least 2, because otherwise the 2-by-2 pivot blocks literally can't happen. 🫶

KB

!>          KB is INTEGER
!>          The number of columns of A that were actually factored.
!>          KB is either NB-1 or NB, or N if N <= NB.

KB is an INTEGER — how many columns of A actually got factored. it's either NB-1 or NB, or N if N <= NB. this is the output one, the "what really happened" one ✨

A

!>          A is COMPLEX array, dimension (LDA,N)
!>          On entry, the Hermitian 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, A contains details of the partial factorization.

A is a COMPLEX array of dimension (LDA,N). on entry it's the Hermitian matrix A. if UPLO = 'U', the leading n-by-n upper triangular part of A holds the upper triangular part of the matrix, and the strictly lower triangular part is not referenced (mind ya business 🚫). if UPLO = 'L', it's the other way around: leading n-by-n lower triangular part holds the lower triangular part, and the strictly upper triangular part is not referenced. on exit, A contains the details of the partial factorization. main character transformation fr 🔥

LDA

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

LDA is an INTEGER, the leading dimension of the array A, and LDA >= max(1,N). no shortcuts, bestie.

IPIV

!>          IPIV is INTEGER array, dimension (N)
!>          Details of the interchanges and the block structure of D.
!>
!>          If UPLO = 'U':
!>             Only the last KB elements of IPIV are set.
!>
!>             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 IPIV(k) < 0 and IPIV(k-1) < 0, then rows and
!>             columns k and -IPIV(k) were interchanged and rows and
!>             columns k-1 and -IPIV(k-1) were inerchaged,
!>             D(k-1:k,k-1:k) is a 2-by-2 diagonal block.
!>
!>          If UPLO = 'L':
!>             Only the first KB elements of IPIV are set.
!>
!>             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 IPIV(k) < 0 and IPIV(k+1) < 0, then rows and
!>             columns k and -IPIV(k) were interchanged and rows and
!>             columns k+1 and -IPIV(k+1) were inerchaged,
!>             D(k:k+1,k:k+1) is a 2-by-2 diagonal block.

IPIV is an INTEGER array of dimension (N) — it holds the details of the interchanges and the block structure of D. and yes, the source really does spell it "inerchaged" twice, so we're keeping that energy 💀

if UPLO = 'U': only the last KB elements of IPIV are set.

  • 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 IPIV(k) < 0 and IPIV(k-1) < 0, then rows and columns k and -IPIV(k) were interchanged and rows and columns k-1 and -IPIV(k-1) were inerchaged, and D(k-1:k,k-1:k) is a 2-by-2 diagonal block.

if UPLO = 'L': only the first KB elements of IPIV are set.

  • 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 IPIV(k) < 0 and IPIV(k+1) < 0, then rows and columns k and -IPIV(k) were interchanged and rows and columns k+1 and -IPIV(k+1) were inerchaged, and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.

W

!>          W is COMPLEX array, dimension (LDW,NB)

W is a COMPLEX array of dimension (LDW,NB). that's the whole description. it's mysterious, it's iconic, it's just vibes 🦋

LDW

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

LDW is an INTEGER, the leading dimension of the array W, and LDW >= max(1,N).

INFO

!>          INFO is INTEGER
!>          = 0: successful exit
!>          > 0: if INFO = k, D(k,k) is exactly zero.  The factorization
!>               has been completed, but the block diagonal matrix D is
!>               exactly singular.

INFO is an INTEGER and it's your little status report:

  • = 0: successful exit, we ate and left no crumbs ✅
  • > 0: if INFO = k, D(k,k) is exactly zero. the factorization has been completed, but the block diagonal matrix D is exactly singular. not an error exactly, but definitely a moment 😭
heads up: a positive INFO means D is singular — the factorization still ran to completion, so don't go treating this like a crash. it's just telling you D(k,k) is exactly zero.

👑 Author 👑

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

🌈 Contributors: 🌈

!>
!>  November 2013, Igor Kozachenko,
!>                  Computer Science Division,
!>                  University of California, Berkeley
!>
!>  September 2007, Sven Hammarling, Nicholas J. Higham, Craig Lucas,
!>                  School of Mathematics,
!>                  University of Manchester
!>

so Igor Kozachenko (Computer Science Division, University of California, Berkeley) came through in November 2013, and Sven Hammarling, Nicholas J. Higham and Craig Lucas (School of Mathematics, University of Manchester) were there in September 2007. legends only 🫶

⭐ Definition ⭐

Definition at line 182 of file clahef_rook.f.

💜 Author 💜

Generated automatically by Doxygen for LAPACK from the source code.

that's the whole page, bestie — LAPACK, Version 3.12.0, /home/abui...hef_rook.f(3), and it's a wrap 🎀✨

📦 where this page comes from