hesv_rook(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

✨ hesv_rook ✨

okay so bestie, we're in the Library Functions Manual and this page is called hesv_rook(3). it's giving "big LAPACK energy", it's giving "your linear algebra assignment but make it fashion". buckle up 🎀

🌸 NAME 🌸

hesv_rook — {he,sy}sv_rook: rook (v2) 💅

🦋 SYNOPSIS 🦋

✨ Functions ✨

  • subroutine chesv_rook (uplo, n, nrhs, a, lda, ipiv, b, ldb, work, lwork, info) — CHESV_ROOK computes the solution to a system of linear equations A * X = B for HE matrices using the bounded Bunch-Kaufman (rook")diagonalpivotingmethod (yes the manpage really does mash it together like that, no cap, i'm not fixing it, that's canon 💀)
  • subroutine csysv_rook (uplo, n, nrhs, a, lda, ipiv, b, ldb, work, lwork, info) — CSYSV_ROOK computes the solution to system of linear equations A * X = B for SY matrices
  • subroutine dsysv_rook (uplo, n, nrhs, a, lda, ipiv, b, ldb, work, lwork, info) — DSYSV_ROOK computes the solution to system of linear equations A * X = B for SY matrices
  • subroutine ssysv_rook (uplo, n, nrhs, a, lda, ipiv, b, ldb, work, lwork, info) — SSYSV_ROOK computes the solution to system of linear equations A * X = B for SY matrices
  • subroutine zhesv_rook (uplo, n, nrhs, a, lda, ipiv, b, ldb, work, lwork, info) — ZHESV_ROOK computes the solution to a system of linear equations A * X = B for HE matrices using the bounded Bunch-Kaufman (rook")diagonalpivotingmethod
  • subroutine zsysv_rook (uplo, n, nrhs, a, lda, ipiv, b, ldb, work, lwork, info) — ZSYSV_ROOK computes the solution to system of linear equations A * X = B for SY matrices

💜 Detailed Description 💜

so this section exists. it has a title. it has a vibe. it has… literally no content under it. we stan a mysterious queen who says nothing and leaves 🫶

👑 Function Documentation 👑

🍓 subroutine chesv_rook (character uplo, integer n, integer nrhs, complex, dimension( lda, * ) a, integer lda, integer, dimension( * ) ipiv, complex, dimension( ldb, * ) b, integer ldb, complex, dimension( * ) work, integer lwork, integer info) 🍓

CHESV_ROOK computes the solution to a system of linear equations A * X = B for HE matrices using the bounded Bunch-Kaufman ("rook") diagonal pivoting method

🔥 Purpose: 🔥

!>
!> CHESV_ROOK computes the solution to a complex system of linear equations
!>    A * X = B,
!> where A is an N-by-N Hermitian matrix and X and B are N-by-NRHS
!> matrices.
!>
!> The bounded Bunch-Kaufman () diagonal pivoting method is used
!> to factor A as
!>    A = U * D * U**T,  if UPLO = 'U', or
!>    A = L * D * L**T,  if UPLO = 'L',
!> where U (or L) is a product of permutation and unit upper (lower)
!> triangular matrices, and D is Hermitian and block diagonal with
!> 1-by-1 and 2-by-2 diagonal blocks.
!>
!> CHETRF_ROOK is called to compute the factorization of a complex
!> Hermition matrix A using the bounded Bunch-Kaufman () diagonal
!> pivoting method.
!>
!> The factored form of A is then used to solve the system
!> of equations A * X = B by calling CHETRS_ROOK (uses BLAS 2).
!>

not the empty () twice and "Hermition" — bestie the source has typos and we are NOT touching them, they're part of the lore now 💅

🌈 Parameters 🌈

UPLO

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

N

!>          N is INTEGER
!>          The number of linear equations, i.e., the order of the
!>          matrix A.  N >= 0.
!>

NRHS

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

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, if INFO = 0, the block diagonal matrix D and the
!>          multipliers used to obtain the factor U or L from the
!>          factorization A = U*D*U**H or A = L*D*L**H as computed by
!>          CHETRF_ROOK.
!>

LDA

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

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

again: "inerchaged". twice. it's a whole aesthetic. leave her alone 😭

B

!>          B is COMPLEX array, dimension (LDB,NRHS)
!>          On entry, the N-by-NRHS right hand side matrix B.
!>          On exit, if INFO = 0, the N-by-NRHS solution matrix X.
!>

LDB

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

WORK

!>          WORK is COMPLEX array, dimension (MAX(1,LWORK))
!>          On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
!>

LWORK

!>          LWORK is INTEGER
!>          The length of WORK.  LWORK >= 1, and for best performance
!>          LWORK >= max(1,N*NB), where NB is the optimal blocksize for
!>          CHETRF_ROOK.
!>          for LWORK < N, TRS will be done with Level BLAS 2
!>          for LWORK >= N, TRS will be done with Level BLAS 3
!>
!>          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.
!>
🌟 LWORK = -1 is the "just tell me how much space you need" move — it reports the optimal size back in WORK(1) and XERBLA stays quiet about LWORK. no drama, no error message. 🧚

INFO

!>          INFO is INTEGER
!>          = 0: successful exit
!>          < 0: if INFO = -i, the i-th argument had an illegal value
!>          > 0: if INFO = i, D(i,i) is exactly zero.  The factorization
!>               has been completed, but the block diagonal matrix D is
!>               exactly singular, so the solution could not be computed.
!>

heads up babes: INFO > 0 means D(i,i) is exactly zero — the factorization finished but D is exactly singular, so the solution could not be computed. the math said "no" and there's nothing to do about it. 💀

🧚 Author 🧚

  • Univ. of Tennessee
  • Univ. of California Berkeley
  • Univ. of Colorado Denver
  • NAG Ltd.
!>
!>  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
!>
!> .fi

Definition at line 203 of file chesv_rook.f.

🎀 subroutine csysv_rook (character uplo, integer n, integer nrhs, complex, dimension( lda, * ) a, integer lda, integer, dimension( * ) ipiv, complex, dimension( ldb, * ) b, integer ldb, complex, dimension( * ) work, integer lwork, integer info) 🎀

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

🔥 Purpose: 🔥

!>
!> CSYSV_ROOK computes the solution to a complex 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.
!>
!> The diagonal pivoting method is used to factor A as
!>    A = U * D * U**T,  if UPLO = 'U', or
!>    A = L * D * L**T,  if UPLO = 'L',
!> where U (or L) is a product of permutation and unit upper (lower)
!> triangular matrices, and D is symmetric and block diagonal with
!> 1-by-1 and 2-by-2 diagonal blocks.
!>
!> CSYTRF_ROOK is called to compute the factorization of a complex
!> symmetric matrix A using the bounded Bunch-Kaufman () diagonal
!> pivoting method.
!>
!> The factored form of A is then used to solve the system
!> of equations A * X = B by calling CSYTRS_ROOK.
!>

🌈 Parameters 🌈

UPLO

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

N

!>          N is INTEGER
!>          The number of linear equations, i.e., the order of the
!>          matrix A.  N >= 0.
!>

NRHS

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

A

!>          A is COMPLEX 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, if INFO = 0, the block diagonal matrix D and the
!>          multipliers used to obtain the factor U or L from the
!>          factorization A = U*D*U**T or A = L*D*L**T as computed by
!>          CSYTRF_ROOK.
!>

LDA

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

IPIV

✨ …and that's literally where we're stopping — IPIV just showed up and the page dips. she's making an entrance and we'll get her whole speech in the next part, i promise 🫶

  • IPIV — IPIV is INTEGER array, dimension (N). This is the whole swap-and-block receipt for D, exactly as CSYTRF_ROOK handed it over. 💅

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.
  • B — B is COMPLEX array, dimension (LDB,NRHS). On entry, it's the N-by-NRHS right hand side matrix B. On exit, if INFO = 0, it's the N-by-NRHS solution matrix X. ✨
  • LDB — LDB is INTEGER. It's the leading dimension of the array B, and bestie, LDB >= max(1,N). No cap. 🫶
  • WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 🎀
  • LWORK — LWORK is INTEGER. It's the length of WORK. LWORK >= 1, and for best performance LWORK >= max(1,N*NB), where NB is the optimal blocksize for CSYTRF_ROOK. 🔥

Also: TRS will be done with Level 2 BLAS — that's a whole sentence in the page, so it stays. 🫠

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

  • INFO — INFO is INTEGER.
    • = 0: successful exit. slay.
    • < 0: if INFO = -i, the i-th argument had an illegal value. 🙈
    • > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, so the solution could not be computed. 😭

🫶 Author 🫶

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

🌈 Contributors: 🌈

  • April 2012, Igor Kozachenko, Computer Science Division, University of California, Berkeley
  • September 2007, Sven Hammarling, Nicholas J. Higham, Craig Lucas, School of Mathematics, University of Manchester

Definition at line 202 of file csysv_rook.f.

🦋 dsysv_rook 🦋

   subroutine dsysv_rook (character uplo, integer n, integer nrhs, double
       precision, dimension( lda, * ) a, integer lda, integer, dimension( * )
       ipiv, double precision, dimension( ldb, * ) b, integer ldb, double
       precision, dimension( * ) work, integer lwork, integer info)

DSYSV_ROOK computes the solution to system of linear equations A * X = B for SY matrices. 👑

✨ Purpose ✨

DSYSV_ROOK 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. 💖

The diagonal pivoting method is used to factor A as

A = U * D * U**T,  if UPLO = 'U', or
A = L * D * L**T,  if UPLO = 'L',

where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is symmetric and block diagonal with 1-by-1 and 2-by-2 diagonal blocks. 🎀

DSYTRF_ROOK is called to compute the factorization of a real symmetric matrix A using the bounded Bunch-Kaufman () diagonal pivoting method. (Yes, the parentheses are empty in the page. We respect the iconique emptiness. 💅)

The factored form of A is then used to solve the system of equations A * X = B by calling DSYTRS_ROOK. ✨

🌸 Parameters 🌸

  • UPLO — UPLO is CHARACTER*1.
    • = 'U': Upper triangle of A is stored.
    • = 'L': Lower triangle of A is stored.
  • N — N is INTEGER. The number of linear equations, i.e., the order of the matrix A. N >= 0. 🫶
  • NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0. 💖
  • A — A is DOUBLE PRECISION 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, if INFO = 0, the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U**T or A = L*D*L**T as computed by DSYTRF_ROOK. 💫

  • LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N). 🎀
  • IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D, as determined by DSYTRF_ROOK. 💅

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.
  • B — B is DOUBLE PRECISION array, dimension (LDB,NRHS). On entry, the N-by-NRHS right hand side matrix B. On exit, if INFO = 0, the N-by-NRHS solution matrix X. 🌈
  • LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N). 🫶
  • WORK — WORK is DOUBLE PRECISION array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. ⭐
  • LWORK — LWORK is INTEGER. The length of WORK. LWORK >= 1, and for best performance LWORK >= max(1,N*NB), where NB is the optimal blocksize for DSYTRF_ROOK. 🔥

TRS will be done with Level 2 BLAS — noted, bestie. 🫠

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

  • INFO — INFO is INTEGER.
    • = 0: successful exit.
    • < 0: if INFO = -i, the i-th argument had an illegal value. 🙈
    • > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, so the solution could not be computed. 😭

🫶 Author 🫶

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

🌈 Contributors: 🌈

  • April 2012, Igor Kozachenko, Computer Science Division, University of California, Berkeley
  • September 2007, Sven Hammarling, Nicholas J. Higham, Craig Lucas, School of Mathematics, University of Manchester

Definition at line 202 of file dsysv_rook.f.

🦋 ssysv_rook 🦋

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

SSYSV_ROOK computes the solution to system of linear equations A * X = B for SY matrices. 👑

✨ Purpose ✨

SSYSV_ROOK 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. 💖

The diagonal pivoting method is used to factor A as

A = U * D * U**T,  if UPLO = 'U', or
A = L * D * L**T,  if UPLO = 'L',

where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is symmetric and block diagonal with 1-by-1 and 2-by-2 diagonal blocks. 🎀

SSYTRF_ROOK is called to compute the factorization of a real symmetric matrix A using the bounded Bunch-Kaufman () diagonal pivoting method. 💅

The factored form of A is then used to solve the system of equations A * X = B by calling SSYTRS_ROOK. ✨

🌸 Parameters 🌸

  • UPLO — UPLO is CHARACTER*1.
    • = 'U': Upper triangle of A is stored.
    • = 'L': Lower triangle of A is stored.

N

  • N — INTEGER, and it's the number of linear equations, aka the order of the matrix A. Constraint: N >= 0. (Zero is allowed bestie, the math just vibes with nothing in it ✨)
  • NRHS — INTEGER, the number of right hand sides, i.e. how many columns the matrix B has. Constraint: NRHS >= 0. Same deal, zero is legal 💅
  • A — REAL array, dimension (LDA,N). Okay so on entry: this is your 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 (don't even worry about it, nobody's reading that half 👀). If UPLO = 'L', it flips: 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, if INFO = 0, A contains the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U**T or A = L*D*L**T as computed by SSYTRF_ROOK. Slay 🔥

  • LDA — INTEGER, the leading dimension of the array A. Constraint: LDA >= max(1,N). Respect the leading dimension or perish fr fr.
  • IPIV — INTEGER array, dimension (N). The receipts for all the interchanges and the block structure of D, as determined by SSYTRF_ROOK. Bestie, this is the tea 🍵:

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. Two-for-one deal 💫

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 -1 vs +1 there — that's not a typo, that's the whole point of the UPLO split. Do not mix them up 😭

  • B — REAL array, dimension (LDB,NRHS). On entry: the N-by-NRHS right hand side matrix B. On exit, if INFO = 0: the N-by-NRHS solution matrix X. Glow-up arc complete 👑
  • LDB — INTEGER, the leading dimension of the array B. Constraint: LDB >= max(1,N).
  • WORK — REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. She's telling you what she needs 💅
  • LWORK — INTEGER, the length of WORK. Constraint: LWORK >= 1, and for best performance LWORK >= max(1,N*NB), where NB is the optimal blocksize for SSYTRF_ROOK.
Heads up: TRS will be done with Level 2 BLAS. That's the slower lane, so size your workspace if you care about speed 🐌

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. It's the "just asking, not doing" mode 🎀

  • INFO — INTEGER. The vibe report:
    • = 0: successful exit ✨
    • < 0: if INFO = -i, the i-th argument had an illegal value (you fed her something cursed 💀)
    • > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, so the solution could not be computed. Translation: the math is unsolvable, no cap. Don't try to use the answer 🌸

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors:

  • April 2012, Igor Kozachenko, Computer Science Division, University of California, Berkeley
  • September 2007, Sven Hammarling, Nicholas J. Higham, Craig Lucas, School of Mathematics, University of Manchester

Definition at line 202 of file ssysv_rook.f.

🌈 subroutine zhesv_rook

subroutine zhesv_rook (character uplo, integer n, integer nrhs, complex*16,
    dimension( lda, * ) a, integer lda, integer, dimension( * ) ipiv,
    complex*16, dimension( ldb, * ) b, integer ldb, complex*16, dimension( *
    ) work, integer lwork, integer info)

ZHESV_ROOK computes the solution to a system of linear equations A * X = B for HE matrices using the bounded Bunch-Kaufman ("rook") diagonal pivoting method. Same energy as the real one, but make it complex 💜

Purpose:

ZHESV_ROOK computes the solution to a complex system of linear equations

   A * X = B,

where A is an N-by-N Hermitian matrix and X and B are N-by-NRHS matrices.

The bounded Bunch-Kaufman () diagonal pivoting method is used to factor A as

   A = U * D * U**T,  if UPLO = 'U', or
   A = L * D * L**T,  if UPLO = 'L',

where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is Hermitian and block diagonal with 1-by-1 and 2-by-2 diagonal blocks. Iconic structure honestly 💅

ZHETRF_ROOK is called to compute the factorization of a complex Hermitian matrix A using the bounded Bunch-Kaufman () diagonal pivoting method.

The factored form of A is then used to solve the system of equations A * X = B by calling ZHETRS_ROOK (uses BLAS 2). It's a whole tag-team situation 🫶

Parameters

  • UPLO — CHARACTER*1. Which triangle are we working with:
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N — INTEGER. The number of linear equations, i.e., the order of the matrix A. Constraint: N >= 0.
  • NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. Constraint: NRHS >= 0.
  • A — COMPLEX*16 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, if INFO = 0, the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U**H or A = L*D*L**H as computed by ZHETRF_ROOK. Note the **H bestie, we're in conjugate-transpose territory now 🦋

  • LDA — INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,N).
  • IPIV — INTEGER array, dimension (N). Details of the interchanges and the block structure of D. ⚠️ Read this part carefully, it's different from the real version:

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 interchanged, 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 interchanged, and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
Not me stressing the "only last / only first KB elements are set" thing — the rest of IPIV is not filled in, so don't go reading it like it means something 🙈
  • B — COMPLEX*16 array, dimension (LDB,NRHS). On entry: the N-by-NRHS right hand side matrix B. On exit, if INFO = 0: the N-by-NRHS solution matrix X. 💖
  • LDB — INTEGER. The leading dimension of the array B. Constraint: LDB >= max(1,N).
  • WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • LWORK — INTEGER. The length of WORK. Constraint: LWORK >= 1, and for best performance LWORK >= max(1,N*NB), where NB is the optimal blocksize for ZHETRF_ROOK.
Here's the fun part: for LWORK < N, TRS will be done with Level BLAS 2 — and for LWORK >= N, TRS will be done with Level BLAS 3. So a bigger workspace literally levels you up ⭐ More WORK, more speed, iykyk 🔥

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.

  • INFO — INTEGER. The status check-in:
    • = 0: successful exit 🎀
    • < 0: if INFO = -i, the i-th argument had an illegal value
    • > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, so the solution could not be computed. She tried, she really did 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

  • 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

That's the tail of the zhesv_rook writeup — Definition at line 203 of file zhesv_rook.f. ✨ And now, bestie, the very next thing in this file is a whole other queen.

🦋 zsysv_rook — the symmetric solve, rook edition 💜

subroutine zsysv_rook (character uplo, integer n, integer nrhs, complex*16, dimension( lda, * ) a, integer lda, integer, dimension( * ) ipiv, complex*16, dimension( ldb, * ) b, integer ldb, complex*16, dimension( * ) work, integer lwork, integer info)

One-liner so you know what you're walking into: ZSYSV_ROOK computes the solution to system of linear equations A * X = B for SY matrices. 💅

🎀 Purpose

Okay so the whole point of ZSYSV_ROOK is that it solves a complex 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. Cute, simple, standard. 🫶

It does it with the diagonal pivoting method, factoring A as

