/home/abui...RC/cpbsv.f(3)

💖 `cpbsv.f(3)` — LAPACK Library Functions Manual 💖

Okay bestie, this is the Library Functions Manual page for /home/abui...RC/cpbsv.f(3) — header energy folded in cute so we don’t have to copy the whole line. LAPACK is about to solve a Hermitian positive definite band system, and we’re gonna understand it fr fr. 💅✨

🌸 NAME 🌸

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

✨ SYNOPSIS ✨

🎀 Functions/Subroutines 🎀

   subroutine CPBSV (uplo, n, kd, nrhs, ab, ldab, b, ldb, info)
        CPBSV computes the solution to system of linear equations A * X = B
       for OTHER matrices

💅 Function/Subroutine Documentation 💅

subroutine CPBSV (character uplo, integer n, integer kd, integer nrhs,
     complex, dimension( ldab, * ) ab, integer ldab, complex, dimension( ldb,
     * ) b, integer ldb, integer info)

Yep, it’s the same CPBSV — and the doc line still says: CPBSV computes the solution to system of linear equations A * X = B for OTHER matrices.

🧚 Purpose 🧚

Here’s the tea, bestie: CPBSV computes the solution to a complex system of linear equations

A * X = B,

where A is an N-by-N Hermitian positive definite band matrix and X and B are N-by-NRHS matrices. No cap, that’s the whole quest.

The Cholesky decomposition is used to factor A as

A = U**H * U,  if UPLO = 'U', or
A = L * L**H,  if UPLO = 'L',

where U is an upper triangular band matrix, and L is a lower triangular band matrix, with the same number of superdiagonals or subdiagonals as A. The factored form of A is then used to solve the system of equations A * X = B.

🧸 Parameters 🧸

UPLO 🎀

UPLO is CHARACTER*1 — it tells us which triangle of A is stored:

= '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. Must be N >= 0.

KD 🎀

KD is INTEGER — the number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. Must be KD >= 0.

NRHS 🎀

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

AB 🎀

AB is COMPLEX array, dimension (LDAB,N).

On entry, it’s the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB like this:

if UPLO = 'U', AB(KD+1+i-j,j) = A(i,j) for max(1,j-KD)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(N,j+KD).

See below for further details. 👀

On exit, if INFO = 0, it’s the triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H of the band matrix A, in the same storage format as A.

LDAB 🎀

LDAB is INTEGER — the leading dimension of the array AB. Must be LDAB >= KD+1.

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 — the leading dimension of the array B. Must be LDB >= max(1,N).

INFO 🎀

INFO is INTEGER — the vibe check at the end:

= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, the leading principal minor of order i
      of A is not positive, so the factorization could not
      be completed, and the solution has not been computed.

Bestie, pay attention here: INFO < 0 means an argument was illegal; INFO > 0 means that leading principal minor of order i of A was not positive, so the factorization could not be completed, and the solution has not been computed. Check it, periodt. 💀✨

👑 Author 👑

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

🔥 Further Details 🔥

The band storage scheme is illustrated by the following example, when N = 6, KD = 2, and UPLO = 'U':

On entry: On exit:

    *    *   a13  a24  a35  a46      *    *   u13  u24  u35  u46
    *   a12  a23  a34  a45  a56      *   u12  u23  u34  u45  u56
   a11  a22  a33  a44  a55  a66     u11  u22  u33  u44  u55  u66

Similarly, if UPLO = 'L' the format of A is as follows: