la_porfsx_extended(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💖 NAME 💖

okay so welcome to the la_porfsx_extended(3) page from the Library Functions Manual, bestie — this is the one about la_porfsx_extended: step in porfsx. That's the whole name section, short and iconic 💅.

✨ SYNOPSIS ✨

🎀 Functions 🎀

  • cla_porfsx_extended — signature:
subroutine cla_porfsx_extended (prec_type, uplo, n, nrhs, a, lda, af,
     ldaf, colequ, c, b, ldb, y, ldy, berr_out, n_norms, err_bnds_norm,
     err_bnds_comp, res, ayb, dy, y_tail, rcond, ithresh, rthresh, dz_ub,
     ignore_cwise, info)

CLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution.

  • dla_porfsx_extended — signature:
subroutine dla_porfsx_extended (prec_type, uplo, n, nrhs, a, lda, af,
     ldaf, colequ, c, b, ldb, y, ldy, berr_out, n_norms, err_bnds_norm,
     err_bnds_comp, res, ayb, dy, y_tail, rcond, ithresh, rthresh, dz_ub,
     ignore_cwise, info)

DLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution.

  • sla_porfsx_extended — signature:
subroutine sla_porfsx_extended (prec_type, uplo, n, nrhs, a, lda, af,
     ldaf, colequ, c, b, ldb, y, ldy, berr_out, n_norms, err_bnds_norm,
     err_bnds_comp, res, ayb, dy, y_tail, rcond, ithresh, rthresh, dz_ub,
     ignore_cwise, info)

SLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution.

  • zla_porfsx_extended — signature:
subroutine zla_porfsx_extended (prec_type, uplo, n, nrhs, a, lda, af,
     ldaf, colequ, c, b, ldb, y, ldy, berr_out, n_norms, err_bnds_norm,
     err_bnds_comp, res, ayb, dy, y_tail, rcond, ithresh, rthresh, dz_ub,
     ignore_cwise, info)

ZLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution.

🌸 Detailed Description 🌸

This section is empty in the source, bestie — no extra lore here, we go straight into the function docs 🫶.

🎀 Function Documentation 🎀

subroutine cla_porfsx_extended

subroutine cla_porfsx_extended (integer prec_type, character uplo, integer
    n, integer nrhs, complex, dimension( lda, * ) a, integer lda, complex,
    dimension( ldaf, * ) af, integer ldaf, logical colequ, real, dimension(
    * ) c, complex, dimension( ldb, * ) b, integer ldb, complex, dimension(
    ldy, * ) y, integer ldy, real, dimension( * ) berr_out, integer n_norms,
    real, dimension( nrhs, * ) err_bnds_norm, real, dimension( nrhs, * )
    err_bnds_comp, complex, dimension( * ) res, real, dimension( * ) ayb,
    complex, dimension( * ) dy, complex, dimension( * ) y_tail, real rcond,
    integer ithresh, real rthresh, real dz_ub, logical ignore_cwise, integer
    info)

CLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution.

🎯 Purpose 🎯

CLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution. This subroutine is called by CPORFSX to perform iterative refinement.

In addition to the normwise error bound, the code provides the maximum componentwise error bound if possible. See the comments for ERR_BNDS_NORM and ERR_BNDS_COMP for details of the error bounds.

Note that this subroutine is only responsible for setting the second fields of ERR_BNDS_NORM and ERR_BNDS_COMP, bestie. That's its whole job 💅.

📋 Parameters 📋

PREC_TYPE

PREC_TYPE is INTEGER.

It specifies the intermediate precision to be used in refinement. The value is defined by ILAPREC(P) where P is a CHARACTER and:

  • P = 'S': Single
  • P = 'D': Double
  • P = 'I': Indigenous
  • P = 'X' or 'E': Extra

UPLO

UPLO is CHARACTER*1.

  • = 'U': Upper triangle of A is stored;
  • = 'L': Lower triangle of A is stored.

N

N is INTEGER.

The number of linear equations, i.e., 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.

A

A is COMPLEX array, dimension (LDA,N).

On entry, the N-by-N matrix A.

LDA

LDA is INTEGER.

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

AF

AF is COMPLEX array, dimension (LDAF,N).

The triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T, as computed by CPOTRF.

LDAF

LDAF is INTEGER.

The leading dimension of the array AF. LDAF >= max(1,N).

COLEQU

COLEQU is LOGICAL.

If .TRUE. then column equilibration was done to A before calling this routine. This is needed to compute the solution and error bounds correctly.

C

C is REAL array, dimension (N).

The column scale factors for A. If COLEQU = .FALSE., C is not accessed. If C is input, each element of C should be a power of the radix to ensure a reliable solution and error estimates.

Scaling by powers of the radix does not cause rounding errors unless the result underflows or overflows. Rounding errors during scaling lead to refining with a matrix that is not equivalent to the input matrix, producing error estimates that may not be reliable.

fr fr, keep C as powers of the radix if you want the error estimates to be trustworthy 💀.

B

B is COMPLEX array, dimension (LDB,NRHS).

The right-hand-side matrix B.

LDB

LDB is INTEGER.

The leading dimension of the array B. LDB >= max(1,N).

Y

Y is COMPLEX array, dimension (LDY,NRHS).

On entry, the solution matrix X, as computed by CPOTRS. On exit, the improved solution matrix Y.

LDY

LDY is INTEGER.

The leading dimension of the array Y. LDY >= max(1,N).

BERR_OUT

BERR_OUT is REAL array, dimension (NRHS).

On exit, BERR_OUT(j) contains the componentwise relative backward error for right-hand-side j from the formula:

max(i) ( abs(RES(i)) / ( abs(op(A_s))*abs(Y) + abs(B_s) )(i) )

where abs(Z) is the componentwise absolute value of the matrix or vector Z. This is computed by CLA_LIN_BERR.

N_NORMS

N_NORMS is INTEGER.

It determines which error bounds to return (see ERR_BNDS_NORM and ERR_BNDS_COMP).

  • If N_NORMS >= 1 return normwise error bounds.
  • If N_NORMS >= 2 return componentwise error bounds.

ERR_BNDS_NORM

ERR_BNDS_NORM is REAL array, dimension (NRHS, N_ERR_BNDS).

For each right-hand side, this array contains information about various error bounds and condition numbers corresponding to the normwise relative error, which is defined as follows:

Normwise relative error in the ith solution vector:

max_j (abs(XTRUE(j,i) - X(j,i)))
------------------------------
     max_j abs(X(j,i))

The array is indexed by the type of error information as described below. There currently are up to three pieces of information returned.

The first index in ERR_BNDS_NORM(i,:) corresponds to the ith right-hand side.

The second index in ERR_BNDS_NORM(:,err) contains the following three fields:

  • err = 1 boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon').
  • err = 2 error bound: The estimated forward error, almost certainly within a factor of 10 of the true error so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon'). This error bound should only be trusted if the previous boolean is true.
  • err = 3 Reciprocal condition number: Estimated normwise reciprocal condition number. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is . These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z. Let Z = S*A, where S scales each row by a power of the radix so all absolute row sums of Z are approximately 1.

This subroutine is only responsible for setting the second field above.

See Lapack Working Note 165 for further details and extra cautions.

yes, the source really just says “is .” there — not me, bestie 😭. I'm preserving the tea exactly.

ERR_BNDS_COMP

ERR_BNDS_COMP

Ok so ERR_BNDS_COMP is a REAL array, dimension (NRHS, N_ERR_BNDS). For each right-hand side it's holding all the tea about error bounds and condition numbers for the componentwise relative error, which is defined like this, bestie:

Componentwise relative error in the ith solution vector:
             abs(XTRUE(j,i) - X(j,i))
      max_j ----------------------
                  abs(X(j,i))

The array is indexed by the right-hand side i (because that's literally what the componentwise relative error depends on), and then by the type of error info, which we're getting to. There are currently up to three pieces of information returned for each right-hand side. And like — important — if componentwise accuracy isn't requested (PARAMS(3) = 0.0), then ERR_BNDS_COMP is not accessed at all, we simply do not touch her. And if N_ERR_BNDS < 3, then at most the first (:,N_ERR_BNDS) entries are returned. That's it, that's the deal.

The first index in ERR_BNDS_COMP(i,:) corresponds to the ith right-hand side.

The second index in ERR_BNDS_COMP(:,err) contains these three fields:

  • err = 1 — boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon').
  • err = 2 — error bound: the estimated forward error, almost certainly within a factor of 10 of the true error, so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon'). 🔥 This error bound should only be trusted if the previous boolean is true. Like, if the boolean said no, this number is just vibes, don't cite it.
  • err = 3 — Reciprocal condition number: the estimated componentwise reciprocal condition number. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is . These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z. Let Z = S*(A*diag(x)), where x is the solution for the current right-hand side and S scales each row of A*diag(x) by a power of the radix so all absolute row sums of Z are approximately 1.

(and yes, the sentence really does just stop at "is ." in the source — we don't gatekeep, we report 💀)

This subroutine is only responsible for setting the second field above. See Lapack Working Note 165 for further details and extra cautions. 👑

RES

RES is a COMPLEX array, dimension (N). Workspace to hold the intermediate residual. That's her job, that's what she does. 🫶

AYB

AYB is a REAL array, dimension (N). Workspace. That's the whole description. Iconic minimalism, honestly. ✨

DY

DY is a COMPLEX array, dimension (N). Workspace to hold the intermediate solution. 🌸

Y_TAIL

Y_TAIL is a COMPLEX array, dimension (N). Workspace to hold the trailing bits of the intermediate solution — the little extra crumbs of precision, the garnish, the last few bits of the vibe. 🎀

RCOND

RCOND is REAL. Reciprocal scaled condition number. It's an estimate of the reciprocal Skeel condition number of the matrix A after equilibration (if that was done). So — if this is less than the machine precision (in particular, if it's zero), the matrix is singular to working precision, no cap. But note 📌: the error may still be small even if this number is very small and the matrix appears ill-conditioned. It's giving "looks scary, might still slay."

ITHRESH

ITHRESH is INTEGER. The maximum number of residual computations allowed for refinement. Default is 10. For 'aggressive' set it to 100 to permit convergence using approximate factorizations or factorizations other than LU. ⚠️ But if the factorization uses a technique other than Gaussian elimination, the guarantees in ERR_BNDS_NORM and ERR_BNDS_COMP may no longer be trustworthy. So go off, but know the risk.

RTHRESH

RTHRESH is REAL. It decides when to stop refinement if the error estimate stops decreasing. Refinement will stop when the next solution no longer satisfies norm(dx_{i+1}) < RTHRESH * norm(dx_i) where norm(Z) is the infinity norm of Z. RTHRESH satisfies 0 < RTHRESH <= 1. Default value is 0.5. For 'aggressive' set it to 0.9 to permit convergence on extremely ill-conditioned matrices. See LAWN 165 for more details. 💅

DZ_UB

DZ_UB is REAL. It determines when to start considering componentwise convergence. Componentwise convergence is only considered after each component of the solution Y is stable, and we define stable as the relative change in each component being less than DZ_UB. Default value is 0.25, which requires the first bit to be stable. See LAWN 165 for more details. ⭐

IGNORE_CWISE

IGNORE_CWISE is LOGICAL. If .TRUE. then ignore componentwise convergence. Default value is .FALSE.. Simple as that, bestie. 🙈

INFO

INFO is INTEGER.

  • = 0: Successful exit. 🎉
  • < 0: if INFO = -i, the ith argument to CPOTRS had an illegal value.

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Definition at line 380 of file cla_porfsx_extended.f.

🦋 Second verse, same energy: dla_porfsx_extended

subroutine dla_porfsx_extended (integer prec_type, character uplo, integer
    n, integer nrhs, double precision, dimension( lda, * ) a, integer lda,
    double precision, dimension( ldaf, * ) af, integer ldaf, logical colequ,
    double precision, dimension( * ) c, double precision, dimension( ldb, *
    ) b, integer ldb, double precision, dimension( ldy, * ) y, integer ldy,
    double precision, dimension( * ) berr_out, integer n_norms, double
    precision, dimension( nrhs, * ) err_bnds_norm, double precision,
    dimension( nrhs, * ) err_bnds_comp, double precision, dimension( * )
    res, double precision, dimension(*) ayb, double precision, dimension( *
    ) dy, double precision, dimension( * ) y_tail, double precision rcond,
    integer ithresh, double precision rthresh, double precision dz_ub,
    logical ignore_cwise, integer info)

DLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement, and it provides error bounds and backward error estimates for the solution. Same routine, double precision era. 💜

✨ Purpose

DLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution. This subroutine is called by DPORFSX to perform iterative refinement. In addition to the normwise error bound, the code provides a maximum componentwise error bound if possible. See the comments for ERR_BNDS_NORM and ERR_BNDS_COMP for the details of the error bounds. Note that this subroutine is only responsible for setting the second fields of ERR_BNDS_NORM and ERR_BNDS_COMP. That's the whole assignment, we're not doing extra credit. 🫡

🌈 Parameters

PREC_TYPE

PREC_TYPE is INTEGER. It specifies the intermediate precision to be used in refinement. The value is defined by ILAPREC(P) where P is a CHARACTER and:

  • P = 'S': Single
  • P = 'D': Double
  • P = 'I': Indigenous
  • P = 'X' or 'E': Extra

UPLO

UPLO is CHARACTER*1.

  • = 'U': Upper triangle of A is stored;
  • = 'L': Lower triangle of A is stored.

N

N is INTEGER. The number of linear equations, i.e., 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. Multiple besties, one call.

A

A is DOUBLE PRECISION array, dimension (LDA,N). On entry, the N-by-N matrix A. Main character energy. 👑

LDA

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

AF

AF is DOUBLE PRECISION array, dimension (LDAF,N). The triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T, as computed by DPOTRF. She's already been factored, she's ready.

LDAF

LDAF is INTEGER. The leading dimension of the array AF. LDAF >= max(1,N).

COLEQU

COLEQU is LOGICAL. If .TRUE. then column equilibration was done to A before calling this routine. This is needed to compute the solution and error bounds correctly. So don't lie about it, the math will notice. 😭

C

C is DOUBLE PRECISION array, dimension (N). The column scale factors for A. If COLEQU = .FALSE., C is not accessed. If C is input, each element of C should be a power of the radix to ensure a reliable solution and error estimates. Scaling by powers of the radix does not cause rounding errors unless the result underflows or overflows. ⚠️ Rounding errors during scaling lead to refining with a matrix that is not equivalent to the input matrix, producing error estimates that may not be reliable. So like, keep it to powers of the radix, fr fr.

B

B is DOUBLE PRECISION array, dimension (LDB,NRHS). The right-hand-side matrix B. The whole reason we're here. 🫶

LDB

LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).

Y

Y is DOUBLE PRECISION array, dimension (LDY,NRHS). On entry, the solution matrix X, as computed by DPOTRS. On exit, the improved solution matrix Y. Glow-up arc complete. ✨

LDY

LDY is INTEGER. The leading dimension of the array Y. LDY >= max(1,N).

BERR_OUT

…and that's exactly where this part cuts off bestie, next one's got the rest of the plot 🫶

BERR_OUT

BERR_OUT is a DOUBLE PRECISION array, dimension (NRHS). On exit, BERR_OUT(j) holds the componentwise relative backward error for right-hand-side j from this formula:

max(i) ( abs(RES(i)) / ( abs(op(A_s))*abs(Y) + abs(B_s) )(i) )

where abs(Z) is the componentwise absolute value of the matrix or vector Z. This is computed by DLA_LIN_BERR. 💅

N_NORMS

N_NORMS is INTEGER. It decides which error bounds come back — see ERR_BNDS_NORM and ERR_BNDS_COMP.

  • If N_NORMS >= 1, return normwise error bounds.
  • If N_NORMS >= 2, return componentwise error bounds.

ERR_BNDS_NORM

ERR_BNDS_NORM is a DOUBLE PRECISION array, dimension (NRHS, N_ERR_BNDS). For each right-hand side, this array carries info about various error bounds and condition numbers for the normwise relative error, defined like this:

        max_j (abs(XTRUE(j,i) - X(j,i)))
       ------------------------------
             max_j abs(X(j,i))

The array is indexed by the type of error information described below. There currently are up to three pieces of information returned.

The first index in ERR_BNDS_NORM(i,:) corresponds to the ith right-hand side.

The second index in ERR_BNDS_NORM(:,err) contains the following three fields:

  • err = 1 — boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon').
  • err = 2 — error bound: the estimated forward error, almost certainly within a factor of 10 of the true error so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon'). This error bound should only be trusted if the previous boolean is true.
  • err = 3 — reciprocal condition number: estimated normwise reciprocal condition number. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is . These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z. Let Z = S*A, where S scales each row by a power of the radix so all absolute row sums of Z are approximately 1.

This subroutine is only responsible for setting the second field above. See Lapack Working Note 165 for further details and extra cautions. 🦋

ERR_BNDS_COMP

ERR_BNDS_COMP is a DOUBLE PRECISION array, dimension (NRHS, N_ERR_BNDS). For each right-hand side, this array carries info about various error bounds and condition numbers for the componentwise relative error, defined like this:

               abs(XTRUE(j,i) - X(j,i))
        max_j ----------------------
                    abs(X(j,i))

The array is indexed by the right-hand side i (on which the componentwise relative error depends), and the type of error information described below. There currently are up to three pieces of information returned for each right-hand side. If componentwise accuracy is not requested (PARAMS(3) = 0.0), then ERR_BNDS_COMP is not accessed. If N_ERR_BNDS < 3, then at most the first (:,N_ERR_BNDS) entries are returned.

The first index in ERR_BNDS_COMP(i,:) corresponds to the ith right-hand side.

The second index in ERR_BNDS_COMP(:,err) contains the following three fields:

  • err = 1 — boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon').
  • err = 2 — error bound: the estimated forward error, almost certainly within a factor of 10 of the true error so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon'). This error bound should only be trusted if the previous boolean is true.
  • err = 3 — reciprocal condition number: estimated componentwise reciprocal condition number. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is . These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z. Let Z = S*(A*diag(x)), where x is the solution for the current right-hand side and S scales each row of A*diag(x) by a power of the radix so all absolute row sums of Z are approximately 1.

This subroutine is only responsible for setting the second field above. See Lapack Working Note 165 for further details and extra cautions. ✨

RES

RES is a DOUBLE PRECISION array, dimension (N). It’s workspace for holding the intermediate residual. 🎀

AYB

AYB is a DOUBLE PRECISION array, dimension (N). Workspace. This can be the same workspace passed for Y_TAIL. 💖

DY

DY is a DOUBLE PRECISION array, dimension (N). Workspace for holding the intermediate solution. 🌸

Y_TAIL

Y_TAIL is a DOUBLE PRECISION array, dimension (N). Workspace for holding the trailing bits of the intermediate solution. 🫶

RCOND

RCOND is DOUBLE PRECISION. Reciprocal scaled condition number. This is an estimate of the reciprocal Skeel condition number of the matrix A after equilibration (if done). If this is less than the machine precision (in particular, if it is zero), the matrix is singular to working precision. Note that the error may still be small even if this number is very small and the matrix appears ill-conditioned. 😭

ITHRESH

ITHRESH is INTEGER. The maximum number of residual computations allowed for refinement. The default is 10. For 'aggressive' set to 100 to permit convergence using approximate factorizations or factorizations other than LU. If the factorization uses a technique other than Gaussian elimination, the guarantees in ERR_BNDS_NORM and ERR_BNDS_COMP may no longer be trustworthy. 🔥

RTHRESH

RTHRESH is DOUBLE PRECISION. Determines when to stop refinement if the error estimate stops decreasing. Refinement will stop when the next solution no longer satisfies norm(dx_{i+1}) < RTHRESH * norm(dx_i) where norm(Z) is the infinity norm of Z. RTHRESH satisfies 0 < RTHRESH <= 1. The default value is 0.5. For 'aggressive' set to 0.9 to permit convergence on extremely ill-conditioned matrices. See LAWN 165 for more details. 👑

DZ_UB

DZ_UB is DOUBLE PRECISION. Determines when to start considering componentwise convergence. Componentwise convergence is only considered after each component of the solution Y is stable, which we define as the relative change in each component being less than DZ_UB. The default value is 0.25, requiring the first bit to be stable. See LAWN 165 for more details. 🌈

IGNORE_CWISE

IGNORE_CWISE is LOGICAL. If .TRUE. then ignore componentwise convergence. Default value is .FALSE.. ⭐

INFO

INFO is INTEGER.

  • = 0: successful exit.
  • < 0: if INFO = -i, the ith argument to DPOTRS had an illegal value.

✨ Author ✨

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Definition at line 380 of file dla_porfsx_extended.f.

🌸 sla_porfsx_extended 🌸

   subroutine sla_porfsx_extended (integer prec_type, character uplo, integer
       n, integer nrhs, real, dimension( lda, * ) a, integer lda, real,
       dimension( ldaf, * ) af, integer ldaf, logical colequ, real, dimension(
       * ) c, real, dimension( ldb, * ) b, integer ldb, real, dimension( ldy, *
       ) y, integer ldy, real, dimension( * ) berr_out, integer n_norms, real,
       dimension( nrhs, * ) err_bnds_norm, real, dimension( nrhs, * )
       err_bnds_comp, real, dimension( * ) res, real, dimension(*) ayb, real,
       dimension( * ) dy, real, dimension( * ) y_tail, real rcond, integer
       ithresh, real rthresh, real dz_ub, logical ignore_cwise, integer info)

SLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution. 💅

✨ Purpose ✨

SLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution. This subroutine is called by SPORFSX to perform iterative refinement. In addition to normwise error bound, the code provides maximum componentwise error bound if possible. See comments for ERR_BNDS_NORM and ERR_BNDS_COMP for details of the error bounds. Note that this subroutine is only responsible for setting the second fields of ERR_BNDS_NORM and ERR_BNDS_COMP. 🧚

✨ Parameters ✨

PREC_TYPE

  • PREC_TYPE — INTEGER, bestie. Tells us which intermediate precision the refinement is gonna use. The value comes from ILAPREC(P) where P is a CHARACTER:
    • = 'S' → Single
    • = 'D' → Double
    • = 'I' → Indigenous
    • = 'X' or 'E' → Extra

iykyk 🎀

  • UPLO — CHARACTER*1, literally just "which triangle of A are we even talking about":
    • = 'U' → the Upper triangle of A is stored
    • = 'L' → the Lower triangle of A is stored
  • N — INTEGER, the number of linear equations, aka the order of the matrix A. Gotta be N >= 0. ✨
  • NRHS — INTEGER, the number of right-hand-sides, which is just the number of columns of the matrix B. Slay, multiple RHS at once 💅
  • A — REAL array, dimension (LDA,N). On entry: the N-by-N matrix A. That's her, she's the main character 👑
  • LDA — INTEGER, the leading dimension of the array A. So LDA >= max(1,N). No cap. 🦋
  • AF — REAL array, dimension (LDAF,N). This is the triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T, exactly as computed by SPOTRF. Like she already did the work, respect it 💖
  • LDAF — INTEGER, the leading dimension of the array AF. LDAF >= max(1,N). fr fr 📏
  • COLEQU — LOGICAL. If .TRUE. then column equilibration was already done to A before this routine got called. This one matters, genuinely — it's needed to compute the solution and the error bounds correctly. Don't lie to her about equilibration 🙈
  • C — REAL array, dimension (N). The column scale factors for A. Listen: if COLEQU = .FALSE., then C is not accessed, so don't stress. But if C is input, each element of C should be a power of the radix, so you get a reliable solution and reliable error estimates. Scaling by powers of the radix doesn't cause rounding errors unless the result underflows or overflows. And rounding errors during scaling? That leads to refining with a matrix that is not equivalent to the input matrix, which produces error estimates that may not be reliable. So cute, so sad, so real 😭
  • B — REAL array, dimension (LDB,NRHS). The right-hand-side matrix B. Her name is B and she's here to be solved 🌸
  • LDB — INTEGER, the leading dimension of the array B. LDB >= max(1,N). periodt 💫
  • Y — REAL array, dimension (LDY,NRHS). On entry: the solution matrix X, as computed by SPOTRS. On exit: the improved solution matrix Y. Glow-up arc confirmed, we love to see it 🔥
  • LDY — INTEGER, the leading dimension of the array Y. LDY >= max(1,N). 🎀
  • BERR_OUT — REAL array, dimension (NRHS). On exit, BERR_OUT(j) holds the componentwise relative backward error for right-hand-side j, straight from this formula:
    max(i) ( abs(RES(i)) / ( abs(op(A_s))*abs(Y) + abs(B_s) )(i) )

where abs(Z) is the componentwise absolute value of the matrix or vector Z. This lil number is computed by SLA_LIN_BERR. 🧚

  • N_NORMS — INTEGER, decides which error bounds come back to you (see ERR_BNDS_NORM and ERR_BNDS_COMP):
    • If N_NORMS >= 1 → return normwise error bounds.
    • If N_NORMS >= 2 → return componentwise error bounds.

Choose your fighter 💅

  • ERR_BNDS_NORM — REAL array, dimension (NRHS, N_ERR_BNDS). For every right-hand side, this array carries info about various error bounds and condition numbers tied to the normwise relative error, defined like so. Normwise relative error in the ith solution vector:
        max_j (abs(XTRUE(j,i) - X(j,i)))
       ------------------------------
             max_j abs(X(j,i))

The array is indexed by the type of error information, as described below. Right now there are up to three pieces of information returned. ⭐

The first index in ERR_BNDS_NORM(i,:) corresponds to the ith right-hand side.

The second index in ERR_BNDS_NORM(:,err) contains these three fields:

  • err = 1 → boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon').
  • err = 2 → error bound: the estimated forward error, almost certainly within a factor of 10 of the true error, so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon'). This error bound should only be trusted if the previous boolean is true. 👀
  • err = 3 → Reciprocal condition number: estimated normwise reciprocal condition number. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is. These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z. Let Z = S*A, where S scales each row by a power of the radix so all absolute row sums of Z are approximately 1.

Heads up: this subroutine is only responsible for setting the second field above. See Lapack Working Note 165 for further details and extra cautions. 🫶

  • ERR_BNDS_COMP — REAL array, dimension (NRHS, N_ERR_BNDS). For every right-hand side, this one holds info about various error bounds and condition numbers for the componentwise relative error, defined as follows. Componentwise relative error in the ith solution vector:
               abs(XTRUE(j,i) - X(j,i))
        max_j ----------------------
                    abs(X(j,i))

Indexed by the right-hand side i (componentwise relative error depends on it, bestie) and by the type of error information described below. Currently up to three pieces of information get returned per right-hand side. Big important one: if componentwise accuracy is not requested (PARAMS(3) = 0.0), then ERR_BNDS_COMP is not accessed. And if N_ERR_BNDS < 3, then at most the first (:,N_ERR_BNDS) entries are returned. 🙈

The first index in ERR_BNDS_COMP(i,:) corresponds to the ith right-hand side.

The second index in ERR_BNDS_COMP(:,err) contains these three fields:

  • err = 1 → boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon').
  • err = 2 → error bound: the estimated forward error, almost certainly within a factor of 10 of the true error, so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon'). This error bound should only be trusted if the previous boolean is true.
  • err = 3 → Reciprocal condition number: estimated componentwise reciprocal condition number. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is. These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z. Let Z = S*(A*diag(x)), where x is the solution for the current right-hand side and S scales each row of A*diag(x) by a power of the radix so all absolute row sums of Z are approximately 1.

Same deal again: this subroutine is only responsible for setting the second field above. See Lapack Working Note 165 for further details and extra cautions. 💜

🌈 the little scratchpads (workspace arguments)

  • RES — REAL array, dimension (N). Workspace to hold the intermediate residual. Temporary queen, doing her job then leaving 💫
  • AYB — REAL array, dimension (N). Workspace. Fun fact: this can be the same workspace you passed for Y_TAIL. Sharing is caring 🫶
  • DY — REAL array, dimension (N). Workspace to hold the intermediate solution. 🎀
  • Y_TAIL — REAL array, dimension (N). Workspace to hold the trailing bits of the intermediate solution. The trailing bits, like a little sparkle trail ✨

🦋 the knobs & dials

  • RCOND — REAL. Reciprocal scaled condition number. It's an estimate of the reciprocal Skeel condition number of the matrix A after equilibration (if that got done). And listen: if this is less than the machine precision — in particular, if it is zero — then the matrix is singular to working precision. ⚠️ That said, the error may still be small even if this number is very small and the matrix appears ill-conditioned. So don't spiral. 😭
  • ITHRESH — INTEGER. The max number of residual computations allowed for refinement. Default is 10. For 'aggressive' set it to 100, which permits convergence using approximate factorizations or factorizations other than LU. Big caveat though: if the factorization uses a technique other than Gaussian elimination, then the guarantees in ERR_BNDS_NORM and ERR_BNDS_COMP may no longer be trustworthy. 💀
  • RTHRESH — REAL. Determines when to stop refining if the error estimate stops decreasing. Refinement stops when the next solution no longer satisfies norm(dx_{i+1}) < RTHRESH * norm(dx_i) where norm(Z) is the infinity norm of Z. RTHRESH satisfies 0 < RTHRESH <= 1. Default value is 0.5. For 'aggressive' set it to 0.9 to permit convergence on extremely ill-conditioned matrices. See LAWN 165 for more details. 🔥
  • DZ_UB — (the next one, hold that thought — her description rolls on in the next part 👑)

DZ_UB is REAL, and it decides when we even start caring about componentwise convergence. Componentwise convergence only gets considered after every component of the solution Y is stable — and “stable” here means the relative change in each component is less than DZ_UB. The default is 0.25, which means the first bit has to be stable. See LAWN 165 for the full tea. 🫖

IGNORE_CWISE 🙈

IGNORE_CWISE is LOGICAL. If it’s .TRUE., then componentwise convergence gets ignored entirely. Default is .FALSE. — so no, bestie, by default we do not ignore it.

INFO 💀

INFO is INTEGER:

  • = 0: successful exit. slay.
  • < 0: if INFO = -i, then the *i*th argument to SPOTRS had an illegal value.
Note: the original really says SPOTRS here — keep that exact name, okay? Don’t come for me. 💅

Author 🖋️

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

Definition at line 380 of file sla_porfsx_extended.f.

subroutine zla_porfsx_extended 🌀

   subroutine zla_porfsx_extended (integer prec_type, character uplo, integer
       n, integer nrhs, complex*16, dimension( lda, * ) a, integer lda,
       complex*16, dimension( ldaf, * ) af, integer ldaf, logical colequ,
       double precision, dimension( * ) c, complex*16, dimension( ldb, * ) b,
       integer ldb, complex*16, dimension( ldy, * ) y, integer ldy, double
       precision, dimension( * ) berr_out, integer n_norms, double precision,
       dimension( nrhs, * ) err_bnds_norm, double precision, dimension( nrhs, *
       ) err_bnds_comp, complex*16, dimension( * ) res, double precision,
       dimension( * ) ayb, complex*16, dimension( * ) dy, complex*16,
       dimension( * ) y_tail, double precision rcond, integer ithresh, double
       precision rthresh, double precision dz_ub, logical ignore_cwise, integer
       info)

ZLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations for symmetric or Hermitian positive-definite matrices by doing extra-precise iterative refinement, and it provides error bounds and backward error estimates for the solution. It’s giving precision AND receipts. 💅

Purpose ✨

ZLA_PORFSX_EXTENDED improves the computed solution to a system of linear equations by performing extra-precise iterative refinement and provides error bounds and backward error estimates for the solution. This subroutine is called by ZPORFSX to do the iterative refinement. On top of the normwise error bound, the code provides the maximum componentwise error bound if possible. See the comments for ERR_BNDS_NORM and ERR_BNDS_COMP for the details of those error bounds. Important: this subroutine is only responsible for setting the second fields of ERR_BNDS_NORM and ERR_BNDS_COMP. That’s the whole assignment, no cap.

Parameters 🧾

PREC_TYPE ⚙️

PREC_TYPE is INTEGER. It specifies the intermediate precision to use in refinement. The value is defined by ILAPREC(P), where P is a CHARACTER, and:

  • P = 'S': Single
  • P = 'D': Double
  • P = 'I': Indigenous
  • P = 'X' or 'E': Extra

UPLO 🥂

UPLO is CHARACTER*1.

  • = 'U': Upper triangle of A is stored.
  • = 'L': Lower triangle of A is stored.

N 🔢

N is INTEGER. It’s the number of linear equations, i.e. the order of the matrix A. N >= 0.

NRHS 🧮

NRHS is INTEGER. It’s the number of right-hand sides, i.e. the number of columns of the matrix B.

A 🧊

A is COMPLEX*16 array, dimension (LDA,N). On entry, it’s the N-by-N matrix A.

LDA 📏

LDA is INTEGER. It’s the leading dimension of the array A. LDA >= max(1,N).

AF 🪞

AF is COMPLEX*16 array, dimension (LDAF,N). It’s the triangular factor U or L from the Cholesky factorization A = U**T*U or A = L*L**T, as computed by ZPOTRF.

LDAF 📐

LDAF is INTEGER. It’s the leading dimension of the array AF. LDAF >= max(1,N).

COLEQU ⚖️

COLEQU is LOGICAL. If .TRUE., then column equilibration was done to A before calling this routine. This is needed to compute the solution and error bounds correctly. So yeah, it actually matters.

C 🎚️

C is DOUBLE PRECISION array, dimension (N). These are the column scale factors for A. If COLEQU = .FALSE., C is not accessed. If C is input, each element of C should be a power of the radix to ensure a reliable solution and error estimates. Scaling by powers of the radix does not cause rounding errors unless the result underflows or overflows. Rounding errors during scaling lead to refining with a matrix that is not equivalent to the input matrix, producing error estimates that may not be reliable. TL;DR: powers of the radix are the safe move; messy scaling can ruin the vibe. 💀

B 🎁

B is COMPLEX*16 array, dimension (LDB,NRHS). It’s the right-hand-side matrix B.

LDB 📏

LDB is INTEGER. It’s the leading dimension of the array B. LDB >= max(1,N).

Y 🌟

Y is COMPLEX*16 array, dimension (LDY,NRHS). On entry, it’s the solution matrix X, as computed by ZPOTRS. On exit, it’s the improved solution matrix Y. Glow-up moment.

LDY 📐

LDY is INTEGER. It’s the leading dimension of the array Y. LDY >= max(1,N).

BERR_OUT 🚨

BERR_OUT is DOUBLE PRECISION array, dimension (NRHS). On exit, BERR_OUT(j) contains the componentwise relative backward error for right-hand-side j from the formula:

max(i) ( abs(RES(i)) / ( abs(op(A_s))*abs(Y) + abs(B_s) )(i) )

where abs(Z) is the componentwise absolute value of the matrix or vector Z. This is computed by ZLA_LIN_BERR. It’s the receipts for your residual. 🧾

N_NORMS 🎛️

N_NORMS is INTEGER. It determines which error bounds to return — see ERR_BNDS_NORM and ERR_BNDS_COMP.

  • If N_NORMS >= 1, return normwise error bounds.
  • If N_NORMS >= 2, return componentwise error bounds.

ERR_BNDS_NORM 🌈

ERR_BNDS_NORM is DOUBLE PRECISION array, dimension (NRHS, N_ERR_BNDS). For each right-hand side, this array contains info about various error bounds and condition numbers corresponding to the normwise relative error, which is defined like this:

Normwise relative error in the *i*th solution vector:

        max_j (abs(XTRUE(j,i) - X(j,i)))
       ------------------------------
             max_j abs(X(j,i))

The array is indexed by the type of error information as described below. There currently are up to three pieces of information returned.

The first index in ERR_BNDS_NORM(i,:) corresponds to the *i*th right-hand side.

The second index in ERR_BNDS_NORM(:,err) contains the following three fields:

  • err = 1: boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon').
  • err = 2: error bound. The estimated forward error, almost certainly within a factor of 10 of the true error so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon'). This error bound should only be trusted if the previous boolean is true.
  • err = 3: Reciprocal condition number. Estimated normwise reciprocal condition number. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is . These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z. Let Z = S*A, where S scales each row by a power of the radix so all absolute row sums of Z are approximately 1.

This subroutine is only responsible for setting the second field above. See Lapack Working Note 165 for further details and extra cautions. 👑

ERR_BNDS_COMP

okay bestie, picking right back up in the argument tea — last stretch, no skips 💅

ERR_BNDS_COMP — is a DOUBLE PRECISION array, dimension (NRHS, N_ERR_BNDS). For each right-hand side, this array contains information about various error bounds and condition numbers corresponding to the componentwise relative error, which is defined as follows:

                   abs(XTRUE(j,i) - X(j,i))
            max_j ----------------------
                        abs(X(j,i))

The array is indexed by the right-hand side i (on which the componentwise relative error depends), and the type of error information as described below. There currently are up to three pieces of information returned for each right-hand side. If componentwise accuracy is not requested (PARAMS(3) = 0.0), then ERR_BNDS_COMP is not accessed. If N_ERR_BNDS < 3, then at most the first (:,N_ERR_BNDS) entries are returned.

The first index in ERR_BNDS_COMP(i,:) corresponds to the ith right-hand side.

The second index in ERR_BNDS_COMP(:,err) contains the following three fields:

  • err = 1 — boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon').
  • err = 2 — error bound: the estimated forward error, almost certainly within a factor of 10 of the true error so long as the next entry is greater than the threshold sqrt(n) * slamch('Epsilon'). This error bound should only be trusted if the previous boolean is true.
  • err = 3 — reciprocal condition number: estimated componentwise reciprocal condition number. Compared with the threshold sqrt(n) * slamch('Epsilon') to determine if the error estimate is . These reciprocal condition numbers are 1 / (norm(Z^{-1},inf) * norm(Z,inf)) for some appropriately scaled matrix Z. Let Z = S*(A*diag(x)), where x is the solution for the current right-hand side and S scales each row of A*diag(x) by a power of the radix so all absolute row sums of Z are approximately 1.

This subroutine is only responsible for setting the second field above. See Lapack Working Note 165 for further details and extra cautions.

  • RES — is a COMPLEX*16 array, dimension (N). Workspace to hold the intermediate residual.
  • AYB — is a DOUBLE PRECISION array, dimension (N). Workspace.
  • DY — is a COMPLEX*16 PRECISION array, dimension (N). Workspace to hold the intermediate solution.
  • Y_TAIL — is a COMPLEX*16 array, dimension (N). Workspace to hold the trailing bits of the intermediate solution.
  • RCOND — is DOUBLE PRECISION. Reciprocal scaled condition number. This is an estimate of the reciprocal Skeel condition number of the matrix A after equilibration (if done). If this is less than the machine precision (in particular, if it is zero), the matrix is singular to working precision. Note that the error may still be small even if this number is very small and the matrix appears ill-conditioned.
  • ITHRESH — is INTEGER. The maximum number of residual computations allowed for refinement. The default is 10. For 'aggressive' set to 100 to permit convergence using approximate factorizations or factorizations other than LU. If the factorization uses a technique other than Gaussian elimination, the guarantees in ERR_BNDS_NORM and ERR_BNDS_COMP may no longer be trustworthy.
  • RTHRESH — is DOUBLE PRECISION. Determines when to stop refinement if the error estimate stops decreasing. Refinement will stop when the next solution no longer satisfies norm(dx_{i+1}) < RTHRESH * norm(dx_i) where norm(Z) is the infinity norm of Z. RTHRESH satisfies 0 < RTHRESH <= 1. The default value is 0.5. For 'aggressive' set to 0.9 to permit convergence on extremely ill-conditioned matrices. See LAWN 165 for more details.
  • DZ_UB — is DOUBLE PRECISION. Determines when to start considering componentwise convergence. Componentwise convergence is only considered after each component of the solution Y is stable, which we define as the relative change in each component being less than DZ_UB. The default value is 0.25, requiring the first bit to be stable. See LAWN 165 for more details.
  • IGNORE_CWISE — is LOGICAL. If .TRUE. then ignore componentwise convergence. Default value is .FALSE..
  • INFO — is INTEGER.
    • = 0: Successful exit.
    • < 0: if INFO = -i, the ith argument to ZPOTRS had an illegal value

✨ Author ✨

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

Definition at line 380 of file zla_porfsx_extended.f.

✨ Author ✨

Generated automatically by Doxygen for LAPACK from the source code.

and that's a wrap, bestie 🎀 source/version: LAPACK Version 3.12.0; page: la_porfsx_extended(3); date: not listed in this footer, so no invented date from me 💅 slay ✨💖

📦 where this page comes from