gbsv(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

🫶 gbsv(3) — the group chat guide to factor-and-solve 🫶

okay so bestie, grab your iced coffee ☕ because this is the gbsv page. That's the factor and solve one — the LAPACK squad that takes a band matrix and just… handles it. Solving A * X = B where A is banded? Yeah. That's the whole vibe. Let's get into it 💅

🌸 NAME 🌸

gbsv — gbsv: factor and solve. that's it, that's the name, she's concise 👑

✨ SYNOPSIS ✨

🌈 Functions 🌈

so there are literally four of these, one for each flavour of arithmetic, and they all take the exact same argument list. it's giving "same energy, different dtype" fr fr 💖

  • subroutine cgbsv (n, kl, ku, nrhs, ab, ldab, ipiv, b, ldb, info) — CGBSV computes the solution to system of linear equations A * X = B for GB matrices (simple driver)
  • subroutine dgbsv (n, kl, ku, nrhs, ab, ldab, ipiv, b, ldb, info) — DGBSV computes the solution to system of linear equations A * X = B for GB matrices (simple driver)
  • subroutine sgbsv (n, kl, ku, nrhs, ab, ldab, ipiv, b, ldb, info) — SGBSV computes the solution to system of linear equations A * X = B for GB matrices (simple driver)
  • subroutine zgbsv (n, kl, ku, nrhs, ab, ldab, ipiv, b, ldb, info) — ZGBSV computes the solution to system of linear equations A * X = B for GB matrices (simple driver)

🦋 Detailed Description 🦋

(that's literally all it says — the real ✨content✨ is in the function docs below, iykyk)

🎀 Function Documentation 🎀

💜 cgbsv — the COMPLEX one 💜

subroutine cgbsv (integer n, integer kl, integer ku, integer nrhs, complex,
    dimension( ldab, * ) ab, integer ldab, integer, dimension( * ) ipiv,
    complex, dimension( ldb, * ) b, integer ldb, integer info)

CGBSV computes the solution to system of linear equations A * X = B for GB matrices (simple driver)

🔥 Purpose 🔥

CGBSV computes the solution to a complex system of linear equations A * X = B, where A is a band matrix of order N with KL subdiagonals and KU superdiagonals, and X and B are N-by-NRHS matrices.

The LU decomposition with partial pivoting and row interchanges is used to factor A as A = L * U, where L is a product of permutation and unit lower triangular matrices with KL subdiagonals, and U is upper triangular with KL+KU superdiagonals. The factored form of A is then used to solve the system of equations A * X = B.

🧚 Parameters 🧚

  • N — N is INTEGER. The number of linear equations, i.e., the order of the matrix A. N >= 0.
  • KL — KL is INTEGER. The number of subdiagonals within the band of A. KL >= 0.
  • KU — KU is INTEGER. The number of superdiagonals within the band of A. KU >= 0.
  • NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • AB — AB is COMPLEX array, dimension (LDAB,N). On entry, the matrix A in band storage, in rows KL+1 to 2*KL+KU+1; rows 1 to KL of the array need not be set. The j-th column of A is stored in the j-th column of the array AB as follows: AB(KL+KU+1+i-j,j) = A(i,j) for max(1,j-KU)<=i<=min(N,j+KL). On exit, details of the factorization: U is stored as an upper triangular band matrix with KL+KU superdiagonals in rows 1 to KL+KU+1, and the multipliers used during the factorization are stored in rows KL+KU+2 to 2*KL+KU+1. See below for further details. 👀
  • LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= 2*KL+KU+1.
  • IPIV — IPIV is INTEGER array, dimension (N). The pivot indices that define the permutation matrix P; row i of the matrix was interchanged with row IPIV(i).
  • 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).
  • INFO — INFO is INTEGER.
    • = 0: successful exit 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value 🙈
    • > 0: if INFO = i, U(i,i) is exactly zero. The factorization has been completed, but the factor U is exactly singular, and the solution has not been computed. 💀 (yeah, that one's a bad day)

👑 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 M = N = 6, KL = 2, KU = 1:

On entry:                       On exit:

    *    *    *    +    +    +       *    *    *   u14  u25  u36
    *    *    +    +    +    +       *    *   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
   a21  a32  a43  a54  a65   *      m21  m32  m43  m54  m65   *
   a31  a42  a53  a64   *    *      m31  m42  m53  m64   *    *

Array elements marked * are not used by the routine; elements marked + need not be set on entry, but are required by the routine to store elements of U because of fill-in resulting from the row interchanges. lowkey iconic how the + slots are just reserving space for the chaos 😌

Definition at line 161 of file cgbsv.f.

💙 dgbsv — the DOUBLE PRECISION one 💙

subroutine dgbsv (integer n, integer kl, integer ku, integer nrhs, double
    precision, dimension( ldab, * ) ab, integer ldab, integer, dimension( *
    ) ipiv, double precision, dimension( ldb, * ) b, integer ldb, integer
    info)

DGBSV computes the solution to system of linear equations A * X = B for GB matrices (simple driver)

🔥 Purpose 🔥

DGBSV computes the solution to a real system of linear equations A * X = B, where A is a band matrix of order N with KL subdiagonals and KU superdiagonals, and X and B are N-by-NRHS matrices.

The LU decomposition with partial pivoting and row interchanges is used to factor A as A = L * U, where L is a product of permutation and unit lower triangular matrices with KL subdiagonals, and U is upper triangular with KL+KU superdiagonals. The factored form of A is then used to solve the system of equations A * X = B.

🧚 Parameters 🧚

  • N — N is INTEGER. The number of linear equations, i.e., the order of the matrix A. N >= 0.
  • KL — KL is INTEGER. The number of subdiagonals within the band of A. KL >= 0.
  • KU — KU is INTEGER. The number of superdiagonals within the band of A. KU >= 0.
  • NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • AB — AB is DOUBLE PRECISION array, dimension (LDAB,N). On entry, the matrix A in band storage, in rows KL+1 to 2*KL+KU+1; rows 1 to KL of the array need not be set. The j-th column of A is stored in the j-th column of the array AB as follows: AB(KL+KU+1+i-j,j) = A(i,j) for max(1,j-KU)<=i<=min(N,j+KL). On exit, details of the factorization: U is stored as an upper triangular band matrix with KL+KU superdiagonals in rows 1 to KL+KU+1, and the multipliers used during the factorization are stored in rows KL+KU+2 to 2*KL+KU+1. See below for further details. 👀
  • LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= 2*KL+KU+1.
  • IPIV — IPIV is INTEGER array, dimension (N). The pivot indices that define the permutation matrix P; row i of the matrix was interchanged with row IPIV(i).
  • 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).
  • INFO — INFO is INTEGER.
    • = 0: successful exit 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value 🙈
    • > 0: if INFO = i, U(i,i) is exactly zero. The factorization has been completed, but the factor U is exactly singular, and the solution has not been computed. 💀 (yeah, that one's a bad day)

👑 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 M = N = 6, KL = 2, KU = 1:

On entry:                       On exit:

    *    *    *    +    +    +       *    *    *   u14  u25  u36
    *    *    +    +    +    +       *    *   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
   a21  a32  a43  a54  a65   *      m21  m32  m43  m54  m65   *
   a31  a42  a53  a64   *    *      m31  m42  m53  m64   *    *

Array elements marked * are not used by the routine; elements marked + need not be set on entry, but are required by the routine to store elements of U because of fill-in resulting from the row interchanges. (yes it's the same table, it's the same scheme, don't come for me 🫶)

Definition at line 161 of file dgbsv.f.

🌸 sgbsv — the REAL one 🌸

subroutine sgbsv (integer n, integer kl, integer ku, integer nrhs, real,
    dimension( ldab, * ) ab, integer ldab, integer, dimension( * ) ipiv,
    real, dimension( ldb, * ) b, integer ldb, integer info)

SGBSV computes the solution to system of linear equations A * X = B for GB matrices (simple driver)

🔥 Purpose 🔥

…and part 2 slides in right here with the rest of sgbsv, bestie — the math does not stop, no cap 🦋

so like, what is sgbsv actually doing for you? 💅

It computes the solution to a real system of linear equations

A * X = B

where A is a band matrix of order N with KL subdiagonals and KU superdiagonals, and X and B are N-by-NRHS matrices.

The LU decomposition with partial pivoting and row interchanges is used to factor A as A = L * U, where L is a product of permutation and unit lower triangular matrices with KL subdiagonals, and U is upper triangular with KL+KU superdiagonals. The factored form of A is then used to solve the system of equations A * X = B. no cap, that's the whole plot 🎀

Parameters 🌸

  • N — INTEGER. The number of linear equations, i.e., the order of the matrix A. N >= 0.
  • KL — INTEGER. The number of subdiagonals within the band of A. KL >= 0.
  • KU — INTEGER. The number of superdiagonals within the band of A. KU >= 0.
  • NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • AB — REAL array, dimension (LDAB,N). On entry, the matrix A in band storage, in rows KL+1 to 2*KL+KU+1; rows 1 to KL of the array need not be set. The j-th column of A is stored in the j-th column of the array AB as follows: AB(KL+KU+1+i-j,j) = A(i,j) for max(1,j-KU)<=i<=min(N,j+KL). On exit, details of the factorization: U is stored as an upper triangular band matrix with KL+KU superdiagonals in rows 1 to KL+KU+1, and the multipliers used during the factorization are stored in rows KL+KU+2 to 2*KL+KU+1. See below for further details.
  • LDAB — INTEGER. The leading dimension of the array AB. LDAB >= 2*KL+KU+1.
  • IPIV — INTEGER array, dimension (N). The pivot indices that define the permutation matrix P; row i of the matrix was interchanged with row IPIV(i).
  • 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.
  • LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
  • INFO — INTEGER. These are the three moods, bestie:
    • = 0: successful exit ✨
    • < 0: if INFO = -i, the i-th argument had an illegal value 🙈
    • > 0: if INFO = i, U(i,i) is exactly zero. The factorization has been completed, but the factor U is exactly singular, and the solution has not been computed. 💀

Author 🫶

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

Further Details: 💫

Okay so the band storage scheme is genuinely iconic once you see it. Here's the example, when M = N = 6, KL = 2, KU = 1:

On entry:                       On exit:

    *    *    *    +    +    +       *    *    *   u14  u25  u36
    *    *    +    +    +    +       *    *   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
   a21  a32  a43  a54  a65   *      m21  m32  m43  m54  m65   *
   a31  a42  a53  a64   *    *      m31  m42  m53  m64   *    *

Array elements marked * are not used by the routine; elements marked + need not be set on entry, but are required by the routine to store elements of U because of fill-in resulting from the row interchanges. the + girlies are doing unpaid labor fr fr 😭

Definition at line 161 of file sgbsv.f.

zgbsv 🦋 — the complex one, main character energy

subroutine zgbsv (integer n, integer kl, integer ku, integer nrhs,
    complex*16, dimension( ldab, * ) ab, integer ldab, integer, dimension( *
    ) ipiv, complex*16, dimension( ldb, * ) b, integer ldb, integer info)

ZGBSV computes the solution to system of linear equations A * X = B for GB matrices (simple driver). 💜

Purpose: ⭐

ZGBSV computes the solution to a complex system of linear equations

A * X = B

where A is a band matrix of order N with KL subdiagonals and KU superdiagonals, and X and B are N-by-NRHS matrices.

The LU decomposition with partial pivoting and row interchanges is used to factor A as A = L * U, where L is a product of permutation and unit lower triangular matrices with KL subdiagonals, and U is upper triangular with KL+KU superdiagonals. The factored form of A is then used to solve the system of equations A * X = B. literally the same slay as sgbsv, just wearing complex glitter 🌈

Parameters 🌸

  • N — INTEGER. The number of linear equations, i.e., the order of the matrix A. N >= 0.
  • KL — INTEGER. The number of subdiagonals within the band of A. KL >= 0.
  • KU — INTEGER. The number of superdiagonals within the band of A. KU >= 0.
  • NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • AB — COMPLEX*16 array, dimension (LDAB,N). On entry, the matrix A in band storage, in rows KL+1 to 2*KL+KU+1; rows 1 to KL of the array need not be set. The j-th column of A is stored in the j-th column of the array AB as follows: AB(KL+KU+1+i-j,j) = A(i,j) for max(1,j-KU)<=i<=min(N,j+KL). On exit, details of the factorization: U is stored as an upper triangular band matrix with KL+KU superdiagonals in rows 1 to KL+KU+1, and the multipliers used during the factorization are stored in rows KL+KU+2 to 2*KL+KU+1. See below for further details.
  • LDAB — INTEGER. The leading dimension of the array AB. LDAB >= 2*KL+KU+1.
  • IPIV — INTEGER array, dimension (N). The pivot indices that define the permutation matrix P; row i of the matrix was interchanged with row IPIV(i).
  • 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. LDB >= max(1,N).
  • INFO — INTEGER. the three moods again, keep up 🎀
    • = 0: successful exit
    • < 0: if INFO = -i, the i-th argument had an illegal value
    • > 0: if INFO = i, U(i,i) is exactly zero. The factorization has been completed, but the factor U is exactly singular, and the solution has not been computed. (yes this is a real heartbreak, the solve just doesn't happen 😭)

Author 🫶

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

Further Details: 💫

Same diagram, same energy — the band storage scheme illustrated by the following example, when M = N = 6, KL = 2, KU = 1:

On entry:                       On exit:

    *    *    *    +    +    +       *    *    *   u14  u25  u36
    *    *    +    +    +    +       *    *   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
   a21  a32  a43  a54  a65   *      m21  m32  m43  m54  m65   *
   a31  a42  a53  a64   *    *      m31  m42  m53  m64   *    *

Array elements marked * are not used by the routine; elements marked + need not be set on entry, but are required by the routine to store elements of U because of fill-in resulting from the row interchanges. the + entries are like, reserved seating, respect it 💅

Definition at line 161 of file zgbsv.f.

Author 🧚

Generated automatically by Doxygen for LAPACK from the source code. (the robots wrote this bit, not me 🤖✨)

and that's the whole page, bestie — LAPACK Version 3.12.0, the gbsv(3) moment, documented and dusted. go solve something banded. periodt 💖🎀🦋

📦 where this page comes from