ptsvx(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

✨ ptsvx(3) ✨ — Library Functions Manual

okay so bestie, we're in ptsvx(3) territory and this is the expert flavour of the PT-matrix saga — factor and solve, with receipts (error bounds, condition estimates, the whole vibe). This page is a chunky one so buckle up 🎀

🌸 NAME 🌸

ptsvx — ptsvx: factor and solve, expert

literally that's the whole name, she's efficient 💅

🌈 SYNOPSIS 🌈

✨ Functions ✨

Here's the whole friend group — four subroutines, one for each flavour of precision and vibes:

subroutine cptsvx (fact, n, nrhs, d, e, df, ef, b, ldb, x, ldx, rcond,
    ferr, berr, work, rwork, info)

CPTSVX computes the solution to system of linear equations A * X = B for PT matrices 🦋

subroutine dptsvx (fact, n, nrhs, d, e, df, ef, b, ldb, x, ldx, rcond,
    ferr, berr, work, info)

DPTSVX computes the solution to system of linear equations A * X = B for PT matrices 🌸

subroutine sptsvx (fact, n, nrhs, d, e, df, ef, b, ldb, x, ldx, rcond,
    ferr, berr, work, info)

SPTSVX computes the solution to system of linear equations A * X = B for PT matrices ⭐

subroutine zptsvx (fact, n, nrhs, d, e, df, ef, b, ldb, x, ldx, rcond,
    ferr, berr, work, rwork, info)

ZPTSVX computes the solution to system of linear equations A * X = B for PT matrices 👑

💅 Detailed Description 💅

(we love a section that's just a heading, she said "the details are in the functions, go look" 😭)

🦋 Function Documentation 🦋

🌟 subroutine cptsvx

subroutine cptsvx (character fact, integer n, integer nrhs, real, dimension(
    * ) d, complex, dimension( * ) e, real, dimension( * ) df, complex,
    dimension( * ) ef, complex, dimension( ldb, * ) b, integer ldb, complex,
    dimension( ldx, * ) x, integer ldx, real rcond, real, dimension( * )
    ferr, real, dimension( * ) berr, complex, dimension( * ) work, real,
    dimension( * ) rwork, integer info)

CPTSVX computes the solution to system of linear equations A * X = B for PT matrices 💖

🎀 Purpose

no cap, here's what she does:

CPTSVX uses the factorization A = L*D*L**H to compute the solution to a complex system of linear equations A*X = B, where A is an N-by-N Hermitian positive definite tridiagonal matrix and X and B are N-by-NRHS matrices.
Error bounds on the solution and a condition estimate are also provided.

like she solves it and tells you how much you should trust the answer. main character energy honestly 👑

🔥 Description

the steps, in order, periodt:

The following steps are performed:
  1. If FACT = 'N', the matrix A is factored as A = L*D*L**H, where L is a unit lower bidiagonal matrix and D is diagonal. The factorization can also be regarded as having the form A = U**H*D*U.
  2. If the leading principal minor of order i is not positive, 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.
  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.

okay so step 2 is the girl who says "this might be messy but I'm finishing the job anyway" and honestly? respect 🫶

💜 Parameters

  • FACT — FACT is CHARACTER*1. Specifies whether or not the factored form of the matrix A is supplied on entry.
    • = 'F': On entry, DF and EF contain the factored form of A. D, E, DF, and EF will not be modified.
    • = 'N': The matrix A will be copied to DF and EF and factored.
  • 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 matrices B and X. NRHS >= 0.
  • D — D is REAL array, dimension (N). The n diagonal elements of the tridiagonal matrix A.
  • E — E is COMPLEX array, dimension (N-1). The (n-1) subdiagonal elements of the tridiagonal matrix A.
  • DF — DF is REAL array, dimension (N). If FACT = 'F', then DF is an input argument and on entry contains the n diagonal elements of the diagonal matrix D from the L*D*L**H factorization of A. If FACT = 'N', then DF is an output argument and on exit contains the n diagonal elements of the diagonal matrix D from the L*D*L**H factorization of A.
  • EF — EF is COMPLEX array, dimension (N-1). If FACT = 'F', then EF is an input argument and on entry contains the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**H factorization of A. If FACT = 'N', then EF is an output argument and on exit contains the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**H factorization of A.
  • B — B is COMPLEX 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 COMPLEX 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 REAL. 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 REAL array, dimension (NRHS). The 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).
  • BERR — BERR is 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 — WORK is COMPLEX array, dimension (N).
  • RWORK — RWORK is REAL array, dimension (N).
  • INFO — INFO is INTEGER.
    • = 0: successful exit 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value
    • > 0: if INFO = i, and i is
      • <= N: the leading principal minor of order i of A is not positive, so the factorization could not be completed, and the solution has not been 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.
ngl the INFO = N+1 case is iconic — she's basically like "the vibes say singular but the math says try me" 💀

🌈 Author

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

Definition at line 232 of file cptsvx.f.

🌸 subroutine dptsvx

subroutine dptsvx (character fact, integer n, integer nrhs, double
    precision, dimension( * ) d, double precision, dimension( * ) e, double
    precision, dimension( * ) df, double precision, dimension( * ) ef,
    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 info)

DPTSVX computes the solution to system of linear equations A * X = B for PT matrices 🧚

🎀 Purpose

DPTSVX uses the factorization A = L*D*L**T to compute the solution to a real system of linear equations A*X = B, where A is an N-by-N symmetric positive definite tridiagonal matrix and X and B are N-by-NRHS matrices.
Error bounds on the solution and a condition estimate are also provided.

note bestie: this one's the real twin — L*D*L**T and symmetric, not L**H and Hermitian. the transposes are lowercase-T here, fr fr 💫

🔥 Description

The following steps are performed:
  1. If FACT = 'N', the matrix A is factored as A = L*D*L**T, where L is a unit lower bidiagonal matrix and D is diagonal. The factorization can also be regarded as having the form A = U**T*D*U.
  2. If the leading principal minor of order i is not positive, 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.
  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.

same four-step choreo, different precision aesthetic ✨

💜 Parameters

  • FACT — FACT is CHARACTER*1. Specifies whether or not the factored form of A has been supplied on entry.
    • = 'F': On entry, DF and EF contain the factored form of A. D, E, DF, and EF will not be modified.
    • = 'N': The matrix A will be copied to DF and EF and factored.
  • 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 matrices B and X. NRHS >= 0.
  • D — DOUBLE PRECISION array, dimension (N). The n diagonal elements of the tridiagonal matrix A. that's her 💅
  • E — DOUBLE PRECISION array, dimension (N-1). The (n-1) subdiagonal elements of the tridiagonal matrix A. yes it's one shorter than D, no that's not a typo, that's just how bidiagonal-ish things roll 🎀
  • DF — DOUBLE PRECISION array, dimension (N). okay so it's giving "depends on FACT":
    • if FACT = 'F', DF is an input argument, and on entry it contains the n diagonal elements of the diagonal matrix D from the L*D*L**T factorization of A.
    • if FACT = 'N', DF is an output argument, and on exit it contains the n diagonal elements of the diagonal matrix D from the L*D*L**T factorization of A.
  • EF — DOUBLE PRECISION array, dimension (N-1). same energy, different slot:
    • if FACT = 'F', EF is an input argument and on entry it contains the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**T factorization of A.
    • if FACT = 'N', EF is an output argument and on exit it contains the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**T factorization of A.
  • B — DOUBLE PRECISION array, dimension (LDB,NRHS). The N-by-NRHS right hand side matrix B. the whole reason we're here fr fr 🫶
  • LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N). respect the constraint bestie, she will notice 😭
  • X — DOUBLE PRECISION array, dimension (LDX,NRHS). If INFO = 0 of INFO = N+1, the N-by-NRHS solution matrix X. (that of is a typo in the original, it means or 💀 the math is fine, the grammar is not)
  • LDX — INTEGER. The leading dimension of the array X. LDX >= max(1,N). same deal as LDB, max(1,N) and all ✨
  • RCOND — DOUBLE PRECISION. 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. so like… she's telling you how sketchy your matrix is 👀
  • FERR — DOUBLE PRECISION array, dimension (NRHS). The 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). literally "how far off are you, relatively speaking" 💅
  • 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). iconic little "how much would I have to lie to you to be right" metric 🦋
  • WORK — DOUBLE PRECISION array, dimension (2*N). scratch space, don't touch, don't question her 🌸
  • INFO — INTEGER. the receipts:
    • = 0: successful exit 😌
    • < 0: if INFO = -i, the i-th argument had an illegal value — you passed something cursed, go fix it 🙈
    • > 0: if INFO = i, and i is
      • <= N: the leading principal minor of order i of A is not positive, so the factorization could not be completed, and the solution has not been computed. RCOND = 0 is returned. translation: she stopped mid-way, no answer for you, and she's telling you exactly where it went wrong 😭
      • = 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. this is the "warning but keep going" one, she's a lil scuffed but she pulled through 💀✨

