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

📦 version 3.12.0, in opensuse-leap 16.0

💅 NAME

okay so this is the manual page for /home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/zsytf2_rk.f — it lives in the Library Functions Manual section (section 3, bestie, the "your code calls this" zone), and it's about one very specific little Fortran file 💖

✨ SYNOPSIS

🦋 Functions/Subroutines

  • subroutine ZSYTF2_RK (uplo, n, a, lda, e, ipiv, info) — bestie. this one. ZSYTF2_RK computes the factorization of a complex symmetric indefinite matrix using the bounded Bunch-Kaufman (rook) diagonal pivoting method (BLAS2 unblocked algorithm).

🎀 Function/Subroutine Documentation

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

ZSYTF2_RK computes the factorization of a complex symmetric indefinite matrix using the bounded Bunch-Kaufman (rook) diagonal pivoting method (BLAS2 unblocked algorithm).

🌸 Purpose

!> ZSYTF2_RK computes the factorization of a complex symmetric matrix A
!> using the bounded Bunch-Kaufman (rook) diagonal pivoting method:
!>
!>    A = P*U*D*(U**T)*(P**T) or A = P*L*D*(L**T)*(P**T),
!>
!> where U (or L) is unit upper (or lower) triangular matrix,
!> U**T (or L**T) is the transpose of U (or L), P is a permutation
!> matrix, P**T is the transpose of P, 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.
!> For more information see Further Details section.
!>

so like. it takes your matrix and splits it into P*U*D*(U**T)*(P**T) or P*L*D*(L**T)*(P**T). iconic. and yeah this is the unblocked one, Level 2 BLAS only, no fancy blocking 🫶

🔥 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
!>

UPLO is a CHARACTER*1 and it tells the routine which triangle of the symmetric matrix A you actually stored, bestie:

  • 'U': upper triangular ✨
  • 'L': lower triangular ✨

N

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

N is an INTEGER — the order of the matrix A. N >= 0, no cap.

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 exit, 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);
!>               (superdiagonal (or subdiagonal) elements of D
!>                are stored on exit in array E), and
!>            b) If UPLO = 'U': factor U in the superdiagonal part of A.
!>               If UPLO = 'L': factor L in the subdiagonal part of A.
!>

A is a COMPLEX*16 array of dimension (LDA,N). on entry it's your symmetric matrix:

  • 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 🙈
  • 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 it contains:

  • a) ONLY the diagonal elements of the symmetric block diagonal matrix D, sitting on the diagonal of A — that's D(k,k) = A(k,k); — and the superdiagonal (or subdiagonal) elements of D get stored on exit in array E instead. and
  • b) if UPLO = 'U': factor U in the superdiagonal part of A. if UPLO = 'L': factor L in the subdiagonal part of A. slay 💅

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. LDA >= max(1,N). that's the law 🫶

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

E is a COMPLEX*16 array of dimension (N). on exit it holds 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 a 1-by-1 diagonal block D(k), where 1 <= k <= N, the element E(k) is set to 0 in both the UPLO = 'U' and UPLO = 'L' cases. no crumbs left behind 🎀

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. For more info see Further
!>          Details section.
!>
!>          If UPLO = 'U',
!>          ( in factorization order, k decreases from N to 1 ):
!>            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 matrix A(1:N,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,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 matrix A(1:N,1:N).
!>                  If -IPIV(k-1) = k-1, no interchange occurred.
!>
!>            c) In both cases a) and b), always ABS( IPIV(k) ) <= k.
!>
!>            d) NOTE: Any entry IPIV(k) is always NONZERO on output.
!>
!>          If UPLO = 'L',
!>          ( in factorization order, k increases from 1 to N ):
!>            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 matrix A(1:N,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: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 matrix A(1:N,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 matrix A(1:N,1:N).
!>                  If -IPIV(k+1) = k+1, no interchange occurred.
!>
!>            c) In both cases a) and b), always ABS( IPIV(k) ) >= k.
!>
!>            d) NOTE: Any entry IPIV(k) is always NONZERO on output.
!>

IPIV is an INTEGER array of dimension (N), and babes it is doing a LOT. it describes the permutation matrix P in the factorization of matrix A like this: the absolute value of IPIV(k) is the index of the row and column that got interchanged with the k-th row and column. UPLO tells you the order the interchanges were applied in. and the sign of IPIV is the block structure of the symmetric block diagonal matrix D — 1-by-1 or 2-by-2 diagonal blocks, corresponding to 1 or 2 interchanges at each factorization step. more below in Further Details 👑

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

  • 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 matrix A(1:N,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,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 matrix A(1:N,1:N). if -IPIV(k-1) = k-1, no interchange occurred.
  • c) in both cases a) and b), always ABS( IPIV(k) ) <= k.
  • d) NOTE: any entry IPIV(k) is always NONZERO on output.

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

  • 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 matrix A(1:N,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: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 matrix A(1:N,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 matrix A(1:N,1:N). if -IPIV(k+1) = k+1, no interchange occurred.
  • c) in both cases a) and b), always ABS( IPIV(k) ) >= k.
  • d) NOTE: any entry IPIV(k) is always NONZERO on output.

INFO

!>          INFO is INTEGER
!>          = 0: successful exit
!>
!>          < 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.
!>
!>               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.
!>

INFO is an INTEGER and it's the vibe check at the end:

  • = 0: successful exit ✨
  • < 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 the superdiagonal elements of column k of U (or the 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's used to solve a system of equations 💀

NOTE: INFO only stores the first occurrence of a singularity. any subsequent occurrence of a singularity is not stored in INFO, even though the factorization always completes. it's giving "we move on" energy.

👑 Author

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

🌈 Further Details:

!> TODO: put further details
!>

yeah. that's the whole section. literally a TODO. the further details are further along in somebody's backlog, bestie 😭 iykyk

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

📍 Definition at line 240 of file zsytf2_rk.f.

that's where the actual code lives. go look. it's right there 🫶

💜 Author

Generated automatically by Doxygen for LAPACK from the source code. not a human, not a vibe, just a doc generator doing its little thing 🎀

and that's the whole page, bestie! this one came from LAPACK, Version 3.12.0 and it's the manpage for /home/abui...sytf2_rk.f(3) — go factor something symmetric and indefinite, you've got this 💖✨🌸

📦 where this page comes from