SRC/zsytf2_rook.f(3)

📦
version 3.12.1 · 4 versions
, in arch rolling

🦋 SRC/zsytf2_rook.f(3) 🦋

okay so bestie, you found the SRC/zsytf2_rook.f(3) page in the Library Functions Manual — this is the whole glow-up of that one Fortran file, and honestly? it ate. let's get into it ✨

🌸 NAME 🌸

SRC/zsytf2_rook.f — yes bestie, that's literally the whole name, the file is the moment 💅

✨ SYNOPSIS ✨

Functions/Subroutines

  • subroutine zsytf2_rook (uplo, n, a, lda, ipiv, info) — ZSYTF2_ROOK computes the factorization of a complex symmetric indefinite matrix using the bounded Bunch-Kaufman ("rook") diagonal pivoting method (unblocked algorithm). that's a mouthful but she's iconic for it 🎀

🫶 Function/Subroutine Documentation 🫶

subroutine zsytf2_rook (character uplo, integer n, complex*16, dimension( lda, * ) a, integer lda, integer, dimension( * ) ipiv, integer info)

ZSYTF2_ROOK computes the factorization of a complex symmetric indefinite matrix using the bounded Bunch-Kaufman ("rook") diagonal pivoting method (unblocked algorithm). so real, so specific, no notes 🔥

Purpose

!>
!> ZSYTF2_ROOK computes the factorization of a complex symmetric matrix A
!> using the bounded 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, U**T is the transpose of U, and D is symmetric and
!> block diagonal with 1-by-1 and 2-by-2 diagonal blocks.
!>
!> This is the unblocked version of the algorithm, calling Level 2 BLAS.
!>

like, she's out here building A out of permutation matrices, unit triangular matrices, and a block diagonal D with lil 1-by-1 and 2-by-2 blocks. and this version is the unblocked one, lowkey calling Level 2 BLAS the entire time. periodt 💜

Parameters

  • UPLO — UPLO is CHARACTER*1, and it's the vibe check for which triangle of the symmetric matrix A you're storing: = 'U' means upper triangular, = 'L' means lower triangular. pick your fighter 🌈
  • N — N is INTEGER, the order of the matrix A. and N >= 0, obviously, we don't do negative order around here 🙈
  • 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 holds the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced (she's ignoring it, respectfully). if UPLO = 'L', the leading n-by-n lower triangular part of A holds the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced. on exit: the block diagonal matrix D and the multipliers used to obtain the factor U or L (peep below for further details, iykyk) 💫
  • LDA — LDA is INTEGER, the leading dimension of the array A, and it's gotta be LDA >= max(1,N). no wiggle room bestie 🎀
  • IPIV — IPIV is INTEGER array, dimension (N). this one's the receipts: details of the interchanges and the block structure of D.
    • if UPLO = 'U':
      • 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 interchanged, and D(k-1:k,k-1:k) is a 2-by-2 diagonal block.
    • if UPLO = 'L':
      • 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 interchanged, and D(k:k+1,k:k+1) is a 2-by-2 diagonal block. 👑 notice the sign of the index flips and the neighbor flips along with it — that's the whole trick, don't sleep on it
  • INFO — INFO is INTEGER, the final report card:
    • = 0: successful exit, we slayed 🎉
    • < 0: if INFO = -k, the k-th argument had an illegal value. bestie. k-th argument. go fix it 😭
    • > 0: if INFO = k, D(k,k) 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. so like... it finished, but it's giving danger 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

okay this is the part where she shows her work and honestly it's beautiful 🌸

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

so for the upper case k decreases from n to 1 in steps of 1 or 2, and for the lower case k increases from 1 to n in steps of 1 or 2. mirror image behavior, both serving 🪞 and v is out here overwriting chunks of A — she reuses memory like a queen, nothing goes to waste 💅

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
  • 01-01-96 - Based on modifications by:
    • J. Lewis, Boeing Computer Services Company
    • A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville abd , USA

shoutout to the whole group chat of mathematicians who made this happen over the years, fr fr 🫶 (yes the abd is in the original, we're not touching it, it's part of the lore 😭)

Definition at line 193 of file zsytf2_rook.f.

🌟 Author 🌟

Generated automatically by Doxygen for LAPACK from the source code. she wasn't hand-written, she was summoned ✨

okay that's the whole page bestie, you're officially caught up 💖 this was LAPACK, Version 3.12.0, and the file is SRC/zsytf2_rook.f(3) — go forth and factorize your complex symmetric matrices with bounded Bunch-Kaufman rook pivoting, and remember: if INFO = k with D(k,k) exactly zero, that's not a vibe, that's a singular matrix 🎀 bye ily 🦋

📦 where this page comes from