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

📦 version 3.12.0, in opensuse-leap 16.0

💅 NAME 💅

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/zlasyf_rk.f — bestie, that's the whole file path, and yes it's giving "full government name" energy. It lives in the Library Functions Manual, section 3. 🎀

✨ SYNOPSIS ✨

🦋 Functions/Subroutines

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

ZLASYF_RK computes a partial factorization of a complex symmetric indefinite matrix using bounded Bunch-Kaufman (rook) diagonal pivoting method. no cap, that's literally the whole vibe of this routine. 👑

🌸 Function/Subroutine Documentation 🌸

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

ZLASYF_RK computes a partial factorization of a complex symmetric indefinite matrix using bounded Bunch-Kaufman (rook) diagonal pivoting method. 💖

🎀 Purpose 🎀

!> ZLASYF_RK computes a partial factorization of a complex symmetric !> matrix A using the bounded Bunch-Kaufman (rook) diagonal !> pivoting method. The partial factorization has the form:

So the tea is, the partial factorization comes out looking like this, and I need you to look at it because it's lowkey gorgeous:

!> A  =  ( I  U12 ) ( A11  0  ) (  I       0    )  if UPLO = 'U', or:
!>       ( 0  U22 ) (  0   D  ) ( U12**T U22**T )
!>
!> A  =  ( L11  0 ) (  D   0  ) ( L11**T L21**T )  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.
!> ZLASYF_RK is an auxiliary routine called by ZSYTRF_RK. It uses !> blocked code (calling Level 3 BLAS) to update the submatrix !> A11 (if UPLO = 'U') or A22 (if UPLO = 'L').

Slay, it's a sidekick routine. It's the auxiliary bestie for ZSYTRF_RK, and it's out here calling Level 3 BLAS to do the heavy lifting. Iconic. ⭐

💜 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
  • 'U' — upper triangular, we're going up 🦋
  • 'L' — lower triangular, we're going down 🌈

N

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

That's the order of matrix A, and it has to be N >= 0. Non-negotiable. ✨

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.

Max number of columns of A that should get factored. NB should be at least 2 so that 2-by-2 pivot blocks have room to exist. Don't come in with NB = 1 and expect 2-by-2 blocks, bestie, that's not how any of this works. 🙈

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.

The number of columns of A that actually got factored — the real count, not the aspirational one. KB is either NB-1 or NB, or N if N <= NB.

A

!> A is COMPLEX*16 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 entry it's the symmetric matrix A, and the triangular half you signed up for is the only half that gets looked at — the other half is not referenced, so don't stress about it. 🫶

On exit, A contains:

  • a) ONLY diagonal elements of the symmetric block diagonal matrix D on the diagonal of A, i.e. D(k,k) = A(k,k) — and the superdiagonal (or subdiagonal) elements of D are stored on exit in array E. 👑
  • b) If UPLO = 'U': factor U in the superdiagonal part of A. If UPLO = 'L': factor L in the subdiagonal part of A.

LDA

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

Leading dimension of A. Must satisfy LDA >= max(1,N). ✨

E

!> E is COMPLEX*16 array, dimension (N) !> On exit, contains the superdiagonal (or subdiagonal) !> elements of the symmetric block diagonal matrix D !> with 1-by-1 or 2-by-2 diagonal blocks, where !> If UPLO = 'U': E(i) = D(i-1,i), i=2:N, E(1) is set to 0; !> If UPLO = 'L': E(i) = D(i+1,i), i=1:N-1, E(N) is set to 0.
!> NOTE: For 1-by-1 diagonal block D(k), where !> 1 <= k <= N, the element E(k) is set to 0 in both !> UPLO = 'U' or UPLO = 'L' cases.

So E catches the off-diagonal bits of D that A doesn't keep. And note the note: for a 1-by-1 diagonal block D(k) where 1 <= k <= N, E(k) gets set to 0 in both the UPLO = 'U' and UPLO = 'L' cases. Both. No exceptions. 💀

IPIV

!> IPIV is INTEGER array, dimension (N) !> IPIV describes the permutation matrix P in the factorization !> of matrix A as follows. The absolute value of IPIV(k) !> represents the index of row and column that were !> interchanged with the k-th row and column. The value of UPLO !> describes the order in which the interchanges were applied. !> Also, the sign of IPIV represents the block structure of !> the symmetric block diagonal matrix D with 1-by-1 or 2-by-2 !> diagonal blocks which correspond to 1 or 2 interchanges !> at each factorization step.

Okay so IPIV is the one carrying all the lore. Let me break it down, because there are two whole sagas here depending on UPLO. 🧚

🦋 If UPLO = 'U'