🎀 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

shoutout to the entire academic-industrial complex, they ate 👑🫶

⭐ Definition at line 226 of file dptsvx.f.

like, line 226 of dptsvx.f, go look, she's there 💖

🦋 and now… the REAL one (yes there's a single-precision twin)

subroutine sptsvx (character fact, integer n, integer nrhs, real, dimension(
* ) d, real, dimension( * ) e, real, dimension( * ) df, real, dimension(
* ) ef, real, dimension( ldb, * ) b, integer ldb, real, dimension( ldx,
* ) x, integer ldx, real rcond, real, dimension( * ) ferr, real,
dimension( * ) berr, real, dimension( * ) work, integer info)

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

so literally the same routine as DPTSVX but everything's REAL instead of DOUBLE PRECISION. same vibes, less precision, arguably more chill 🌈

🌸 Purpose:

SPTSVX uses the factorization A = L*D*L**T to compute the solution to a real system of linear equations A*X = B, where A is an N-by-N symmetric positive definite tridiagonal matrix and X and B are N-by-NRHS matrices.

Error bounds on the solution and a condition estimate are also provided. so not only does she solve it, she also tells you how much to trust the answer. main character behaviour 💅👑

🐚 Description:

here's the whole plot, step by step:

  1. If FACT = 'N', the matrix A is factored as A = L*D*L**T, where L is a unit lower bidiagonal matrix and D is diagonal. The factorization can also be regarded as having the form A = U**T*D*U. two ways to look at the same glow-up 🦋
  2. If the leading principal minor of order i is not positive, 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's not gonna abandon you over a warning, she's built different 💀
  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. glow-up round two, now with receipts ✨

🧚 Parameters

  • FACT — CHARACTER*1. Specifies whether or not the factored form of A has been supplied on entry.
    • = 'F': On entry, DF and EF contain the factored form of A. D, E, DF, and EF will not be modified. she respects your inputs, no cap 🫶
    • = 'N': The matrix A will be copied to DF and EF and factored. she'll do it herself, it's fine 💅
  • 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 matrices B and X. NRHS >= 0. yes you can feed her multiple right hand sides at once, she's efficient like that 🌸
  • D — REAL array, dimension (N). The n diagonal elements of the tridiagonal matrix A. 🎀
  • E — REAL array, dimension (N-1). The (n-1) subdiagonal elements of the tridiagonal matrix A.
  • DF — REAL array, dimension (N). again, FACT-dependent:
    • if FACT = 'F', then DF is an input argument and on entry contains the n diagonal elements of the diagonal matrix D from the L*D*L**T factorization of A.
    • if FACT = 'N', then DF is an output argument and on exit contains the n diagonal elements of the diagonal matrix D from the L*D*L**T factorization of A.
  • EF — REAL array, dimension (N-1). same pattern bestie:
    • if FACT = 'F', then EF is an input argument and on entry contains the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**T factorization of A.
    • if FACT = 'N', then EF is an output argument and on exit contains the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**T factorization of A.
  • B — REAL array, dimension (LDB,NRHS). The N-by-NRHS right hand side matrix B. 🍓
  • LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
  • X — REAL array, dimension (LDX,NRHS). If INFO = 0 of INFO = N+1, the N-by-NRHS solution matrix X. (again with the of, again meaning or, again not my fault 😭)
  • LDX — INTEGER. The leading dimension of the array X. LDX >= max(1,N).
  • RCOND — REAL. 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. your vibe check on the matrix, basically 👀
  • FERR — REAL array, dimension (NRHS). The 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).
  • 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 (2*N). scratch space, she needs room to think 🌸
  • INFO — INTEGER. bestie this one has lore, hold on 💜

