NAG Library Function Document

nag_sparse_herm_basic_diagnostic (f11gtc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     itn – Integer *Output

On exit: the number of iterations carried out by nag_sparse_herm_basic_solver (f11gsc).

2:     stplhs – double *Output

On exit: the current value of the left-hand side of the termination criterion used by nag_sparse_herm_basic_solver (f11gsc).

3:     stprhs – double *Output

On exit: the current value of the right-hand side of the termination criterion used by nag_sparse_herm_basic_solver (f11gsc).

4:     anorm – double *Output

On exit: the norm ${‖A‖}_1={‖A‖}_{\infty }$ when either it has been supplied to nag_sparse_herm_basic_setup (f11grc) or it has been estimated by nag_sparse_herm_basic_solver (f11gsc) (see also Sections 3 and 5 in nag_sparse_herm_basic_setup (f11grc)). Otherwise, $\mathbf{anorm}=0.0$ is returned.

5:     sigmax – double *Output

On exit: the current estimate of the largest singular value ${\sigma }_1\left(\stackrel{-}{A}\right)$ of the preconditioned iteration matrix $\stackrel{-}{A}=E^{-1}A{E}^{-\mathrm{H}}$, when either it has been supplied to nag_sparse_herm_basic_setup (f11grc) or it has been estimated by nag_sparse_herm_basic_solver (f11gsc) (see also Sections 3 and 5 in nag_sparse_herm_basic_setup (f11grc)). Note that if $\mathbf{its}<\mathbf{itn}$ then sigmax contains the final estimate. If, on final exit from nag_sparse_herm_basic_solver (f11gsc), $\mathbf{its}=\mathbf{itn}$, then the estimation of ${\sigma }_1\left(\stackrel{-}{A}\right)$ may have not converged: in this case you should look at the value returned in sigerr. Otherwise, $\mathbf{sigmax}=0.0$ is returned.

6:     its – Integer *Output

On exit: the number of iterations employed so far in the computation of the estimate of ${\sigma }_1\left(\stackrel{-}{A}\right)$, the largest singular value of the preconditioned matrix $\stackrel{-}{A}=E^{-1}A{E}^{-\mathrm{H}}$, when ${\sigma }_1\left(\stackrel{-}{A}\right)$ has been estimated by nag_sparse_herm_basic_solver (f11gsc) using the bisection method (see also Sections 3, 5 and 9 in nag_sparse_herm_basic_setup (f11grc)). Otherwise, $\mathbf{its}=0$ is returned.

7:     sigerr – double *Output

On exit: if ${\sigma }_1\left(\stackrel{-}{A}\right)$ has been estimated by nag_sparse_herm_basic_solver (f11gsc) using bisection,

$$\mathbf{sigerr}=\max \left(\frac{\left|{\sigma }_1^{\left(k\right)}-{\sigma }_1^{\left(k-1\right)}\right|}{{\sigma }_1^{\left(k\right)}},\frac{\left|{\sigma }_1^{\left(k\right)}-{\sigma }_1^{\left(k-2\right)}\right|}{{\sigma }_1^{\left(k\right)}}\right)\text{,}$$

where $k=\mathbf{its}$ denotes the iteration number. The estimation has converged if $\mathbf{sigerr}\le \mathbf{sigtol}$ where sigtol is an input argument to nag_sparse_herm_basic_setup (f11grc). Otherwise, $\mathbf{sigerr}=0.0$ is returned.

8:     work[lwork] – const ComplexCommunication Array

On entry: the array work as returned by nag_sparse_herm_basic_solver (f11gsc) (see also Section 3 in nag_sparse_herm_basic_solver (f11gsc)).

9:     lwork – IntegerInput

On entry: the dimension of the array work (see also Section 5 in nag_sparse_herm_basic_setup (f11grc)).

Constraint: $\mathbf{lwork}\ge 120$.

Note:  although the minimum value of lwork ensures the correct functioning of nag_sparse_herm_basic_diagnostic (f11gtc), a larger value is required by the iterative solver nag_sparse_herm_basic_solver (f11gsc) (see also Section 5 in nag_sparse_herm_basic_setup (f11grc)).

10:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_BAD_PARAM

On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.

NE_INT

On entry, $\mathbf{lwork}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lwork}\ge 120$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

NE_OUT_OF_SEQUENCE

nag_sparse_herm_basic_diagnostic (f11gtc) has been called out of sequence.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example