gtrfs(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💅 gtrfs(3) — Library Functions Manual

okay bestie, buckle up, because this one is a whole family of routines, not just one. we're in the <gtrfs> section 3 pages, the Library Functions Manual vibe. this is part 1 of the gtrfs saga, and it's giving "iterative refinement, but make it a girlboss". 💖

🌸 NAME

gtrfs — gtrfs: iterative refinement 💫

like, that's literally the whole name section. short and iconic. 👑

✨ SYNOPSIS

🎀 Functions

here's the whole squad, all four of them, and yes they all take the same shape of args except the last couple (that's the whole real/complex divide, iykyk):

subroutine cgtrfs (trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv,
    b, ldb, x, ldx, ferr, berr, work, rwork, info)
    CGTRFS
subroutine dgtrfs (trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv,
    b, ldb, x, ldx, ferr, berr, work, iwork, info)
    DGTRFS
subroutine sgtrfs (trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv,
    b, ldb, x, ldx, ferr, berr, work, iwork, info)
    SGTRFS
subroutine zgtrfs (trans, n, nrhs, dl, d, du, dlf, df, duf, du2, ipiv,
    b, ldb, x, ldx, ferr, berr, work, rwork, info)
    ZGTRFS

<cute note>the work array is the main character who sometimes brings a plus-one: the single/double ones roll with iwork, the complex ones bring rwork instead. slay.</cute note>

💫 Detailed Description

okay so the original page literally has this heading with nothing under it. empty. void. a vibe. 🕳️ we move on, bestie — the good stuff is right below. 🫶

📖 Function Documentation

🔥 subroutine cgtrfs — CGTRFS

subroutine cgtrfs (character trans, integer n, integer nrhs, complex,
    dimension( * ) dl, complex, dimension( * ) d, complex, dimension( * )
    du, complex, dimension( * ) dlf, complex, dimension( * ) df, complex,
    dimension( * ) duf, complex, dimension( * ) du2, integer, dimension( * )
    ipiv, complex, dimension( ldb, * ) b, integer ldb, complex, dimension(
    ldx, * ) x, integer ldx, real, dimension( * ) ferr, real, dimension( * )
    berr, complex, dimension( * ) work, real, dimension( * ) rwork, integer
    info)
    CGTRFS

🦋 Purpose

CGTRFS improves the computed solution to a system of linear equations when the coefficient matrix is tridiagonal, and provides error bounds and backward error estimates for the solution.

so basically: your tridiagonal solve came out a little crusty, and this routine polishes it up 💅 and then hands you receipts (the error bounds) proving how good the polished answer is. no cap, it's giving "trust but verify".

🌸 Parameters

  • TRANS — CHARACTER*1. tells us which flavor of system we're solving:
    • = 'N': A * X = B (no transpose)
    • = 'T': A**T * X = B (transpose)
    • = 'C': A**H * X = B (conjugate transpose)
  • N — INTEGER. the order of the matrix A. must be N >= 0.
  • NRHS — INTEGER. the number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • DL — COMPLEX array, dimension (N-1). the (n-1) subdiagonal elements of A.
  • D — COMPLEX array, dimension (N). the diagonal elements of A.
  • DU — COMPLEX array, dimension (N-1). the (n-1) superdiagonal elements of A.
  • DLF — COMPLEX array, dimension (N-1). the (n-1) multipliers that define the matrix L from the LU factorization of A as computed by CGTTRF.
  • DF — COMPLEX array, dimension (N). the n diagonal elements of the upper triangular matrix U from the LU factorization of A.
  • DUF — COMPLEX array, dimension (N-1). the (n-1) elements of the first superdiagonal of U.
  • DU2 — COMPLEX array, dimension (N-2). the (n-2) elements of the second superdiagonal of U.
  • IPIV — INTEGER array, dimension (N). the pivot indices; for 1 <= i <= n, row i of the matrix was interchanged with row IPIV(i). IPIV(i) will always be either i or i+1; IPIV(i) = i indicates a row interchange was not required. (so like, minimal drama pivoting 🎀)
  • B — COMPLEX array, dimension (LDB,NRHS). the right hand side matrix B.
  • LDB — INTEGER. the leading dimension of the array B. LDB >= max(1,N).
  • X — COMPLEX array, dimension (LDX,NRHS). on entry, the solution matrix X, as computed by CGTTRS. on exit, the improved solution matrix X. ✨ glow-up complete ✨
  • LDX — INTEGER. the leading dimension of the array X. LDX >= max(1,N).
  • FERR — REAL array, dimension (NRHS). the estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). if XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). the estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.
