complexPTsolve(3)

📦
version 3.11.0 · 2 versions
, in debian bookworm

✨ complexPTsolve ✨

okay bestie, so this is complexPTsolve, from section 3 of the LAPACK manual (the library-functions girlies 💅). We're deep in the LAPACK docs, so grab a strawberry drink 🍓 and let's go.

💖 NAME 💖

complexPTsolve — complex 🦋

🌸 SYNOPSIS 🌸

✨ Functions ✨

  • cptsv — CPTSV computes the solution to system of linear equations A * X = B for PT matrices
subroutine cptsv (N, NRHS, D, E, B, LDB, INFO)
  • cptsvx — CPTSVX computes the solution to system of linear equations A * X = B for PT matrices
subroutine cptsvx (FACT, N, NRHS, D, E, DF, EF, B, LDB, X, LDX, RCOND,
     FERR, BERR, WORK, RWORK, INFO)

🦋 Detailed Description 🦋

This is literally the whole group of complex solve driver functions for PT matrices. It's giving family reunion, it's giving the PT-matrix clique showing up together 👑

👑 Function Documentation 👑

💜 subroutine cptsv 💜

subroutine cptsv (integer N, integer NRHS, real, dimension( * ) D, complex,
     dimension( * ) E, complex, dimension( ldb, * ) B, integer LDB, integer
     INFO)

CPTSV computes the solution to system of linear equations A * X = B for PT matrices. no cap.

🌟 Purpose 🌟

CPTSV computes 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. so basically it's the tridiagonal Hermitian positive definite serve 💅

A is factored as A = L*D*L**H, and the factored form of A is then used to solve the system of equations. she factors, then she solves. main character energy fr fr ✨

🌸 Parameters 🌸

  • 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.
  • D — D is REAL array, dimension (N). On entry, the n diagonal elements of the tridiagonal matrix A. On exit, the n diagonal elements of the diagonal matrix D from the factorization A = L*D*L**H. she comes in as A's diagonal and leaves as D's diagonal, glow-up moment 🦋
  • E — E is COMPLEX array, dimension (N-1). On entry, the (n-1) subdiagonal elements of the tridiagonal matrix A. On exit, the (n-1) subdiagonal elements of the unit bidiagonal factor L from the L*D*L**H factorization of A. E can also be regarded as the superdiagonal of the unit bidiagonal factor U from the U**H*D*U factorization of A. she's versatile like that, lowkey two jobs at once 😭
  • B — B is COMPLEX array, dimension (LDB,NRHS). On entry, the N-by-NRHS right hand side matrix B. On exit, if INFO = 0, the N-by-NRHS solution matrix X. glow-up: goes in as the problem, comes out as the answer 💖
  • 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, the leading minor of order i is not positive definite, and the solution has not been computed. The factorization has not been completed unless i = N.
bestie listen: if INFO > 0 the solution was NOT computed, and the factorization is incomplete unless i = N. no solution, no vibes, only sadness 🙈

🎀 Author 🎀

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

💜 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. the deluxe version, she does error bounds too 💅

🌟 Purpose 🌟

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. she's not just solving, she's also doing a vibe check on her own accuracy ✨

🌈 Description 🌈

The following steps are performed, in this exact order, periodt:

  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 i-by-i principal minor is not positive definite, 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 literally warns you and keeps going, iconic behavior 💀
  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. step 4 is the glow-up step 🦋

🌸 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. input or output depending on FACT, she's flexible 💅
  • 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. same energy as DF, no cap.
  • 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. yes bestie, even at INFO = N+1 she still hands you 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). she's telling you how far off you might be, respectfully 🫶
  • 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 minor of order i of A is not positive definite, 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 wild: she says "this matrix is basically singular to working precision" and then solves it anyway because sometimes the answer is better than RCOND implies. she contains multitudes 😭

🎀 Author 🎀

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

💜 Author 💜

Generated automatically by Doxygen for LAPACK from the source code. yes, a robot wrote this and she ate 🤖✨

aaaand that's the whole page bestie 🫶 this was Version 3.11.0, dated Sun Nov 27 2022, and that's the complexPTsolve(3) manual page, done and dusted. go solve something tridiagonal, i believe in you 💖🌈⭐

📦 where this page comes from