gbequ(3)

📦

version 3.12.1 · 9 versions

3.12.1 · arch rolling (latest)
3.12.0 · opensuse-leap 16.0
3.12.1 · ubuntu stonking
3.12.1 · ubuntu questing
3.12.0 · ubuntu noble
3.12.0 · ubuntu noble
3.12.0 · centos-stream 10, fedora 43, fedora 44
3.12.1 · ubuntu resolute
3.12.1 · debian trixie

🦋 gbequ — the equilibration girlies ✨

okay so bestie, listen: this is gbequ from the Library Functions Manual, and she is literally the glow-up artist for band matrices. four routines, one job. let's get into it 💅

🌸 SYNOPSIS

the four icons in question, all queued up:

subroutine cgbequ (m, n, kl, ku, ab, ldab, r, c, rowcnd, colcnd, amax, info)
    CGBEQU
subroutine dgbequ (m, n, kl, ku, ab, ldab, r, c, rowcnd, colcnd, amax, info)
    DGBEQU
subroutine sgbequ (m, n, kl, ku, ab, ldab, r, c, rowcnd, colcnd, amax, info)
    SGBEQU
subroutine zgbequ (m, n, kl, ku, ab, ldab, r, c, rowcnd, colcnd, amax, info)
    ZGBEQU

like yes, the names are just one letter off from each other and that's the whole bit 🙈 — one for each precision, same energy.

🔥 DETAILED DESCRIPTION

no cap, this page is basically four copies of the same function wearing different outfits. same purpose, same parameters, same author credits — the only thing that changes is whether your numbers are REAL, DOUBLE PRECISION, or COMPLEX. we love a consistent queen 👑

💖 FUNCTION DOCUMENTATION

`subroutine cgbequ`</p>

subroutine cgbequ (integer m, integer n, integer kl, integer ku, complex,
    dimension( ldab, * ) ab, integer ldab, real, dimension( * ) r, real,
    dimension( * ) c, real rowcnd, real colcnd, real amax, integer info)
    CGBEQU

✨ Purpose

okay so here's the tea, straight from the source:

!>
!> CGBEQU computes row and column scalings intended to equilibrate an
!> M-by-N band matrix A and reduce its condition number.  R returns the
!> row scale factors and C the column scale factors, chosen to try to
!> make the largest element in each row and column of the matrix B with
!> elements B(i,j)=R(i)*A(i,j)*C(j) have absolute value 1.
!>
!> R(i) and C(j) are restricted to be between SMLNUM = smallest safe
!> number and BIGNUM = largest safe number.  Use of these scaling
!> factors is not guaranteed to reduce the condition number of A but
!> works well in practice.
!>

translation, bestie: she picks scale factors R and C so that B(i,j)=R(i)*A(i,j)*C(j) has the biggest element in every row and column sitting at absolute value 1. it's giving "make the matrix presentable". 📸

and the vibe check: R(i) and C(j) are clamped between SMLNUM = smallest safe number and BIGNUM = largest safe number. ⚠️ important caveat though — using these factors is not guaranteed to reduce the condition number of A. it just works well in practice, iykyk. no lies told.

🎀 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). the band matrix A, stored in rows 1 to KL+KU+1. and here's exactly how the j-th column of A lands in the j-th column of AB:

AB(ku+1+i-j,j) = A(i,j) for max(1,j-ku)<=i<=min(m,j+kl).

LDAB — LDAB is INTEGER. the leading dimension of the array AB. LDAB >= KL+KU+1.
R — R is REAL array, dimension (M). if INFO = 0, or INFO > M, R contains the row scale factors for A.
C — C is REAL array, dimension (N). if INFO = 0, C contains the column scale factors for A.
ROWCND — ROWCND is REAL. if INFO = 0 or INFO > M, ROWCND contains the ratio of the smallest R(i) to the largest R(i). if ROWCND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by R.
COLCND — COLCND is REAL. if INFO = 0, COLCND contains the ratio of the smallest C(i) to the largest C(i). if COLCND >= 0.1, it is not worth scaling by C.
AMAX — AMAX is REAL. absolute value of largest matrix element. if AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
INFO — INFO is INTEGER.

= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, and i is
      <= M:  the i-th row of A is exactly zero
      >  M:  the (i-M)-th column of A is exactly zero

🌈 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Definition at line 152 of file cgbequ.f.

`subroutine dgbequ`

subroutine dgbequ (integer m, integer n, integer kl, integer ku, double
    precision, dimension( ldab, * ) ab, integer ldab, double precision,
    dimension( * ) r, double precision, dimension( * ) c, double precision
    rowcnd, double precision colcnd, double precision amax, integer info)
    DGBEQU

✨ Purpose

same purpose text, double the precision, same slay:

!>
!> DGBEQU computes row and column scalings intended to equilibrate an
!> M-by-N band matrix A and reduce its condition number.  R returns the
!> row scale factors and C the column scale factors, chosen to try to
!> make the largest element in each row and column of the matrix B with
!> elements B(i,j)=R(i)*A(i,j)*C(j) have absolute value 1.
!>
!> R(i) and C(j) are restricted to be between SMLNUM = smallest safe
!> number and BIGNUM = largest safe number.  Use of these scaling
!> factors is not guaranteed to reduce the condition number of A but
!> works well in practice.
!>

so: R = row scale factors, C = column scale factors, B(i,j)=R(i)*A(i,j)*C(j) should have max absolute value 1 in each row and column, and R(i)/C(j) stay inside SMLNUM → BIGNUM. 🫶 and again — not guaranteed to reduce the condition number of A, just works well in practice. periodt.

🎀 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). the band matrix A, stored in rows 1 to KL+KU+1, and the j-th column of A lives in the j-th column of AB like so:

AB(ku+1+i-j,j) = A(i,j) for max(1,j-ku)<=i<=min(m,j+kl).

LDAB — LDAB is INTEGER. the leading dimension of the array AB. LDAB >= KL+KU+1.
R — R is DOUBLE PRECISION array, dimension (M). if INFO = 0, or INFO > M, R contains the row scale factors for A.
C — C is DOUBLE PRECISION array, dimension (N). if INFO = 0, C contains the column scale factors for A.
ROWCND — ROWCND is DOUBLE PRECISION. if INFO = 0 or INFO > M, ROWCND contains the ratio of the smallest R(i) to the largest R(i). if ROWCND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by R.
COLCND — COLCND is DOUBLE PRECISION. if INFO = 0, COLCND contains the ratio of the smallest C(i) to the largest C(i). if COLCND >= 0.1, it is not worth scaling by C.
AMAX — AMAX is DOUBLE PRECISION. absolute value of largest matrix element. if AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
INFO — INFO is INTEGER.

= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, and i is
      <= M:  the i-th row of A is exactly zero
      >  M:  the (i-M)-th column of A is exactly zero

🌈 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Definition at line 151 of file dgbequ.f.

`subroutine sgbequ`

subroutine sgbequ (integer m, integer n, integer kl, integer ku, real,
    dimension( ldab, * ) ab, integer ldab, real, dimension( * ) r, real,
    dimension( * ) c, real rowcnd, real colcnd, real amax, integer info)
    SGBEQU

✨ Purpose

you already know the words, but here they are again because every detail matters:

!>
!> SGBEQU computes row and column scalings intended to equilibrate an
!> M-by-N band matrix A and reduce its condition number.  R returns the
!> row scale factors and C the column scale factors, chosen to try to
!> make the largest element in each row and column of the matrix B with
!> elements B(i,j)=R(i)*A(i,j)*C(j) have absolute value 1.
!>
!> R(i) and C(j) are restricted to be between SMLNUM = smallest safe
!> number and BIGNUM = largest safe number.  Use of these scaling
!> factors is not guaranteed to reduce the condition number of A but
!> works well in practice.
!>

single precision this time, same mission: pick R (rows) and C (columns) so B(i,j)=R(i)*A(i,j)*C(j) tops out at absolute value 1, keep R(i) and C(j) in the SMLNUM … BIGNUM safe range, and ⚠️ remember the scaling isn't guaranteed to bring the condition number down — it's just good in practice, 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). the band matrix A, stored in rows 1 to KL+KU+1, with the j-th column of A sitting in the j-th column of AB as:

AB(ku+1+i-j,j) = A(i,j) for max(1,j-ku)<=i<=min(m,j+kl).

LDAB — LDAB is INTEGER. the leading dimension of the array AB. LDAB >= KL+KU+1.
R — R is REAL array, dimension (M). if INFO = 0, or INFO > M, R contains the row scale factors for A.
C — C is REAL array, dimension (N). if INFO = 0, C contains the column scale factors for A.
ROWCND — ROWCND is REAL. if INFO = 0 or INFO > M, ROWCND contains the ratio of the smallest R(i) to the largest R(i). if ROWCND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by R.
COLCND — COLCND is REAL. if INFO = 0, COLCND contains the ratio of the smallest C(i) to the largest C(i). if COLCND >= 0.1, it is not worth scaling by C.
AMAX — AMAX is REAL. absolute value of largest matrix element. if AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
INFO — INFO is INTEGER.

= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, and i is
      <= M:  the i-th row of A is exactly zero
      >  M:  the (i-M)-th column of A is exactly zero

ok bestie that's where this part wraps — the rest of the icons are still queued up 💜

INFO — INFO is INTEGER. bestie this is the ✨vibe report✨, read it before you trust anything else:
- = 0: successful exit 🎉 slay, we're done here
- < 0: if INFO = -i, the i-th argument had an illegal value 😭 someone passed nonsense, go check argument number i
- > 0: if INFO = i, and i is
  - <= M: the i-th row of A is exactly zero 💀 like, entirely zero, no thoughts head empty
  - > M: the (i-M)-th column of A is exactly zero 💀 same energy, but a column

🫶 Author

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

Definition at line 151 of file sgbequ.f.

💜 ZGBEQU 💜