so yeah, it's a bound, and it's almost always a lil bit dramatic (slight overestimate). reliable though — same trust level as RCOND. 🫶
  • BERR — REAL array, dimension (NRHS). the componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
  • WORK — COMPLEX array, dimension (2*N).
  • RWORK — REAL array, dimension (N).
  • INFO — INTEGER.
    • = 0: successful exit 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value 💀

💜 Internal Parameters

ITMAX is the maximum number of steps of iterative refinement.

(yes, it's internal, so don't come for her, she's not in your arg list.)

👑 Author

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

Definition at line 207 of file cgtrfs.f.

🌈 subroutine dgtrfs — DGTRFS

subroutine dgtrfs (character trans, integer n, integer nrhs, double
    precision, dimension( * ) dl, double precision, dimension( * ) d, double
    precision, dimension( * ) du, double precision, dimension( * ) dlf,
    double precision, dimension( * ) df, double precision, dimension( * )
    duf, double precision, dimension( * ) du2, integer, dimension( * ) ipiv,
    double precision, dimension( ldb, * ) b, integer ldb, double precision,
    dimension( ldx, * ) x, integer ldx, double precision, dimension( * )
    ferr, double precision, dimension( * ) berr, double precision,
    dimension( * ) work, integer, dimension( * ) iwork, integer info)
    DGTRFS

🦋 Purpose

DGTRFS improves the computed solution to a system of linear equations when the coefficient matrix is tridiagonal, and provides error bounds and backward error estimates for the solution.

same energy, double precision flavor. the double-precision girlies get the exact same deal: better solution + receipts. 💅

🌸 Parameters

  • TRANS — CHARACTER*1. specifies the form of the system of equations:
    • = 'N': A * X = B (no transpose)
    • = 'T': A**T * X = B (transpose)
    • = 'C': A**H * X = B (conjugate transpose = Transpose)
small but important detail bestie: over here in real-land, 'C' is literally the same thing as transpose, and the page says so out loud. 🫶
  • N — INTEGER. the order of the matrix A. N >= 0.
  • NRHS — INTEGER. the number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • DL — DOUBLE PRECISION array, dimension (N-1). the (n-1) subdiagonal elements of A.
  • D — DOUBLE PRECISION array, dimension (N). the diagonal elements of A.
  • DU — DOUBLE PRECISION array, dimension (N-1). the (n-1) superdiagonal elements of A.
  • DLF — DOUBLE PRECISION array, dimension (N-1). the (n-1) multipliers that define the matrix L from the LU factorization of A as computed by DGTTRF.
  • DF — DOUBLE PRECISION array, dimension (N). the n diagonal elements of the upper triangular matrix U from the LU factorization of A.
  • DUF — DOUBLE PRECISION array, dimension (N-1). the (n-1) elements of the first superdiagonal of U.
  • DU2 — DOUBLE PRECISION array, dimension (N-2). the (n-2) elements of the second superdiagonal of U.
  • IPIV — INTEGER array, dimension (N). the pivot indices; for 1 <= i <= n, row i of the matrix was interchanged with row IPIV(i). IPIV(i) will always be either i or i+1; IPIV(i) = i indicates a row interchange was not required.
  • B — DOUBLE PRECISION array, dimension (LDB,NRHS). the right hand side matrix B.
  • LDB — INTEGER. the leading dimension of the array B. LDB >= max(1,N).
  • X — DOUBLE PRECISION array, dimension (LDX,NRHS). on entry, the solution matrix X, as computed by DGTTRS. on exit, the improved solution matrix X. ✨
  • LDX — INTEGER. the leading dimension of the array X. LDX >= max(1,N).
  • FERR — DOUBLE PRECISION array, dimension (NRHS). the estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). if XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). the estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.
  • BERR — DOUBLE PRECISION array, dimension (NRHS). the componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
  • WORK — DOUBLE PRECISION array, dimension (3*N).
👀 yes, 3*N here, not the 2*N the complex one uses. don't mix them up, bestie, that's a whole different girl.
  • IWORK — INTEGER array, dimension (N).
  • INFO — INTEGER.
    • = 0: successful exit 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value 💀

💜 Internal Parameters

ITMAX is the maximum number of steps of iterative refinement.

okay and that's where part 1 stops — <sgtrfs> and <zgtrfs> are still backstage getting ready, and there's more of dgtrfs's paperwork to come. don't go anywhere bestie, part 2 is literally right there. 💖

💫 Author

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

Definition at line 206 of file dgtrfs.f.

🦋 sgtrfs 💖

subroutine sgtrfs (character trans, integer n, integer nrhs, real,
dimension( * ) dl, real, dimension( * ) d, real, dimension( * ) du,
real, dimension( * ) dlf, real, dimension( * ) df, real, dimension( * )
duf, real, dimension( * ) du2, integer, dimension( * ) ipiv, real,
dimension( ldb, * ) b, integer ldb, real, dimension( ldx, * ) x, integer
ldx, real, dimension( * ) ferr, real, dimension( * ) berr, real,
dimension( * ) work, integer, dimension( * ) iwork, integer info)

SGTRFS — single precision, real, tridiagonal, and honestly? She ate. 💅

✨ Purpose ✨

okay so real talk: SGTRFS improves the computed solution to a system of linear equations when the coefficient matrix is tridiagonal, and provides error bounds and backward error estimates for the solution. That's the whole gig. She takes your kinda-good answer and makes it good good. 🫶

🎀 Parameters 🎀

  • TRANS — CHARACTER*1. Specifies the form of the system of equations:
    • = 'N': A * X = B (No transpose)
    • = 'T': A**T * X = B (Transpose)
    • = 'C': A**H * X = B (Conjugate transpose = Transpose)
  • N — INTEGER. The order of the matrix A. N >= 0.
  • NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • DL — REAL array, dimension (N-1). The (n-1) subdiagonal elements of A.
  • D — REAL array, dimension (N). The diagonal elements of A. the main character energy of the tridiagonal trio tbh. 👑
  • DU — REAL array, dimension (N-1). The (n-1) superdiagonal elements of A.
  • DLF — REAL array, dimension (N-1). The (n-1) multipliers that define the matrix L from the LU factorization of A as computed by SGTTRF.
  • DF — REAL array, dimension (N). The n diagonal elements of the upper triangular matrix U from the LU factorization of A.
  • DUF — REAL array, dimension (N-1). The (n-1) elements of the first superdiagonal of U.
  • DU2 — REAL array, dimension (N-2). The (n-2) elements of the second superdiagonal of U.
  • IPIV — INTEGER array, dimension (N). The pivot indices; for 1 <= i <= n, row i of the matrix was interchanged with row IPIV(i). IPIV(i) will always be either i or i+1; IPIV(i) = i indicates a row interchange was not required. lowkey the receipts of who moved where. 🔥
  • B — REAL array, dimension (LDB,NRHS). The right hand side matrix B.
  • LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
  • X — REAL array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by SGTTRS. On exit, the improved solution matrix X. glow-up arc fr fr. ✨
  • LDX — INTEGER. The leading dimension of the array X. LDX >= max(1,N).
  • FERR — REAL array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. ngl she's a little dramatic but she's not wrong. 💀
  • BERR — REAL array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
  • WORK — REAL array, dimension (3*N).
  • IWORK — INTEGER array, dimension (N).
  • INFO — INTEGER.
    • = 0: successful exit
    • < 0: if INFO = -i, the i-th argument had an illegal value

