LAPACK  3.10.0 LAPACK: Linear Algebra PACKage

## ◆ cla_gerfsx_extended()

 subroutine cla_gerfsx_extended ( integer PREC_TYPE, integer TRANS_TYPE, integer N, integer NRHS, complex, dimension( lda, * ) A, integer LDA, complex, dimension( ldaf, * ) AF, integer LDAF, integer, dimension( * ) IPIV, 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, * ) ERRS_N, real, dimension( nrhs, * ) ERRS_C, 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_GERFSX_EXTENDED

Purpose:
``` CLA_GERFSX_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 CGERFSX to perform iterative refinement.
In addition to normwise error bound, the code provides maximum
componentwise error bound if possible. See comments for ERRS_N
and ERRS_C for details of the error bounds. Note that this
subroutine is only resonsible for setting the second fields of
ERRS_N and ERRS_C.```
Parameters
 [in] PREC_TYPE ``` PREC_TYPE is INTEGER 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 = 'D': Double = 'I': Indigenous = 'X' or 'E': Extra``` [in] TRANS_TYPE ``` TRANS_TYPE is INTEGER Specifies the transposition operation on A. The value is defined by ILATRANS(T) where T is a CHARACTER and T = 'N': No transpose = 'T': Transpose = 'C': Conjugate transpose``` [in] N ``` N is INTEGER The number of linear equations, i.e., the order of the matrix A. N >= 0.``` [in] NRHS ``` NRHS is INTEGER The number of right-hand-sides, i.e., the number of columns of the matrix B.``` [in] A ``` A is COMPLEX array, dimension (LDA,N) On entry, the N-by-N matrix A.``` [in] LDA ``` LDA is INTEGER The leading dimension of the array A. LDA >= max(1,N).``` [in] AF ``` AF is COMPLEX array, dimension (LDAF,N) The factors L and U from the factorization A = P*L*U as computed by CGETRF.``` [in] LDAF ``` LDAF is INTEGER The leading dimension of the array AF. LDAF >= max(1,N).``` [in] IPIV ``` IPIV is INTEGER array, dimension (N) The pivot indices from the factorization A = P*L*U as computed by CGETRF; row i of the matrix was interchanged with row IPIV(i).``` [in] 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.``` [in] 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.``` [in] B ``` B is COMPLEX array, dimension (LDB,NRHS) The right-hand-side matrix B.``` [in] LDB ``` LDB is INTEGER The leading dimension of the array B. LDB >= max(1,N).``` [in,out] Y ``` Y is COMPLEX array, dimension (LDY,NRHS) On entry, the solution matrix X, as computed by CGETRS. On exit, the improved solution matrix Y.``` [in] LDY ``` LDY is INTEGER The leading dimension of the array Y. LDY >= max(1,N).``` [out] 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.``` [in] N_NORMS ``` N_NORMS is INTEGER Determines which error bounds to return (see ERRS_N and ERRS_C). If N_NORMS >= 1 return normwise error bounds. If N_NORMS >= 2 return componentwise error bounds.``` [in,out] ERRS_N ``` ERRS_N 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 ERRS_N(i,:) corresponds to the ith right-hand side. The second index in ERRS_N(:,err) contains the following three fields: err = 1 "Trust/don't trust" boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon'). err = 2 "Guaranteed" 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 "guaranteed". 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.``` [in,out] ERRS_C ``` ERRS_C 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 componentwise relative error, which is defined as follows: 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 (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 ERRS_C is not accessed. If N_ERR_BNDS < 3, then at most the first (:,N_ERR_BNDS) entries are returned. The first index in ERRS_C(i,:) corresponds to the ith right-hand side. The second index in ERRS_C(:,err) contains the following three fields: err = 1 "Trust/don't trust" boolean. Trust the answer if the reciprocal condition number is less than the threshold sqrt(n) * slamch('Epsilon'). err = 2 "Guaranteed" 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 "guaranteed". 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.``` [in] RES ``` RES is COMPLEX array, dimension (N) Workspace to hold the intermediate residual.``` [in] AYB ``` AYB is REAL array, dimension (N) Workspace.``` [in] DY ``` DY is COMPLEX array, dimension (N) Workspace to hold the intermediate solution.``` [in] Y_TAIL ``` Y_TAIL is COMPLEX array, dimension (N) Workspace to hold the trailing bits of the intermediate solution.``` [in] RCOND ``` RCOND is REAL 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.``` [in] 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 ERRS_N and ERRS_C may no longer be trustworthy.``` [in] RTHRESH ``` RTHRESH is REAL 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.``` [in] DZ_UB ``` DZ_UB is REAL 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.``` [in] IGNORE_CWISE ``` IGNORE_CWISE is LOGICAL If .TRUE. then ignore componentwise convergence. Default value is .FALSE..``` [out] INFO ``` INFO is INTEGER = 0: Successful exit. < 0: if INFO = -i, the ith argument to CGETRS had an illegal value```

Definition at line 391 of file cla_gerfsx_extended.f.

397 *
398 * -- LAPACK computational routine --
399 * -- LAPACK is a software package provided by Univ. of Tennessee, --
400 * -- Univ. of California Berkeley, Univ. of Colorado Denver and NAG Ltd..--
401 *
402 * .. Scalar Arguments ..
403  INTEGER INFO, LDA, LDAF, LDB, LDY, N, NRHS, PREC_TYPE,
404  \$ TRANS_TYPE, N_NORMS
405  LOGICAL COLEQU, IGNORE_CWISE
406  INTEGER ITHRESH
407  REAL RTHRESH, DZ_UB
408 * ..
409 * .. Array Arguments
410  INTEGER IPIV( * )
411  COMPLEX A( LDA, * ), AF( LDAF, * ), B( LDB, * ),
412  \$ Y( LDY, * ), RES( * ), DY( * ), Y_TAIL( * )
413  REAL C( * ), AYB( * ), RCOND, BERR_OUT( * ),
414  \$ ERRS_N( NRHS, * ), ERRS_C( NRHS, * )
415 * ..
416 *
417 * =====================================================================
418 *
419 * .. Local Scalars ..
420  CHARACTER TRANS
421  INTEGER CNT, I, J, X_STATE, Z_STATE, Y_PREC_STATE
422  REAL YK, DYK, YMIN, NORMY, NORMX, NORMDX, DXRAT,
423  \$ DZRAT, PREVNORMDX, PREV_DZ_Z, DXRATMAX,
424  \$ DZRATMAX, DX_X, DZ_Z, FINAL_DX_X, FINAL_DZ_Z,
425  \$ EPS, HUGEVAL, INCR_THRESH
426  LOGICAL INCR_PREC
427  COMPLEX ZDUM
428 * ..
429 * .. Parameters ..
430  INTEGER UNSTABLE_STATE, WORKING_STATE, CONV_STATE,
431  \$ NOPROG_STATE, BASE_RESIDUAL, EXTRA_RESIDUAL,
432  \$ EXTRA_Y
433  parameter( unstable_state = 0, working_state = 1,
434  \$ conv_state = 2,
435  \$ noprog_state = 3 )
436  parameter( base_residual = 0, extra_residual = 1,
437  \$ extra_y = 2 )
438  INTEGER FINAL_NRM_ERR_I, FINAL_CMP_ERR_I, BERR_I
439  INTEGER RCOND_I, NRM_RCOND_I, NRM_ERR_I, CMP_RCOND_I
440  INTEGER CMP_ERR_I, PIV_GROWTH_I
441  parameter( final_nrm_err_i = 1, final_cmp_err_i = 2,
442  \$ berr_i = 3 )
443  parameter( rcond_i = 4, nrm_rcond_i = 5, nrm_err_i = 6 )
444  parameter( cmp_rcond_i = 7, cmp_err_i = 8,
445  \$ piv_growth_i = 9 )
446  INTEGER LA_LINRX_ITREF_I, LA_LINRX_ITHRESH_I,
447  \$ LA_LINRX_CWISE_I
448  parameter( la_linrx_itref_i = 1,
449  \$ la_linrx_ithresh_i = 2 )
450  parameter( la_linrx_cwise_i = 3 )
451  INTEGER LA_LINRX_TRUST_I, LA_LINRX_ERR_I,
452  \$ LA_LINRX_RCOND_I
453  parameter( la_linrx_trust_i = 1, la_linrx_err_i = 2 )
454  parameter( la_linrx_rcond_i = 3 )
455 * ..
456 * .. External Subroutines ..
457  EXTERNAL caxpy, ccopy, cgetrs, cgemv, blas_cgemv_x,
458  \$ blas_cgemv2_x, cla_geamv, cla_wwaddw, slamch,
460  REAL SLAMCH
461  CHARACTER CHLA_TRANSTYPE
462 * ..
463 * .. Intrinsic Functions ..
464  INTRINSIC abs, max, min
465 * ..
466 * .. Statement Functions ..
467  REAL CABS1
468 * ..
469 * .. Statement Function Definitions ..
470  cabs1( zdum ) = abs( real( zdum ) ) + abs( aimag( zdum ) )
471 * ..
472 * .. Executable Statements ..
473 *
474  IF ( info.NE.0 ) RETURN
475  trans = chla_transtype(trans_type)
476  eps = slamch( 'Epsilon' )
477  hugeval = slamch( 'Overflow' )
478 * Force HUGEVAL to Inf
479  hugeval = hugeval * hugeval
480 * Using HUGEVAL may lead to spurious underflows.
481  incr_thresh = real( n ) * eps
482 *
483  DO j = 1, nrhs
484  y_prec_state = extra_residual
485  IF ( y_prec_state .EQ. extra_y ) THEN
486  DO i = 1, n
487  y_tail( i ) = 0.0
488  END DO
489  END IF
490
491  dxrat = 0.0
492  dxratmax = 0.0
493  dzrat = 0.0
494  dzratmax = 0.0
495  final_dx_x = hugeval
496  final_dz_z = hugeval
497  prevnormdx = hugeval
498  prev_dz_z = hugeval
499  dz_z = hugeval
500  dx_x = hugeval
501
502  x_state = working_state
503  z_state = unstable_state
504  incr_prec = .false.
505
506  DO cnt = 1, ithresh
507 *
508 * Compute residual RES = B_s - op(A_s) * Y,
509 * op(A) = A, A**T, or A**H depending on TRANS (and type).
510 *
511  CALL ccopy( n, b( 1, j ), 1, res, 1 )
512  IF ( y_prec_state .EQ. base_residual ) THEN
513  CALL cgemv( trans, n, n, (-1.0e+0,0.0e+0), a, lda,
514  \$ y( 1, j ), 1, (1.0e+0,0.0e+0), res, 1)
515  ELSE IF (y_prec_state .EQ. extra_residual) THEN
516  CALL blas_cgemv_x( trans_type, n, n, (-1.0e+0,0.0e+0), a,
517  \$ lda, y( 1, j ), 1, (1.0e+0,0.0e+0),
518  \$ res, 1, prec_type )
519  ELSE
520  CALL blas_cgemv2_x( trans_type, n, n, (-1.0e+0,0.0e+0),
521  \$ a, lda, y(1, j), y_tail, 1, (1.0e+0,0.0e+0), res, 1,
522  \$ prec_type)
523  END IF
524
525 ! XXX: RES is no longer needed.
526  CALL ccopy( n, res, 1, dy, 1 )
527  CALL cgetrs( trans, n, 1, af, ldaf, ipiv, dy, n, info )
528 *
529 * Calculate relative changes DX_X, DZ_Z and ratios DXRAT, DZRAT.
530 *
531  normx = 0.0e+0
532  normy = 0.0e+0
533  normdx = 0.0e+0
534  dz_z = 0.0e+0
535  ymin = hugeval
536 *
537  DO i = 1, n
538  yk = cabs1( y( i, j ) )
539  dyk = cabs1( dy( i ) )
540
541  IF ( yk .NE. 0.0e+0 ) THEN
542  dz_z = max( dz_z, dyk / yk )
543  ELSE IF ( dyk .NE. 0.0 ) THEN
544  dz_z = hugeval
545  END IF
546
547  ymin = min( ymin, yk )
548
549  normy = max( normy, yk )
550
551  IF ( colequ ) THEN
552  normx = max( normx, yk * c( i ) )
553  normdx = max( normdx, dyk * c( i ) )
554  ELSE
555  normx = normy
556  normdx = max(normdx, dyk)
557  END IF
558  END DO
559
560  IF ( normx .NE. 0.0 ) THEN
561  dx_x = normdx / normx
562  ELSE IF ( normdx .EQ. 0.0 ) THEN
563  dx_x = 0.0
564  ELSE
565  dx_x = hugeval
566  END IF
567
568  dxrat = normdx / prevnormdx
569  dzrat = dz_z / prev_dz_z
570 *
571 * Check termination criteria
572 *
573  IF (.NOT.ignore_cwise
574  \$ .AND. ymin*rcond .LT. incr_thresh*normy
575  \$ .AND. y_prec_state .LT. extra_y )
576  \$ incr_prec = .true.
577
578  IF ( x_state .EQ. noprog_state .AND. dxrat .LE. rthresh )
579  \$ x_state = working_state
580  IF ( x_state .EQ. working_state ) THEN
581  IF (dx_x .LE. eps) THEN
582  x_state = conv_state
583  ELSE IF ( dxrat .GT. rthresh ) THEN
584  IF ( y_prec_state .NE. extra_y ) THEN
585  incr_prec = .true.
586  ELSE
587  x_state = noprog_state
588  END IF
589  ELSE
590  IF ( dxrat .GT. dxratmax ) dxratmax = dxrat
591  END IF
592  IF ( x_state .GT. working_state ) final_dx_x = dx_x
593  END IF
594
595  IF ( z_state .EQ. unstable_state .AND. dz_z .LE. dz_ub )
596  \$ z_state = working_state
597  IF ( z_state .EQ. noprog_state .AND. dzrat .LE. rthresh )
598  \$ z_state = working_state
599  IF ( z_state .EQ. working_state ) THEN
600  IF ( dz_z .LE. eps ) THEN
601  z_state = conv_state
602  ELSE IF ( dz_z .GT. dz_ub ) THEN
603  z_state = unstable_state
604  dzratmax = 0.0
605  final_dz_z = hugeval
606  ELSE IF ( dzrat .GT. rthresh ) THEN
607  IF ( y_prec_state .NE. extra_y ) THEN
608  incr_prec = .true.
609  ELSE
610  z_state = noprog_state
611  END IF
612  ELSE
613  IF ( dzrat .GT. dzratmax ) dzratmax = dzrat
614  END IF
615  IF ( z_state .GT. working_state ) final_dz_z = dz_z
616  END IF
617 *
618 * Exit if both normwise and componentwise stopped working,
619 * but if componentwise is unstable, let it go at least two
620 * iterations.
621 *
622  IF ( x_state.NE.working_state ) THEN
623  IF ( ignore_cwise ) GOTO 666
624  IF ( z_state.EQ.noprog_state .OR. z_state.EQ.conv_state )
625  \$ GOTO 666
626  IF ( z_state.EQ.unstable_state .AND. cnt.GT.1 ) GOTO 666
627  END IF
628
629  IF ( incr_prec ) THEN
630  incr_prec = .false.
631  y_prec_state = y_prec_state + 1
632  DO i = 1, n
633  y_tail( i ) = 0.0
634  END DO
635  END IF
636
637  prevnormdx = normdx
638  prev_dz_z = dz_z
639 *
640 * Update soluton.
641 *
642  IF ( y_prec_state .LT. extra_y ) THEN
643  CALL caxpy( n, (1.0e+0,0.0e+0), dy, 1, y(1,j), 1 )
644  ELSE
645  CALL cla_wwaddw( n, y( 1, j ), y_tail, dy )
646  END IF
647
648  END DO
649 * Target of "IF (Z_STOP .AND. X_STOP)". Sun's f77 won't EXIT.
650  666 CONTINUE
651 *
652 * Set final_* when cnt hits ithresh
653 *
654  IF ( x_state .EQ. working_state ) final_dx_x = dx_x
655  IF ( z_state .EQ. working_state ) final_dz_z = dz_z
656 *
657 * Compute error bounds
658 *
659  IF (n_norms .GE. 1) THEN
660  errs_n( j, la_linrx_err_i ) = final_dx_x / (1 - dxratmax)
661
662  END IF
663  IF ( n_norms .GE. 2 ) THEN
664  errs_c( j, la_linrx_err_i ) = final_dz_z / (1 - dzratmax)
665  END IF
666 *
667 * Compute componentwise relative backward error from formula
668 * max(i) ( abs(R(i)) / ( abs(op(A_s))*abs(Y) + abs(B_s) )(i) )
669 * where abs(Z) is the componentwise absolute value of the matrix
670 * or vector Z.
671 *
672 * Compute residual RES = B_s - op(A_s) * Y,
673 * op(A) = A, A**T, or A**H depending on TRANS (and type).
674 *
675  CALL ccopy( n, b( 1, j ), 1, res, 1 )
676  CALL cgemv( trans, n, n, (-1.0e+0,0.0e+0), a, lda, y(1,j), 1,
677  \$ (1.0e+0,0.0e+0), res, 1 )
678
679  DO i = 1, n
680  ayb( i ) = cabs1( b( i, j ) )
681  END DO
682 *
683 * Compute abs(op(A_s))*abs(Y) + abs(B_s).
684 *
685  CALL cla_geamv ( trans_type, n, n, 1.0e+0,
686  \$ a, lda, y(1, j), 1, 1.0e+0, ayb, 1 )
687
688  CALL cla_lin_berr ( n, n, 1, res, ayb, berr_out( j ) )
689 *
690 * End of loop for each RHS.
691 *
692  END DO
693 *
694  RETURN
695 *
696 * End of CLA_GERFSX_EXTENDED
697 *
character *1 function chla_transtype(TRANS)
CHLA_TRANSTYPE
subroutine ccopy(N, CX, INCX, CY, INCY)
CCOPY
Definition: ccopy.f:81
subroutine caxpy(N, CA, CX, INCX, CY, INCY)
CAXPY
Definition: caxpy.f:88
subroutine cgemv(TRANS, M, N, ALPHA, A, LDA, X, INCX, BETA, Y, INCY)
CGEMV
Definition: cgemv.f:158
subroutine cgetrs(TRANS, N, NRHS, A, LDA, IPIV, B, LDB, INFO)
CGETRS
Definition: cgetrs.f:121
subroutine cla_geamv(TRANS, M, N, ALPHA, A, LDA, X, INCX, BETA, Y, INCY)
CLA_GEAMV computes a matrix-vector product using a general matrix to calculate error bounds.
Definition: cla_geamv.f:175