Still on sptsvx: INFO is INTEGER, and it's the final vibe report of the call:

  • = 0: successful exit — slay, we're done. ✅
  • < 0: if INFO = -i, the i-th argument had an illegal value — so something you passed was lowkey not it. 🙈
  • > 0: if INFO = i, and i is:
    • <= N: the leading principal minor of order i of A is not positive, so the factorization could not be completed, and the solution has not been 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. 💀

🫶 Author

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

Definition at line 226 of file sptsvx.f.

🌟 subroutine zptsvx

subroutine zptsvx (character fact, integer n, integer nrhs, double
       precision, dimension( * ) d, complex*16, dimension( * ) e, double
       precision, dimension( * ) df, complex*16, dimension( * ) ef, complex*16,
       dimension( ldb, * ) b, integer ldb, complex*16, dimension( ldx, * ) x,
       integer ldx, double precision rcond, double precision, dimension( * )
       ferr, double precision, dimension( * ) berr, complex*16, dimension( * )
       work, double precision, dimension( * ) rwork, integer info)

ZPTSVX computes the solution to system of linear equations A * X = B for PT matrices — literally what it says on the tin, and it's giving main character energy. 👑

🦋 Purpose

ZPTSVX uses the factorization A = L*D*L**H to compute the solution to a complex system of linear equations A*X = B, where A is an N-by-N Hermitian positive definite tridiagonal matrix and X and B are N-by-NRHS matrices.

