heequb(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

🦋 heequb(3) 🦋

okay so this whole page lives in the Library Functions Manual, and the star of the show is heequb — which is really the squad name for {he,sy}equb: equilibration, power of 2. bestie, it's a whole family of Fortran subroutines that rescale your matrix so it stops being dramatic 💅

🌸 NAME 🌸

heequb — {he,sy}equb: equilibration, power of 2 ✨

🎀 SYNOPSIS 🎀

Functions

  • subroutine cheequb (uplo, n, a, lda, s, scond, amax, work, info) — CHEEQUB 💖
  • subroutine csyequb (uplo, n, a, lda, s, scond, amax, work, info) — CSYEQUB 🦋
  • subroutine dsyequb (uplo, n, a, lda, s, scond, amax, work, info) — DSYEQUB 🌸
  • subroutine ssyequb (uplo, n, a, lda, s, scond, amax, work, info) — SSYEQUB ⭐
  • subroutine zheequb (uplo, n, a, lda, s, scond, amax, work, info) — ZHEEQUB 👑
  • subroutine zsyequb (uplo, n, a, lda, s, scond, amax, work, info) — ZSYEQUB 🌈

💜 Detailed Description 💜

ngl the "Detailed Description" section is giving empty-group-chat energy — there's literally nothing in it here, so we go straight to the good stuff 🫶

🔥 Function Documentation 🔥

🫶 cheequb — CHEEQUB

subroutine cheequb (character uplo, integer n, complex, dimension( lda, * )
a, integer lda, real, dimension( * ) s, real scond, real amax, complex,
dimension( * ) work, integer info)

✨ Purpose ✨

CHEEQUB computes row and column scalings intended to equilibrate a Hermitian matrix A (with respect to the Euclidean norm) and reduce its condition number. The scale factors S are computed by the BIN algorithm (see references) so that the scaled matrix B with elements B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of the smallest possible condition number over all possible diagonal scalings. it's giving "make your matrix less of a mess" and honestly? iconic 😭

🎀 Parameters 🎀

  • UPLO — UPLO is CHARACTER*1
= 'U':  Upper triangle of A is stored;
= 'L':  Lower triangle of A is stored.
  • N — N is INTEGER — the order of the matrix A. N >= 0.
  • A — A is COMPLEX array, dimension (LDA,N) — the N-by-N Hermitian matrix whose scaling factors are to be computed.
  • LDA — LDA is INTEGER — the leading dimension of the array A. LDA >= max(1,N).
  • S — S is REAL array, dimension (N) — if INFO = 0, S contains the scale factors for A.
  • SCOND — SCOND is REAL — if INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S. (lowkey "don't bother" energy 🫠)
  • AMAX — AMAX is REAL — largest absolute value of any matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
  • WORK — WORK is COMPLEX array, dimension (2*N)
  • INFO — INFO is INTEGER
= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, the i-th diagonal element is nonpositive.

💖 Author 💖

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

🦋 References 🦋

Livne, O.E. and Golub, G.H., "Scaling by Binormalization", Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. DOI 10.1023/B:NUMA.0000016606.32820.69 Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679

Definition at line 131 of file cheequb.f.

🦋 csyequb — CSYEQUB

subroutine csyequb (character uplo, integer n, complex, dimension( lda, * )
a, integer lda, real, dimension( * ) s, real scond, real amax, complex,
dimension( * ) work, integer info)

✨ Purpose ✨

CSYEQUB computes row and column scalings intended to equilibrate a symmetric matrix A (with respect to the Euclidean norm) and reduce its condition number. The scale factors S are computed by the BIN algorithm (see references) so that the scaled matrix B with elements B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of the smallest possible condition number over all possible diagonal scalings. same energy as CHEEQUB but it's the symmetric sibling, periodt 💅

🎀 Parameters 🎀

  • UPLO — UPLO is CHARACTER*1
= 'U':  Upper triangle of A is stored;
= 'L':  Lower triangle of A is stored.
  • N — N is INTEGER — the order of the matrix A. N >= 0.
  • A — A is COMPLEX array, dimension (LDA,N) — the N-by-N symmetric matrix whose scaling factors are to be computed.
  • LDA — LDA is INTEGER — the leading dimension of the array A. LDA >= max(1,N).
  • S — S is REAL array, dimension (N) — if INFO = 0, S contains the scale factors for A.
  • SCOND — SCOND is REAL — if INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S.
  • AMAX — AMAX is REAL — largest absolute value of any matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
  • WORK — WORK is COMPLEX array, dimension (2*N)
  • INFO — INFO is INTEGER
= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, the i-th diagonal element is nonpositive.

💖 Author 💖

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

🦋 References 🦋

Livne, O.E. and Golub, G.H., "Scaling by Binormalization", Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. DOI 10.1023/B:NUMA.0000016606.32820.69 Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679

Definition at line 131 of file csyequb.f.

🌸 dsyequb — DSYEQUB

subroutine dsyequb (character uplo, integer n, double precision, dimension(
lda, * ) a, integer lda, double precision, dimension( * ) s, double
precision scond, double precision amax, double precision, dimension( * )
work, integer info)

✨ Purpose ✨

DSYEQUB computes row and column scalings intended to equilibrate a symmetric matrix A (with respect to the Euclidean norm) and reduce its condition number. The scale factors S are computed by the BIN algorithm (see references) so that the scaled matrix B with elements B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of the smallest possible condition number over all possible diagonal scalings. double precision edition, no cap 🧚

🎀 Parameters 🎀

  • UPLO — UPLO is CHARACTER*1
= 'U':  Upper triangle of A is stored;
= 'L':  Lower triangle of A is stored.
  • N — N is INTEGER — the order of the matrix A. N >= 0.
  • A — A is DOUBLE PRECISION array, dimension (LDA,N) — the N-by-N symmetric matrix whose scaling factors are to be computed.
  • LDA — LDA is INTEGER — the leading dimension of the array A. LDA >= max(1,N).
  • S — S is DOUBLE PRECISION array, dimension (N) — if INFO = 0, S contains the scale factors for A.
  • SCOND — SCOND is DOUBLE PRECISION — if INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S.
  • AMAX — AMAX is DOUBLE PRECISION — largest absolute value of any matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
  • WORK — WORK is DOUBLE PRECISION array, dimension (2*N)
  • INFO — INFO is INTEGER
= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, the i-th diagonal element is nonpositive.

💖 Author 💖

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

🦋 References 🦋

Livne, O.E. and Golub, G.H., "Scaling by Binormalization", Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. DOI 10.1023/B:NUMA.0000016606.32820.69 Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679

Definition at line 130 of file dsyequb.f.

⭐ ssyequb — SSYEQUB

subroutine ssyequb (character uplo, integer n, real, dimension( lda, * ) a,
integer lda, real, dimension( * ) s, real scond, real amax, real,
dimension( * ) work, integer info)

✨ Purpose ✨

SSYEQUB computes row and column scalings intended to equilibrate a symmetric matrix A (with respect to the Euclidean norm) and reduce its condition number. The scale factors S are computed by the BIN algorithm (see references) so that the scaled matrix B with elements B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of the smallest possible condition number over all possible diagonal scalings. single precision but make it fashion ⭐

🎀 Parameters 🎀

  • UPLO — UPLO is CHARACTER*1
= 'U':  Upper triangle of A is stored;
= 'L':  Lower triangle of A is stored.
  • N — N is INTEGER — the order of the matrix A. N >= 0.
  • A — A is REAL array, dimension (LDA,N) — the N-by-N symmetric matrix whose scaling factors are to be computed.
  • LDA — LDA is INTEGER — the leading dimension of the array A. LDA >= max(1,N).
  • S — S is REAL array, dimension (N) — if INFO = 0, S contains the scale factors for A.
  • SCOND — SCOND is REAL
  • SCOND — SCOND is REAL. If INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S. 💅 like, don't bother, bestie, it's already fine.
  • AMAX — AMAX is REAL. Largest absolute value of any matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled. 🚨 like hello?? danger zone, scale it.
  • WORK — WORK is REAL array, dimension (2*N).
  • INFO — INFO is INTEGER
    • = 0: successful exit ✨
    • < 0: if INFO = -i, the i-th argument had an illegal value 😭
    • > 0: if INFO = i, the i-th diagonal element is nonpositive. 💀

🌸 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

(no cap, the whole academic avengers assembled for this one 🫶)

📚 References:

Livne, O.E. and Golub, G.H., "Scaling by Binormalization", Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. DOI 10.1023/B:NUMA.0000016606.32820.69 Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679

Definition at line 130 of file ssyequb.f.

🦋 subroutine zheequb

subroutine zheequb (character uplo, integer n, complex*16, dimension( lda, * ) a, integer lda, double precision, dimension( * ) s, double precision scond, double precision amax, complex*16, dimension( * ) work, integer info)

ZHEEQUB — the complex*16 Hermitian girlie 💜

✨ Purpose:

ZHEEQUB computes row and column scalings intended to equilibrate a Hermitian matrix A (with respect to the Euclidean norm) and reduce its condition number. The scale factors S are computed by the BIN algorithm (see references) so that the scaled matrix B with elements B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of the smallest possible condition number over all possible diagonal scalings.

like, it's out here finding the glow-up for your matrix ✨ so the condition number is, at worst, a factor N off from the absolute best possible diagonal scaling. iconic behaviour, honestly. 👑

🎀 Parameters

  • UPLO — UPLO is CHARACTER*1
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N — N is INTEGER. The order of the matrix A. N >= 0.
  • A — A is COMPLEX*16 array, dimension (LDA,N). The N-by-N Hermitian matrix whose scaling factors are to be computed.
  • LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
  • S — S is DOUBLE PRECISION array, dimension (N). If INFO = 0, S contains the scale factors for A.
  • SCOND — SCOND is DOUBLE PRECISION. If INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S. 💅 save yourself the effort babes.
  • AMAX — AMAX is DOUBLE PRECISION. Largest absolute value of any matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled. ⚠️ fr fr, scale it before it becomes a whole crisis.
  • WORK — WORK is COMPLEX*16 array, dimension (2*N).
  • INFO — INFO is INTEGER
    • = 0: successful exit ✨
    • < 0: if INFO = -i, the i-th argument had an illegal value 😭
    • > 0: if INFO = i, the i-th diagonal element is nonpositive. 💀

🌸 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

📚 References:

Livne, O.E. and Golub, G.H., "Scaling by Binormalization", Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. DOI 10.1023/B:NUMA.0000016606.32820.69 Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679

Definition at line 131 of file zheequb.f.

🌈 subroutine zsyequb

subroutine zsyequb (character uplo, integer n, complex*16, dimension( lda, * ) a, integer lda, double precision, dimension( * ) s, double precision scond, double precision amax, complex*16, dimension( * ) work, integer info)

ZSYEQUB — same energy, but symmetric this time 🦋 (Hermitian's chill cousin, iykyk)

✨ Purpose:

ZSYEQUB computes row and column scalings intended to equilibrate a symmetric matrix A (with respect to the Euclidean norm) and reduce its condition number. The scale factors S are computed by the BIN algorithm (see references) so that the scaled matrix B with elements B(i,j) = S(i)*A(i,j)*S(j) has a condition number within a factor N of the smallest possible condition number over all possible diagonal scalings.

literally the same slay as ZHEEQUB but for a symmetric A — the BIN algorithm does the work, and your condition number ends up within a factor N of the best possible diagonal scaling. no notes. 🎀

🎀 Parameters

  • UPLO — UPLO is CHARACTER*1
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N — N is INTEGER. The order of the matrix A. N >= 0.
  • A — A is COMPLEX*16 array, dimension (LDA,N). The N-by-N symmetric matrix whose scaling factors are to be computed.
  • LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
  • S — S is DOUBLE PRECISION array, dimension (N). If INFO = 0, S contains the scale factors for A.
  • SCOND — SCOND is DOUBLE PRECISION. If INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S.
  • AMAX — AMAX is DOUBLE PRECISION. Largest absolute value of any matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled. 🚨
  • WORK — WORK is COMPLEX*16 array, dimension (2*N).
  • INFO — INFO is INTEGER
    • = 0: successful exit ✨
    • < 0: if INFO = -i, the i-th argument had an illegal value 😭
    • > 0: if INFO = i, the i-th diagonal element is nonpositive. 💀

🌸 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

📚 References:

Livne, O.E. and Golub, G.H., "Scaling by Binormalization", Numerical Algorithms, vol. 35, no. 1, pp. 97-120, January 2004. DOI 10.1023/B:NUMA.0000016606.32820.69 Tech report version: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.3.1679

Definition at line 131 of file zsyequb.f.

👑 Author

Generated automatically by Doxygen for LAPACK from the source code.

and that's the whole page, bestie!! 🎀✨ this little beauty is from LAPACK, Version 3.12.0, and you clocked it as heequb(3) — auto-generated by Doxygen straight from the LAPACK source code, so every word up there is canon. go scale something responsibly. 💖🦋💅

📦 where this page comes from