naginterfaces.library.sparse.complex_​gen_​basic_​solver

naginterfaces.library.sparse.complex_gen_basic_solver(irevcm, u, v, comm, wgt=None)

complex_gen_basic_solver is an iterative solver for a complex general (non-Hermitian) system of simultaneous linear equations; complex_gen_basic_solver is the second in a suite of three functions, where the first function, complex_gen_basic_setup(), must be called prior to complex_gen_basic_solver to set up the suite, and the third function in the suite, complex_gen_basic_diag(), can be used to return additional information about the computation.

These three functions are suitable for the solution of large sparse general (non-Hermitian) systems of equations.

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

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

Parameters

irevcmint

On initial entry: $irevcm=0$, otherwise an error condition will be raised.

On intermediate entry: must either be unchanged from its previous exit value, or can have one of the following values.

$irevcm=5$

Tidy termination: the computation will terminate at the end of the current iteration. Further reverse communication exits may occur depending on when the termination request is issued. complex_gen_basic_solver will then return with the termination code $irevcm=4$. Note that before calling complex_gen_basic_solver with $irevcm=5$ the calling program must have performed the tasks required by the value of $irevcm$ returned by the previous call to complex_gen_basic_solver, otherwise subsequently returned values may be invalid.

$irevcm=6$

Immediate termination: complex_gen_basic_solver will return immediately with termination code $irevcm=4$ and with any useful information available. This includes the last iterate of the solution.

Immediate termination may be useful, for example, when errors are detected during matrix-vector multiplication or during the solution of the preconditioning equation.

Changing $irevcm$ to any other value between calls will result in an error.

ucomplex, ndarray, shape $\left(\text{n}\right)$, modified in place

On initial entry: an initial estimate, $x_0$, of the solution of the system of equations $Ax=b$.

On intermediate entry: must remain unchanged.

On intermediate exit: the returned value of $irevcm$ determines the contents of $u$ as follows.

If $irevcm=-1$, $1$ or $2$, $u$ holds the vector $u$ on which the operation specified by $irevcm$ is to be carried out.

If $irevcm=3$, $u$ holds the current iterate of the solution vector.

On final exit: if $errno$ = 3 or $errno$ < 0, the array $u$ is unchanged from the initial entry to complex_gen_basic_solver.

If $errno$ = 1, the array $u$ is unchanged from the last entry to complex_gen_basic_solver.

Otherwise, $u$ holds the last available iterate of the solution of the system of equations, for all returned values of $\text{errno}$.

vcomplex, ndarray, shape $\left(\text{n}\right)$, modified in place

On initial entry: the right-hand side $b$ of the system of equations $Ax=b$.

On intermediate entry: the returned value of $irevcm$ determines the contents of $v$ as follows.

If $irevcm=-1$, $1$ or $2$, $v$ must store the vector $v$, the result of the operation specified by the value of $irevcm$ returned by the previous call to complex_gen_basic_solver.

If $irevcm=3$, $v$ must remain unchanged.

On intermediate exit: if $irevcm=3$, $v$ holds the current iterate of the residual vector. Note that this is an approximation to the true residual vector. Otherwise, it does not contain any useful information.

On final exit: if $errno$ = 3 or $errno$ < 0, the array $v$ is unchanged from the initial entry to complex_gen_basic_solver.

If $errno$ = 1, the array $v$ is unchanged from the last entry to complex_gen_basic_solver.

If the function exits successfully or $errno$ = 2, the array $v$ contains the true residual vector of the system of equations (see also Exceptions).

Otherwise, $v$ stores the last available iterate of the residual vector unless $errno$ = 8 is returned on last entry, in which case $v$ is set to $0.0$.

commdict, communication object, modified in place

Communication structure.

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

wgtNone or float, array-like, shape $\left(\text{n}\right)$, optional

The user-supplied weights, if these are to be used in the computation of the vector norms in the termination criterion (see Notes for complex_gen_basic_setup and Parameters for complex_gen_basic_setup).

Returns

irevcmint

On intermediate exit: has the following meanings.

$irevcm=-1$

The calling program must compute the matrix-vector product $v=A^{H}u$, where $u$ and $v$ are stored in $u$ and $v$, respectively; RGMRES, CGS and BI-CGSTAB($\ell$) methods return $irevcm=-1$ only if the matrix norm ${\parallel A\parallel }_1$ or ${\parallel A\parallel }_{\infty }$ is estimated internally using Higham’s method. This can only happen if $\text{iterm}=1$ in complex_gen_basic_setup().

$irevcm=1$

The calling program must compute the matrix-vector product $v=Au$, where $u$ and $v$ are stored in $u$ and $v$, respectively.

$irevcm=2$

The calling program must solve the preconditioning equation $Mv=u$, where $u$ and $v$ are stored in $u$ and $v$, respectively.

$irevcm=3$