A = U * D * U**T,  if UPLO = 'U', or
A = L * D * L**T,  if UPLO = 'L',

…where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is symmetric and block diagonal with 1-by-1 and 2-by-2 diagonal blocks. D is honestly giving main character energy in this whole story.

So then ZSYTRF_ROOK gets called to compute the factorization of a complex symmetric matrix A using the bounded Bunch-Kaufman () diagonal pivoting method. (Yes, those parentheses are empty in the original — we don't gatekeep, we just report. 🙈)

And then the factored form of A is used to solve the system of equations A * X = B by calling ZSYTRS_ROOK. Two-step slay, no cap. ✨

💖 Parameters

UPLO — is CHARACTER*1

  • = 'U': Upper triangle of A is stored;
  • = 'L': Lower triangle of A is stored.

Only one of them, bestie, pick a side.

N — is INTEGER. The number of linear equations, i.e., the order of the matrix A. N >= 0. (Negative dimensions are not the vibe.)

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

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, if INFO = 0, the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U**T or A = L*D*L**T as computed by ZSYTRF_ROOK.

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

IPIV — is INTEGER array, dimension (N). Details of the interchanges and the block structure of D, as determined by ZSYTRF_ROOK.

  • 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, 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, D(k:k+1,k:k+1) is a 2-by-2 diagonal block.

Notice which neighbour the negative case reaches for: k-1 when you're upper, k+1 when you're lower. That's the whole ✨ thing ✨ — don't mix them up.

B — is COMPLEX*16 array, dimension (LDB,NRHS). On entry, the N-by-NRHS right hand side matrix B. On exit, if INFO = 0, the N-by-NRHS solution matrix X. It literally transforms in place, an icon. 💅

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

WORK — is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

LWORK — is INTEGER. The length of WORK. LWORK >= 1, and for best performance LWORK >= max(1,N*NB), where NB is the optimal blocksize for ZSYTRF_ROOK.

TRS will be done with Level 2 BLAS.

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.

🧚 Pro tip straight from the page, no inventing: for best performance, size LWORK as max(1,N*NB). And LWORK = -1 is the "just tell me how much room I need" mode — it won't even yell at you via XERBLA.

INFO — is INTEGER

  • = 0: successful exit
  • < 0: if INFO = -i, the i-th argument had an illegal value
  • > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, so the solution could not be computed.
🚨 Bestie, listen to this one: INFO > 0 means the factorization finished but D is exactly singular, so the solution could not be computed. It's not a crash, but it is definitely not the outcome you were manifesting. 😭

👑 Author

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

🌸 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

And that's the roundup for this routine: Definition at line 202 of file zsysv_rook.f. 🫶

📜 Author (yes, again — the Doxygen kind)

Generated automatically by Doxygen for LAPACK from the source code. So nobody hand-wrote that last bit, it's just the machine doing its little thing. 🎀

Okay that's the whole hesv_rook(3) page, bestie — we made it to the end and you ate. 💖 This one's from LAPACK Version 3.12.0, and the hesv_rook(3) page you've been reading is the whole thing, from NAME all the way down to this little wave goodbye. Go solve something symmetric. 🦋👑

📦 where this page comes from