gbtrf(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💅 gbtrf(3) — the triangular factor bestie

okay so bestie, this is gbtrf(3) from the Library Functions Manual, and it is literally the band-matrix LU factorization moment. we're keeping every flag, constraint, and cursed little matrix diagram, no cap. 🫶

✨ NAME ✨

gbtrf — gbtrf: triangular factor

🌸 SYNOPSIS 🌸

Functions

  • subroutine cgbtrf (m, n, kl, ku, ab, ldab, ipiv, info) — CGBTRF
  • subroutine dgbtrf (m, n, kl, ku, ab, ldab, ipiv, info) — DGBTRF
  • subroutine sgbtrf (m, n, kl, ku, ab, ldab, ipiv, info) — SGBTRF
  • subroutine zgbtrf (m, n, kl, ku, ab, ldab, ipiv, info) — ZGBTRF

🎀 Detailed Description 🎀

the full breakdown lives in the function docs below, bestie. it's giving “we go function by function and we do not skip a single parameter.” 💖

🧚 Function Documentation 🧚

💜 subroutine cgbtrf

subroutine cgbtrf (integer m, integer n, integer kl, integer ku, complex,
     dimension( ldab, * ) ab, integer ldab, integer, dimension( * ) ipiv,
     integer info)

CGBTRF

Purpose

CGBTRF computes an LU factorization of a complex m-by-n band matrix A using partial pivoting with row interchanges.

This is the blocked version of the algorithm, calling Level 3 BLAS. slay. ✨

Parameters

  • M

M is INTEGER. the number of rows of the matrix A. M >= 0.

  • N

N is INTEGER. the number of columns 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.

  • 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(m,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 (min(M,N)). the pivot indices; for 1 <= i <= min(M,N), row i of the matrix was interchanged with row IPIV(i).

  • 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 division by zero will occur if it is used to solve a system of equations.
bestie, that INFO > 0 case is not a vibe. U(i,i) is exactly zero, the factor U is exactly singular, and division by zero will occur if it is used to solve a system of equations. 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 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. 🦋

Definition at line 143 of file cgbtrf.f.

💙 subroutine dgbtrf

subroutine dgbtrf (integer m, integer n, integer kl, integer ku, double
     precision, dimension( ldab, * ) ab, integer ldab, integer, dimension( *
     ) ipiv, integer info)

DGBTRF

Purpose

DGBTRF computes an LU factorization of a real m-by-n band matrix A using partial pivoting with row interchanges.

This is the blocked version of the algorithm, calling Level 3 BLAS. iconic. 💅

Parameters

  • M

M is INTEGER. the number of rows of the matrix A. M >= 0.

  • N

N is INTEGER. the number of columns 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.

  • 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(m,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 (min(M,N)). the pivot indices; for 1 <= i <= min(M,N), row i of the matrix was interchanged with row IPIV(i).

  • 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 division by zero will occur if it is used to solve a system of equations.
again with the singular U warning: INFO > 0 means U(i,i) is exactly zero. the factorization completed, but the factor U is exactly singular, and division by zero will occur if it is used to solve a system of equations. do not ignore her.

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

Definition at line 143 of file dgbtrf.f.

💖 subroutine sgbtrf

subroutine sgbtrf (integer m, integer n, integer kl, integer ku, real,
     dimension( ldab, * ) ab, integer ldab, integer, dimension( * ) ipiv,
     integer info)

SGBTRF

Purpose

SGBTRF computes an LU factorization of a real m-by-n band matrix A using partial pivoting with row interchanges.

This is the blocked version of the algorithm, calling Level 3 BLAS. main character energy fr fr. 🌟

Parameters

  • M

M is INTEGER. the number of rows of the matrix A. M >= 0.

  • N

N is INTEGER. the number of columns 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.

  • AB

AB is 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(m,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 (min(M,N)). the pivot indices; for 1 <= i <= min(M,N), row i of the matrix was interchanged with row IPIV(i).

  • 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 division by zero will occur if it is used to solve a system of equations.
one more time for the people in the back: INFO > 0 means U(i,i) is exactly zero. the factorization has been completed, but the factor U is exactly singular, and division by zero will occur if it is used to solve a system of equations. not cute, but important.

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details

okay so picture this 💖 — same band storage scheme, but as a whole aesthetic. When M = N = 6, KL = 2, KU = 1, here's literally what it looks like. Left half is On entry, right half is 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   *    *

k so read the room bestie 🫶 — array elements marked * are not used by the routine, they're just vibing there being decorative. Elements marked + need not be set on entry, but the routine does require them so it can stash elements of U, because of fill-in resulting from the row interchanges. So like, don't panic if they're garbage going in, but don't touch them after 😭

Definition at line 143 of file sgbtrf.f.

🌟 zgbtrf — the complex/COMPLEX*16 glow-up 💅

subroutine zgbtrf (integer m, integer n, integer kl, integer ku, complex*16,
    dimension( ldab, * ) ab, integer ldab, integer, dimension( * ) ipiv,
    integer info)

✨ Purpose ✨

okay so ZGBTRF computes an LU factorization of a complex m-by-n band matrix A using partial pivoting with row interchanges. slay 💖

and like, for the record: this is the blocked version of the algorithm, calling Level 3 BLAS. highkey iconic 🎀

🌸 Parameters 🌸

  • M — M is INTEGER. the number of rows of the matrix A. M >= 0. no cap.
  • N — N is INTEGER. the number of columns of the matrix A. N >= 0. periodt.
  • 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.
  • AB — AB is COMPLEX*16 array, dimension (LDAB,N). okay so:
    • On entry, it's 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 (they're just... there 🦋). the j-th column of A is stored in the j-th column of the array AB like this: AB(kl+ku+1+i-j,j) = A(i,j) for max(1,j-ku)<=i<=min(m,j+kl).
    • On exit, it's the factorization details: 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. bestie do not skimp on this one.
  • IPIV — IPIV is INTEGER array, dimension (min(M,N)). the pivot indices; for 1 <= i <= min(M,N), row i of the matrix was interchanged with row IPIV(i). it's giving receipts for every swap 🔥
  • 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 division by zero will occur if it is used to solve a system of equations. ⚠️ like, it finished, but she's singular. do not pass go.

💜 Author 💜

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

🦋 Further Details 🦋

(the band storage scheme again, because consistency is a lifestyle 💅 — illustrated for when M = N = 6, KL = 2, KU = 1:)

     *    *    *    +    +    +       *    *    *   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   *    *

again for the people in the back 📣 — 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. 🌈

Definition at line 143 of file zgbtrf.f.

🎀 AUTHOR 🎀

Generated automatically by Doxygen for LAPACK from the source code. (not me writing my own press release, the robot did it 🤖💖)

and that's the whole vibe check, bestie — this beauty is from LAPACK, Version 3.12.0, living at gbtrf(3). go forth and factorize 💅✨🍓

📦 where this page comes from