!> If UPLO = 'U', !> ( in factorization order, k decreases from N to 1 ):

Note the direction: k decreases from N to 1. Main character energy moves backwards here. 👑

  • a) A single positive entry IPIV(k) > 0 means:
    • D(k,k) is a 1-by-1 diagonal block.
    • If IPIV(k) != k, rows and columns k and IPIV(k) were interchanged in the submatrix A(1:N,N-KB+1:N).
    • If IPIV(k) = k, no interchange occurred.
  • b) A pair of consecutive negative entries IPIV(k) < 0 and IPIV(k-1) < 0 means:
    • D(k-1:k,k-1:k) is a 2-by-2 diagonal block.
    • (NOTE: negative entries in IPIV appear ONLY in pairs).
    • 1) If -IPIV(k) != k, rows and columns k and -IPIV(k) were interchanged in the matrix A(1:N,N-KB+1:N). If -IPIV(k) = k, no interchange occurred.
    • 2) If -IPIV(k-1) != k-1, rows and columns k-1 and -IPIV(k-1) were interchanged in the submatrix A(1:N,N-KB+1:N). If -IPIV(k-1) = k-1, no interchange occurred.
  • c) In both cases a) and b), it's always ABS( IPIV(k) ) <= k.
  • d) NOTE: Any entry IPIV(k) is always NONZERO on output.

🦋 If UPLO = 'L'

!> If UPLO = 'L', !> ( in factorization order, k increases from 1 to N ):

Now k increases from 1 to N. We're going forwards, we're thriving. 🌈

  • a) A single positive entry IPIV(k) > 0 means:
    • D(k,k) is a 1-by-1 diagonal block.
    • If IPIV(k) != k, rows and columns k and IPIV(k) were interchanged in the submatrix A(1:N,1:KB). If IPIV(k) = k, no interchange occurred.
  • b) A pair of consecutive negative entries IPIV(k) < 0 and IPIV(k+1) < 0 means:
    • D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
    • (NOTE: negative entries in IPIV appear ONLY in pairs).
    • 1) If -IPIV(k) != k, rows and columns k and -IPIV(k) were interchanged in the submatrix A(1:N,1:KB). If -IPIV(k) = k, no interchange occurred.
    • 2) If -IPIV(k+1) != k+1, rows and columns k-1 and -IPIV(k-1) were interchanged in the submatrix A(1:N,1:KB). If -IPIV(k+1) = k+1, no interchange occurred.
  • c) In both cases a) and b), it's always ABS( IPIV(k) ) >= k.
  • d) NOTE: Any entry IPIV(k) is always NONZERO on output.

See how case c) flipped from <= k to >= k between the two? That's not a typo bestie, that's the manual being extremely intentional. Periodt. 💅

W

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

That's it. That's the whole description. It's giving minimal, it's giving mystery. 🎀

LDW

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

Leading dimension of W, and yes: LDW >= max(1,N). ⭐

INFO

!> INFO is INTEGER !> = 0: successful exit
  • = 0 — successful exit, we ate and left no crumbs. 🍓
  • < 0 — If INFO = -k, the k-th argument had an illegal value. 🚩
  • > 0 — If INFO = k, the matrix A is singular, because:
!> If UPLO = 'U': column k in the upper !> triangular part of A contains all zeros. !> If UPLO = 'L': column k in the lower !> triangular part of A contains all zeros.
!> Therefore D(k,k) is exactly zero, and superdiagonal !> elements of column k of U (or subdiagonal elements of !> column k of L ) are all zeros. 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.
Heads up, for real: the factorization has been completed, but D is exactly singular, and division by zero will occur if you try to use it to solve a system of equations. That is a hard no. Do not pass go. 😭
!> NOTE: INFO only stores the first occurrence of !> a singularity, any subsequent occurrence of singularity !> is not stored in INFO even though the factorization !> always completes.

So INFO is a first-come-first-served situation: it only stores the first singularity. Any later singularities don't get stored in INFO even though the factorization always completes. Silent treatment. 💀

👑 Author 👑

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

The whole squad. 🫶

🌟 Contributors: 🌟

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

Legends, all of them. 💜

🧚 Definition 🧚

Definition at line 260 of file zlasyf_rk.f. Yes, line 260. You're welcome. ✨

💖 Author 💖

Generated automatically by Doxygen for LAPACK from the source code. Not me, not you — Doxygen did that. 🤖

LAPACK — Version 3.12.0 — and that's the whole page, /home/abui...lasyf_rk.f(3), footer included. Go forth and factor your complex symmetric indefinite matrices, bestie. 💅✨🎀🦋🌸🫶👑🌈⭐💜

📦 where this page comes from