latrs(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💖 latrs(3) — from the Library Functions Manual — triangular solve with robust scaling 💖

🌸 NAME 🌸

latrs — latrs: triangular solve with robust scaling 💅

✨ SYNOPSIS ✨

🌈 Functions 🌈

  • clatrs — CLATRS solves a triangular system of equations with the scale factor set to prevent overflow. Signature: subroutine clatrs (uplo, trans, diag, normin, n, a, lda, x, scale, cnorm, info)
  • dlatrs — DLATRS solves a triangular system of equations with the scale factor set to prevent overflow. Signature: subroutine dlatrs (uplo, trans, diag, normin, n, a, lda, x, scale, cnorm, info)
  • slatrs — SLATRS solves a triangular system of equations with the scale factor set to prevent overflow. Signature: subroutine slatrs (uplo, trans, diag, normin, n, a, lda, x, scale, cnorm, info)
  • zlatrs — ZLATRS solves a triangular system of equations with the scale factor set to prevent overflow. Signature: subroutine zlatrs (uplo, trans, diag, normin, n, a, lda, x, scale, cnorm, info)

🌟 DETAILED DESCRIPTION 🌟

Okay so this page is the full breakdown of the latrs family — the routines that solve triangular systems with scaling so overflow doesn't crash the party. 🎉

🧚 FUNCTION DOCUMENTATION 🧚

Each subroutine gets its own little spotlight. 👑

💅 subroutine clatrs 💅

subroutine clatrs (character uplo, character trans, character diag, character normin, integer n, complex, dimension( lda, * ) a, integer lda, complex, dimension( * ) x, real scale, real, dimension( * ) cnorm, integer info)

CLATRS solves a triangular system of equations with the scale factor set to prevent overflow. 💖

🎯 Purpose 🎯

CLATRS solves one of the triangular systems:

   A * x = s*b,  A**T * x = s*b,  or  A**H * x = s*b,

with scaling to prevent overflow. Here A is an upper or lower triangular matrix, A**T denotes the transpose of A, A**H denotes the conjugate transpose of A, x and b are n-element vectors, and s is a scaling factor, usually less than or equal to 1, chosen so that the components of x will be less than the overflow threshold. If the unscaled problem will not cause overflow, the Level 2 BLAS routine CTRSV is called. If the matrix A is singular (A(j,j) = 0 for some j), then s is set to 0 and a non-trivial solution to A*x = 0 is returned.

🚨 Singular matrix alert: if A(j,j) = 0 for some j, then s is set to 0 and a non-trivial solution to A*x = 0 is returned. That's the contract, bestie. 💅

🌸 Parameters 🌸

UPLO — CHARACTER*1. Specifies whether the matrix A is upper or lower triangular.

  • 'U': Upper triangular
  • 'L': Lower triangular

TRANS — CHARACTER*1. Specifies the operation applied to A.

  • 'N': Solve A * x = s*b (No transpose)
  • 'T': Solve A**T * x = s*b (Transpose)
  • 'C': Solve A**H * x = s*b (Conjugate transpose)

DIAG — CHARACTER*1. Specifies whether or not the matrix A is unit triangular.

  • 'N': Non-unit triangular
  • 'U': Unit triangular

NORMIN — CHARACTER*1. Specifies whether CNORM has been set or not.

  • 'Y': CNORM contains the column norms on entry
  • 'N': CNORM is not set on entry. On exit, the norms will be computed and stored in CNORM.

N — INTEGER. The order of the matrix A. N >= 0.

A — COMPLEX array, dimension (LDA,N). The triangular matrix A. If UPLO = 'U', the leading n by n upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading n by n lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1.

LDA — INTEGER. The leading dimension of the array A. LDA >= max (1,N).

X — COMPLEX array, dimension (N). On entry, the right hand side b of the triangular system. On exit, X is overwritten by the solution vector x.

SCALE — REAL. The scaling factor s for the triangular system:

   A * x = s*b,  A**T * x = s*b,  or  A**H * x = s*b.

If SCALE = 0, the matrix A is singular or badly scaled, and the vector x is an exact or approximate solution to A*x = 0.

CNORM — REAL array, dimension (N).

If NORMIN = 'Y', CNORM is an input argument and CNORM(j) contains the norm of the off-diagonal part of the j-th column of A. If TRANS = 'N', CNORM(j) must be greater than or equal to the infinity-norm, and if TRANS = 'T' or 'C', CNORM(j) must be greater than or equal to the 1-norm.

If NORMIN = 'N', CNORM is an output argument and CNORM(j) returns the 1-norm of the offdiagonal part of the j-th column of A.

INFO — INTEGER.

  • = 0: successful exit
  • < 0: if INFO = -k, the k-th argument had an illegal value

👑 Author 👑

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

🔍 Further Details 🔍

A rough bound on x is computed; if that is less than overflow, CTRSV is called; otherwise, specific code is used which checks for possible overflow or divide-by-zero at every operation.

A columnwise scheme is used for solving A*x = b. The basic algorithm if A is lower triangular is:

      x[1:n] := b[1:n]
      for j = 1, ..., n
           x(j) := x(j) / A(j,j)
           x[j+1:n] := x[j+1:n] - x(j) * A[j+1:n,j]
      end

Define bounds on the components of x after j iterations of the loop:

    M(j) = bound on x[1:j]
    G(j) = bound on x[j+1:n]

Initially, let M(0) = 0 and G(0) = max{x(i), i=1,...,n}.

Then for iteration j+1 we have:

    M(j+1) <= G(j) / | A(j+1,j+1) |
    G(j+1) <= G(j) + M(j+1) * | A[j+2:n,j+1] |
           <= G(j) ( 1 + CNORM(j+1) / | A(j+1,j+1) | )

where CNORM(j+1) is greater than or equal to the infinity-norm of column j+1 of A, not counting the diagonal. Hence:

    G(j) <= G(0) product ( 1 + CNORM(i) / | A(i,i) | )
                 1<=i<=j

and:

    |x(j)| <= ( G(0) / |A(j,j)| ) product ( 1 + CNORM(i) / |A(i,i)| )
                                  1<=i< j

Since |x(j)| <= M(j), we use the Level 2 BLAS routine CTRSV if the reciprocal of the largest M(j), j=1,..,n, is larger than max(underflow, 1/overflow).

The bound on x(j) is also used to determine when a step in the columnwise method can be performed without fear of overflow. If the computed bound is greater than a large constant, x is scaled to prevent overflow, but if the bound overflows, x is set to 0, x(j) to 1, and scale to 0, and a non-trivial solution to A*x = 0 is found.

Similarly, a row-wise scheme is used to solve A**T *x = b or A**H *x = b. The basic algorithm for A upper triangular is:

      for j = 1, ..., n
           x(j) := ( b(j) - A[1:j-1,j]' * x[1:j-1] ) / A(j,j)
      end

We simultaneously compute two bounds:

      G(j) = bound on ( b(i) - A[1:i-1,i]' * x[1:i-1] ), 1<=i<=j
      M(j) = bound on x(i), 1<=i<=j

The initial values are G(0) = 0, M(0) = max{b(i), i=1,..,n}, and we add the constraint G(j) >= G(j-1) and M(j) >= M(j-1) for j >= 1. Then the bound on x(j) is:

      M(j) <= M(j-1) * ( 1 + CNORM(j) ) / | A(j,j) |

           <= M(0) * product ( ( 1 + CNORM(i) ) / |A(i,i)| )
                     1<=i<=j

and we can safely call CTRSV if 1/M(n) and 1/G(n) are both greater than max(underflow, 1/overflow).

Definition at line 237 of file clatrs.f.

💅 subroutine dlatrs 💅

subroutine dlatrs (character uplo, character trans, character diag, character normin, integer n, double precision, dimension( lda, * ) a, integer lda, double precision, dimension( * ) x, double precision scale, double precision, dimension( * ) cnorm, integer info)

DLATRS solves a triangular system of equations with the scale factor set to prevent overflow. 💖

🎯 Purpose 🎯

DLATRS solves one of the triangular systems:

   A *x = s*b  or  A**T *x = s*b

with scaling to prevent overflow. Here A is an upper or lower triangular matrix, A**T denotes the transpose of A, x and b are n-element vectors, and s is a scaling factor, usually less than or equal to 1, chosen so that the components of x will be less than the overflow threshold. If the unscaled problem will not cause overflow, the Level 2 BLAS routine DTRSV is called. If the matrix A is singular (A(j,j) = 0 for some j), then s is set to 0 and a non-trivial solution to A*x = 0 is returned.

🚨 Same singular-matrix energy: if A(j,j) = 0 for some j, then s is set to 0 and a non-trivial solution to A*x = 0 is returned. Not a drill. 💅

🌸 Parameters 🌸

UPLO — CHARACTER*1. Specifies whether the matrix A is upper or lower triangular.

  • 'U': Upper triangular
  • 'L': Lower triangular

TRANS — CHARACTER*1. Specifies the operation applied to A.

  • 'N': Solve A * x = s*b (No transpose)
  • 'T': Solve A**T* x = s*b (Transpose)
  • 'C': Solve A**T* x = s*b (Conjugate transpose = Transpose)

DIAG — CHARACTER*1. Specifies whether or not the matrix A is unit triangular.

  • 'N': Non-unit triangular
  • 'U': Unit triangular

NORMIN

  • NORMIN (CHARACTER*1) — tells the routine whether CNORM is already loaded or not. = 'Y' means yep, CNORM has the column norms on entry 💅. = 'N' means nope, nothing set — and on the way out the norms get computed and dropped into CNORM for you 🫶
  • N (INTEGER) — the order of the matrix A. N >= 0, bestie, non-negotiable ✨
  • A (DOUBLE PRECISION array, dimension (LDA,N)) — the triangular matrix A itself 👑
    • If UPLO = 'U', the leading n by n upper triangular part of the array A holds the upper triangular matrix, and the strictly lower triangular part of A is not referenced (we literally do not look at it 🙈).
    • If UPLO = 'L', the leading n by n lower triangular part of the array A holds the lower triangular matrix, and the strictly upper triangular part of A is not referenced.
    • If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1 — free real estate, we just pretend they're ones 🎀
  • LDA (INTEGER) — the leading dimension of the array A. Must satisfy LDA >= max (1,N). Math is math, no cap 📏
  • X (DOUBLE PRECISION array, dimension (N)) — on entry, this is the right hand side b of the triangular system. On exit, X gets overwritten by the solution vector x 🔥 (so screenshot your input first if you were attached to it 😭)
  • SCALE (DOUBLE PRECISION) — the scaling factor s for the triangular system
A * x = s*b  or  A**T* x = s*b

If SCALE = 0, then the matrix A is singular or badly scaled, and the vector x is an exact or approximate solution to A*x = 0. That's your "we tried, it's cooked" signal 💀

  • CNORM (DOUBLE PRECISION array, dimension (N)) — the column-norm situation, and it flips roles based on NORMIN 👀
    • If NORMIN = 'Y', CNORM is an input argument and CNORM(j) contains the norm of the off-diagonal part of the j-th column of A. If TRANS = 'N', CNORM(j) must be greater than or equal to the infinity-norm, and if TRANS = 'T' or 'C', CNORM(j) must be greater than or equal to the 1-norm. Respect the requirements, bestie 🧚
    • If NORMIN = 'N', CNORM is an output argument and CNORM(j) returns the 1-norm of the offdiagonal part of the j-th column of A 🌸
  • INFO (INTEGER) — the receipts 📜
    • = 0: successful exit, we ate and left no crumbs ✨
    • < 0: if INFO = -k, the k-th argument had an illegal value 🚨

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💖 Further Details 💖

okay so this part is the why and it's honestly iconic. A rough bound on x is computed; if that is less than overflow, DTRSV is called, otherwise, specific code is used which checks for possible overflow or divide-by-zero at every operation 👀

A columnwise scheme is used for solving A*x = b. The basic algorithm if A is lower triangular is

     x[1:n] := b[1:n]
     for j = 1, ..., n
          x(j) := x(j) / A(j,j)
          x[j+1:n] := x[j+1:n] - x(j) * A[j+1:n,j]
     end

Define bounds on the components of x after j iterations of the loop:

   M(j) = bound on x[1:j]
   G(j) = bound on x[j+1:n]

Initially, let M(0) = 0 and G(0) = max{x(i), i=1,...,n}.

Then for iteration j+1 we have

   M(j+1) <= G(j) / | A(j+1,j+1) |
   G(j+1) <= G(j) + M(j+1) * | A[j+2:n,j+1] |
          <= G(j) ( 1 + CNORM(j+1) / | A(j+1,j+1) | )

where CNORM(j+1) is greater than or equal to the infinity-norm of column j+1 of A, not counting the diagonal. Hence

   G(j) <= G(0) product ( 1 + CNORM(i) / | A(i,i) | )
                1<=i<=j

and

   |x(j)| <= ( G(0) / |A(j,j)| ) product ( 1 + CNORM(i) / |A(i,i)| )
                                 1<=i< j

Since |x(j)| <= M(j), we use the Level 2 BLAS routine DTRSV if the reciprocal of the largest M(j), j=1,..,n, is larger than max(underflow, 1/overflow) 🧮

The bound on x(j) is also used to determine when a step in the columnwise method can be performed without fear of overflow. If the computed bound is greater than a large constant, x is scaled to prevent overflow, but if the bound overflows, x is set to 0, x(j) to 1, and scale to 0, and a non-trivial solution to A*x = 0 is found 😳 (yes that's real, read it twice)

Similarly, a row-wise scheme is used to solve A**T*x = b. The basic algorithm for A upper triangular is

     for j = 1, ..., n
          x(j) := ( b(j) - A[1:j-1,j]**T * x[1:j-1] ) / A(j,j)
     end

We simultaneously compute two bounds

     G(j) = bound on ( b(i) - A[1:i-1,i]**T * x[1:i-1] ), 1<=i<=j
     M(j) = bound on x(i), 1<=i<=j

The initial values are G(0) = 0, M(0) = max{b(i), i=1,..,n}, and we add the constraint G(j) >= G(j-1) and M(j) >= M(j-1) for j >= 1. Then the bound on x(j) is

     M(j) <= M(j-1) * ( 1 + CNORM(j) ) / | A(j,j) |

          <= M(0) * product ( ( 1 + CNORM(i) ) / |A(i,i)| )
                    1<=i<=j

and we can safely call DTRSV if 1/M(n) and 1/G(n) are both greater than max(underflow, 1/overflow) ⭐

Definition at line 236 of file dlatrs.f.

🌈 subroutine slatrs 🌈

subroutine slatrs (character uplo, character trans, character diag,
    character normin, integer n, real, dimension( lda, * ) a, integer lda,
    real, dimension( * ) x, real scale, real, dimension( * ) cnorm, integer
    info)

SLATRS solves a triangular system of equations with the scale factor set to prevent overflow 💅 same energy as the D version, just single precision, and honestly? she's giving reliable 🔥

✨ Purpose ✨

SLATRS solves one of the triangular systems

   A *x = s*b  or  A**T*x = s*b

with scaling to prevent overflow. Here A is an upper or lower triangular matrix, A**T denotes the transpose of A, x and b are n-element vectors, and s is a scaling factor, usually less than or equal to 1, chosen so that the components of x will be less than the overflow threshold 🎀

If the unscaled problem will not cause overflow, the Level 2 BLAS routine STRSV is called. If the matrix A is singular (A(j,j) = 0 for some j), then s is set to 0 and a non-trivial solution to A*x = 0 is returned 🫶 (yes, singular means you get the "not the zero vector somehow" outcome — iconic behaviour, lowkey)

🦋 Parameters 🦋

  • UPLO (CHARACTER*1) — specifies whether the matrix A is upper or lower triangular.
    • = 'U': Upper triangular
    • = 'L': Lower triangular
  • TRANS (CHARACTER*1) — specifies the operation applied to A.
    • = 'N': Solve A * x = s*b (No transpose)
    • = 'T': Solve A**T* x = s*b (Transpose)
    • = 'C': Solve A**T* x = s*b (Conjugate transpose = Transpose) — same thing here, do not panic 😌
  • DIAG (CHARACTER*1) — specifies whether or not the matrix A is unit triangular.
    • = 'N': Non-unit triangular
    • = 'U': Unit triangular
  • NORMIN (CHARACTER*1) — specifies whether CNORM has been set or not.
    • = 'Y': CNORM contains the column norms on entry
    • = 'N': CNORM is not set on entry. On exit, the norms will be computed and stored in CNORM 🌸
  • N (INTEGER) — the order of the matrix A. N >= 0.
  • A (REAL array, dimension (LDA,N)) — the triangular matrix A 💖
    • If UPLO = 'U', the leading n by n upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced.
    • If UPLO = 'L', the leading n by n lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced.
    • If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1 ✨
  • LDA (INTEGER) — the leading dimension of the array A. LDA >= max (1,N).
  • X (REAL array, dimension (N)) — on entry, the right hand side b of the triangular system. On exit, X is overwritten by the solution vector x 🔥
  • SCALE (REAL) — the scaling factor s for the triangular system
A * x = s*b  or  A**T* x = s*b

If SCALE = 0, the matrix A is singular or badly scaled, and the vector x is an exact or approximate solution to A*x = 0 🙈

  • CNORM (REAL array, dimension (N)) —
    • If NORMIN = 'Y', CNORM is an input argument and CNORM(j) contains the norm of the off-diagonal part of the j-th column of A. If TRANS = 'N', CNORM(j) must be greater than or equal to the infinity-norm, and if TRANS = 'T' or 'C', CNORM(j) must be greater than or equal to the 1-norm ⭐
    • If NORMIN = 'N', CNORM is an output argument and CNORM(j) returns the 1-norm of the offdiagonal part of the j-th column of A 💜
  • INFO (INTEGER) —
    • = 0: successful exit 🎉
    • < 0: if INFO = -k, the k-th argument had an illegal value 🚨

🌸 Author 🌸

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🎀 Further Details 🎀

ngl bestie there is literally nothing here — the original page leaves this section empty 🙈 (the D version above has the whole bound-derivation essay, so go read that one if you want the math tea ☕)

so like, a rough bound on x gets computed first. if that bound is less than overflow, STRSV is called. otherwise, specific code is used which checks for possible overflow or divide-by-zero at every operation. no cap, it's giving cautious.

for solving A*x = b, it’s a columnwise scheme. the basic algorithm if A is lower triangular is:

x[1:n] := b[1:n]
for j = 1, ..., n
     x(j) := x(j) / A(j,j)
     x[j+1:n] := x[j+1:n] - x(j) * A[j+1:n,j]
end

define bounds on the components of x after j iterations of the loop:

M(j) = bound on x[1:j]
G(j) = bound on x[j+1:n]

initially, let M(0) = 0 and G(0) = max{x(i), i=1,...,n}.

then for iteration j+1 we have:

M(j+1) <= G(j) / | A(j+1,j+1) |
G(j+1) <= G(j) + M(j+1) * | A[j+2:n,j+1] |
         <= G(j) ( 1 + CNORM(j+1) / | A(j+1,j+1) | )

where CNORM(j+1) is greater than or equal to the infinity-norm of column j+1 of A, not counting the diagonal. hence:

G(j) <= G(0) product ( 1 + CNORM(i) / | A(i,i) | )
             1<=i<=j

and:

|x(j)| <= ( G(0) / |A(j,j)| ) product ( 1 + CNORM(i) / |A(i,i)| )
                              1<=i< j

since |x(j)| <= M(j), we use the Level 2 BLAS routine STRSV if the reciprocal of the largest M(j), j=1,..,n, is larger than max(underflow, 1/overflow).

the bound on x(j) is also used to determine when a step in the columnwise method can be performed without fear of overflow. if the computed bound is greater than a large constant, x is scaled to prevent overflow, but if the bound overflows, x is set to 0, x(j) to 1, and scale to 0, and a non-trivial solution to A*x = 0 is found. periodt, that’s the overflow safety tea.

similarly, a row-wise scheme is used to solve A**T*x = b. the basic algorithm for A upper triangular is:

for j = 1, ..., n
     x(j) := ( b(j) - A[1:j-1,j]**T * x[1:j-1] ) / A(j,j)
end

we simultaneously compute two bounds:

G(j) = bound on ( b(i) - A[1:i-1,i]**T * x[1:i-1] ), 1<=i<=j
M(j) = bound on x(i), 1<=i<=j

the initial values are G(0) = 0, M(0) = max{b(i), i=1,..,n}, and we add the constraint G(j) >= G(j-1) and M(j) >= M(j-1) for j >= 1. then the bound on x(j) is:

M(j) <= M(j-1) * ( 1 + CNORM(j) ) / | A(j,j) |

     <= M(0) * product ( ( 1 + CNORM(i) ) / |A(i,i)| )
               1<=i<=j

and we can safely call STRSV if 1/M(n) and 1/G(n) are both greater than max(underflow, 1/overflow).

Definition at line 236 of file slatrs.f.

subroutine zlatrs 💅

subroutine zlatrs (character uplo, character trans, character diag,
       character normin, integer n, complex*16, dimension( lda, * ) a, integer
       lda, complex*16, dimension( * ) x, double precision scale, double
       precision, dimension( * ) cnorm, integer info)

ZLATRS solves a triangular system of equations with the scale factor set to prevent overflow.

Purpose 💖

okay so ZLATRS solves one of the triangular systems:

A * x = s*b,  A**T * x = s*b,  or  A**H * x = s*b,

with scaling to prevent overflow. here A is an upper or lower triangular matrix, A**T denotes the transpose of A, A**H denotes the conjugate transpose of A, x and b are n-element vectors, and s is a scaling factor, usually less than or equal to 1, chosen so that the components of x will be less than the overflow threshold. if the unscaled problem will not cause overflow, the Level 2 BLAS routine ZTRSV is called. if the matrix A is singular (A(j,j) = 0 for some j), then s is set to 0 and a non-trivial solution to A*x = 0 is returned. iconic scaling behavior, honestly.

Parameters 🎀

  • UPLO — UPLO is CHARACTER*1. specifies whether the matrix A is upper or lower triangular. = 'U': upper triangular. = 'L': lower triangular.
  • TRANS — TRANS is CHARACTER*1. specifies the operation applied to A. = 'N': solve A * x = s*b (No transpose). = 'T': solve A**T * x = s*b (Transpose). = 'C': solve A**H * x = s*b (Conjugate transpose).
  • DIAG — DIAG is CHARACTER*1. specifies whether or not the matrix A is unit triangular. = 'N': non-unit triangular. = 'U': unit triangular.
  • NORMIN — NORMIN is CHARACTER*1. specifies whether CNORM has been set or not. = 'Y': CNORM contains the column norms on entry. = 'N': CNORM is not set on entry. on exit, the norms will be computed and stored in CNORM.
  • N — N is INTEGER. the order of the matrix A. N >= 0.
  • A — A is COMPLEX*16 array, dimension (LDA,N). the triangular matrix A. if UPLO = 'U', the leading n by n upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. if UPLO = 'L', the leading n by n lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. if DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1.
  • LDA — LDA is INTEGER. the leading dimension of the array A. LDA >= max (1,N).
  • X — X is COMPLEX*16 array, dimension (N). on entry, the right hand side b of the triangular system. on exit, X is overwritten by the solution vector x.
  • SCALE — SCALE is DOUBLE PRECISION. the scaling factor s for the triangular system A * x = s*b, A**T * x = s*b, or A**H * x = s*b. if SCALE = 0, the matrix A is singular or badly scaled, and the vector x is an exact or approximate solution to A*x = 0.
ngl, that SCALE = 0 case is the “bestie, the matrix is not okay” moment.
  • CNORM — CNORM is DOUBLE PRECISION array, dimension (N). if NORMIN = 'Y', CNORM is an input argument and CNORM(j) contains the norm of the off-diagonal part of the j-th column of A. if TRANS = 'N', CNORM(j) must be greater than or equal to the infinity-norm, and if TRANS = 'T' or 'C', CNORM(j) must be greater than or equal to the 1-norm. if NORMIN = 'N', CNORM is an output argument and CNORM(j) returns the 1-norm of the offdiagonal part of the j-th column of A.
  • INFO — INFO is INTEGER. = 0: successful exit. < 0: if INFO = -k, the k-th argument had an illegal value.

Author 👑

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

Further Details: 🔥

a rough bound on x is computed; if that is less than overflow, ZTRSV is called, otherwise, specific code is used which checks for possible overflow or divide-by-zero at every operation. very demure, very mindful.

a columnwise scheme is used for solving A*x = b. the basic algorithm if A is lower triangular is:

x[1:n] := b[1:n]
for j = 1, ..., n
     x(j) := x(j) / A(j,j)
     x[j+1:n] := x[j+1:n] - x(j) * A[j+1:n,j]
end

define bounds on the components of x after j iterations of the loop:

M(j) = bound on x[1:j]
G(j) = bound on x[j+1:n]

initially, let M(0) = 0 and G(0) = max{x(i), i=1,...,n}.

then for iteration j+1 we have:

M(j+1) <= G(j) / | A(j+1,j+1) |
G(j+1) <= G(j) + M(j+1) * | A[j+2:n,j+1] |
         <= G(j) ( 1 + CNORM(j+1) / | A(j+1,j+1) | )

where CNORM(j+1) is greater than or equal to the infinity-norm of column j+1 of A, not counting the diagonal. hence:

G(j) <= G(0) product ( 1 + CNORM(i) / | A(i,i) | )
             1<=i<=j

and:

|x(j)| <= ( G(0) / |A(j,j)| ) product ( 1 + CNORM(i) / |A(i,i)| )
                              1<=i< j

since |x(j)| <= M(j), we use the Level 2 BLAS routine ZTRSV if the reciprocal of the largest M(j), j=1,..,n, is larger than max(underflow, 1/overflow).

the bound on x(j) is also used to determine when a step in the columnwise method can be performed without fear of overflow. if the computed bound is greater than a large constant, x is scaled to prevent overflow, but if the bound overflows, x is set to 0, x(j) to 1, and scale to 0, and a non-trivial solution to A*x = 0 is found. that’s the overflow plot twist, bestie.

similarly, a row-wise scheme is used to solve A**T *x = b or A**H *x = b. the basic algorithm for A upper triangular is:

for j = 1, ..., n
     x(j) := ( b(j) - A[1:j-1,j]' * x[1:j-1] ) / A(j,j)
end

we simultaneously compute two bounds:

G(j) = bound on ( b(i) - A[1:i-1,i]' * x[1:i-1] ), 1<=i<=j
M(j) = bound on x(i), 1<=i<=j

the initial values are G(0) = 0, M(0) = max{b(i), i=1,..,n}, and we add the constraint G(j) >= G(j-1) and M(j) >= M(j-1) for j >= 1. then the bound on x(j) is:

M(j) <= M(j-1) * ( 1 + CNORM(j) ) / | A(j,j) |

     <= M(0) * product ( ( 1 + CNORM(i) ) / |A(i,i)| )
               1<=i<=j

and we can safely call ZTRSV if 1/M(n) and 1/G(n) are both greater than max(underflow, 1/overflow).

Definition at line 237 of file zlatrs.f.

🫶 AUTHOR 🫶

So who wrote this masterpiece? Plot twist: nobody sat down and typed it, bestie. This page was generated automatically by Doxygen for LAPACK from the source code — Doxygen literally pulled it out of the source, no human author hand-crafting it, no cap. Iconic automation moment ✨

Lowkey important vibe check: because it's auto-generated from the source, the source is the main character here — the docs just follow along 💅

<h2>🎀 the cute lil sign-off 🎀</h2>

And that's the whole page, bestie — you made it to the end, obsessed with your dedication fr fr 🌸 This gem comes from LAPACK, Version 3.12.0, and the page in your hands is latrs(3) 🦋 Go forth and triangular-solve with main character energy 👑💖

📦 where this page comes from