Okay so now we do the complex version, and honestly? It's the same girl just with better jewelry. Here's the whole signature, no cap:

subroutine zgbequ (integer m, integer n, integer kl, integer ku, complex*16,
    dimension( ldab, * ) ab, integer ldab, double precision, dimension( * )
    r, double precision, dimension( * ) c, double precision rowcnd, double
    precision colcnd, double precision amax, integer info)

ZGBEQU

✨ Purpose ✨

!> !> ZGBEQU computes row and column scalings intended to equilibrate an !> M-by-N band matrix A and reduce its condition number. R returns the !> row scale factors and C the column scale factors, chosen to try to !> make the largest element in each row and column of the matrix B with !> elements B(i,j)=R(i)*A(i,j)*C(j) have absolute value 1. !> !> R(i) and C(j) are restricted to be between SMLNUM = smallest safe !> number and BIGNUM = largest safe number. Use of these scaling !> factors is not guaranteed to reduce the condition number of A but !> works well in practice. !>

Translating from nerd: it hands you back row scalers R and column scalers C so that every entry of B(i,j)=R(i)*A(i,j)*C(j) lands at absolute value 1 — main character energy for every single element. 🦋

Two receipts though, because accuracy is the moment: R(i) and C(j) are clamped between SMLNUM = the smallest safe number and BIGNUM = the largest safe number. And no, this is not guaranteed to actually shrink the condition number of A — it just works well in practice. It's giving "trust me bestie, empirically iconic." 💅

🎀 Parameters 🎀

M — M is INTEGER, the number of rows of the matrix A. Constraint: M >= 0. Zero rows is legal, we don't judge. 🍓
N — N is INTEGER, the number of columns of the matrix A. Constraint: N >= 0. Same deal. 🌸
KL — KL is INTEGER, the number of subdiagonals within the band of A. Constraint: KL >= 0. That's the stuff hanging below the main diagonal. ⬇️
KU — KU is INTEGER, the number of superdiagonals within the band of A. Constraint: KU >= 0. And that's the stuff floating above it. ⬆️
AB — AB is COMPLEX*16 array, dimension (LDAB,N). This is the band matrix A itself, packed into rows 1 to KL+KU+1. The j-th column of A lives in the j-th column of AB, and the mapping is literally:

AB(ku+1+i-j,j) = A(i,j) for max(1,j-ku)<=i<=min(m,j+kl).

Memorize the offset ku+1+i-j, iykyk. 🔥

LDAB — LDAB is INTEGER, the leading dimension of the array AB. Must satisfy LDAB >= KL+KU+1. Do not skimp on this one, it's load-bearing. 😭
R — R is DOUBLE PRECISION array, dimension (M). On the way out: if INFO = 0, or INFO > M, then R is holding the row scale factors for A. 👑
C — C is DOUBLE PRECISION array, dimension (N). On the way out: if INFO = 0, C contains the column scale factors for A. 💖
ROWCND — ROWCND is DOUBLE PRECISION. If INFO = 0 or INFO > M, this is the ratio of the smallest R(i) to the largest R(i). And here's the vibe check: if ROWCND >= 0.1 and AMAX is neither too large nor too small, then it is not worth scaling by R. Save yourself the trouble bestie. 🙈
COLCND — COLCND is DOUBLE PRECISION. If INFO = 0, this holds the ratio of the smallest C(i) to the largest C(i). And if COLCND >= 0.1, it is not worth scaling by C. Same energy, column edition. ✨
AMAX — AMAX is DOUBLE PRECISION, the absolute value of the largest matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled. No debate, it's a whole emergency. 🚨
INFO — INFO is INTEGER. The finale, the receipts, the group chat read-receipt:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭 go fix argument i
- > 0: if INFO = i, and i is
  - <= M: the i-th row of A is exactly zero 💀
  - > M: the (i-M)-th column of A is exactly zero 💀

🫶 Author

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

Definition at line 152 of file zgbequ.f.

👑 Author

Generated automatically by Doxygen for LAPACK from the source code. Not a human, just a very diligent little robot doing its thing. 🤖

That's the whole page babes — LAPACK, Version 3.12.0, gbequ(3) — go forth and equilibrate responsibly, mwah 💋🫶

📦 where this page comes from

arch rolling: lapack-doc 3.12.1-2 · custom
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms

gbequ(3)

🦋 gbequ — the equilibration girlies ✨

🌸 SYNOPSIS

🔥 DETAILED DESCRIPTION

💖 FUNCTION DOCUMENTATION

subroutine cgbequ</p>

✨ Purpose

🎀 Parameters

🌈 Author

subroutine dgbequ

✨ Purpose

🎀 Parameters

🌈 Author

subroutine sgbequ

✨ Purpose

🎀 Parameters

🫶 Author

💜 ZGBEQU 💜

✨ Purpose ✨

🎀 Parameters 🎀

🫶 Author

👑 Author

`subroutine cgbequ`</p>

`subroutine dgbequ`

`subroutine sgbequ`