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

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

complex_gen_solve_bdilu solves a complex sparse non-Hermitian 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 f11du

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11duf.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 value of $nnz$ as supplied to a previous call to complex_gen_precon_bdilu()

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

The value of $a$ returned by a previous call to complex_gen_precon_bdilu()

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

The value of $irow$ returned by a previous call to complex_gen_precon_bdilu()

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

The value of $icol$ returned by a previous call to complex_gen_precon_bdilu()

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

The value of $istb$ as supplied to a previous call to complex_gen_precon_bdilu()

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

The value of $indb$ as supplied to a previous call to complex_gen_precon_bdilu()

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

The value of $ipivp$ returned by a previous call to complex_gen_precon_bdilu()

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

The value of $ipivq$ returned by a previous call to complex_gen_precon_bdilu()

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

The value of $istr$ returned by a previous call to complex_gen_precon_bdilu()

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

The value of $idiag$ returned by a previous call to complex_gen_precon_bdilu()

bcomplex, 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.

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

An initial approximation to the solution vector $x$.

Returns

xcomplex, 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 complex_gen_precon_bdilu() and complex_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 complex_gen_precon_bdilu() and complex_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 complex_gen_precon_bdilu() and complex_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 complex_gen_precon_bdilu() and complex_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 complex_gen_precon_bdilu() and complex_gen_solve_bdilu.

(errno $4$)

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

(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

complex_gen_solve_bdilu solves a complex sparse non-Hermitian 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.

complex_gen_solve_bdilu uses the incomplete (possibly overlapping) block $LU$ factorization determined by complex_gen_precon_bdilu() as the preconditioning matrix. A call to complex_gen_solve_bdilu must always be preceded by a call to complex_gen_precon_bdilu(). Alternative preconditioners for the same storage scheme are available by calling complex_gen_solve_ilu() or complex_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 complex_gen_precon_bdilu(). The array $a$ holds the nonzero entries in these matrices, while $irow$ and $icol$ hold the corresponding row and column indices.

complex_gen_solve_bdilu is a Black Box function which calls complex_gen_basic_setup(), complex_gen_basic_solver() and complex_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

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