doubleGTsolve(3)

📦
version 3.11.0 · 2 versions
, in debian bookworm

🌸 doubleGTsolve(3) — LAPACK's double GT solve era 🌸

okay so bestie, this is the doubleGTsolve(3) page, and it's giving very specific linear algebra in the best way. it's a LAPACK group page. sit down, hydrate, we're doing tridiagonal solves 💅

✨ NAME ✨

doubleGTsolve — double 🫶 (that's it, that's the name, the whole name, no notes)

✨ SYNOPSIS ✨

🎀 Functions 🎀

  • subroutine dgtsv (N, NRHS, DL, D, DU, B, LDB, INFO) — DGTSV computes the solution to system of linear equations A * X = B for GT matrices ✨
  • subroutine dgtsvx (FACT, TRANS, N, NRHS, DL, D, DU, DLF, DF, DUF, DU2, IPIV, B, LDB, X, LDX, RCOND, FERR, BERR, WORK, IWORK, INFO) — DGTSVX computes the solution to system of linear equations A * X = B for GT matrices ✨

🌈 Detailed Description 🌈

This is the group of double solve driver functions for GT matrices. like, the whole squad. the GT solve squad. no cap 💖

👑 Function Documentation 👑

🦋 subroutine dgtsv 🦋

subroutine dgtsv (integer N, integer NRHS, double precision, dimension( * )
    DL, double precision, dimension( * ) D, double precision, dimension( * )
    DU, double precision, dimension( ldb, * ) B, integer LDB, integer INFO)

DGTSV computes the solution to system of linear equations A * X = B for GT matrices ✨

💜 Purpose 💜

DGTSV solves the equation

   A*X = B,

where A is an n by n tridiagonal matrix, by Gaussian elimination with partial pivoting.

lowkey important heads up: the equation A**T*X = B may be solved by interchanging the order of the arguments DU and DL. yes bestie, just swap them. the way that works is iconic ngl 🫶

🌸 Parameters 🌸

  • N — N is INTEGER. the order of the matrix A. N >= 0.
  • NRHS — NRHS is INTEGER. the number of right hand sides, aka the number of columns of the matrix B. NRHS >= 0.
  • DL — DL is DOUBLE PRECISION array, dimension (N-1). on entry, DL must contain the (n-1) sub-diagonal elements of A. on exit, DL is overwritten by the (n-2) elements of the second super-diagonal of the upper triangular matrix U from the LU factorization of A, sitting in DL(1), ..., DL(n-2). she gets recycled, periodt 💅
  • D — D is DOUBLE PRECISION array, dimension (N). on entry, D must contain the diagonal elements of A. on exit, D is overwritten by the n diagonal elements of U.
  • DU — DU is DOUBLE PRECISION array, dimension (N-1). on entry, DU must contain the (n-1) super-diagonal elements of A. on exit, DU is overwritten by the (n-1) elements of the first super-diagonal of U.
  • B — B is DOUBLE PRECISION array, dimension (LDB,NRHS). on entry, the N by NRHS matrix of right hand side matrix B. on exit, if INFO = 0, the N by NRHS solution matrix X. she came in as B and left as X, main character behavior 😌
  • LDB — LDB is INTEGER. the leading dimension of the array B. LDB >= max(1,N).
  • INFO — INFO is INTEGER.
    • = 0: successful exit 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value 😭
    • > 0: if INFO = i, U(i,i) is exactly zero, and the solution has not been computed. the factorization has not been completed unless i = N. 💀 this is not a drill bestie

🧚 Author 🧚

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

🦋 subroutine dgtsvx 🦋

subroutine dgtsvx (character FACT, 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 RCOND,
    double precision, dimension( * ) FERR, double precision, dimension( * )
    BERR, double precision, dimension( * ) WORK, integer, dimension( * )
    IWORK, integer INFO)

DGTSVX computes the solution to system of linear equations A * X = B for GT matrices ✨

💜 Purpose 💜

DGTSVX uses the LU factorization to compute the solution to a real system of linear equations A * X = B or A**T * X = B, where A is a tridiagonal matrix of order N and X and B are N-by-NRHS matrices.

error bounds on the solution and a condition estimate are also provided. she's thorough like that 💖

🌈 Description 🌈

the following steps are performed:

  1. If FACT = 'N', the LU decomposition is used to factor the matrix A as A = L * U, where L is a product of permutation and unit lower bidiagonal matrices and U is upper triangular with nonzeros in only the main diagonal and first two superdiagonals.
  2. If some U(i,i)=0, so that U is exactly singular, then the routine returns with INFO = i. otherwise, the factored form of A is used to estimate the condition number of the matrix A. if the reciprocal of the condition number is less than machine precision, INFO = N+1 is returned as a warning, but the routine still goes on to solve for X and compute error bounds as described below. she warns you but she does NOT stop, she's committed 😤
  3. The system of equations is solved for X using the factored form of A.
  4. Iterative refinement is applied to improve the computed solution matrix and calculate error bounds and backward error estimates for it.

