gebal(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

💅 gebal(3) — the balance-your-matrix glow-up 💅

okay so bestie, welcome to gebal from the Library Functions Manual. this is the page where a general matrix gets its whole life together: eigenvalues isolated, rows and columns brought into harmony, the works. it's giving makeover montage but for linear algebra ✨

🎀 NAME 🎀

gebal — gebal: balance matrix. that's it, that's the whole name section. short, sweet, iconic.

✨ SYNOPSIS ✨

🫶 Functions

subroutine cgebal (job, n, a, lda, ilo, ihi, scale, info) — CGEBAL
subroutine dgebal (job, n, a, lda, ilo, ihi, scale, info) — DGEBAL
subroutine sgebal (job, n, a, lda, ilo, ihi, scale, info) — SGEBAL
subroutine zgebal (job, n, a, lda, ilo, ihi, scale, info) — ZGEBAL

four flavors, same vibe. one for each of your favorite precisions/types, no cap 🦋

🦋 Detailed Description 🦋

so like, the headline: balancing a matrix can reduce the 1-norm of that matrix, and it can also improve the accuracy of the eigenvalues and/or eigenvectors you compute from it. that's the whole point, that's the moment, that's the arc 🫶

🔥 Function Documentation 🔥

🩷 `subroutine cgebal (character job, integer n, complex, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, real, dimension( * ) scale, integer info)`

💖 CGEBAL 💖

Purpose:

bestie, CGEBAL balances a general complex matrix A. and it does it in two whole steps, both of which are optional, because options are everything 💅

permuting A by a similarity transformation, so the eigenvalues get isolated in the first 1 to ILO-1 and the last IHI+1 to N elements on the diagonal.
scaling — applying a diagonal similarity transformation to rows and columns ILO to IHI, to make the rows and columns as close in norm as possible. the way it just evens everything out, honestly obsessed ✨

and yeah — Balancing may reduce the 1-norm of the matrix, and improve the accuracy of the computed eigenvalues and/or eigenvectors. both of those, at the same time. main character behavior fr fr.

Parameters

JOB — JOB is CHARACTER*1. it picks which operations get performed on A:
- = 'N': none: simply set ILO = 1, IHI = N, SCALE(I) = 1.0 for i = 1,...,N;
- = 'P': permute only;
- = 'S': scale only;
- = 'B': both permute and scale.
N — N is INTEGER. the order of the matrix A. and it has to be N >= 0. yes, zero counts, she's inclusive 💜
A — A is COMPLEX array, dimension (LDA,N). on entry, the input matrix A. on exit, A is overwritten by the balanced matrix. if JOB = 'N', then A is literally not referenced at all. check Further Details below for the full tea 🍓
LDA — LDA is INTEGER. the leading dimension of the array A. requirement: LDA >= max(1,N). don't skip this, it will matter 😭
ILO — ILO is INTEGER.
IHI — IHI is INTEGER. ILO and IHI get set to integers such that on exit, A(i,j) = 0 if i > j and j = 1,...,ILO-1 or I = IHI+1,...,N. and if JOB = 'N' or 'S', then ILO = 1 and IHI = N. noted 🫡
SCALE — SCALE is REAL array, dimension (N). all the details of the permutations and scaling factors that got applied to A. so if P(j) is the index of the row and column interchanged with row and column j, and D(j) is the scaling factor applied to row and column j, then:

SCALE(j) = P(j)    for j = 1,...,ILO-1
         = D(j)    for j = ILO,...,IHI
         = P(j)    for j = IHI+1,...,N.

also, the order in which the interchanges are made is N to IHI+1, and then 1 to ILO-1. order matters, bestie, it always does 💀

INFO — INFO is INTEGER:
- = 0: successful exit. slay 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. not slay 🙈

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

okay so the permutations are row and column interchanges that put the matrix into this exact shape:

           ( T1   X   Y  )
   P A P = (  0   B   Z  )
           (  0   0   T2 )

where T1 and T2 are upper triangular matrices whose eigenvalues lie right along the diagonal. and the column indices ILO and IHI mark the starting and ending columns of the submatrix B. 🎀

Balancing itself consists of applying a diagonal similarity transformation inv(D) * B * D to make the 1-norms of each row of B and its corresponding column nearly equal. so the output matrix is literally:

   ( T1     X*D          Y    )
   (  0  inv(D)*B*D  inv(D)*Z )
   (  0      0           T2   )

and all the info about the permutations P and the diagonal matrix D comes back to you in the vector SCALE. cute, right? 🦋

This subroutine is based on the EISPACK routine CBAL.

Modified by Tzu-Yi Chen, Computer Science Division, University of California at Berkeley, USA

Refactored by Evert Provoost, Department of Computer Science, KU Leuven, Belgium

Definition at line 164 of file cgebal.f.

💜 `subroutine dgebal (character job, integer n, double precision, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, double precision, dimension( * ) scale, integer info)`

💜 DGEBAL 💜

Purpose:

DGEBAL balances a general real matrix A. same two-step routine as always, bestie:

permuting A by a similarity transformation to isolate eigenvalues in the first 1 to ILO-1 and last IHI+1 to N elements on the diagonal.
applying a diagonal similarity transformation to rows and columns ILO to IHI to make the rows and columns as close in norm as possible.

Both steps are optional — again, options are the moment ✨

Balancing may reduce the 1-norm of the matrix, and improve the accuracy of the computed eigenvalues and/or eigenvectors. same iconic promise, real-number edition.

Parameters

JOB — JOB is CHARACTER*1. specifies which operations happen to A:
- = 'N': none: simply set ILO = 1, IHI = N, SCALE(I) = 1.0 for i = 1,...,N;
- = 'P': permute only;
- = 'S': scale only;
- = 'B': both permute and scale.
N — N is INTEGER. the order of the matrix A. N >= 0.
A — A is DOUBLE PRECISION array, dimension (LDA,N). on entry, the input matrix A. on exit, A is overwritten by the balanced matrix. if JOB = 'N', A is not referenced. See Further Details 💖
LDA — LDA is INTEGER. the leading dimension of the array A. LDA >= max(1,N).
ILO — ILO is INTEGER.
IHI — IHI is INTEGER. ILO and IHI are set to integers such that on exit A(i,j) = 0 if i > j and j = 1,...,ILO-1 or I = IHI+1,...,N. If JOB = 'N' or 'S', ILO = 1 and IHI = N.
SCALE — SCALE is DOUBLE PRECISION array, dimension (N). details of the permutations and scaling factors applied to A. If P(j) is the index of the row and column interchanged with row and column j and D(j) is the scaling factor applied to row and column j, then:

SCALE(j) = P(j)    for j = 1,...,ILO-1
         = D(j)    for j = ILO,...,IHI
         = P(j)    for j = IHI+1,...,N.

the order in which the interchanges are made is <blue>N to IHI+1, then <blue>1 to ILO-1. keep that order, i'm begging 🥺

INFO — INFO is INTEGER:
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

the permutations consist of row and column interchanges which put the matrix in the form:

           ( T1   X   Y  )
   P A P = (  0   B   Z  )
           (  0   0   T2 )

where T1 and T2 are upper triangular matrices whose eigenvalues lie along the diagonal. the column indices ILO and IHI mark the starting and ending columns of the submatrix B. Balancing consists of applying a diagonal similarity transformation inv(D) * B * D to make the 1-norms of each row of B and its corresponding column nearly equal. and the output matrix is:

   ( T1     X*D          Y    )
   (  0  inv(D)*B*D  inv(D)*Z )
   (  0      0           T2   )

information about the permutations P and the diagonal matrix D is returned in the vector SCALE. 🫶

This subroutine is based on the EISPACK routine BALANC. (note: BALANC, not CBAL — different ancestor, different lore, iykyk)

Modified by Tzu-Yi Chen, Computer Science Division, University of California at Berkeley, USA

Refactored by Evert Provoost, Department of Computer Science, KU Leuven, Belgium

Definition at line 162 of file dgebal.f.

🩵 `subroutine sgebal (character job, integer n, real, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, real, dimension( * ) scale, integer info)`

🩵 SGEBAL 🩵

Purpose:

SGEBAL balances a general real matrix A. you already know the drill, but here it is again because consistency is queen 👑

permuting A by a similarity transformation to isolate eigenvalues in the first 1 to ILO-1 and last IHI+1 to N elements on the diagonal;
and second, applying a diagonal similarity transformation to rows and columns ILO to IHI to make the rows and columns as close in norm as possible.

Both steps are optional. Both. Steps. Optional. 💅

Balancing may reduce the 1-norm of the matrix, and improve the accuracy of the computed eigenvalues and/or eigenvectors. yes bestie, it really said that.

Parameters

JOB — JOB is CHARACTER*1. specifies the operations to be performed on A:
- = 'N': none: simply set ILO = 1, IHI = N, SCALE(I) = 1.0 for i = 1,...,N;
- = 'P': permute only;
- = 'S': scale only;
- = 'B': both permute and scale.
N — N is INTEGER. The order of the matrix A. N >= 0.
A — A is REAL array, dimension (LDA,N). On entry, the input matrix A. On exit, A is overwritten by the balanced matrix. If JOB = 'N', A is not referenced. See Further Details 🌸
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
ILO — ILO is INTEGER.

…and this is exactly the spot where part 2 swoops in, so don't you dare close the tab 🧚‍♀️💜

ILO is INTEGER — that's the whole note, bestie: it's an integer 💅
IHI is INTEGER — ILO and IHI are set to integers such that on exit A(i,j) = 0 if i > j and j = 1,...,ILO-1 or I = IHI+1,...,N. If JOB = 'N' or 'S', ILO = 1 and IHI = N ✨
SCALE is REAL array, dimension (N) — this is where the deets of the permutations and scaling factors applied to A live. If P(j) is the index of the row and column interchanged with row and column j, and D(j) is the scaling factor applied to row and column j, then:

SCALE(j) = P(j)    for j = 1,...,ILO-1
         = D(j)    for j = ILO,...,IHI
         = P(j)    for j = IHI+1,...,N.

The order in which the interchanges are made is N to IHI+1, then 1 to ILO-1 🌀

INFO is INTEGER —
- = 0: successful exit 😌
- < 0: if INFO = -i, the i-th argument had an illegal value 🚨

👑 Author

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

🔍 Further Details:

The permutations consist of row and column interchanges which put the matrix in the form

            ( T1   X   Y  )
    P A P = (  0   B   Z  )
            (  0   0   T2 )

where T1 and T2 are upper triangular matrices whose eigenvalues lie along the diagonal. The column indices ILO and IHI mark the starting and ending columns of the submatrix B. Balancing consists of applying a diagonal similarity transformation inv(D) * B * D to make the 1-norms of each row of B and its corresponding column nearly equal. The output matrix is

    ( T1     X*D          Y    )
    (  0  inv(D)*B*D  inv(D)*Z ).
    (  0      0           T2   )

Information about the permutations P and the diagonal matrix D is returned in the vector SCALE 🫶

This subroutine is based on the EISPACK routine BALANC.

Modified by Tzu-Yi Chen, Computer Science Division, University of California at Berkeley, USA

Refactored by Evert Provoost, Department of Computer Science, KU Leuven, Belgium

Definition at line 162 of file sgebal.f.

🌈 `subroutine zgebal` — the complex*16 edition, bestie ✨

subroutine zgebal (character job, integer n, complex*16, dimension( lda, * )
    a, integer lda, integer ilo, integer ihi, double precision, dimension( *
    ) scale, integer info)

ZGEBAL

🎯 Purpose:

ZGEBAL balances a general complex matrix A. This involves, first, permuting A by a similarity transformation to isolate eigenvalues in the first 1 to ILO-1 and last IHI+1 to N elements on the diagonal; and second, applying a diagonal similarity transformation to rows and columns ILO to IHI to make the rows and columns as close in norm as possible. Both steps are optional 💖

Balancing may reduce the 1-norm of the matrix, and improve the accuracy of the computed eigenvalues and/or eigenvectors. iconic behavior, honestly 👑

🧩 Parameters

JOB is CHARACTER*1 — specifies the operations to be performed on A:
- 'N': none: simply set ILO = 1, IHI = N, SCALE(I) = 1.0 for i = 1,...,N;
- 'P': permute only;
- 'S': scale only;
- 'B': both permute and scale.
N is INTEGER — the order of the matrix A. N >= 0.
A is COMPLEX*16 array, dimension (LDA,N) — on entry, the input matrix A. On exit, A is overwritten by the balanced matrix. If JOB = 'N', A is not referenced. See Further Details 👀
LDA is INTEGER — the leading dimension of the array A. LDA >= max(1,N).
ILO is INTEGER — yes bestie, an integer 💅
IHI is INTEGER — ILO and IHI are set to integers such that on exit A(i,j) = 0 if i > j and j = 1,...,ILO-1 or I = IHI+1,...,N. If JOB = 'N' or 'S', ILO = 1 and IHI = N ✨
SCALE is DOUBLE PRECISION array, dimension (N) — details of the permutations and scaling factors applied to A. If P(j) is the index of the row and column interchanged with row and column j, and D(j) is the scaling factor applied to row and column j, then:

SCALE(j) = P(j)    for j = 1,...,ILO-1
         = D(j)    for j = ILO,...,IHI
         = P(j)    for j = IHI+1,...,N.

The order in which the interchanges are made is N to IHI+1, then 1 to ILO-1 🌀

INFO is INTEGER —
- = 0: successful exit 😌
- < 0: if INFO = -i, the i-th argument had an illegal value 🚨

👑 Author

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

🔍 Further Details:

The permutations consist of row and column interchanges which put the matrix in the form

            ( T1   X   Y  )
    P A P = (  0   B   Z  )
            (  0   0   T2 )

    ( T1     X*D          Y    )
    (  0  inv(D)*B*D  inv(D)*Z ).
    (  0      0           T2   )

Information about the permutations P and the diagonal matrix D is returned in the vector SCALE 🫶

This subroutine is based on the EISPACK routine CBAL.

Modified by Tzu-Yi Chen, Computer Science Division, University of California at Berkeley, USA

Refactored by Evert Provoost, Department of Computer Science, KU Leuven, Belgium

Definition at line 164 of file zgebal.f.

🧚 Author

Generated automatically by Doxygen for LAPACK from the source code.

okay that's a wrap on gebal(3), bestie 💖 the footer credits LAPACK Version 3.12.0 and this page is gebal(3); the date slot is literally not in that footer line, so no made-up date from me 🫶✨

📦 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

gebal(3)

💅 gebal(3) — the balance-your-matrix glow-up 💅

🎀 NAME 🎀

✨ SYNOPSIS ✨

🫶 Functions

🦋 Detailed Description 🦋

🔥 Function Documentation 🔥

🩷 subroutine cgebal (character job, integer n, complex, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, real, dimension( * ) scale, integer info)

💖 CGEBAL 💖

Purpose:

Parameters

Author

Further Details:

💜 subroutine dgebal (character job, integer n, double precision, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, double precision, dimension( * ) scale, integer info)

💜 DGEBAL 💜

Purpose:

Parameters

Author

Further Details:

🩵 subroutine sgebal (character job, integer n, real, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, real, dimension( * ) scale, integer info)

🩵 SGEBAL 🩵

Purpose:

Parameters

👑 Author

🔍 Further Details:

🌈 subroutine zgebal — the complex*16 edition, bestie ✨

🎯 Purpose:

🧩 Parameters

👑 Author

🔍 Further Details:

🧚 Author

🩷 `subroutine cgebal (character job, integer n, complex, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, real, dimension( * ) scale, integer info)`

💜 `subroutine dgebal (character job, integer n, double precision, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, double precision, dimension( * ) scale, integer info)`

🩵 `subroutine sgebal (character job, integer n, real, dimension( lda, * ) a, integer lda, integer ilo, integer ihi, real, dimension( * ) scale, integer info)`

🌈 `subroutine zgebal` — the complex*16 edition, bestie ✨