Error bounds on the solution and a condition estimate are also provided — yes, it's doing the most, and we love that for it. 💅

🌸 Description

The following steps are performed — yes, all of them, bestie:

  1. If FACT = 'N', the matrix A is factored as A = L*D*L**H, where L is a unit lower bidiagonal matrix and D is diagonal. The factorization can also be regarded as having the form A = U**H*D*U.
  2. If the leading principal minor of order i is not positive, 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.
  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. It specifies whether or not the factored form of the matrix A is supplied on entry.
    • = 'F': On entry, DF and EF contain the factored form of A. D, E, DF, and EF will not be modified.
    • = 'N': The matrix A will be copied to DF and EF and factored.
  • 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 matrices B and X. NRHS >= 0.
  • D — D is DOUBLE PRECISION array, dimension (N). The n diagonal elements of the tridiagonal matrix A.
  • E — E is COMPLEX*16 array, dimension (N-1). The (n-1) subdiagonal elements of the tridiagonal matrix 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 diagonal matrix D from the L*D*L**H factorization of A. If FACT = 'N', then DF is an output argument and on exit contains the n diagonal elements of the diagonal matrix D from the L*D*L**H factorization of A.
  • EF — EF is COMPLEX*16 array, dimension (N-1). If FACT = 'F', then EF is an input argument and on entry contains the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**H factorization of A. If FACT = 'N', then EF is an output argument and on exit contains the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**H factorization of A.
  • B — B is COMPLEX*16 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 COMPLEX*16 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 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 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).
  • 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 is COMPLEX*16 array, dimension (N).
  • RWORK — RWORK is DOUBLE PRECISION array, dimension (N).
  • INFO — INFO is INTEGER.
    • = 0: successful exit
    • < 0: if INFO = -i, the i-th argument had an illegal value
    • > 0: if INFO = i, and i is:
      • <= N: the leading principal minor of order i of A is not positive, so the factorization could not be completed, and the solution has not been 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.

👑 Author

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

Definition at line 232 of file zptsvx.f.

📜 Author

Generated automatically by Doxygen for LAPACK from the source code.

Okay that's the whole page, bestie. 🫶 The footer is serving source/version/date energy: LAPACK, Version 3.12.0, and the ptsvx(3) date stamp — iconic, no notes. 💅✨

📦 where this page comes from