naginterfaces.library.sparse.real_​symm_​basic_​diag

naginterfaces.library.sparse.real_symm_basic_diag(comm)

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

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

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f11/f11gff.html

Parameters

commdict, communication object

Communication structure.

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

Returns

itnint

The number of iterations carried out by real_symm_basic_solver().

stplhsfloat

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

stprhsfloat

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

anormfloat

For CG and SYMMLQ methods, the norm ${\parallel A\parallel }_1={\parallel A\parallel }_{\infty }$ when either it has been supplied to real_symm_basic_setup() or it has been estimated by real_symm_basic_solver() (see also Notes for real_symm_basic_setup and Parameters for real_symm_basic_setup). Otherwise, $anorm=0.0$ is returned.

For MINRES method, an estimate of the infinity norm of the preconditioned matrix operator.

sigmaxfloat

For CG and SYMMLQ methods, 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}^{-T}$, when either it has been supplied to real_symm_basic_setup() or it has been estimated by real_symm_basic_solver() (see also Notes for real_symm_basic_setup and Parameters for real_symm_basic_setup). Note that if $its<itn$ then $sigmax$ contains the final estimate. If, on final exit from real_symm_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.

For MINRES method, an estimate of the final transformed residual.

itsint

For CG and SYMMLQ methods, 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}^{-T}$, when ${\sigma }_1\left(\overline{A}\right)$ has been estimated by real_symm_basic_solver() using the bisection method (see also Notes for real_symm_basic_setup, Parameters for real_symm_basic_setup and Further Comments). Otherwise, $its=0$ is returned.

sigerrfloat

For CG and SYMMLQ methods, if ${\sigma }_1\left(\overline{A}\right)$ has been estimated by real_symm_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 real_symm_basic_setup(). Otherwise, $sigerr=0.0$ is returned.

For MINRES method, an estimate of the condition number of the preconditioned matrix.

Raises

NagValueError

(errno $1$)

real_symm_basic_diag has been called out of sequence.

Notes

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

For further information you should read the documentation for real_symm_basic_setup() and real_symm_basic_solver().

References

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