Monitoring step: the solution and residual at the current iteration are returned in the arrays $u$ and $v$, respectively. No action by the calling program is required. complex_gen_basic_diag() can be called at this step to return additional information.

On final exit: $irevcm=4$: complex_gen_basic_solver has completed its tasks. The value of $\text{errno}$ determines whether the iteration has been successfully completed, errors have been detected or the calling program has requested termination.

Raises

NagValueError

(errno $-1$)

On intermediate re-entry, $irevcm=⟨value⟩$.

Constraint: either $irevcm$ must be unchanged from its previous exit value or $irevcm=5$ or $6$.

(errno $-1$)

On initial entry, $irevcm=⟨value⟩$.

Constraint: $irevcm=0$.

(errno $3$)

Either complex_gen_basic_setup() was not called before calling complex_gen_basic_solver or it has returned an error.

Warns

NagAlgorithmicWarning

(errno $1$)

complex_gen_basic_solver has already completed its tasks. You need to set a new problem.

(errno $2$)

The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

(errno $2$)

User-requested termination: the required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

(errno $4$)

User-requested tidy termination. The solution has not converged after $⟨value⟩$ iterations.

(errno $5$)

The solution has not converged after $⟨value⟩$ iterations.

(errno $6$)

Algorithm breakdown at iteration no. $⟨value⟩$.

(errno $8$)

User-requested immediate termination.

(errno $10$)

The weights in array $wgt$ are all zero.

Notes

complex_gen_basic_solver solves the general (non-Hermitian) system of linear simultaneous equations $Ax=b$ of order $\text{n}$, where $\text{n}$ is large and the coefficient matrix $A$ is sparse, using one of four available methods: RGMRES, the preconditioned restarted generalized minimum residual method (see Saad and Schultz (1986)); CGS, the preconditioned conjugate gradient squared method (see Sonneveld (1989)); BI-CGSTAB($\ell$), the bi-conjugate gradient stabilized method of order $\ell$ (see Van der Vorst (1989) and Sleijpen and Fokkema (1993)); or TFQMR, the transpose-free quasi-minimal residual method (see Freund and Nachtigal (1991) and Freund (1993)).

For a general description of the methods employed you are referred to Notes for complex_gen_basic_setup.

complex_gen_basic_solver can solve the system after the first function in the suite, complex_gen_basic_setup(), has been called to initialize the computation and specify the method of solution. The third function in the suite, complex_gen_basic_diag(), can be used to return additional information generated by the computation during monitoring steps and after complex_gen_basic_solver has completed its tasks.

complex_gen_basic_solver uses reverse communication, i.e., it returns repeatedly to the calling program with the argument $irevcm$ (see Parameters) set to specified values which require the calling program to carry out one of the following tasks:

compute the matrix-vector product $v=Au$ or $v=A^{H}u$ (the four methods require the matrix transpose-vector product only if ${\parallel A\parallel }_1$ or ${\parallel A\parallel }_{\infty }$ is estimated internally by Higham’s method (see Higham (1988)));

solve the preconditioning equation $Mv=u$;

notify the completion of the computation;

allow the calling program to monitor the solution.

Through the argument $irevcm$ the calling program can cause immediate or tidy termination of the execution. On final exit, the last iterates of the solution and of the residual vectors of the original system of equations are returned.

Reverse communication has the following advantages.

1. Maximum flexibility in the representation and storage of sparse matrices: all matrix operations are performed outside the solver function, thereby avoiding the need for a complicated interface with enough flexibility to cope with all types of storage schemes and sparsity patterns. This applies also to preconditioners.

2. Enhanced user interaction: you can closely monitor the progress of the solution and tidy or immediate termination can be requested. This is useful, for example, when alternative termination criteria are to be employed or in case of failure of the external functions used to perform matrix operations.

References

Freund, R W, 1993, A transpose-free quasi-minimal residual algorithm for non-Hermitian linear systems, SIAM J. Sci. Comput. (14), 470–482

Freund, R W and Nachtigal, N, 1991, QMR: a Quasi-Minimal Residual Method for Non-Hermitian Linear Systems, Numer. Math. (60), 315–339

Higham, N J, 1988, FORTRAN codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation, ACM Trans. Math. Software (14), 381–396

Saad, Y and Schultz, M, 1986, GMRES: a generalized minimal residual algorithm for solving nonsymmetric linear systems, SIAM J. Sci. Statist. Comput. (7), 856–869

Sleijpen, G L G and Fokkema, D R, 1993, BiCGSTAB $\left(\ell \right)$ for linear equations involving matrices with complex spectrum, ETNA (1), 11–32

Sonneveld, P, 1989, CGS, a fast Lanczos-type solver for nonsymmetric linear systems, SIAM J. Sci. Statist. Comput. (10), 36–52

Van der Vorst, H, 1989, Bi-CGSTAB, a fast and smoothly converging variant of Bi-CG for the solution of nonsymmetric linear systems, SIAM J. Sci. Statist. Comput. (13), 631–644