🌸 Parameters 🌸

  • FACT — FACT is CHARACTER*1. specifies whether or not the factored form of A has been supplied on entry.
    • = 'F': DLF, DF, DUF, DU2, and IPIV contain the factored form of A; DL, D, DU, DLF, DF, DUF, DU2 and IPIV will not be modified. hands off bestie, they're taken 💅
    • = 'N': the matrix will be copied to DLF, DF, and DUF and factored.
  • TRANS — TRANS is 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 — N is INTEGER. the order of the matrix A. N >= 0.
  • NRHS — NRHS is INTEGER. the number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
  • DL — DL is DOUBLE PRECISION array, dimension (N-1). the (n-1) subdiagonal elements of A.
  • D — D is DOUBLE PRECISION array, dimension (N). the n diagonal elements of A.
  • DU — DU is DOUBLE PRECISION array, dimension (N-1). the (n-1) superdiagonal elements of A.
  • DLF — DLF is DOUBLE PRECISION array, dimension (N-1).
    • If FACT = 'F', then DLF is an input argument and on entry contains the (n-1) multipliers that define the matrix L from the LU factorization of A as computed by DGTTRF.
    • If FACT = 'N', then DLF is an output argument and on exit contains the (n-1) multipliers that define the matrix L from the LU factorization of A.
  • DF — DF is DOUBLE PRECISION array, dimension (N).
    • If FACT = 'F', then DF is an input argument and on entry contains the n diagonal elements of the upper triangular matrix U from the LU factorization of A.
    • If FACT = 'N', then DF is an output argument and on exit contains the n diagonal elements of the upper triangular matrix U from the LU factorization of A.
  • DUF — DUF is DOUBLE PRECISION array, dimension (N-1).
    • If FACT = 'F', then DUF is an input argument and on entry contains the (n-1) elements of the first superdiagonal of U.
    • If FACT = 'N', then DUF is an output argument and on exit contains the (n-1) elements of the first superdiagonal of U.
  • DU2 — DU2 is DOUBLE PRECISION array, dimension (N-2).
    • If FACT = 'F', then DU2 is an input argument and on entry contains the (n-2) elements of the second superdiagonal of U.
    • If FACT = 'N', then DU2 is an output argument and on exit contains the (n-2) elements of the second superdiagonal of U.
  • IPIV — IPIV is INTEGER array, dimension (N).
    • If FACT = 'F', then IPIV is an input argument and on entry contains the pivot indices from the LU factorization of A as computed by DGTTRF.
    • If FACT = 'N', then IPIV is an output argument and on exit contains the pivot indices from the LU factorization of A; 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 — B is DOUBLE PRECISION array, dimension (LDB,NRHS). the N-by-NRHS right hand side matrix B.
  • LDB — LDB is INTEGER. the leading dimension of the array B. LDB >= max(1,N).
  • X — X is DOUBLE PRECISION array, dimension (LDX,NRHS). if INFO = 0 or INFO = N+1, the N-by-NRHS solution matrix X. 🎀
  • LDX — LDX is INTEGER. the leading dimension of the array X. LDX >= max(1,N).
  • RCOND — RCOND is DOUBLE PRECISION. the estimate of the reciprocal condition number of the matrix A. if RCOND is less than the machine precision (in particular, if RCOND = 0), the matrix is singular to working precision. this condition is indicated by a return code of INFO > 0. 😭
  • FERR — FERR is 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. she's a little dramatic, she overestimates, relatable 💅
  • BERR — BERR is 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 —
  • WORK — DOUBLE PRECISION array, dimension (3*N). yeah bestie this is the scratch space, give it 3*N doubles, she needs room to breathe ✨
  • IWORK — INTEGER array, dimension (N). the integer bestie, dimension N, she's here for the bookkeeping 🎀
  • INFO — INTEGER, and this is the ✨vibe check✨ at the end. here's the tea, every possible value, no skips:
= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, and i is
      <= N:  U(i,i) is exactly zero.  The factorization
             has not been completed unless i = N, but the
             factor U is exactly singular, so the solution
             and error bounds could not be computed.
             RCOND = 0 is returned.
      = N+1: U is nonsingular, but RCOND is less than machine
             precision, meaning that the matrix is singular
             to working precision.  Nevertheless, the
             solution and error bounds are computed because
             there are a number of situations where the
             computed solution can be more accurate than the
             value of RCOND would suggest.
okay so let's decode that because it's giving cryptic 💀
  • INFO = 0 — we ate. successful exit, no notes. 💅
  • INFO < 0 — if INFO = -i, then the i-th argument had an illegal value. something you passed in was a no ❌ bestie, the i-th one specifically.
  • INFO > 0 — if INFO = i, then it depends on what i is:
    • if i <= N: U(i,i) is exactly zero. the factorization has not been completed unless i = N, but the factor U is exactly singular, so the solution and error bounds could not be computed, and RCOND = 0 is returned. it's giving singular, it's giving unsolvable, it's giving not today 💀
    • if i = N+1: U is nonsingular, but RCOND is less than machine precision, which means the matrix is singular to working precision. nevertheless, the solution and error bounds are computed, because there are a number of situations where the computed solution can be more accurate than the value of RCOND would suggest. like okay she's technically singular but she's still serving, lowkey iconic 😭🫶

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 Author (yes, again)

Generated automatically by Doxygen for LAPACK from the source code. not a human writing this one bestie, the machine did it, and honestly? she did that 💅✨

okay and that's a wrap on doubleGTsolve(3)!! this lil page is from LAPACK Version 3.11.0, dated Sun Nov 27 2022, and it was auto-generated by Doxygen for LAPACK from the source code. go solve something slay, bestie 🦋💖 mwah!

📦 where this page comes from