🧚 Internal Parameters: 🧚

ITMAX is the maximum number of steps of iterative refinement. she doesn't grind forever, okay? there's a limit. 😌

💜 Author 💜

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

Definition at line 206 of file sgtrfs.f.

🌈 zgtrfs 🍓

subroutine zgtrfs (character trans, integer n, integer nrhs, complex*16,
dimension( * ) dl, complex*16, dimension( * ) d, complex*16, dimension(
* ) du, complex*16, dimension( * ) dlf, complex*16, dimension( * ) df,
complex*16, dimension( * ) duf, complex*16, dimension( * ) du2, integer,
dimension( * ) ipiv, complex*16, dimension( ldb, * ) b, integer ldb,
complex*16, dimension( ldx, * ) x, integer ldx, double precision,
dimension( * ) ferr, double precision, dimension( * ) berr, complex*16,
dimension( * ) work, double precision, dimension( * ) rwork, integer
info)

ZGTRFS — complex*16 era, double precision error bounds, absolutely serving. 🦋

✨ Purpose ✨

ZGTRFS improves the computed solution to a system of linear equations when the coefficient matrix is tridiagonal, and provides error bounds and backward error estimates for the solution. same assignment as her single-precision sister, just with complex numbers in the mix. no cap. 💖

🎀 Parameters 🎀

  • TRANS — CHARACTER*1. Specifies the form of the system of equations:
    • = 'N': A * X = B (No transpose)
    • = 'T': A**T * X = B (Transpose)
    • = 'C': A**H * X = B (Conjugate transpose)
  • N — INTEGER. The order of the matrix A. N >= 0.
  • NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • DL — COMPLEX*16 array, dimension (N-1). The (n-1) subdiagonal elements of A.
  • D — COMPLEX*16 array, dimension (N). The diagonal elements of A.
  • DU — COMPLEX*16 array, dimension (N-1). The (n-1) superdiagonal elements of A.
  • DLF — COMPLEX*16 array, dimension (N-1). The (n-1) multipliers that define the matrix L from the LU factorization of A as computed by ZGTTRF.
  • DF — COMPLEX*16 array, dimension (N). The n diagonal elements of the upper triangular matrix U from the LU factorization of A.
  • DUF — COMPLEX*16 array, dimension (N-1). The (n-1) elements of the first superdiagonal of U.
  • DU2 — COMPLEX*16 array, dimension (N-2). The (n-2) elements of the second superdiagonal of U.
  • IPIV — INTEGER array, dimension (N). The pivot indices; for 1 <= i <= n, row i of the matrix was interchanged with row IPIV(i). IPIV(i) will always be either i or i+1; IPIV(i) = i indicates a row interchange was not required.
  • B — COMPLEX*16 array, dimension (LDB,NRHS). The right hand side matrix B.
  • LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
  • X — COMPLEX*16 array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by ZGTTRS. On exit, the improved solution matrix X.
  • LDX — INTEGER. The leading dimension of the array X. LDX >= max(1,N).
  • FERR — DOUBLE PRECISION array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.
  • BERR — DOUBLE PRECISION array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
  • WORK — COMPLEX*16 array, dimension (2*N).
  • RWORK — DOUBLE PRECISION array, dimension (N).
  • INFO — INTEGER.
    • = 0: successful exit
    • < 0: if INFO = -i, the i-th argument had an illegal value

🧚 Internal Parameters: 🧚

ITMAX is the maximum number of steps of iterative refinement. yes bestie, there's a cap on the grinding. 🙈

💜 Author 💜

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

Definition at line 207 of file zgtrfs.f.

⭐ Author ⭐

Generated automatically by Doxygen for LAPACK from the source code. not a human author, a machine author, and honestly she's slaying the automation. 🤖💅

that's the whole page bestie, you made it to the end!! 🎉 this one's stamped LAPACK, Version 3.12.0, and it lives at gtrfs(3) in the manual — so if you ever need to find her again, that's the address. mwah, go improve some solutions. 🌸🎀🫶

📦 where this page comes from