naginterfaces.library.sparse.complex_​herm_​basic_​diag

naginterfaces.library.sparse.complex_herm_basic_diag(comm)

complex_herm_basic_diag is the third in a suite of three functions for the iterative solution of a complex Hermitian system of simultaneous linear equations (see Golub and Van Loan (1996)). complex_herm_basic_diag returns information about the computations during an iteration and/or after this has been completed. The first function of the suite, complex_herm_basic_setup(), is a setup function, the second function, complex_herm_basic_solver() is the proper iterative solver.

These three functions are suitable for the solution of large sparse complex Hermitian systems of equations.

For full information please refer to the NAG Library document for f11gt

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11gtf.html

Parameters

commdict, communication object

Communication structure.

This argument must have been initialized by a prior call to complex_herm_basic_solver().

Returns

itnint

The number of iterations carried out by complex_herm_basic_solver().

stplhsfloat

The current value of the left-hand side of the termination criterion used by complex_herm_basic_solver().

stprhsfloat

The current value of the right-hand side of the termination criterion used by complex_herm_basic_solver().

anormfloat

The norm ${\parallel A\parallel }_1={\parallel A\parallel }_{\infty }$ when either it has been supplied to complex_herm_basic_setup() or it has been estimated by complex_herm_basic_solver() (see also Notes for complex_herm_basic_setup and Parameters for complex_herm_basic_setup).

Otherwise, $anorm=0.0$ is returned.

sigmaxfloat

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

itsint

The number of iterations employed so far in the computation of the estimate of ${\sigma }_1\left(\overline{A}\right)$, the largest singular value of the preconditioned matrix $\overline{A}=E^{-1}A{E}^{-H}$, when ${\sigma }_1\left(\overline{A}\right)$ has been estimated by complex_herm_basic_solver() using the bisection method (see also Notes for complex_herm_basic_setup, Parameters for complex_herm_basic_setup and Further Comments). Otherwise, $its=0$ is returned.

sigerrfloat

If ${\sigma }_1\left(\overline{A}\right)$ has been estimated by complex_herm_basic_solver() using bisection,

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

where $k=its$ denotes the iteration number. The estimation has converged if $sigerr\le \text{sigtol}$ where $\text{sigtol}$ is an input argument to complex_herm_basic_setup().

Otherwise, $sigerr=0.0$ is returned.

Raises

NagValueError

(errno $1$)

complex_herm_basic_diag has been called out of sequence.

Notes

complex_herm_basic_diag returns information about the solution process. It can be called both during a monitoring step of the solver complex_herm_basic_solver() or after this solver has completed its tasks. Calling complex_herm_basic_diag at any other time will result in an error condition being raised.

For further information you should read the documentation for complex_herm_basic_setup() and complex_herm_basic_solver().

References

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore