naginterfaces.library.sparse.real_​gen_​solve_​bdilu

naginterfaces.library.sparse.real_gen_solve_bdilu(method, nnz, a, irow, icol, istb, indb, ipivp, ipivq, istr, idiag, b, m, tol, maxitn, x)

real_gen_solve_bdilu solves a real sparse nonsymmetric system of linear equations, represented in coordinate storage format, using a restarted generalized minimal residual (RGMRES), conjugate gradient squared (CGS), stabilized bi-conjugate gradient (BI-CGSTAB), or transpose-free quasi-minimal residual (TFQMR) method, with block Jacobi or additive Schwarz preconditioning.

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

https://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/f11/f11dgf.html

Parameters

methodstr

Specifies the iterative method to be used.

$method=\text{'RGMRES'}$

Restarted generalized minimum residual method.

$method=\text{'CGS'}$

Conjugate gradient squared method.

$method=\text{'BICGSTAB'}$

Bi-conjugate gradient stabilized ($\ell$) method.

$method=\text{'TFQMR'}$

Transpose-free quasi-minimal residual method.

nnzint

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

afloat, array-like, shape $\left(\text{la}\right)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

irowint, array-like, shape $\left(\text{la}\right)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

icolint, array-like, shape $\left(\text{la}\right)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

istbint, array-like, shape $(\text{nb}+1)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

indbint, array-like, shape $\left(\text{lindb}\right)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

ipivpint, array-like, shape $\left(\text{lindb}\right)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

ipivqint, array-like, shape $\left(\text{lindb}\right)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

istrint, array-like, shape $(\text{lindb}+1)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

idiagint, array-like, shape $\left(\text{lindb}\right)$

The values returned in arrays $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ by a previous call to real_gen_precon_bdilu().

The arrays $istb$, $indb$ and $a$ together with the scalars $\text{n}$, $nnz$, $\text{la}$, $\text{nb}$ and $\text{lindb}$ must be the same values that were supplied in the preceding call to real_gen_precon_bdilu().

bfloat, array-like, shape $\left(n\right)$

The right-hand side vector $b$.

mint

If $method=\text{'RGMRES'}$, $m$ is the dimension of the restart subspace.

If $method=\text{'BICGSTAB'}$, $m$ is the order $\ell$ of the polynomial BI-CGSTAB method.

Otherwise, $m$ is not referenced.

tolfloat

The required tolerance. Let $x_k$ denote the approximate solution at iteration $k$, and $r_k$ the corresponding residual. The algorithm is considered to have converged at iteration $k$ if

$${\parallel r_k\parallel }_{\infty }\le \tau \times ({\parallel b\parallel }_{\infty }+{\parallel A\parallel }_{\infty }{\parallel x_k\parallel }_{\infty })\text{.}$$

If $tol\le 0.0$, $\tau =max\left(\sqrt{ϵ},\sqrt{n}ϵ\right)$ is used, where $ϵ$ is the machine precision. Otherwise $\tau =max(tol,10ϵ,\sqrt{n}ϵ)$ is used.

maxitnint

The maximum number of iterations allowed.

xfloat, array-like, shape $\left(n\right)$

An initial approximation to the solution vector $x$.

Returns

xfloat, ndarray, shape $\left(n\right)$

An improved approximation to the solution vector $x$.

rnormfloat

The final value of the residual norm ${\parallel r_k\parallel }_{\infty }$, where $k$ is the output value of $itn$.

itnint

The number of iterations carried out.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $1$)

On entry, $nnz=⟨value⟩$.

Constraint: $nnz\ge 1$.

(errno $1$)

On entry, $nnz=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $nnz\le n^2$.

(errno $1$)

On entry, $\text{la}=⟨value⟩$ and $nnz=⟨value⟩$.

Constraint: $\text{la}\ge 2\times nnz$.

(errno $1$)

On entry, $\text{nb}=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $1\le \text{nb}\le n$.

(errno $1$)

On entry, $istb\left[0\right]=⟨value⟩$.

Constraint: $istb\left[0\right]\ge 1$.

(errno $1$)

On entry, for $b=⟨value⟩$, $istb\left[b\right]=⟨value⟩$ and $istb[b-1]=⟨value⟩$.

Constraint: $istb\left[\text{b}\right]>istb[\text{b}-1]$, for $\text{b}=1,2,\dots ,\text{nb}$.

(errno $1$)

On entry, $indb[⟨value⟩]=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $1\le indb[\text{m}-1]\le n$, for $\text{m}=1,2,\dots ,istb\left[\text{nb}\right]-1$

(errno $1$)

On entry, $\text{lindb}=⟨value⟩$, $istb\left[\text{nb}\right]-1=⟨value⟩$ and $\text{nb}=⟨value⟩$.

Constraint: $\text{lindb}\ge istb\left[\text{nb}\right]-1$.

(errno $1$)

On entry, $method=⟨value⟩$.

Constraint: $method=\text{'RGMRES'}$, $\text{'CGS'}$ or $\text{'BICGSTAB'}$.

(errno $1$)

On entry, $m=⟨value⟩$ and $n=⟨value⟩$.

Constraint: if $method=\text{'RGMRES'}$, $1\le m\le min(n,⟨value⟩)$.

If $method=\text{'BICGSTAB'}$, $1\le m\le min(n,⟨value⟩)$.

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol<1.0$.

(errno $1$)

On entry, $maxitn=⟨value⟩$.

Constraint: $maxitn\ge 1$.

(errno $2$)

On entry, $irow[⟨value⟩]=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $1\le irow[\text{i}-1]\le n$, for $\text{i}=1,2,\dots ,nnz$.

Check that $a$, $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ have not been corrupted between calls to real_gen_precon_bdilu() and real_gen_solve_bdilu.

(errno $2$)

On entry, $icol[⟨value⟩]=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $1\le icol[\text{i}-1]\le n$, for $\text{i}=1,2,\dots ,nnz$.

Check that $a$, $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ have not been corrupted between calls to real_gen_precon_bdilu() and real_gen_solve_bdilu.

(errno $2$)

On entry, element $⟨value⟩$ of $a$ was out of order.

Check that $a$, $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ have not been corrupted between calls to real_gen_precon_bdilu() and real_gen_solve_bdilu.

(errno $2$)

On entry, location $⟨value⟩$ of $(irow,icol)$ was a duplicate.

Check that $a$, $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ have not been corrupted between calls to real_gen_precon_bdilu() and real_gen_solve_bdilu.

(errno $3$)

The CS representation of the preconditioner is invalid.

Check that $a$, $irow$, $icol$, $ipivp$, $ipivq$, $istr$ and $idiag$ have not been corrupted between calls to real_gen_precon_bdilu() and real_gen_solve_bdilu.

(errno $4$)

The required accuracy could not be obtained. However a reasonable accuracy may have been achieved. You should check the output value of $rnorm$ for acceptability. This error code usually implies that your problem has been fully and satisfactorily solved to within or close to the accuracy available on your system. Further iterations are unlikely to improve on this situation.

(errno $5$)

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

(errno $6$)

Algorithmic breakdown. A solution is returned, although it is possible that it is completely inaccurate.

Notes

real_gen_solve_bdilu solves a real sparse nonsymmetric linear system of equations:

$$Ax=b\text{,}$$

using a preconditioned RGMRES (see Saad and Schultz (1986)), CGS (see Sonneveld (1989)), BI-CGSTAB($\ell$) (see Van der Vorst (1989) and Sleijpen and Fokkema (1993)), or TFQMR (see Freund and Nachtigal (1991) and Freund (1993)) method.

real_gen_solve_bdilu uses the incomplete (possibly overlapping) block $LU$ factorization determined by real_gen_precon_bdilu() as the preconditioning matrix. A call to real_gen_solve_bdilu must always be preceded by a call to real_gen_precon_bdilu(). Alternative preconditioners for the same storage scheme are available by calling real_gen_solve_ilu() or real_gen_solve_jacssor().

The matrix $A$, and the preconditioning matrix $M$, are represented in coordinate storage (CS) format (see the F11 Introduction) in the arrays $a$, $irow$ and $icol$, as returned from real_gen_precon_bdilu(). The array $a$ holds the nonzero entries in these matrices, while $irow$ and $icol$ hold the corresponding row and column indices.

real_gen_solve_bdilu is a Black Box function which calls real_gen_basic_setup(), real_gen_basic_solver() and real_gen_basic_diag(). If you wish to use an alternative storage scheme, preconditioner, or termination criterion, or require additional diagnostic information, you should call these underlying functions directly.

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

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

Salvini, S A and Shaw, G J, 1996, An evaluation of new NAG Library solvers for large sparse unsymmetric linear systems, NAG Technical Report TR2/96

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