# Source code for naginterfaces.library.sparse

# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 29.0 sparse Chapter.

sparse - Large Scale Linear Systems

This module provides functions for the solution of large sparse systems of simultaneous linear equations.
These include **iterative** methods for real nonsymmetric and symmetric, complex non-Hermitian and Hermitian linear systems and **direct** methods for general real linear systems.
Further direct methods are currently available in submodule :mod:~naginterfaces.library.matop and submodule :mod:~naginterfaces.library.linsys.

--------
naginterfaces.library.examples.sparse :
This subpackage contains examples for the sparse module.
See also the :ref:library_sparse_ex subsection.

Functionality Index
-------------------

**Basic functions for complex Hermitian linear systems**

diagnostic function: :meth:complex_herm_basic_diag

reverse communication CG or SYMMLQ solver function: :meth:complex_herm_basic_solver

setup function: :meth:complex_herm_basic_setup

**Basic functions for complex non-Hermitian linear systems**

diagnostic function: :meth:complex_gen_basic_diag

reverse communication RGMRES, CGS, Bi-CGSTAB\ :math:\left(\ell \right) or TFQMR solver function: :meth:complex_gen_basic_solver

setup function: :meth:complex_gen_basic_setup

**Basic functions for real nonsymmetric linear systems**

diagnostic function: :meth:real_gen_basic_diag

reverse communication RGMRES, CGS, Bi-CGSTAB\ :math:\left(\ell \right) or TFQMR solver function: :meth:real_gen_basic_solver

setup function: :meth:real_gen_basic_setup

**Basic functions for real symmetric linear systems**

diagnostic function: :meth:real_symm_basic_diag

reverse communication CG or SYMMLQ solver: :meth:real_symm_basic_solver

setup function: :meth:real_symm_basic_setup

**Black Box functions for complex Hermitian linear systems**

CG or SYMMLQ solver

with incomplete Cholesky preconditioning: :meth:complex_herm_solve_ilu

with no preconditioning, Jacobi or SSOR preconditioning: :meth:complex_herm_solve_jacssor

**Black Box functions for complex non-Hermitian linear systems**

RGMRES, CGS, Bi-CGSTAB\ :math:\left(\ell \right) or TFQMR solver

with block Jacobi or additive Schwarz preconditioning: :meth:complex_gen_solve_bdilu

with incomplete :math:LU preconditioning: :meth:complex_gen_solve_ilu

with no preconditioning, Jacobi, or SSOR preconditioning: :meth:complex_gen_solve_jacssor

**Black Box functions for real nonsymmetric linear systems**

RGMRES, CGS, Bi-CGSTAB\ :math:\left(\ell \right) or TFQMR solver

with block Jacobi or additive Schwarz preconditioning: :meth:real_gen_solve_bdilu

with incomplete :math:LU preconditioning: :meth:real_gen_solve_ilu

with no preconditioning, Jacobi, or SSOR preconditioning: :meth:real_gen_solve_jacssor

**Black Box functions for real symmetric linear systems**

CG or SYMMLQ solver

with incomplete Cholesky preconditioning: :meth:real_symm_solve_ichol

with no preconditioning, Jacobi, or SSOR preconditioning: :meth:real_symm_solve_jacssor

**Direct methods for real sparse nonsymmetric linear systems in CCS format**

apply iterative refinement to the solution and compute error estimates, after factorizing the matrix of coefficients: :meth:direct_real_gen_refine

condition number estimation, after factorizing the matrix of coefficients: :meth:direct_real_gen_cond

:math:LU factorization

diagnostic: :meth:direct_real_gen_diag

factorize: :meth:direct_real_gen_lu

setup: :meth:direct_real_gen_setup

solution of simultaneous linear equations, after factorizing the matrix of coefficients: :meth:direct_real_gen_solve

utility

compute a norm or the element of largest absolute value: :meth:direct_real_gen_norm

matrix-matrix multiplier: :meth:direct_real_gen_matmul

**Utility function for complex Hermitian linear systems**

incomplete Cholesky factorization: :meth:complex_herm_precon_ichol

matrix-vector multiplier for complex Hermitian matrices in SCS format: :meth:complex_herm_matvec

solver for linear systems involving preconditioning matrix from :meth:complex_herm_precon_ichol: :meth:complex_herm_precon_ilu_solve

solver for linear systems involving SSOR preconditioning matrix: :meth:complex_herm_precon_ssor_solve

sort function for complex Hermitian matrices in SCS format: :meth:complex_herm_sort

**Utility function for complex linear systems**

solver for linear systems involving iterated Jacobi method: :meth:complex_gen_precon_jacobi

**Utility function for complex non-Hermitian linear systems**

incomplete :math:LU factorization: :meth:complex_gen_precon_ilu

incomplete :math:LU factorization of local or overlapping diagonal blocks: :meth:complex_gen_precon_bdilu

matrix-vector multiplier for complex non-Hermitian matrices in CS format: :meth:complex_gen_matvec

solver for linear systems involving preconditioning matrix from :meth:complex_gen_precon_ilu: :meth:complex_gen_precon_ilu_solve

solver for linear systems involving SSOR preconditioning matrix: :meth:complex_gen_precon_ssor_solve

sort function for complex non-Hermitian matrices in CS format: :meth:complex_gen_sort

**Utility function for real linear systems**

solver for linear systems involving iterated Jacobi method: :meth:real_gen_precon_jacobi

**Utility function for real nonsymmetric linear systems**

incomplete :math:LU factorization: :meth:real_gen_precon_ilu

incomplete :math:LU factorization of local or overlapping diagonal blocks: :meth:real_gen_precon_bdilu

matrix-vector multiplier for real nonsymmetric matrices in CS format: :meth:real_gen_matvec

solver for linear systems involving preconditioning matrix from :meth:real_gen_precon_ilu: :meth:real_gen_precon_ilu_solve

solver for linear systems involving SSOR preconditioning matrix: :meth:real_gen_precon_ssor_solve

sort function for real nonsymmetric matrices in CS format: :meth:real_gen_sort

sort function for real rectangular matrices in CS or CCS format: :meth:real_rect_sort

**Utility function for real symmetric linear systems**

incomplete Cholesky factorization: :meth:real_symm_precon_ichol

matrix-vector multiplier for real symmetric matrices in SCS format: :meth:real_symm_matvec

solver for linear systems involving preconditioning matrix from :meth:real_symm_precon_ichol: :meth:real_symm_precon_ichol_solve

solver for linear systems involving SSOR preconditioning matrix: :meth:real_symm_precon_ssor_solve

sort function for real symmetric matrices in SCS format: :meth:real_symm_sort

Utility function for real symmetric linear systems, compute bandwidth-reducing reverse Cuthill--McKee permutation: :meth:sym_rcm

For full information please refer to the NAG Library document

https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html
"""

[docs]def real_gen_basic_setup(n, method='BICGSTAB', precon='P', norm=None, weight='N', iterm=1, m=None, tol=0.0, maxitn=20, anorm=0.0, sigmax=0.0, monit=0):
r"""
real_gen_basic_setup is a setup function, the first in a suite of three functions for the iterative solution of a real general (nonsymmetric) system of simultaneous linear equations. real_gen_basic_setup must be called before :meth:real_gen_basic_solver, the iterative solver.
The third function in the suite, :meth:real_gen_basic_diag, can be used to return additional information about the computation.

These functions are suitable for the solution of large sparse general (nonsymmetric) systems of equations.

.. _f11bd-py2-py-doc:

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

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

.. _f11bd-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the order of the matrix :math:A.

**method** : str, optional
The iterative method to be used.

:math:\mathrm{method} = \texttt{'RGMRES'}

Restarted generalized minimum residual method.

:math:\mathrm{method} = \texttt{'CGS'}

:math:\mathrm{method} = \texttt{'BICGSTAB'}

Bi-conjugate gradient stabilized (:math:\ell) method.

:math:\mathrm{method} = \texttt{'TFQMR'}

Transpose-free quasi-minimal residual method.

**precon** : str, length 1, optional
Determines whether preconditioning is used.

:math:\mathrm{precon} = \texttt{'N'}

No preconditioning.

:math:\mathrm{precon} = \texttt{'P'}

Preconditioning.

**norm** : None or str, length 1, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:\mathrm{iterm} = 1: :math:{ \texttt{'I'} }; otherwise: :math:{ \texttt{'2'} }.

Defines the matrix and vector norm to be used in the termination criteria.

:math:\mathrm{norm} = \texttt{'1'}

:math:l_1 norm.

:math:\mathrm{norm} = \texttt{'I'}

:math:l_{\infty } norm.

:math:\mathrm{norm} = \texttt{'2'}

:math:l_2 norm.

**weight** : str, length 1, optional
Specifies whether a vector :math:w of user-supplied weights is to be used in the computation of the vector norms required in termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__ (:math:\mathrm{iterm} = 1): :math:\left\lVert v\right\rVert_p^{\left(w\right)} = \left\lVert v^{\left(w\right)}\right\rVert_p, where :math:v_{\textit{i}}^{\left(w\right)} = w_{\textit{i}}v_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n. The suffix :math:p = 1,2,\infty denotes the vector norm used, as specified by the argument :math:\mathrm{norm}. Note that weights cannot be used when :math:\mathrm{iterm} = 2, i.e., when criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne3>__ is used.

:math:\mathrm{weight} = \texttt{'W'}

User-supplied weights are to be used and must be supplied on initial entry to :meth:real_gen_basic_solver.

:math:\mathrm{weight} = \texttt{'N'}

All weights are implicitly set equal to one. Weights do not need to be supplied on initial entry to :meth:real_gen_basic_solver.

**iterm** : int, optional
Defines the termination criterion to be used.

:math:\mathrm{iterm} = 1

Use the termination criterion defined in (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__.

:math:\mathrm{iterm} = 2

Use the termination criterion defined in (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne3>__.

**m** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:\mathrm{method} = \texttt{'RGMRES'}: :math:{ \min\left(\mathrm{n},50\right) }; if :math:\mathrm{method} = \texttt{'BICGSTAB'}: :math:{ \min\left(\mathrm{n},10\right) }; otherwise: :math:{ 0 }.

If :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m} is the dimension :math:m of the restart subspace.

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m} is the order :math:\ell of the polynomial BI-CGSTAB method.

Otherwise, :math:\mathrm{m} is not referenced.

**tol** : float, optional
The tolerance :math:\tau for the termination criterion. If :math:\mathrm{tol}\leq 0.0, \tau = \mathrm{max}\left({\sqrt{\epsilon }}, {\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol}}, {10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int, optional
The maximum number of iterations.

**anorm** : float, optional
If :math:\mathrm{anorm} > 0.0, the value of :math:\left\lVert A\right\rVert_p to be used in the termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__ (:math:\mathrm{iterm} = 1).

If :math:\mathrm{anorm}\leq 0.0, :math:\mathrm{iterm} = 1 and :math:\mathrm{norm} = \texttt{'1'} or :math:\texttt{'I'}, then :math:\left\lVert A\right\rVert_1 = \left\lVert A\right\rVert_\infty is estimated internally by :meth:real_gen_basic_solver.

If :math:\mathrm{iterm} = 2, :math:\mathrm{anorm} is not referenced.

**sigmax** : float, optional
If :math:\mathrm{iterm} = 2, the largest singular value :math:\sigma_1 of the preconditioned iteration matrix; otherwise, :math:\mathrm{sigmax} is not referenced.

If :math:\mathrm{sigmax}\leq 0.0, :math:\mathrm{iterm} = 2 and :math:\mathrm{method} = \texttt{'RGMRES'}, the value of :math:\sigma_1 will be estimated internally.

**monit** : int, optional
If :math:\mathrm{monit} > 0, the frequency at which a monitoring step is executed by :meth:real_gen_basic_solver: if :math:\mathrm{method} = \texttt{'CGS'} or :math:\texttt{'TFQMR'}, a monitoring step is executed every :math:\mathrm{monit} iterations; otherwise, a monitoring step is executed every :math:\mathrm{monit} super-iterations (groups of up to :math:m or :math:\ell iterations for RGMRES or BI-CGSTAB(:math:\ell), respectively).

There are some additional computational costs involved in monitoring the solution and residual vectors when the BI-CGSTAB(:math:\ell) method is used with :math:\ell > 1.

**Returns**
**comm** : dict, communication object
Communication structure.

.. _f11bd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-12)
On entry, :math:\mathrm{monit} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{monit}\leq \mathrm{maxitn}.

(errno :math:-11)
On entry, :math:\mathrm{iterm} = 2, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{sigmax} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2 and :math:\mathrm{method} = \texttt{'CGS'} or :math:\texttt{'BICGSTAB'}, :math:\mathrm{sigmax} > 0.0.

(errno :math:-10)
On entry, :math:\mathrm{iterm} = 1, :math:\mathrm{norm} = \texttt{'2'} and :math:\mathrm{anorm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 1 and :math:\mathrm{norm} = \texttt{'2'}, :math:\mathrm{anorm} > 0.0.

(errno :math:-9)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn} > 0.

(errno :math:-8)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:-7)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{method} = \texttt{'RGMRES'} or :math:\texttt{'BICGSTAB'}, :math:\mathrm{m} > 0.

(errno :math:-7)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m}\leq \mathrm{min}\left(\mathrm{n}, 50\right). If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m}\leq \mathrm{min}\left(\mathrm{n}, 10\right).

(errno :math:-6)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} > 0.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iterm} = 1 or :math:2.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{method} = \texttt{'TFQMR'}.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{method} \neq \texttt{'TFQMR'}.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{norm} = \texttt{'2'}.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{weight} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{weight} = \texttt{'N'}.

(errno :math:-4)
On entry, :math:\mathrm{weight} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{weight} = \texttt{'N'} or :math:\texttt{'W'}.

(errno :math:-3)
On entry, :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{norm} = \texttt{'1'}, :math:\texttt{'I'} or :math:\texttt{'2'}.

(errno :math:-2)
On entry, :math:\mathrm{precon} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{precon} = \texttt{'N'} or :math:\texttt{'P'}.

(errno :math:-1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\texttt{'CGS'}, :math:\texttt{'BICGSTAB'} or :math:\texttt{'TFQMR'}.

(errno :math:1)
real_gen_basic_setup has been called out of sequence: either real_gen_basic_setup has been called twice or :meth:real_gen_basic_solver has not terminated its current task.

.. _f11bd-py2-py-notes:

**Notes**
The suite consisting of the functions real_gen_basic_setup, :meth:real_gen_basic_solver and :meth:real_gen_basic_diag is designed to solve the general (nonsymmetric) system of simultaneous linear equations :math:Ax = b of order :math:n, where :math:n is large and the coefficient matrix :math:A is sparse.

real_gen_basic_setup is a setup function which must be called before :meth:real_gen_basic_solver, the iterative solver.
The third function in the suite, :meth:real_gen_basic_diag, can be used to return additional information about the computation.
A choice of methods is available:

restarted generalized minimum residual method (RGMRES);

bi-conjugate gradient stabilized (:math:\ell) method (BI-CGSTAB(:math:\ell));

transpose-free quasi-minimal residual method (TFQMR).

**Restarted Generalized Minimum Residual Method (RGMRES)**

The restarted generalized minimum residual method (RGMRES) (see Saad and Schultz (1986), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)) starts from the residual :math:r_0 = b-Ax_0, where :math:x_0 is an initial estimate for the solution (often :math:x_0 = 0).
An orthogonal basis for the Krylov subspace :math:\mathrm{span}\left\{A^{\textit{k}}r_0\right\}, for :math:\textit{k} = 0,1,\ldots,, is generated explicitly: this is referred to as Arnoldi's method (see Arnoldi (1951)).
The solution is then expanded onto the orthogonal basis so as to minimize the residual norm :math:\left\lVert b-Ax\right\rVert_2.
The lack of symmetry of :math:A implies that the orthogonal basis is generated by applying a 'long' recurrence relation, whose length increases linearly with the iteration count.
For all but the most trivial problems, computational and storage costs can quickly become prohibitive as the iteration count increases. RGMRES limits these costs by employing a restart strategy: every :math:m iterations at most, the Arnoldi process is restarted from :math:r_l = b-Ax_l, where the subscript :math:l denotes the last available iterate.
Each group of :math:m iterations is referred to as a 'super-iteration'.
The value of :math:m is chosen in advance and is fixed throughout the computation.
Unfortunately, an optimum value of :math:m cannot easily be predicted.

The conjugate gradient squared method (CGS) (see Sonneveld (1989), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)) is a development of the bi-conjugate gradient method where the nonsymmetric Lanczos method is applied to reduce the coefficients matrix to real tridiagonal form: two bi-orthogonal sequences of vectors are generated starting from the residual :math:r_0 = b-Ax_0, where :math:x_0 is an initial estimate for the solution (often :math:x_0 = 0) and from the shadow residual :math:\hat{r}_0 corresponding to the arbitrary problem :math:A^\mathrm{T}\hat{x} = \hat{b}, where :math:\hat{b} can be any vector, but in practice is chosen so that :math:r_0 = \hat{r}_0.
In the course of the iteration, the residual and shadow residual :math:r_i = P_i\left(A\right)r_0 and :math:\hat{r}_i = P_i\left(A^\mathrm{T}\right)\hat{r}_0 are generated, where :math:P_i is a polynomial of order :math:i, and bi-orthogonality is exploited by computing the vector product :math:\rho_i = \left(\hat{r}_i, r_i\right) = \left({P_i\left(A^\mathrm{T}\right)\hat{r}_0}, { P_i\left(A\right)r_0}\right) = \left(\hat{r}_0, {P_i^2\left(A\right)r_0}\right).
Applying the 'contraction' operator :math:P_i\left(A\right) twice, the iteration coefficients can still be recovered without advancing the solution of the shadow problem, which is of no interest.
The CGS method often provides fast convergence; however, there is no reason why the contraction operator should also reduce the once reduced vector :math:P_i\left(A\right)r_0: this may well lead to a highly irregular convergence which may result in large cancellation errors.

**Bi-Conjugate Gradient Stabilized (** :math:\ell **) Method (BI-CGSTAB(** :math:\ell **))**

The bi-conjugate gradient stabilized (:math:\ell) method (BI-CGSTAB(:math:\ell)) (see Van der Vorst (1989), Sleijpen and Fokkema (1993) and Dias da Cunha and Hopkins (1994)) is similar to the CGS method above.
However, instead of generating the sequence :math:\left\{P_i^2\left(A\right)r_0\right\}, it generates the sequence :math:\left\{Q_i\left(A\right)P_i\left(A\right)r_0\right\}, where the :math:Q_i\left(A\right) are polynomials chosen to minimize the residual after the application of the contraction operator :math:P_i\left(A\right).
Two main steps can be identified for each iteration: an OR (Orthogonal Residuals) step where a basis of order :math:\ell is generated by a Bi-CG iteration and an MR (Minimum Residuals) step where the residual is minimized over the basis generated, by a method akin to GMRES.
For :math:\ell = 1, the method corresponds to the BI-CGSTAB method of Van der Vorst (1989).
For :math:\ell > 1, more information about complex eigenvalues of the iteration matrix can be taken into account, and this may lead to improved convergence and robustness.
However, as :math:\ell increases, numerical instabilities may arise.
For this reason, a maximum value of :math:\ell = 10 is imposed, but probably :math:\ell = 4 is sufficient in most cases.

**Transpose-free Quasi-minimal Residual Method (TFQMR)**

The transpose-free quasi-minimal residual method (TFQMR) (see Freund and Nachtigal (1991) and Freund (1993)) is conceptually derived from the CGS method.
The residual is minimized over the space of the residual vectors generated by the CGS iterations under the simplifying assumption that residuals are almost orthogonal.
In practice, this is not the case but theoretical analysis has proved the validity of the method.
This has the effect of remedying the rather irregular convergence behaviour with wild oscillations in the residual norm that can degrade the numerical performance and robustness of the CGS method.
In general, the TFQMR method can be expected to converge at least as fast as the CGS method, in terms of number of iterations, although each iteration involves a higher operation count.
When the CGS method exhibits irregular convergence, the TFQMR method can produce much smoother, almost monotonic convergence curves.
However, the close relationship between the CGS and TFQMR method implies that the overall speed of convergence is similar for both methods.
In some cases, the TFQMR method may converge faster than the CGS method.

**General Considerations**

For each method, a sequence of solution iterates :math:\left\{x_i\right\} is generated such that, hopefully, the sequence of the residual norms :math:\left\{\left\lVert r_i\right\rVert \right\} converges to a required tolerance.
Note that, in general, convergence, when it occurs, is not monotonic.

In the RGMRES and BI-CGSTAB(:math:\ell) methods above, your program must provide the **maximum** number of basis vectors used, :math:m or :math:\ell, respectively; however, a **smaller** number of basis vectors may be generated and used when the stability of the solution process requires this (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#fcomments>__).

Faster convergence can be achieved using a **preconditioner** (see Golub and Van Loan (1996) and Barrett et al. (1994)).
A preconditioner maps the original system of equations onto a different system, say

.. math::
\bar{A}\bar{x} = \bar{b}\text{,}

with, hopefully, better characteristics with respect to its speed of convergence: for example, the condition number of the coefficients matrix can be improved or eigenvalues in its spectrum can be made to coalesce.
An orthogonal basis for the Krylov subspace :math:\mathrm{span}\left\{\bar{A}^{\textit{k}}\bar{r}_0\right\}, for :math:\textit{k} = 0,1,\ldots,, is generated and the solution proceeds as outlined above.
The algorithms used are such that the solution and residual iterates of the original system are produced, not their preconditioned counterparts.
Note that an unsuitable preconditioner or no preconditioning at all may result in a very slow rate, or lack, of convergence.
However, preconditioning involves a trade-off between the reduction in the number of iterations required for convergence and the additional computational costs per iteration.
Also, setting up a preconditioner may involve non-negligible overheads.

A left preconditioner :math:M^{-1} can be used by the RGMRES, CGS and TFQMR methods, such that :math:\bar{A} = M^{-1}A\sim I_n in (1) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne1>__, where :math:I_n is the identity matrix of order :math:n; a right preconditioner :math:M^{-1} can be used by the BI-CGSTAB(:math:\ell) method, such that :math:\bar{A} = AM^{-1}\sim I_n.
These are formal definitions, used only in the design of the algorithms; in practice, only the means to compute the matrix--vector products :math:v = Au and :math:v = A^\mathrm{T}u (the latter only being required when an estimate of :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty is computed internally), and to solve the preconditioning equations :math:Mv = u are required, i.e., explicit information about :math:M, or its inverse is not required at any stage.

The first termination criterion

.. math::
\left\lVert r_k\right\rVert_p\leq \tau \left({\left\lVert b\right\rVert_p+\left\lVert A\right\rVert_p}\times {\left\lVert x_k\right\rVert_p}\right)

is available for all four methods.
In (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__, :math:p = 1, :math:\infty \text{ or }2 and :math:\tau denotes a user-specified tolerance subject to :math:\mathrm{max}\left(10, {\sqrt{n}}\right), :math:\epsilon \leq \tau < 1, where :math:\epsilon is the machine precision.
Facilities are provided for the estimation of the norm of the coefficients matrix :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty, when this is not known in advance, by applying Higham's method (see Higham (1988)).
Note that :math:\left\lVert A\right\rVert_2 cannot be estimated internally.
This criterion uses an error bound derived from **backward** error analysis to ensure that the computed solution is the exact solution of a problem as close to the original as the termination tolerance requires.
Termination criteria employing bounds derived from **forward** error analysis are not used because any such criteria would require information about the condition number :math:\kappa \left(A\right) which is not easily obtainable.

The second termination criterion

.. math::
\left\lVert \bar{r}_k\right\rVert_2\leq \tau \left({\left\lVert \bar{r}_0\right\rVert_2+\sigma_1\left(\bar{A}\right)}\times {\left\lVert \Delta \bar{x}_k\right\rVert_2}\right)

is available for all methods except TFQMR.
In (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne3>__, :math:\sigma_1\left(\bar{A}\right) = \left\lVert \bar{A}\right\rVert_2 is the largest singular value of the (preconditioned) iteration matrix :math:\bar{A}.
This termination criterion monitors the progress of the solution of the preconditioned system of equations and is less expensive to apply than criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__ for the BI-CGSTAB(:math:\ell) method with :math:\ell > 1.
Only the RGMRES method provides facilities to estimate :math:\sigma_1\left(\bar{A}\right) internally, when this is not supplied (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#fcomments>__).

Termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__ is the recommended choice, despite its additional costs per iteration when using the BI-CGSTAB(:math:\ell) method with :math:\ell > 1.
Also, if the norm of the initial estimate is much larger than the norm of the solution, that is, if :math:\left\lVert x_0\right\rVert ≫\left\lVert x\right\rVert, a dramatic loss of significant digits could result in complete lack of convergence.
The use of criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__ will enable the detection of such a situation, and the iteration will be restarted at a suitable point.
No such restart facilities are provided for criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne3>__.

Optionally, a vector :math:w of user-specified weights can be used in the computation of the vector norms in termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__, i.e., :math:\left\lVert v\right\rVert_p^{\left(w\right)} = \left\lVert v^{\left(w\right)}\right\rVert_p, where :math:{\left(v^{\left(w\right)}\right)}_{\textit{i}} = w_{\textit{i}}v_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n.
Note that the use of weights increases the computational costs.

The sequence of calls to the functions comprising the suite is enforced: first, the setup function real_gen_basic_setup must be called, followed by the solver :meth:real_gen_basic_solver. :meth:real_gen_basic_diag can be called either when :meth:real_gen_basic_solver is carrying out a monitoring step or after :meth:real_gen_basic_solver has completed its tasks.
Incorrect sequencing will raise an error condition.

In general, it is not possible to recommend one method in preference to another. RGMRES is often used in the solution of systems arising from PDEs.
On the other hand, it can easily stagnate when the size :math:m of the orthogonal basis is too small, or the preconditioner is not good enough. CGS can be the fastest method, but the computed residuals can exhibit instability which may greatly affect the convergence and quality of the solution. BI-CGSTAB(:math:\ell) seems robust and reliable, but it can be slower than the other methods: if a preconditioner is used and :math:\ell > 1, BI-CGSTAB(:math:\ell) computes the solution of the preconditioned system :math:\bar{x}_k = Mx_k: the preconditioning equations must be solved to obtain the required solution.
The algorithm employed limits to :math:10\% or less, when no intermediate monitoring is requested, the number of times the preconditioner has to be thus applied compared with the total number of applications of the preconditioner. TFQMR can be viewed as a more robust variant of the CGS method: it shares the CGS method speed but avoids the CGS fluctuations in the residual, which may give rise to instability.
Also, when the termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11bdf.html#eqne2>__ is used, the CGS, BI-CGSTAB(:math:\ell) and TFQMR methods will restart the iteration automatically when necessary in order to solve the given problem.

.. _f11bd-py2-py-references:

**References**
Arnoldi, W, 1951, The principle of minimized iterations in the solution of the matrix eigenvalue problem, Quart. Appl. Math. (9), 17--29

Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Dias da Cunha, R and Hopkins, T, 1994, PIM 1.1 --- the parallel iterative method package for systems of linear equations user's guide --- Fortran 77 version, Technical Report, Computing Laboratory, University of Kent at Canterbury, Kent, UK

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

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

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 :math:\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

--------
:meth:naginterfaces.library.examples.sparse.real_gen_basic_solver_ex.main
"""
raise NotImplementedError

[docs]def real_gen_basic_solver(irevcm, u, v, comm, wgt=None):
r"""
real_gen_basic_solver is an iterative solver for a real general (nonsymmetric) system of simultaneous linear equations; real_gen_basic_solver is the second in a suite of three functions, where the first function, :meth:real_gen_basic_setup, must be called prior to real_gen_basic_solver to set up the suite, and the third function in the suite, :meth:real_gen_basic_diag, can be used to return additional information about the computation.

These functions are suitable for the solution of large sparse general (nonsymmetric) systems of equations.

.. _f11be-py2-py-doc:

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

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

.. _f11be-py2-py-parameters:

**Parameters**
**irevcm** : int
On initial entry: :math:\mathrm{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.

:math:\mathrm{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. real_gen_basic_solver will then return with the termination code :math:\mathrm{irevcm} = 4. Note that before calling real_gen_basic_solver with :math:\mathrm{irevcm} = 5 the calling program must have performed the tasks required by the value of :math:\mathrm{irevcm} returned by the previous call to real_gen_basic_solver, otherwise subsequently returned values may be invalid.

:math:\mathrm{irevcm} = 6

Immediate termination: real_gen_basic_solver will return immediately with termination code :math:\mathrm{irevcm} = 4 and with any useful information available. This includes the last iterate of the solution. The residual vector is generally not available.

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

Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

**u** : float, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: an initial estimate, :math:x_0, of the solution of the system of equations :math:Ax = b.

On intermediate entry: must remain unchanged.

On intermediate exit: the returned value of :math:\mathrm{irevcm} determines the contents of :math:\mathrm{u} in the following way:

if :math:\mathrm{irevcm} = -1, :math:1 or :math:2, :math:\mathrm{u} holds the vector :math:u on which the operation specified by :math:\mathrm{irevcm} is to be carried out;

if :math:\mathrm{irevcm} = 3, :math:\mathrm{u} holds the current iterate of the solution vector.

On final exit: if :math:\mathrm{errno} = 3 or :math:\mathrm{errno} < 0, the array :math:\mathrm{u} is unchanged from the initial entry to real_gen_basic_solver.

If :math:\mathrm{errno} = 1, the array :math:\mathrm{u} is unchanged from the last entry to real_gen_basic_solver.

Otherwise, :math:\mathrm{u} holds the last available iterate of the solution of the system of equations, for all returned values of :math:\textit{errno}.

**v** : float, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: the right-hand side :math:b of the system of equations :math:Ax = b.

On intermediate entry: the returned value of :math:\mathrm{irevcm} determines the contents of :math:\mathrm{v} in the following way:

if :math:\mathrm{irevcm} = -1, :math:1 or :math:2, :math:\mathrm{v} must store the vector :math:v, the result of the operation specified by the value of :math:\mathrm{irevcm} returned by the previous call to real_gen_basic_solver;

if :math:\mathrm{irevcm} = 3, :math:\mathrm{v} must remain unchanged.

On intermediate exit: if :math:\mathrm{irevcm} = 3, :math:\mathrm{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 :math:\mathrm{errno} = 3 or :math:\mathrm{errno} < 0, the array :math:\mathrm{v} is unchanged from the initial entry to real_gen_basic_solver.

If :math:\mathrm{errno} = 1, the array :math:\mathrm{v} is unchanged from the last entry to real_gen_basic_solver.

If the function exits successfully or :math:\mathrm{errno} = 2, the array :math:\mathrm{v} contains the true residual vector of the system of equations (see also :ref:Exceptions <f11be-py2-py-errors>).

Otherwise, :math:\mathrm{v} stores the last available iterate of the residual vector unless :math:\mathrm{errno} = 8 is returned on last entry, in which case :math:\mathrm{v} is set to :math:0.0.

**comm** : dict, communication object, modified in place
Communication structure.

This argument must have been initialized by a prior call to :meth:real_gen_basic_setup.

**wgt** : None or float, array-like, shape :math:\left(\textit{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 :ref:Notes for real_gen_basic_setup <f11bd-py2-py-notes> and :ref:Parameters for real_gen_basic_setup <f11bd-py2-py-parameters>).

**Returns**
**irevcm** : int
On intermediate exit: has the following meanings.

:math:\mathrm{irevcm} = -1

The calling program must compute the matrix-vector product :math:v = A^\mathrm{T}u, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively; RGMRES, CGS and BI-CGSTAB(:math:\ell) methods return :math:\mathrm{irevcm} = -1 only if the matrix norm :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty is estimated internally using Higham's method. This can only happen if :math:{\textit{iterm}} = 1 in :meth:real_gen_basic_setup.

:math:\mathrm{irevcm} = 1

The calling program must compute the matrix-vector product :math:v = Au, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively.

:math:\mathrm{irevcm} = 2

The calling program must solve the preconditioning equation :math:Mv = u, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively.

:math:\mathrm{irevcm} = 3

Monitoring step: the solution and residual at the current iteration are returned in the arrays :math:\mathrm{u} and :math:\mathrm{v}, respectively. No action by the calling program is required. :meth:real_gen_basic_diag can be called at this step to return additional information.

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

.. _f11be-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On intermediate re-entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: either :math:\mathrm{irevcm} must be unchanged from its previous exit value or :math:\mathrm{irevcm} = 5 or :math:6.

(errno :math:-1)
On initial entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irevcm} = 0.

(errno :math:3)
Either :meth:real_gen_basic_setup was not called before calling real_gen_basic_solver or it has returned an error.

**Warns**
**NagAlgorithmicWarning**
(errno :math:1)
real_gen_basic_solver has already completed its tasks. You need to set a new problem.

(errno :math:2)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

(errno :math:2)
User-requested tidy termination. The required accuracy has not been achieved. However, a reasonable accuracy may have been achieved.

(errno :math:4)
User-requested tidy termination. The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
Algorithm breakdown at iteration no. :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:8)
User-requested immediate termination.

(errno :math:10)
The weights in array :math:\mathrm{wgt} are all zero.

.. _f11be-py2-py-notes:

**Notes**
real_gen_basic_solver solves the general (nonsymmetric) system of linear simultaneous equations :math:Ax = b of order :math:\textit{n}, where :math:\textit{n} is large and the coefficient matrix :math: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(:math:\ell), the bi-conjugate gradient stabilized method of order :math:\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 :ref:Notes for real_gen_basic_setup <f11bd-py2-py-notes>.

real_gen_basic_solver can solve the system after the first function in the suite, :meth:real_gen_basic_setup, has been called to initialize the computation and specify the method of solution.
The third function in the suite, :meth:real_gen_basic_diag, can be used to return additional information generated by the computation, during monitoring steps and after real_gen_basic_solver has completed its tasks.

real_gen_basic_solver uses **reverse communication**, i.e., it returns repeatedly to the calling program with the argument :math:\mathrm{irevcm} (see :ref:Parameters <f11be-py2-py-parameters>) set to specified values which require the calling program to carry out one of the following tasks:

-   compute the matrix-vector product :math:v = Au or :math:v = A^\mathrm{T}u (the four methods require the matrix transpose-vector product only if :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty is estimated internally by Higham's method (see Higham (1988)));

-   solve the preconditioning equation :math:Mv = u;

-   notify the completion of the computation;

-   allow the calling program to monitor the solution.

Through the argument :math:\mathrm{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.

(#) 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.

.. _f11be-py2-py-references:

**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 :math:\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

--------
:meth:naginterfaces.library.examples.sparse.real_gen_basic_solver_ex.main
"""
raise NotImplementedError

[docs]def real_gen_basic_diag(comm):
r"""
real_gen_basic_diag is the third in a suite of three functions for the iterative solution of a real general (nonsymmetric) system of simultaneous linear equations (see Golub and Van Loan (1996)). real_gen_basic_diag returns information about the computations during an iteration and/or after this has been completed.
The first function of the suite, :meth:real_gen_basic_setup, is a setup function; the second function, :meth:real_gen_basic_solver, is the iterative solver itself.

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

.. _f11bf-py2-py-doc:

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

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

.. _f11bf-py2-py-parameters:

**Parameters**
**comm** : dict, communication object
Communication structure.

This argument must have been initialized by a prior call to :meth:real_gen_basic_setup.

**Returns**
**itn** : int
The number of iterations carried out by :meth:real_gen_basic_solver.

**stplhs** : float
The current value of the left-hand side of the termination criterion used by :meth:real_gen_basic_solver.

**stprhs** : float
The current value of the right-hand side of the termination criterion used by :meth:real_gen_basic_solver.

**anorm** : float
If :math:{\textit{iterm}} = 1 in the previous call to :meth:real_gen_basic_setup, then :math:\mathrm{anorm} contains :math:\left\lVert A\right\rVert_p, where :math:p = 1, :math:2 or :math:\infty, either supplied or, in the case of :math:1 or :math:\infty, estimated by :meth:real_gen_basic_solver; otherwise :math:\mathrm{anorm} = 0.0.

**sigmax** : float
If :math:{\textit{iterm}} = 2 in the previous call to :meth:real_gen_basic_setup, the current estimate of the largest singular value :math:\sigma_1\left(\bar{A}\right) of the preconditioned iteration matrix, either when it has been supplied to :meth:real_gen_basic_setup or it has been estimated by :meth:real_gen_basic_solver (see also :ref:Notes for real_gen_basic_setup <f11bd-py2-py-notes> and :ref:Parameters for real_gen_basic_setup <f11bd-py2-py-parameters>); otherwise, :math:\mathrm{sigmax} = 0.0 is returned.

.. _f11bf-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
real_gen_basic_diag has been called out of sequence.

.. _f11bf-py2-py-notes:

**Notes**
real_gen_basic_diag returns information about the solution process.
It can be called either during a monitoring step of :meth:real_gen_basic_solver or after :meth:real_gen_basic_solver has completed its tasks.
Calling real_gen_basic_diag at any other time will result in an error condition being raised.

For further information you should read the documentation for :meth:real_gen_basic_setup and :meth:real_gen_basic_solver.

.. _f11bf-py2-py-references:

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

--------
:meth:naginterfaces.library.examples.sparse.real_gen_basic_solver_ex.main
"""
raise NotImplementedError

[docs]def complex_gen_basic_setup(n, method='BICGSTAB', precon='P', norm=None, weight='N', iterm=1, m=None, tol=0.0, maxitn=20, anorm=0.0, sigmax=0.0, monit=0):
r"""
complex_gen_basic_setup is a setup function, the first in a suite of three functions for the iterative solution of a complex general (non-Hermitian) system of simultaneous linear equations. complex_gen_basic_setup must be called before :meth:complex_gen_basic_solver, the iterative solver.
The third function in the suite, :meth: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.

.. _f11br-py2-py-doc:

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

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

.. _f11br-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the order of the matrix :math:A.

**method** : str, optional
The iterative method to be used.

:math:\mathrm{method} = \texttt{'RGMRES'}

Restarted generalized minimum residual method.

:math:\mathrm{method} = \texttt{'CGS'}

:math:\mathrm{method} = \texttt{'BICGSTAB'}

Bi-conjugate gradient stabilized (:math:\ell) method.

:math:\mathrm{method} = \texttt{'TFQMR'}

Transpose-free quasi-minimal residual method.

**precon** : str, length 1, optional
Determines whether preconditioning is used.

:math:\mathrm{precon} = \texttt{'N'}

No preconditioning.

:math:\mathrm{precon} = \texttt{'P'}

Preconditioning.

**norm** : None or str, length 1, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:\mathrm{iterm} = 1: :math:{ \texttt{'I'} }; otherwise: :math:{ \texttt{'2'} }.

Defines the matrix and vector norm to be used in the termination criteria.

:math:\mathrm{norm} = \texttt{'1'}

:math:l_1 norm.

:math:\mathrm{norm} = \texttt{'I'}

:math:l_{\infty } norm.

:math:\mathrm{norm} = \texttt{'2'}

:math:l_2 norm.

**weight** : str, length 1, optional
Specifies whether a vector :math:w of user-supplied weights is to be used in the computation of the vector norms required in termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__ (:math:\mathrm{iterm} = 1): :math:\left\lVert v\right\rVert_p^{\left(w\right)} = \left\lVert v^{\left(w\right)}\right\rVert_p, where :math:v_{\textit{i}}^{\left(w\right)} = w_{\textit{i}}v_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n. The suffix :math:p = 1,2,\infty denotes the vector norm used, as specified by the argument :math:\mathrm{norm}. Note that weights cannot be used when :math:\mathrm{iterm} = 2, i.e., when criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne3>__ is used.

:math:\mathrm{weight} = \texttt{'W'}

User-supplied weights are to be used and must be supplied on initial entry to :meth:complex_gen_basic_solver.

:math:\mathrm{weight} = \texttt{'N'}

All weights are implicitly set equal to one. Weights do not need to be supplied on initial entry to :meth:complex_gen_basic_solver.

**iterm** : int, optional
Defines the termination criterion to be used.

:math:\mathrm{iterm} = 1

Use the termination criterion defined in (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__.

:math:\mathrm{iterm} = 2

Use the termination criterion defined in (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne3>__.

**m** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:\mathrm{method} = \texttt{'RGMRES'}: :math:{ \min\left(\mathrm{n},50\right) }; if :math:\mathrm{method} = \texttt{'BICGSTAB'}: :math:{ \min\left(\mathrm{n},10\right) }; otherwise: :math:{ 0 }.

If :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m} is the dimension :math:m of the restart subspace.

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m} is the order :math:\ell of the polynomial BI-CGSTAB method.

Otherwise, :math:\mathrm{m} is not referenced.

**tol** : float, optional
The tolerance :math:\tau for the termination criterion. If :math:\mathrm{tol}\leq 0.0, \tau = \mathrm{max}\left({\sqrt{\epsilon }}, {\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol}}, {10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int, optional
The maximum number of iterations.

**anorm** : float, optional
If :math:\mathrm{anorm} > 0.0, the value of :math:\left\lVert A\right\rVert_p to be used in the termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__ (:math:\mathrm{iterm} = 1).

If :math:\mathrm{anorm}\leq 0.0, :math:\mathrm{iterm} = 1 and :math:\mathrm{norm} = \texttt{'1'} or :math:\texttt{'I'}, then :math:\left\lVert A\right\rVert_1 = \left\lVert A\right\rVert_\infty is estimated internally by :meth:complex_gen_basic_solver.

If :math:\mathrm{iterm} = 2, :math:\mathrm{anorm} is not referenced.

**sigmax** : float, optional
If :math:\mathrm{iterm} = 2, the largest singular value :math:\sigma_1 of the preconditioned iteration matrix; otherwise, :math:\mathrm{sigmax} is not referenced.

If :math:\mathrm{sigmax}\leq 0.0, :math:\mathrm{iterm} = 2 and :math:\mathrm{method} = \texttt{'RGMRES'}, the value of :math:\sigma_1 will be estimated internally.

**monit** : int, optional
If :math:\mathrm{monit} > 0, the frequency at which a monitoring step is executed by :meth:complex_gen_basic_solver: if :math:\mathrm{method} = \texttt{'CGS'} or :math:\texttt{'TFQMR'}, a monitoring step is executed every :math:\mathrm{monit} iterations; otherwise, a monitoring step is executed every :math:\mathrm{monit} super-iterations (groups of up to :math:m or :math:\ell iterations for RGMRES or BI-CGSTAB(:math:\ell), respectively).

There are some additional computational costs involved in monitoring the solution and residual vectors when the BI-CGSTAB(:math:\ell) method is used with :math:\ell > 1.

**Returns**
**comm** : dict, communication object
Communication structure.

.. _f11br-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-12)
On entry, :math:\mathrm{monit} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{monit}\leq \mathrm{maxitn}.

(errno :math:-11)
On entry, :math:\mathrm{iterm} = 2, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{sigmax} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2 and :math:\mathrm{method} = \texttt{'CGS'} or :math:\texttt{'BICGSTAB'}, :math:\mathrm{sigmax} > 0.0.

(errno :math:-10)
On entry, :math:\mathrm{iterm} = 1, :math:\mathrm{norm} = \texttt{'2'} and :math:\mathrm{anorm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 1 and :math:\mathrm{norm} = \texttt{'2'}, :math:\mathrm{anorm} > 0.0.

(errno :math:-9)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn} > 0.

(errno :math:-8)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:-7)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m}\leq \mathrm{min}\left(\mathrm{n}, 50\right). If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m}\leq \mathrm{min}\left(\mathrm{n}, 10\right).

(errno :math:-7)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{method} = \texttt{'RGMRES'} or :math:\texttt{'BICGSTAB'}, :math:\mathrm{m} > 0.

(errno :math:-6)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} > 0.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{method} = \texttt{'TFQMR'}.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{method} \neq \texttt{'TFQMR'}.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{norm} = \texttt{'2'}.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{weight} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{weight} = \texttt{'N'}.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iterm} = 1 or :math:2.

(errno :math:-4)
On entry, :math:\mathrm{weight} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{weight} = \texttt{'N'} or :math:\texttt{'W'}.

(errno :math:-3)
On entry, :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{norm} = \texttt{'1'}, :math:\texttt{'I'} or :math:\texttt{'2'}.

(errno :math:-2)
On entry, :math:\mathrm{precon} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{precon} = \texttt{'N'} or :math:\texttt{'P'}.

(errno :math:-1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\texttt{'CGS'}, :math:\texttt{'BICGSTAB'} or :math:\texttt{'TFQMR'}.

(errno :math:1)
complex_gen_basic_setup has been called out of sequence: either complex_gen_basic_setup has been called twice or :meth:complex_gen_basic_solver has not terminated its current task.

.. _f11br-py2-py-notes:

**Notes**
The suite consisting of the functions complex_gen_basic_setup, :meth:complex_gen_basic_solver and :meth:complex_gen_basic_diag is designed to solve the general (non-Hermitian) system of simultaneous linear equations :math:Ax = b of order :math:n, where :math:n is large and the coefficient matrix :math:A is sparse.

complex_gen_basic_setup is a setup function which must be called before :meth:complex_gen_basic_solver, the iterative solver.
The third function in the suite, :meth:complex_gen_basic_diag, can be used to return additional information about the computation.
A choice of methods is available:

restarted generalized minimum residual method (RGMRES);

bi-conjugate gradient stabilized (:math:\ell) method (BI-CGSTAB(:math:\ell));

transpose-free quasi-minimal residual method (TFQMR).

**Restarted Generalized Minimum Residual Method (RGMRES)**

The restarted generalized minimum residual method (RGMRES) (see Saad and Schultz (1986), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)) starts from the residual :math:r_0 = b-Ax_0, where :math:x_0 is an initial estimate for the solution (often :math:x_0 = 0).
An orthogonal basis for the Krylov subspace :math:\mathrm{span}\left\{A^{\textit{k}}r_0\right\}, for :math:\textit{k} = 0,1,\ldots,, is generated explicitly: this is referred to as Arnoldi's method (see Arnoldi (1951)).
The solution is then expanded onto the orthogonal basis so as to minimize the residual norm :math:\left\lVert b-Ax\right\rVert_2.
The lack of symmetry of :math:A implies that the orthogonal basis is generated by applying a 'long' recurrence relation, whose length increases linearly with the iteration count.
For all but the most trivial problems, computational and storage costs can quickly become prohibitive as the iteration count increases. RGMRES limits these costs by employing a restart strategy: every :math:m iterations at most, the Arnoldi process is restarted from :math:r_l = b-Ax_l, where the subscript :math:l denotes the last available iterate.
Each group of :math:m iterations is referred to as a 'super-iteration'.
The value of :math:m is chosen in advance and is fixed throughout the computation.
Unfortunately, an optimum value of :math:m cannot easily be predicted.

The conjugate gradient squared method (CGS) (see Sonneveld (1989), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)) is a development of the bi-conjugate gradient method where the nonsymmetric Lanczos method is applied to reduce the coefficients matrix to tridiagonal form: two bi-orthogonal sequences of vectors are generated starting from the residual :math:r_0 = b-Ax_0, where :math:x_0 is an initial estimate for the solution (often :math:x_0 = 0) and from the shadow residual :math:\hat{r}_0 corresponding to the arbitrary problem :math:A^\mathrm{H}\hat{x} = \hat{b}, where :math:\hat{b} can be any vector, but in practice is chosen so that :math:r_0 = \hat{r}_0.
In the course of the iteration, the residual and shadow residual :math:r_i = P_i\left(A\right)r_0 and :math:\hat{r}_i = P_i\left(A^\mathrm{H}\right)\hat{r}_0 are generated, where :math:P_i is a polynomial of order :math:i, and bi-orthogonality is exploited by computing the vector product :math:\rho_i = \left(\hat{r}_i, r_i\right) = \left({P_i\left(A^\mathrm{H}\right)\hat{r}_0}, { P_i\left(A\right)r_0}\right) = \left(\hat{r}_0, {P_i^2\left(A\right)r_0}\right).
Applying the 'contraction' operator :math:P_i\left(A\right) twice, the iteration coefficients can still be recovered without advancing the solution of the shadow problem, which is of no interest.
The CGS method often provides fast convergence; however, there is no reason why the contraction operator should also reduce the once reduced vector :math:P_i\left(A\right)r_0: this may well lead to a highly irregular convergence which may result in large cancellation errors.

**Bi-Conjugate Gradient Stabilized (** :math:\ell **) Method (BI-CGSTAB(** :math:\ell **))**

The bi-conjugate gradient stabilized (:math:\ell) method (BI-CGSTAB(:math:\ell)) (see Van der Vorst (1989), Sleijpen and Fokkema (1993) and Dias da Cunha and Hopkins (1994)) is similar to the CGS method above.
However, instead of generating the sequence :math:\left\{P_i^2\left(A\right)r_0\right\}, it generates the sequence :math:\left\{Q_i\left(A\right)P_i\left(A\right)r_0\right\}, where the :math:Q_i\left(A\right) are polynomials chosen to minimize the residual after the application of the contraction operator :math:P_i\left(A\right).
Two main steps can be identified for each iteration: an OR (Orthogonal Residuals) step where a basis of order :math:\ell is generated by a Bi-CG iteration and an MR (Minimum Residuals) step where the residual is minimized over the basis generated, by a method akin to GMRES.
For :math:\ell = 1, the method corresponds to the BI-CGSTAB method of Van der Vorst (1989).
For :math:\ell > 1, more information about complex eigenvalues of the iteration matrix can be taken into account, and this may lead to improved convergence and robustness.
However, as :math:\ell increases, numerical instabilities may arise.
For this reason, a maximum value of :math:\ell = 10 is imposed, but probably :math:\ell = 4 is sufficient in most cases.

**Transpose-free Quasi-minimal Residual Method (TFQMR)**

The transpose-free quasi-minimal residual method (TFQMR) (see Freund and Nachtigal (1991) and Freund (1993)) is conceptually derived from the CGS method.
The residual is minimized over the space of the residual vectors generated by the CGS iterations under the simplifying assumption that residuals are almost orthogonal.
In practice, this is not the case but theoretical analysis has proved the validity of the method.
This has the effect of remedying the rather irregular convergence behaviour with wild oscillations in the residual norm that can degrade the numerical performance and robustness of the CGS method.
In general, the TFQMR method can be expected to converge at least as fast as the CGS method, in terms of number of iterations, although each iteration involves a higher operation count.
When the CGS method exhibits irregular convergence, the TFQMR method can produce much smoother, almost monotonic convergence curves.
However, the close relationship between the CGS and TFQMR method implies that the overall speed of convergence is similar for both methods.
In some cases, the TFQMR method may converge faster than the CGS method.

**General Considerations**

For each method, a sequence of solution iterates :math:\left\{x_i\right\} is generated such that, hopefully, the sequence of the residual norms :math:\left\{\left\lVert r_i\right\rVert \right\} converges to a required tolerance.
Note that, in general, convergence, when it occurs, is not monotonic.

In the RGMRES and BI-CGSTAB(:math:\ell) methods above, your program must provide the **maximum** number of basis vectors used, :math:m or :math:\ell, respectively; however, a **smaller** number of basis vectors may be generated and used when the stability of the solution process requires this (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#fcomments>__).

Faster convergence can be achieved using a **preconditioner** (see Golub and Van Loan (1996) and Barrett et al. (1994)).
A preconditioner maps the original system of equations onto a different system, say

.. math::
\bar{A}\bar{x} = \bar{b}\text{,}

with, hopefully, better characteristics with respect to its speed of convergence: for example, the condition number of the coefficients matrix can be improved or eigenvalues in its spectrum can be made to coalesce.
An orthogonal basis for the Krylov subspace :math:\mathrm{span}\left\{\bar{A}^{\textit{k}}\bar{r}_0\right\}, for :math:\textit{k} = 0,1,\ldots,, is generated and the solution proceeds as outlined above.
The algorithms used are such that the solution and residual iterates of the original system are produced, not their preconditioned counterparts.
Note that an unsuitable preconditioner or no preconditioning at all may result in a very slow rate, or lack, of convergence.
However, preconditioning involves a trade-off between the reduction in the number of iterations required for convergence and the additional computational costs per iteration.
Also, setting up a preconditioner may involve non-negligible overheads.

A left preconditioner :math:M^{-1} can be used by the RGMRES, CGS and TFQMR methods, such that :math:\bar{A} = M^{-1}A\sim I_n in (1) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne1>__, where :math:I_n is the identity matrix of order :math:n; a right preconditioner :math:M^{-1} can be used by the BI-CGSTAB(:math:\ell) method, such that :math:\bar{A} = AM^{-1}\sim I_n.
These are formal definitions, used only in the design of the algorithms; in practice, only the means to compute the matrix--vector products :math:v = Au and :math:v = A^\mathrm{H}u (the latter only being required when an estimate of :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty is computed internally), and to solve the preconditioning equations :math:Mv = u are required, i.e., explicit information about :math:M, or its inverse is not required at any stage.

The first termination criterion

.. math::
\left\lVert r_k\right\rVert_p\leq \tau \left({\left\lVert b\right\rVert_p+\left\lVert A\right\rVert_p}\times {\left\lVert x_k\right\rVert_p}\right)

is available for all four methods.
In (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__, :math:p = 1, :math:\infty \text{ or }2 and :math:\tau denotes a user-specified tolerance subject to :math:\mathrm{max}\left(10, {\sqrt{n}}\right), :math:\epsilon \leq \tau < 1, where :math:\epsilon is the machine precision.
Facilities are provided for the estimation of the norm of the coefficients matrix :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty, when this is not known in advance, by applying Higham's method (see Higham (1988)).
Note that :math:\left\lVert A\right\rVert_2 cannot be estimated internally.
This criterion uses an error bound derived from **backward** error analysis to ensure that the computed solution is the exact solution of a problem as close to the original as the termination tolerance requires.
Termination criteria employing bounds derived from **forward** error analysis are not used because any such criteria would require information about the condition number :math:\kappa \left(A\right) which is not easily obtainable.

The second termination criterion

.. math::
\left\lVert \bar{r}_k\right\rVert_2\leq \tau \left({\left\lVert \bar{r}_0\right\rVert_2+\sigma_1\left(\bar{A}\right)}\times {\left\lVert \Delta \bar{x}_k\right\rVert_2}\right)

is available for all methods except TFQMR.
In (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne3>__, :math:\sigma_1\left(\bar{A}\right) = \left\lVert \bar{A}\right\rVert_2 is the largest singular value of the (preconditioned) iteration matrix :math:\bar{A}.
This termination criterion monitors the progress of the solution of the preconditioned system of equations and is less expensive to apply than criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__ for the BI-CGSTAB(:math:\ell) method with :math:\ell > 1.
Only the RGMRES method provides facilities to estimate :math:\sigma_1\left(\bar{A}\right) internally, when this is not supplied (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#fcomments>__).

Termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__ is the recommended choice, despite its additional costs per iteration when using the BI-CGSTAB(:math:\ell) method with :math:\ell > 1.
Also, if the norm of the initial estimate is much larger than the norm of the solution, that is, if :math:\left\lVert x_0\right\rVert ≫\left\lVert x\right\rVert, a dramatic loss of significant digits could result in complete lack of convergence.
The use of criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__ will enable the detection of such a situation, and the iteration will be restarted at a suitable point.
No such restart facilities are provided for criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne3>__.

Optionally, a vector :math:w of user-specified weights can be used in the computation of the vector norms in termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__, i.e., :math:\left\lVert v\right\rVert_p^{\left(w\right)} = \left\lVert v^{\left(w\right)}\right\rVert_p, where :math:{\left(v^{\left(w\right)}\right)}_{\textit{i}} = w_{\textit{i}}v_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n.
Note that the use of weights increases the computational costs.

The sequence of calls to the functions comprising the suite is enforced: first, the setup function complex_gen_basic_setup must be called, followed by the solver :meth:complex_gen_basic_solver. :meth:complex_gen_basic_diag can be called either when :meth:complex_gen_basic_solver is carrying out a monitoring step or after :meth:complex_gen_basic_solver has completed its tasks.
Incorrect sequencing will raise an error condition.

In general, it is not possible to recommend one method in preference to another. RGMRES is often used in the solution of systems arising from PDEs.
On the other hand, it can easily stagnate when the size :math:m of the orthogonal basis is too small, or the preconditioner is not good enough. CGS can be the fastest method, but the computed residuals can exhibit instability which may greatly affect the convergence and quality of the solution. BI-CGSTAB(:math:\ell) seems robust and reliable, but it can be slower than the other methods: if a preconditioner is used and :math:\ell > 1, BI-CGSTAB(:math:\ell) computes the solution of the preconditioned system :math:\bar{x}_k = Mx_k: the preconditioning equations must be solved to obtain the required solution.
The algorithm employed limits to :math:10\% or less, when no intermediate monitoring is requested, the number of times the preconditioner has to be thus applied compared with the total number of applications of the preconditioner. TFQMR can be viewed as a more robust variant of the CGS method: it shares the CGS method speed but avoids the CGS fluctuations in the residual, which may give rise to instability.
Also, when the termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11brf.html#eqne2>__ is used, the CGS, BI-CGSTAB(:math:\ell) and TFQMR methods will restart the iteration automatically when necessary in order to solve the given problem.

.. _f11br-py2-py-references:

**References**
Arnoldi, W, 1951, The principle of minimized iterations in the solution of the matrix eigenvalue problem, Quart. Appl. Math. (9), 17--29

Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Dias da Cunha, R and Hopkins, T, 1994, PIM 1.1 --- the parallel iterative method package for systems of linear equations user's guide --- Fortran 77 version, Technical Report, Computing Laboratory, University of Kent at Canterbury, Kent, UK

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

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

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 :math:\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
"""
raise NotImplementedError

[docs]def complex_gen_basic_solver(irevcm, u, v, comm, wgt=None):
r"""
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, :meth: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, :meth: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.

.. _f11bs-py2-py-doc:

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

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

.. _f11bs-py2-py-parameters:

**Parameters**
**irevcm** : int
On initial entry: :math:\mathrm{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.

:math:\mathrm{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 :math:\mathrm{irevcm} = 4. Note that before calling complex_gen_basic_solver with :math:\mathrm{irevcm} = 5 the calling program must have performed the tasks required by the value of :math:\mathrm{irevcm} returned by the previous call to complex_gen_basic_solver, otherwise subsequently returned values may be invalid.

:math:\mathrm{irevcm} = 6

Immediate termination: complex_gen_basic_solver will return immediately with termination code :math:\mathrm{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 :math:\mathrm{irevcm} to any other value between calls will result in an error.

**u** : complex, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: an initial estimate, :math:x_0, of the solution of the system of equations :math:Ax = b.

On intermediate entry: must remain unchanged.

On intermediate exit: the returned value of :math:\mathrm{irevcm} determines the contents of :math:\mathrm{u} as follows.

If :math:\mathrm{irevcm} = -1, :math:1 or :math:2, :math:\mathrm{u} holds the vector :math:u on which the operation specified by :math:\mathrm{irevcm} is to be carried out.

If :math:\mathrm{irevcm} = 3, :math:\mathrm{u} holds the current iterate of the solution vector.

On final exit: if :math:\mathrm{errno} = 3 or :math:\mathrm{errno} < 0, the array :math:\mathrm{u} is unchanged from the initial entry to complex_gen_basic_solver.

If :math:\mathrm{errno} = 1, the array :math:\mathrm{u} is unchanged from the last entry to complex_gen_basic_solver.

Otherwise, :math:\mathrm{u} holds the last available iterate of the solution of the system of equations, for all returned values of :math:\textit{errno}.

**v** : complex, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: the right-hand side :math:b of the system of equations :math:Ax = b.

On intermediate entry: the returned value of :math:\mathrm{irevcm} determines the contents of :math:\mathrm{v} as follows.

If :math:\mathrm{irevcm} = -1, :math:1 or :math:2, :math:\mathrm{v} must store the vector :math:v, the result of the operation specified by the value of :math:\mathrm{irevcm} returned by the previous call to complex_gen_basic_solver.

If :math:\mathrm{irevcm} = 3, :math:\mathrm{v} must remain unchanged.

On intermediate exit: if :math:\mathrm{irevcm} = 3, :math:\mathrm{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 :math:\mathrm{errno} = 3 or :math:\mathrm{errno} < 0, the array :math:\mathrm{v} is unchanged from the initial entry to complex_gen_basic_solver.

If :math:\mathrm{errno} = 1, the array :math:\mathrm{v} is unchanged from the last entry to complex_gen_basic_solver.

If the function exits successfully or :math:\mathrm{errno} = 2, the array :math:\mathrm{v} contains the true residual vector of the system of equations (see also :ref:Exceptions <f11bs-py2-py-errors>).

Otherwise, :math:\mathrm{v} stores the last available iterate of the residual vector unless :math:\mathrm{errno} = 8 is returned on last entry, in which case :math:\mathrm{v} is set to :math:0.0.

**comm** : dict, communication object, modified in place
Communication structure.

This argument must have been initialized by a prior call to :meth:complex_gen_basic_setup.

**wgt** : None or float, array-like, shape :math:\left(\textit{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 :ref:Notes for complex_gen_basic_setup <f11br-py2-py-notes> and :ref:Parameters for complex_gen_basic_setup <f11br-py2-py-parameters>).

**Returns**
**irevcm** : int
On intermediate exit: has the following meanings.

:math:\mathrm{irevcm} = -1

The calling program must compute the matrix-vector product :math:v = A^\mathrm{H}u, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively; RGMRES, CGS and BI-CGSTAB(:math:\ell) methods return :math:\mathrm{irevcm} = -1 only if the matrix norm :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty is estimated internally using Higham's method. This can only happen if :math:{\textit{iterm}} = 1 in :meth:complex_gen_basic_setup.

:math:\mathrm{irevcm} = 1

The calling program must compute the matrix-vector product :math:v = Au, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively.

:math:\mathrm{irevcm} = 2

The calling program must solve the preconditioning equation :math:Mv = u, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively.

:math:\mathrm{irevcm} = 3

Monitoring step: the solution and residual at the current iteration are returned in the arrays :math:\mathrm{u} and :math:\mathrm{v}, respectively. No action by the calling program is required. :meth:complex_gen_basic_diag can be called at this step to return additional information.

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

.. _f11bs-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On intermediate re-entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: either :math:\mathrm{irevcm} must be unchanged from its previous exit value or :math:\mathrm{irevcm} = 5 or :math:6.

(errno :math:-1)
On initial entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irevcm} = 0.

(errno :math:3)
Either :meth:complex_gen_basic_setup was not called before calling complex_gen_basic_solver or it has returned an error.

**Warns**
**NagAlgorithmicWarning**
(errno :math:1)
complex_gen_basic_solver has already completed its tasks. You need to set a new problem.

(errno :math:2)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

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

(errno :math:4)
User-requested tidy termination. The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
Algorithm breakdown at iteration no. :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:8)
User-requested immediate termination.

(errno :math:10)
The weights in array :math:\mathrm{wgt} are all zero.

.. _f11bs-py2-py-notes:

**Notes**
complex_gen_basic_solver solves the general (non-Hermitian) system of linear simultaneous equations :math:Ax = b of order :math:\textit{n}, where :math:\textit{n} is large and the coefficient matrix :math: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(:math:\ell), the bi-conjugate gradient stabilized method of order :math:\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 :ref:Notes for complex_gen_basic_setup <f11br-py2-py-notes>.

complex_gen_basic_solver can solve the system after the first function in the suite, :meth:complex_gen_basic_setup, has been called to initialize the computation and specify the method of solution.
The third function in the suite, :meth: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 :math:\mathrm{irevcm} (see :ref:Parameters <f11bs-py2-py-parameters>) set to specified values which require the calling program to carry out one of the following tasks:

compute the matrix-vector product :math:v = Au or :math:v = A^\mathrm{H}u (the four methods require the matrix transpose-vector product only if :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty is estimated internally by Higham's method (see Higham (1988)));

solve the preconditioning equation :math:Mv = u;

notify the completion of the computation;

allow the calling program to monitor the solution.

Through the argument :math:\mathrm{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.

(#) 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.

.. _f11bs-py2-py-references:

**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 :math:\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
"""
raise NotImplementedError

[docs]def complex_gen_basic_diag(comm):
r"""
complex_gen_basic_diag is the third in a suite of three functions for the iterative solution of a complex general (non-Hermitian) system of simultaneous linear equations (see Golub and Van Loan (1996)). complex_gen_basic_diag returns information about the computations during an iteration and/or after this has been completed.
The first function of the suite, :meth:complex_gen_basic_setup, is a setup function; the second function, :meth:complex_gen_basic_solver, is the iterative solver itself.

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

.. _f11bt-py2-py-doc:

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

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

.. _f11bt-py2-py-parameters:

**Parameters**
**comm** : dict, communication object, modified in place
Communication structure.

This argument must have been initialized by a prior call to :meth:complex_gen_basic_setup.

**Returns**
**itn** : int
The number of iterations carried out by :meth:complex_gen_basic_solver.

**stplhs** : float
The current value of the left-hand side of the termination criterion used by :meth:complex_gen_basic_solver.

**stprhs** : float
The current value of the right-hand side of the termination criterion used by :meth:complex_gen_basic_solver.

**anorm** : float
If :math:{\textit{iterm}} = 1 in the previous call to :meth:complex_gen_basic_setup, then :math:\mathrm{anorm} contains :math:\left\lVert A\right\rVert_p, where :math:p = 1, :math:2 or :math:\infty, either supplied or, in the case of :math:1 or :math:\infty, estimated by :meth:complex_gen_basic_solver; otherwise :math:\mathrm{anorm} = 0.0.

**sigmax** : float
If :math:{\textit{iterm}} = 2 in the previous call to :meth:complex_gen_basic_setup, the current estimate of the largest singular value :math:\sigma_1\left(\bar{A}\right) of the preconditioned iteration matrix when it is used by the termination criterion in :meth:complex_gen_basic_solver, either when it has been supplied to :meth:complex_gen_basic_setup or it has been estimated by :meth:complex_gen_basic_solver (see also :ref:Notes for complex_gen_basic_setup <f11br-py2-py-notes> and :ref:Parameters for complex_gen_basic_setup <f11br-py2-py-parameters>); otherwise, :math:\mathrm{sigmax} = 0.0 is returned.

.. _f11bt-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
complex_gen_basic_diag has been called out of sequence.

.. _f11bt-py2-py-notes:

**Notes**
complex_gen_basic_diag returns information about the solution process.
It can be called either during a monitoring step of :meth:complex_gen_basic_solver or after :meth:complex_gen_basic_solver has completed its tasks.
Calling complex_gen_basic_diag at any other time will result in an error condition being raised.

For further information you should read the documentation for :meth:complex_gen_basic_setup and :meth:complex_gen_basic_solver.

.. _f11bt-py2-py-references:

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

[docs]def real_gen_precon_ilu(nnz, a, irow, icol, n=None, lfill=0, dtol=0.0, pstrat='C', milu='N', ipivp=None, ipivq=None):
r"""
real_gen_precon_ilu computes an incomplete :math:LU factorization of a real sparse nonsymmetric matrix, represented in coordinate storage format.
This factorization may be used as a preconditioner in combination with :meth:real_gen_solve_ilu or :meth:real_gen_basic_solver.

.. _f11da-py2-py-doc:

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

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

.. _f11da-py2-py-parameters:

**Parameters**
**nnz** : int
The number of nonzero elements in the matrix :math:A.

**a** : float, array-like, shape :math:\left(\textit{la}\right)
The nonzero elements in the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**n** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:\mathrm{ipivp}.\mathrm{shape}[0].

:math:n, the order of the matrix :math:A.

**lfill** : int, optional
If :math:\mathrm{lfill}\geq 0 its value is the maximum level of fill allowed in the decomposition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments2>__). A negative value of :math:\mathrm{lfill} indicates that :math:\mathrm{dtol} will be used to control the fill instead.

**dtol** : float, optional
If :math:\mathrm{lfill} < 0, :math:\mathrm{dtol} is used as a drop tolerance to control the fill-in (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments2>__); otherwise :math:\mathrm{dtol} is not referenced.

**pstrat** : str, length 1, optional
Specifies the pivoting strategy to be adopted.

:math:\mathrm{pstrat} = \texttt{'N'}

No pivoting is carried out.

:math:\mathrm{pstrat} = \texttt{'U'}

Pivoting is carried out according to the user-defined input values of :math:\mathrm{ipivp} and :math:\mathrm{ipivq}.

:math:\mathrm{pstrat} = \texttt{'P'}

Partial pivoting by columns for stability is carried out.

:math:\mathrm{pstrat} = \texttt{'C'}

Complete pivoting by rows for sparsity, and by columns for stability, is carried out.

**milu** : str, length 1, optional
Indicates whether or not the factorization should be modified to preserve row-sums (see Choice of Arguments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments3>__).

:math:\mathrm{milu} = \texttt{'M'}

The factorization is modified.

:math:\mathrm{milu} = \texttt{'N'}

The factorization is not modified.

**ipivp** : None or int, array-like, shape :math:\left(\mathrm{n}\right), optional
If :math:\mathrm{pstrat} = \texttt{'U'}, :math:\mathrm{ipivp}[k-1] and :math:\mathrm{ipivq}[k-1] must specify the row and column indices of the element used as a pivot at elimination stage :math:k. Otherwise :math:\mathrm{ipivp} and :math:\mathrm{ipivq} need not be initialized.

**ipivq** : None or int, array-like, shape :math:\left(\mathrm{n}\right), optional
If :math:\mathrm{pstrat} = \texttt{'U'}, :math:\mathrm{ipivp}[k-1] and :math:\mathrm{ipivq}[k-1] must specify the row and column indices of the element used as a pivot at elimination stage :math:k. Otherwise :math:\mathrm{ipivp} and :math:\mathrm{ipivq} need not be initialized.

**Returns**
**a** : float, ndarray, shape :math:\left(\mathrm{nnz}+\mathrm{nnzc}\right)
The first :math:\mathrm{nnz} entries of :math:\mathrm{a} contain the nonzero elements of :math:A and the next :math:\mathrm{nnzc} entries contain the elements of the matrix :math:C. Matrix elements are ordered by increasing row index, and by increasing column index within each row.

**irow** : int, ndarray, shape :math:\left(\mathrm{nnz}+\mathrm{nnzc}\right)
The row indices of the nonzero elements returned in :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\mathrm{nnz}+\mathrm{nnzc}\right)
The column indices of the nonzero elements returned in :math:\mathrm{a}.

**ipivp** : int, ndarray, shape :math:\left(\mathrm{n}\right)
The pivot indices. If :math:\mathrm{ipivp}[k-1] = i and :math:\mathrm{ipivq}[k-1] = j then the element in row :math:i and column :math:j was used as the pivot at elimination stage :math:k.

**ipivq** : int, ndarray, shape :math:\left(\mathrm{n}\right)
The pivot indices. If :math:\mathrm{ipivp}[k-1] = i and :math:\mathrm{ipivq}[k-1] = j then the element in row :math:i and column :math:j was used as the pivot at elimination stage :math:k.

**istr** : int, ndarray, shape :math:\left(\mathrm{n}+1\right)
:math:\mathrm{istr}[\textit{i}-1]-1, for :math:\textit{i} = 1,2,\ldots,\mathrm{n}, is the starting address in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:i of the matrix :math:C. :math:\mathrm{istr}[\mathrm{n}]-1 is the address of the last nonzero element in :math:C plus one.

**idiag** : int, ndarray, shape :math:\left(\mathrm{n}\right)
:math:\mathrm{idiag}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,\mathrm{n}, holds the index of arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} which holds the diagonal element in row :math:i of the matrix :math:C.

**nnzc** : int
The number of nonzero elements in the matrix :math:C.

**npivm** : int
If :math:\mathrm{npivm} > 0 it gives the number of pivots which were modified during the factorization to ensure that :math:M exists.

If :math:\mathrm{npivm} = -1 no pivot modifications were required, but a local restart occurred (see Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments25>__).

The quality of the preconditioner will generally depend on the returned value of :math:\mathrm{npivm}.

If :math:\mathrm{npivm} is large the preconditioner may not be satisfactory.

In this case it may be advantageous to call real_gen_precon_ilu again with an increased value of :math:\mathrm{lfill}, a reduced value of :math:\mathrm{dtol}, or set :math:\mathrm{pstrat} = \texttt{'C'}.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments4>__.

.. _f11da-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq \mathrm{n}^2.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{milu} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{milu} = \texttt{'M'} or :math:\texttt{'N'}.

(errno :math:1)
On entry, :math:\mathrm{pstrat} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{pstrat} = \texttt{'N'}, :math:\texttt{'U'}, :math:\texttt{'P'} or :math:\texttt{'C'}.

(errno :math:1)
On entry, :math:\mathrm{dtol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dtol}\geq 0.0.

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:2)
On entry, the location :math:\left(\mathrm{irow}[i-1], \mathrm{icol}[i-1]\right) is a duplicate: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq \mathrm{n}.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq \mathrm{n}.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipivq} is repeated.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipivq} lies outside the range :math:\left[1, \mathrm{n}\right].

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipivp} is repeated.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipivp} lies outside the range :math:\left[1, \mathrm{n}\right].

(errno :math:4)
The number of nonzero entries in the decomposition is too large. The decomposition has been terminated before completion. Either increase :math:\textit{la}, or reduce the fill by reducing :math:\mathrm{lfill}, or increasing :math:\mathrm{dtol}.

(errno :math:5)
A serious error has occurred in an internal call to an auxiliary function. Check all function calls and array sizes. Seek expert help.

(errno :math:14)
Either :math:\mathrm{n} or the pair :math:\mathrm{ipivp} and :math:\mathrm{ipivq}, and not all three, must be provided.

.. _f11da-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

real_gen_precon_ilu computes an incomplete :math:LU factorization (see Meijerink and Van der Vorst (1977) and Meijerink and Van der Vorst (1981)) of a real sparse nonsymmetric :math:n\times n matrix :math:A.
The factorization is intended primarily for use as a preconditioner with one of the iterative solvers :meth:real_gen_solve_ilu or :meth:real_gen_basic_solver.

The decomposition is written in the form

.. math::
A = M+R

where

.. math::
M = PLDUQ

and :math:L is lower triangular with unit diagonal elements, :math:D is diagonal, :math:U is upper triangular with unit diagonals, :math:P and :math:Q are permutation matrices, and :math:R is a remainder matrix.

The amount of fill-in occurring in the factorization can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill :math:\mathrm{lfill}, or the drop tolerance :math:\mathrm{dtol}.

The argument :math:\mathrm{pstrat} defines the pivoting strategy to be used.
The options currently available are no pivoting, user-defined pivoting, partial pivoting by columns for stability, and complete pivoting by rows for sparsity and by columns for stability.
The factorization may optionally be modified to preserve the row-sums of the original matrix.

The sparse matrix :math:A is represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__).
The array :math:\mathrm{a} stores all the nonzero elements of the matrix :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.
Multiple nonzero elements may not be specified for the same row and column index.

The preconditioning matrix :math:M is returned in terms of the CS representation of the matrix

.. math::
C = L+D^{-1}+U-2I\text{.}

Further algorithmic details are given in Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments25>__.

.. _f11da-py2-py-references:

**References**
Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148--162

Meijerink, J and Van der Vorst, H, 1981, Guidelines for the usage of incomplete decompositions in solving sets of linear equations as they occur in practical problems, J. Comput. Phys. (44), 134--155

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

--------
:meth:naginterfaces.library.examples.sparse.real_gen_basic_solver_ex.main
"""
raise NotImplementedError

[docs]def real_gen_precon_ilu_solve(trans, a, irow, icol, ipivp, ipivq, istr, idiag, y, check='N'):
r"""
real_gen_precon_ilu_solve solves a system of linear equations involving the incomplete :math:LU preconditioning matrix generated by :meth:real_gen_precon_ilu.

.. _f11db-py2-py-doc:

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

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

.. _f11db-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether or not the matrix :math:M is transposed.

:math:\mathrm{trans} = \texttt{'N'}

:math:Mx = y is solved.

:math:\mathrm{trans} = \texttt{'T'}

:math:M^\mathrm{T}x = y is solved.

**a** : float, array-like, shape :math:\left(\textit{la}\right)
The values returned in the array :math:\mathrm{a} by a previous call to :meth:real_gen_precon_ilu.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

**ipivp** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

**ipivq** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

**istr** : int, array-like, shape :math:\left(n+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

**idiag** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

**y** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:y.

**check** : str, length 1, optional
Specifies whether or not the CS representation of the matrix :math:M should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried on the values of :math:\textit{n}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dbf.html#fcomments2>__.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
The solution vector :math:x.

.. _f11db-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, :math:\mathrm{ipivq}[i-1] is a repeated value: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ipivq}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ipivq}[i-1]\geq 1 and :math:\mathrm{ipivq}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{ipivp}[i-1] is a repeated value: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ipivp}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ipivp}[i-1]\geq 1 and :math:\mathrm{ipivp}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr}[i-1] is inconsistent with :math:\mathrm{irow}: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{idiag}[i-1] appears to be incorrect: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[i-1],\mathrm{icol}[i-1]) is a duplicate: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr} appears to be invalid.

.. _f11db-py2-py-notes:

**Notes**
real_gen_precon_ilu_solve solves a system of linear equations

.. math::
\begin{array}{ccc}Mx = y\text{,}&\text{or}&M^\mathrm{T}x = y\text{,}\end{array}

according to the value of the argument :math:\mathrm{trans}, where the matrix :math:M = PLDUQ, corresponds to an incomplete :math:LU decomposition of a sparse matrix stored in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__), as generated by :meth:real_gen_precon_ilu.

In the above decomposition :math:L is a lower triangular sparse matrix with unit diagonal elements, :math:D is a diagonal matrix, :math:U is an upper triangular sparse matrix with unit diagonal elements and, :math:P and :math:Q are permutation matrices. :math:L, :math:D and :math:U are supplied to real_gen_precon_ilu_solve through the matrix

.. math::
C = L+D^{-1}+U-2I

which is an :math:\textit{n} by :math:\textit{n} sparse matrix, stored in CS format, as returned by :meth:real_gen_precon_ilu.
The permutation matrices :math:P and :math:Q are returned from :meth:real_gen_precon_ilu via the arrays :math:\mathrm{ipivp} and :math:\mathrm{ipivq}.

It is envisaged that a common use of real_gen_precon_ilu_solve will be to carry out the preconditioning step required in the application of :meth:real_gen_basic_solver to sparse linear systems. real_gen_precon_ilu_solve is used for this purpose by the Black Box function :meth:real_gen_solve_ilu.

real_gen_precon_ilu_solve may also be used in combination with :meth:real_gen_precon_ilu to solve a sparse system of linear equations directly (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments4>__).

--------
:meth:naginterfaces.library.examples.sparse.real_gen_basic_solver_ex.main
"""
raise NotImplementedError

[docs]def real_gen_solve_ilu(method, nnz, a, irow, icol, ipivp, ipivq, istr, idiag, b, m, tol, maxitn, x):
r"""
real_gen_solve_ilu 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 incomplete :math:LU preconditioning.

.. _f11dc-py2-py-doc:

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

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

.. _f11dc-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'RGMRES'}

Restarted generalized minimum residual method.

:math:\mathrm{method} = \texttt{'CGS'}

:math:\mathrm{method} = \texttt{'BICGSTAB'}

Bi-conjugate gradient stabilized (:math:\ell) method.

:math:\mathrm{method} = \texttt{'TFQMR'}

Transpose-free quasi-minimal residual method.

**nnz** : int
The number of nonzero elements in the matrix :math:A. This **must** be the same value as was supplied in the preceding call to :meth:real_gen_precon_ilu.

**a** : float, array-like, shape :math:\left(\textit{la}\right)
The values returned in the array :math:\mathrm{a} by a previous call to :meth:real_gen_precon_ilu.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**ipivp** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**ipivq** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**istr** : int, array-like, shape :math:\left(n+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**idiag** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**b** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

**m** : int
If :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m} is the dimension of the restart subspace.

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m} is the order :math:\ell of the polynomial BI-CGSTAB method; otherwise, :math:\mathrm{m} is not referenced.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },10\epsilon,\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : float, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11dc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m}\geq 1 and :math:\mathrm{m}\leq \mathrm{min}\left(n, \langle\mathit{\boldsymbol{value}}\rangle\right).

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\texttt{'CGS'} or :math:\texttt{'BICGSTAB'}.

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq n^2.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[i-1],\mathrm{icol}[i-1]) is a duplicate: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
The :math:\mathrm{CS} representation of the preconditioner is invalid.

(errno :math:6)
Algorithmic breakdown. A solution is returned, although it is possible that it is completely inaccurate.

(errno :math:7)
A serious error, code :math:\langle\mathit{\boldsymbol{value}}\rangle, has occurred in an internal call. Check all function calls and array sizes. Seek expert help.

**Warns**
**NagAlgorithmicWarning**
(errno :math:4)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

.. _f11dc-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

real_gen_solve_ilu solves a real sparse nonsymmetric linear system of equations:

.. math::
Ax = b\text{,}

using a preconditioned RGMRES (see Saad and Schultz (1986)), CGS (see Sonneveld (1989)), BI-CGSTAB(:math:\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_ilu uses the incomplete :math:LU factorization determined by :meth:real_gen_precon_ilu as the preconditioning matrix.
A call to real_gen_solve_ilu must always be preceded by a call to :meth:real_gen_precon_ilu.
Alternative preconditioners for the same storage scheme are available by calling :meth:real_gen_solve_jacssor.

The matrix :math:A, and the preconditioning matrix :math:M, are represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}, as returned from :meth:real_gen_precon_ilu.
The array :math:\mathrm{a} holds the nonzero entries in these matrices, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

real_gen_solve_ilu is a Black Box function which calls :meth:real_gen_basic_setup, :meth:real_gen_basic_solver and :meth: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.

.. _f11dc-py2-py-references:

**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 :math:\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
"""
raise NotImplementedError

[docs]def real_gen_precon_ssor_solve(trans, a, irow, icol, rdiag, omega, y, check='N'):
r"""
real_gen_precon_ssor_solve solves a system of linear equations involving the preconditioning matrix corresponding to SSOR applied to a real sparse nonsymmetric matrix, represented in coordinate storage format.

.. _f11dd-py2-py-doc:

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

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

.. _f11dd-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether or not the matrix :math:M is transposed.

:math:\mathrm{trans} = \texttt{'N'}

:math:Mx = y is solved.

:math:\mathrm{trans} = \texttt{'T'}

:math:M^\mathrm{T}x = y is solved.

**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements in the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**rdiag** : float, array-like, shape :math:\left(n\right)
The elements of the diagonal matrix :math:D^{-1}, where :math:D is the diagonal part of :math:A.

**omega** : float
The relaxation parameter :math:\omega.

**y** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:y.

**check** : str, length 1, optional
Specifies whether or not the CS representation of the matrix :math:M should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow}, :math:\mathrm{icol} and :math:\mathrm{omega}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11ddf.html#fcomments2>__.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
The solution vector :math:x.

.. _f11dd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:2)
On entry, :math:\mathrm{omega} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0 < \mathrm{omega} < 2.0.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \textit{nnz}\leq n^2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \textit{nnz}\leq n^2.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:4)
The matrix :math:A has no diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

.. _f11dd-py2-py-notes:

**Notes**
real_gen_precon_ssor_solve solves a system of linear equations

.. math::
\begin{array}{ccc}Mx = y\text{,}&\text{or}&M^\mathrm{T}x = y\text{,}\end{array}

according to the value of the argument :math:\mathrm{trans}, where the matrix

.. math::
M = \frac{1}{{\omega \left(2-\omega \right)}}\left(D+\omega L\right)D^{-1}\left(D+\omega U\right)

corresponds to symmetric successive-over-relaxation (SSOR) (see Young (1971)) applied to a linear system :math:Ax = b, where :math:A is a real sparse nonsymmetric matrix stored in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__).

In the definition of :math:M given above :math:D is the diagonal part of :math:A, :math:L is the strictly lower triangular part of :math:A, :math:U is the strictly upper triangular part of :math:A, and :math:\omega is a user-defined relaxation parameter.

It is envisaged that a common use of real_gen_precon_ssor_solve will be to carry out the preconditioning step required in the application of :meth:real_gen_basic_solver to sparse linear systems. real_gen_precon_ssor_solve is also used for this purpose by the Black Box function :meth:real_gen_solve_jacssor.

.. _f11dd-py2-py-references:

**References**
Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def real_gen_solve_jacssor(method, precon, a, irow, icol, omega, b, m, tol, maxitn, x):
r"""
real_gen_solve_jacssor 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, without preconditioning, with Jacobi, or with SSOR preconditioning.

.. _f11de-py2-py-doc:

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

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

.. _f11de-py2-py-parameters:

**Parameters**
**method** : str
The iterative method to be used.

:math:\mathrm{method} = \texttt{'RGMRES'}

Restarted generalized minimum residual method.

:math:\mathrm{method} = \texttt{'CGS'}

:math:\mathrm{method} = \texttt{'BICGSTAB'}

Bi-conjugate gradient stabilized (:math:\ell) method.

:math:\mathrm{method} = \texttt{'TFQMR'}

Transpose-free quasi-minimal residual method.

**precon** : str, length 1
Specifies the type of preconditioning to be used.

:math:\mathrm{precon} = \texttt{'N'}

No preconditioning.

:math:\mathrm{precon} = \texttt{'J'}

Jacobi.

:math:\mathrm{precon} = \texttt{'S'}

Symmetric successive-over-relaxation.

**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**omega** : float
If :math:\mathrm{precon} = \texttt{'S'}, :math:\mathrm{omega} is the relaxation parameter :math:\omega to be used in the SSOR method. Otherwise :math:\mathrm{omega} need not be initialized and is not referenced.

**b** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

**m** : int
If :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m} is the dimension of the restart subspace.

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m} is the order :math:\ell of the polynomial BI-CGSTAB method.

Otherwise, :math:\mathrm{m} is not referenced.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },10\epsilon,\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : float, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11de-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m}\geq 1 and :math:\mathrm{m}\leq \mathrm{MIN}\left(n, \langle\mathit{\boldsymbol{value}}\rangle\right).

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\texttt{'CGS'} or :math:\texttt{'BICGSTAB'}.

(errno :math:1)
On entry, :math:\mathrm{omega} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{omega} > 0.0 and :math:\mathrm{omega} < 2.0.

(errno :math:1)
On entry, :math:\mathrm{precon} \neq \texttt{'N'}, :math:\texttt{'J'} or :math:\texttt{'S'}: :math:\mathrm{precon} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n^2.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
The matrix :math:A has a zero diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
The matrix :math:A has no diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:6)
Algorithmic breakdown. A solution is returned, although it is possible that it is completely inaccurate.

(errno :math:7)
A serious error has occurred in an internal call: :math:\mathrm{IREVCM} = \langle\mathit{\boldsymbol{value}}\rangle. Check all function calls and array sizes. Seek expert help.

(errno :math:7)
A serious error has occurred in an internal call: :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle. Check all function calls and array sizes. Seek expert help.

**Warns**
**NagAlgorithmicWarning**
(errno :math:4)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

.. _f11de-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

real_gen_solve_jacssor solves a real sparse nonsymmetric system of linear equations

.. math::
Ax = b\text{,}

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

The function allows the following choices for the preconditioner:

no preconditioning;

Jacobi preconditioning (see Young (1971));

symmetric successive-over-relaxation (SSOR) preconditioning (see Young (1971)).

For incomplete :math:LU (ILU) preconditioning see :meth:real_gen_solve_ilu.

The matrix :math:A is represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}.
The array :math:\mathrm{a} holds the nonzero entries in the matrix, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

real_gen_solve_jacssor is a Black Box function which calls :meth:real_gen_basic_setup, :meth:real_gen_basic_solver and :meth: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.

.. _f11de-py2-py-references:

**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 :math:\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

Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def real_gen_precon_bdilu(n, nnz, a, irow, icol, istb, indb, lfill, dtol, milu, ipivp, ipivq, pstrat=None):
r"""
real_gen_precon_bdilu computes a block diagonal incomplete :math:LU factorization of a real sparse nonsymmetric matrix, represented in coordinate storage format.
The diagonal blocks may be composed of arbitrary rows and the corresponding columns, and may overlap.
This factorization can be used to provide a block Jacobi or additive Schwarz preconditioner, for use in combination with :meth:real_gen_solve_bdilu or :meth:real_gen_basic_solver.

.. _f11df-py2-py-doc:

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

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

.. _f11df-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the order of the matrix :math:A.

**nnz** : int
The number of nonzero elements in the matrix :math:A.

**a** : float, array-like, shape :math:\left(\textit{la}\right)
The nonzero elements in the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**istb** : int, array-like, shape :math:\left(\textit{nb}+1\right)
:math:\mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}, holds the indices in arrays :math:\mathrm{indb}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq} and :math:\mathrm{idiag} that, on successful exit from this function, define block :math:\textit{b}. :math:\mathrm{istb}[{\textit{nb}+1}-1] holds the sum of the number of rows in all blocks plus :math:\mathrm{istb}[0].

**indb** : int, array-like, shape :math:\left(\textit{lindb}\right)
:math:\mathrm{indb} must hold the row indices appearing in each diagonal block, stored consecutively. Thus the elements :math:\mathrm{indb}[\mathrm{istb}[b-1]-1] to :math:\mathrm{indb}[\mathrm{istb}[b]-2] are the row indices in the :math:\textit{b}\ th block, for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

**lfill** : int, array-like, shape :math:\left(\textit{nb}\right)
If :math:\mathrm{lfill}[b-1]\geq 0 its value is the maximum level of fill allowed in the decomposition of the block (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments2>__). A negative value of :math:\mathrm{lfill}[b-1] indicates that :math:\mathrm{dtol}[b-1] will be used to control the fill in the block instead.

**dtol** : float, array-like, shape :math:\left(\textit{nb}\right)
If :math:\mathrm{lfill}[b-1] < 0 then :math:\mathrm{dtol}[b-1] is used as a drop tolerance in the block to control the fill-in (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments2>__); otherwise :math:\mathrm{dtol}[b-1] is not referenced.

**milu** : str, length 1, array-like, shape :math:\left(\textit{nb}\right)
:math:\mathrm{milu}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}, indicates whether or not the factorization in the block should be modified to preserve row-sums (see Further Comments for real_gen_precon_ilu <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments3>__).

:math:\mathrm{milu}[b-1] = \texttt{'M'}

The factorization is modified.

:math:\mathrm{milu}[b-1] = \texttt{'N'}

The factorization is not modified.

**ipivp** : int, array-like, shape :math:\left(\textit{lindb}\right)
If :math:\mathrm{pstrat}[b-1] = \texttt{'U'}, :math:\mathrm{ipivp}[\mathrm{istb}[b-1]+k-2] and :math:\mathrm{ipivq}[\mathrm{istb}[b-1]+k-2] must specify the row and column indices of the element used as a pivot at elimination stage :math:k of the factorization of the block. Otherwise :math:\mathrm{ipivp} and :math:\mathrm{ipivq} need not be initialized.

**ipivq** : int, array-like, shape :math:\left(\textit{lindb}\right)
If :math:\mathrm{pstrat}[b-1] = \texttt{'U'}, :math:\mathrm{ipivp}[\mathrm{istb}[b-1]+k-2] and :math:\mathrm{ipivq}[\mathrm{istb}[b-1]+k-2] must specify the row and column indices of the element used as a pivot at elimination stage :math:k of the factorization of the block. Otherwise :math:\mathrm{ipivp} and :math:\mathrm{ipivq} need not be initialized.

**pstrat** : None or str, length 1, array-like, shape :math:\left(\textit{nb}\right), optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:\texttt{'C'}.

:math:\mathrm{pstrat}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}, specifies the pivoting strategy to be adopted in the block as follows:

:math:\mathrm{pstrat}[b-1] = \texttt{'N'}

No pivoting is carried out.

:math:\mathrm{pstrat}[b-1] = \texttt{'U'}

Pivoting is carried out according to the user-defined input values of :math:\mathrm{ipivp} and :math:\mathrm{ipivq}.

:math:\mathrm{pstrat}[b-1] = \texttt{'P'}

Partial pivoting by columns for stability is carried out.

:math:\mathrm{pstrat}[b-1] = \texttt{'C'}

Complete pivoting by rows for sparsity, and by columns for stability, is carried out.

**Returns**
**a** : float, ndarray, shape :math:\left(\textit{la}\right)
The first :math:\mathrm{nnz} entries of :math:\mathrm{a} contain the nonzero elements of :math:A and the next :math:\mathrm{nnzc} entries contain the elements of the matrices :math:C_{\textit{b}}, for :math:\textit{b} = 1,2,\ldots,\textit{nb} stored consecutively. Within each block the matrix elements are ordered by increasing row index, and by increasing column index within each row.

**irow** : int, ndarray, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements returned in :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements returned in :math:\mathrm{a}.

**ipivp** : int, ndarray, shape :math:\left(\textit{lindb}\right)
The row and column indices of the pivot elements, arranged consecutively for each block, as for :math:\mathrm{indb}. If :math:\mathrm{ipivp}[\mathrm{istb}[b-1]+k-2] = i and :math:\mathrm{ipivq}[\mathrm{istb}[b-1]+k-2] = j, the element in row :math:i and column :math:j of :math:A_b was used as the pivot at elimination stage :math:k.

**ipivq** : int, ndarray, shape :math:\left(\textit{lindb}\right)
The row and column indices of the pivot elements, arranged consecutively for each block, as for :math:\mathrm{indb}. If :math:\mathrm{ipivp}[\mathrm{istb}[b-1]+k-2] = i and :math:\mathrm{ipivq}[\mathrm{istb}[b-1]+k-2] = j, the element in row :math:i and column :math:j of :math:A_b was used as the pivot at elimination stage :math:k.

**istr** : int, ndarray, shape :math:\left(\textit{lindb}+1\right)
:math:\mathrm{istr}[\mathrm{istb}[\textit{b}-1]+\textit{k}-2], gives the index in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:\textit{k} of the matrix :math:C_{\textit{b}}, for :math:\textit{k} = 1,2,\ldots,\mathrm{istb}[{\textit{b}+1}-1]-\mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

:math:\mathrm{istr}[\mathrm{istb}[\textit{nb}]-1] contains :math:\mathrm{nnz}+\mathrm{nnzc}+1.

**idiag** : int, ndarray, shape :math:\left(\textit{lindb}\right)
:math:\mathrm{idiag}[\mathrm{istb}[\textit{b}-1]+\textit{k}-2], gives the index in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of the diagonal element in row :math:\textit{k} of the matrix :math:C_{\textit{b}}, for :math:\textit{k} = 1,2,\ldots,\mathrm{istb}[{\textit{b}+1}-1]-\mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

**nnzc** : int
The sum total number of nonzero elements in the matrices :math:C_{\textit{b}}, for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

**npivm** : int, ndarray, shape :math:\left(\textit{nb}\right)
If :math:\mathrm{npivm}[b-1] > 0 it gives the number of pivots which were modified during the factorization to ensure that :math:M_b exists.

If :math:\mathrm{npivm}[\textit{b}-1] = -1 no pivot modifications were required, but a local restart occurred (see Further Comments for real_gen_precon_ilu <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11daf.html#fcomments25>__). The quality of the preconditioner will generally depend on the returned values of :math:\mathrm{npivm}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

If :math:\mathrm{npivm}[b-1] is large, for some block, the preconditioner may not be satisfactory.

In this case it may be advantageous to call real_gen_precon_bdilu again with an increased value of :math:\mathrm{lfill}[b-1], a reduced value of :math:\mathrm{dtol}[b-1], or :math:\mathrm{pstrat}[b-1] = \texttt{'C'}.

.. _f11df-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:1)
On entry, :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \textit{nb}\leq \mathrm{n}.

(errno :math:1)
On entry, :math:\mathrm{istb}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istb}[0]\geq 1.

(errno :math:1)
On entry, for :math:b = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istb}[b] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{istb}[b-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istb}[\textit{b}] > \mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

(errno :math:1)
On entry, :math:\mathrm{indb}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{indb}[\textit{m}-1]\leq \mathrm{n}, for :math:\textit{m} = 1,2,\ldots,\mathrm{istb}[\textit{nb}]-1

(errno :math:1)
On entry, :math:\textit{lindb} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istb}[\textit{nb}]-1 = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{lindb}\geq \mathrm{istb}[\textit{nb}]-1.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq \mathrm{n}^2.

(errno :math:1)
On entry, :math:\mathrm{dtol}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dtol}[\textit{b}-1]\geq 0.0, for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

(errno :math:1)
On entry, :math:\mathrm{pstrat}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{pstrat}[b-1] = \texttt{'N'}, :math:\texttt{'U'}, :math:\texttt{'P'} or :math:\texttt{'C'} for all :math:b.

(errno :math:1)
On entry, :math:\mathrm{milu}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{milu}[b-1] = \texttt{'M'} or :math:\texttt{'N'} for all :math:b.

(errno :math:2)
On entry, :math:\mathrm{irow}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{irow}[\textit{i}-1]\leq \mathrm{n}, for :math:\textit{i} = 1,2,\ldots,\mathrm{nnz}.

(errno :math:2)
On entry, :math:\mathrm{icol}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{icol}[\textit{j}-1]\leq \mathrm{n}, for :math:\textit{j} = 1,2,\ldots,\mathrm{nnz}.

(errno :math:2)
On entry, element :math:\langle\mathit{\boldsymbol{value}}\rangle of :math:\mathrm{a} was out of order.

(errno :math:2)
On entry, location :math:\langle\mathit{\boldsymbol{value}}\rangle of :math:\left(\mathrm{irow}, \mathrm{icol}\right) was a duplicate.

(errno :math:3)
On entry, the user-supplied value of :math:\mathrm{ipivp} for block :math:\langle\mathit{\boldsymbol{value}}\rangle lies outside its range.

(errno :math:3)
On entry, the user-supplied value of :math:\mathrm{ipivp} for block :math:\langle\mathit{\boldsymbol{value}}\rangle was repeated.

(errno :math:3)
On entry, the user-supplied value of :math:\mathrm{ipivq} for block :math:\langle\mathit{\boldsymbol{value}}\rangle lies outside its range.

(errno :math:3)
On entry, the user-supplied value of :math:\mathrm{ipivq} for block :math:\langle\mathit{\boldsymbol{value}}\rangle was repeated.

(errno :math:4)
The number of nonzero entries in the decomposition is too large.

The decomposition has been terminated before completion.

Either increase :math:\textit{la}, or reduce the fill by reducing :math:\mathrm{lfill}, or increasing :math:\mathrm{dtol}.

.. _f11df-py2-py-notes:

**Notes**
real_gen_precon_bdilu computes an incomplete :math:LU factorization (see Meijerink and Van der Vorst (1977) and Meijerink and Van der Vorst (1981)) of the (possibly overlapping) diagonal blocks :math:A_{\textit{b}}, for :math:\textit{b} = 1,2,\ldots,\textit{nb}, of a real sparse nonsymmetric :math:n\times n matrix :math:A.
The factorization is intended primarily for use as a block Jacobi or additive Schwarz preconditioner (see Saad (1996)), with one of the iterative solvers :meth:real_gen_solve_bdilu and :meth:real_gen_basic_solver.

The :math:\textit{nb} diagonal blocks need not consist of consecutive rows and columns of :math:A, but may be composed of arbitrarily indexed rows, and the corresponding columns, as defined in the arguments :math:\mathrm{indb} and :math:\mathrm{istb}.
Any given row or column index may appear in more than one diagonal block, resulting in overlap.
Each diagonal block :math:A_{\textit{b}}, for :math:\textit{b} = 1,2,\ldots,\textit{nb}, is factorized as:

.. math::
A_b = M_b+R_b

where

.. math::
M_b = P_bL_bD_bU_bQ_b

and :math:L_b is lower triangular with unit diagonal elements, :math:D_b is diagonal, :math:U_b is upper triangular with unit diagonals, :math:P_b and :math:Q_b are permutation matrices, and :math:R_b is a remainder matrix.

The amount of fill-in occurring in the factorization of block :math:b can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill :math:\mathrm{lfill}[b-1], or the drop tolerance :math:\mathrm{dtol}[b-1].

The parameter :math:\mathrm{pstrat}[b-1] defines the pivoting strategy to be used in block :math:b.
The options currently available are no pivoting, user-defined pivoting, partial pivoting by columns for stability, and complete pivoting by rows for sparsity and by columns for stability.
The factorization may optionally be modified to preserve the row-sums of the original block matrix.

The sparse matrix :math:A is represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__).
The array :math:\mathrm{a} stores all the nonzero elements of the matrix :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.
Multiple nonzero elements may not be specified for the same row and column index.

The preconditioning matrices :math:M_{\textit{b}}, for :math:\textit{b} = 1,2,\ldots,\textit{nb}, are returned in terms of the CS representations of the matrices

.. math::
C_b = L_b+D^{-1}_b+U_b-2I\text{.}

.. _f11df-py2-py-references:

**References**
Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148--162

Meijerink, J and Van der Vorst, H, 1981, Guidelines for the usage of incomplete decompositions in solving sets of linear equations as they occur in practical problems, J. Comput. Phys. (44), 134--155

Saad, Y, 1996, Iterative Methods for Sparse Linear Systems, PWS Publishing Company, Boston, MA
"""
raise NotImplementedError

[docs]def real_gen_solve_bdilu(method, nnz, a, irow, icol, istb, indb, ipivp, ipivq, istr, idiag, b, m, tol, maxitn, x):
r"""
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.

.. _f11dg-py2-py-doc:

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

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

.. _f11dg-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'RGMRES'}

Restarted generalized minimum residual method.

:math:\mathrm{method} = \texttt{'CGS'}

:math:\mathrm{method} = \texttt{'BICGSTAB'}

Bi-conjugate gradient stabilized (:math:\ell) method.

:math:\mathrm{method} = \texttt{'TFQMR'}

Transpose-free quasi-minimal residual method.

**nnz** : int
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**a** : float, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**istb** : int, array-like, shape :math:\left(\textit{nb}+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**indb** : int, array-like, shape :math:\left(\textit{lindb}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**ipivp** : int, array-like, shape :math:\left(\textit{lindb}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**ipivq** : int, array-like, shape :math:\left(\textit{lindb}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**istr** : int, array-like, shape :math:\left(\textit{lindb}+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**idiag** : int, array-like, shape :math:\left(\textit{lindb}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:real_gen_precon_bdilu.

The arrays :math:\mathrm{istb}, :math:\mathrm{indb} and :math:\mathrm{a} together with the scalars :math:\textit{n}, :math:\mathrm{nnz}, :math:\textit{la}, :math:\textit{nb} and :math:\textit{lindb} must be the same values that were supplied in the preceding call to :meth:real_gen_precon_bdilu.

**b** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

**m** : int
If :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m} is the dimension of the restart subspace.

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m} is the order :math:\ell of the polynomial BI-CGSTAB method.

Otherwise, :math:\mathrm{m} is not referenced.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : float, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11dg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq n^2.

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:1)
On entry, :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \textit{nb}\leq n.

(errno :math:1)
On entry, :math:\mathrm{istb}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istb}[0]\geq 1.

(errno :math:1)
On entry, for :math:b = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istb}[b] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{istb}[b-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istb}[\textit{b}] > \mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

(errno :math:1)
On entry, :math:\mathrm{indb}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{indb}[\textit{m}-1]\leq n, for :math:\textit{m} = 1,2,\ldots,\mathrm{istb}[\textit{nb}]-1

(errno :math:1)
On entry, :math:\textit{lindb} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istb}[\textit{nb}]-1 = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{lindb}\geq \mathrm{istb}[\textit{nb}]-1.

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\texttt{'CGS'} or :math:\texttt{'BICGSTAB'}.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{method} = \texttt{'RGMRES'}, :math:1\leq \mathrm{m}\leq \mathrm{min}\left(n, \langle\mathit{\boldsymbol{value}}\rangle\right).

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:1\leq \mathrm{m}\leq \mathrm{min}\left(n, \langle\mathit{\boldsymbol{value}}\rangle\right).

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:2)
On entry, :math:\mathrm{irow}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{irow}[\textit{i}-1]\leq n, for :math:\textit{i} = 1,2,\ldots,\mathrm{nnz}.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:real_gen_precon_bdilu and real_gen_solve_bdilu.

(errno :math:2)
On entry, :math:\mathrm{icol}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{icol}[\textit{i}-1]\leq n, for :math:\textit{i} = 1,2,\ldots,\mathrm{nnz}.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:real_gen_precon_bdilu and real_gen_solve_bdilu.

(errno :math:2)
On entry, element :math:\langle\mathit{\boldsymbol{value}}\rangle of :math:\mathrm{a} was out of order.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:real_gen_precon_bdilu and real_gen_solve_bdilu.

(errno :math:2)
On entry, location :math:\langle\mathit{\boldsymbol{value}}\rangle of :math:\left(\mathrm{irow}, \mathrm{icol}\right) was a duplicate.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:real_gen_precon_bdilu and real_gen_solve_bdilu.

(errno :math:3)
The CS representation of the preconditioner is invalid.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:real_gen_precon_bdilu and real_gen_solve_bdilu.

(errno :math:4)
The required accuracy could not be obtained. However a reasonable accuracy may have been achieved. You should check the output value of :math:\mathrm{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 :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
Algorithmic breakdown. A solution is returned, although it is possible that it is completely inaccurate.

.. _f11dg-py2-py-notes:

**Notes**
real_gen_solve_bdilu solves a real sparse nonsymmetric linear system of equations:

.. math::
Ax = b\text{,}

using a preconditioned RGMRES (see Saad and Schultz (1986)), CGS (see Sonneveld (1989)), BI-CGSTAB(:math:\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 :math:LU factorization determined by :meth:real_gen_precon_bdilu as the preconditioning matrix.
A call to real_gen_solve_bdilu must always be preceded by a call to :meth:real_gen_precon_bdilu.
Alternative preconditioners for the same storage scheme are available by calling :meth:real_gen_solve_ilu or :meth:real_gen_solve_jacssor.

The matrix :math:A, and the preconditioning matrix :math:M, are represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}, as returned from :meth:real_gen_precon_bdilu.
The array :math:\mathrm{a} holds the nonzero entries in these matrices, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

real_gen_solve_bdilu is a Black Box function which calls :meth:real_gen_basic_setup, :meth:real_gen_basic_solver and :meth: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.

.. _f11dg-py2-py-references:

**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 :math:\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
"""
raise NotImplementedError

[docs]def real_gen_precon_jacobi(store, trans, init, niter, a, irow, icol, b, diag, check='N'):
r"""
real_gen_precon_jacobi computes the **approximate** solution of a real, symmetric or nonsymmetric, sparse system of linear equations applying a number of Jacobi iterations.
It is expected that real_gen_precon_jacobi will be used as a preconditioner for the iterative solution of real sparse systems of equations.

.. _f11dk-py2-py-doc:

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

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

.. _f11dk-py2-py-parameters:

**Parameters**
**store** : str, length 1
Specifies whether the matrix :math:A is stored using symmetric coordinate storage (SCS) (applicable only to a symmetric matrix :math:A) or coordinate storage (CS) (applicable to both symmetric and non-symmetric matrices).

:math:\mathrm{store} = \texttt{'N'}

The complete matrix :math:A is stored in CS format.

:math:\mathrm{store} = \texttt{'S'}

The lower triangle of the symmetric matrix :math:A is stored in SCS format.

**trans** : str, length 1
If :math:\mathrm{store} = \texttt{'N'}, specifies whether the approximate solution of :math:Ax = b or of :math:A^\mathrm{T}x = b is required.

:math:\mathrm{trans} = \texttt{'N'}

The approximate solution of :math:Ax = b is calculated.

:math:\mathrm{trans} = \texttt{'T'}

The approximate solution of :math:A^\mathrm{T}x = b is calculated.

Suggested value: if the matrix :math:A is symmetric and stored in CS format, it is recommended that :math:\mathrm{trans} = \texttt{'N'} for reasons of efficiency.

**init** : str, length 1
On first entry, :math:\mathrm{init} should be set to 'I', unless the diagonal elements of :math:A are already stored in the array :math:\mathrm{diag}. If :math:\mathrm{diag} already contains the diagonal of :math:A, it must be set to 'N'.

:math:\mathrm{init} = \texttt{'N'}

:math:\mathrm{diag} must contain the diagonal of :math:A.

:math:\mathrm{init} = \texttt{'I'}

:math:\mathrm{diag} will store the diagonal of :math:A on exit.

Suggested value: :math:\mathrm{init} = \texttt{'I'} on first entry; :math:\mathrm{init} = \texttt{'N'}, subsequently, unless :math:\mathrm{diag} has been overwritten.

**niter** : int
The number of Jacobi iterations requested.

**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
If :math:\mathrm{store} = \texttt{'N'}, the nonzero elements in the matrix :math:A (CS format).

If :math:\mathrm{store} = \texttt{'S'}, the nonzero elements in the lower triangle of the matrix :math:A (SCS format).

In both cases, the elements of either :math:A or of its lower triangle must be ordered by increasing row index and by increasing column index within each row.

Multiple entries for the same row and columns indices are not permitted.

The function :meth:real_gen_sort or :meth:real_symm_sort may be used to reorder the elements in this way for CS and SCS storage, respectively.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
If :math:\mathrm{store} = \texttt{'N'}, the row indices of the nonzero elements supplied in :math:\mathrm{a}.

If :math:\mathrm{store} = \texttt{'S'}, the row and column indices of the nonzero elements of the lower triangle of the matrix :math:A supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
If :math:\mathrm{store} = \texttt{'N'}, the column indices of the nonzero elements supplied in :math:\mathrm{a}.

If :math:\mathrm{store} = \texttt{'S'}, the row and column indices of the nonzero elements of the lower triangle of the matrix :math:A supplied in :math:\mathrm{a}.

**b** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

**diag** : float, array-like, shape :math:\left(n\right)
If :math:\mathrm{init} = \texttt{'N'}, the diagonal elements of :math:A.

**check** : str, length 1, optional
Specifies whether or not the CS or SCS representation of the matrix :math:A should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried out on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow}, :math:\mathrm{icol}; if :math:\mathrm{init} = \texttt{'N'}, :math:\mathrm{diag} is also checked.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dkf.html#fcomments2>__.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
The approximate solution vector :math:x_{\mathrm{niter}}.

**diag** : float, ndarray, shape :math:\left(n\right)
If :math:\mathrm{init} = \texttt{'N'}, unchanged on exit.

If :math:\mathrm{init} = \texttt{'I'}, the diagonal elements of :math:A.

.. _f11dk-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{niter} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{niter}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'N'} or :math:\texttt{'C'}.

(errno :math:1)
On entry, :math:\mathrm{init} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{init} = \texttt{'N'} or :math:\texttt{'I'}.

(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{store} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{store} = \texttt{'N'} or :math:\texttt{'S'}.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n^2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n\times \left(n+1\right)/2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq n.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[\textit{I}-1]\geq 1 and :math:\mathrm{irow}[\textit{I}-1]\leq n.

(errno :math:4)
On entry, the element :math:\mathrm{diag}[\textit{I}-1] is zero: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:5)
On entry, the diagonal element of the :math:\textit{I}\ th row is zero or missing: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

.. _f11dk-py2-py-notes:

**Notes**
real_gen_precon_jacobi computes the **approximate** solution of the real sparse system of linear equations :math:Ax = b using :math:\mathrm{niter} iterations of the Jacobi algorithm (see also Golub and Van Loan (1996) and Young (1971)):

.. math::
x_{{k+1}} = x_k+D^{-1}\left(b-Ax_k\right)

where :math:k = 1,2,\ldots,\mathrm{niter} and :math:x_0 = 0.

real_gen_precon_jacobi can be used both for nonsymmetric and symmetric systems of equations.
For symmetric matrices, either all nonzero elements of the matrix :math:A can be supplied using coordinate storage (CS), or only the nonzero elements of the lower triangle of :math:A, using symmetric coordinate storage (SCS) (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html>__).

It is expected that real_gen_precon_jacobi will be used as a preconditioner for the iterative solution of real sparse systems of equations, using either the suite comprising the functions :meth:real_symm_basic_setup, :meth:real_symm_basic_solver and :meth:real_symm_basic_diag, for symmetric systems, or the suite comprising the functions :meth:real_gen_basic_setup, :meth:real_gen_basic_solver and :meth:real_gen_basic_diag, for nonsymmetric systems of equations.

.. _f11dk-py2-py-references:

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

Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def complex_gen_precon_ilu(nnz, a, irow, icol, n=None, lfill=0, dtol=0.0, pstrat='C', milu='N', ipivp=None, ipivq=None):
r"""
complex_gen_precon_ilu computes an incomplete :math:LU factorization of a complex sparse non-Hermitian matrix, represented in coordinate storage format.
This factorization may be used as a preconditioner in combination with :meth:complex_gen_solve_ilu or :meth:complex_gen_basic_solver.

.. _f11dn-py2-py-doc:

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

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

.. _f11dn-py2-py-parameters:

**Parameters**
**nnz** : int
The number of nonzero elements in the matrix :math:A.

**a** : complex, array-like, shape :math:\left(\textit{la}\right)
The nonzero elements in the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**n** : None or int, optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:\mathrm{ipivp}.\mathrm{shape}[0].

:math:n, the order of the matrix :math:A.

**lfill** : int, optional
If :math:\mathrm{lfill}\geq 0 its value is the maximum level of fill allowed in the decomposition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments2>__). A negative value of :math:\mathrm{lfill} indicates that :math:\mathrm{dtol} will be used to control the fill instead.

**dtol** : float, optional
If :math:\mathrm{lfill} < 0, :math:\mathrm{dtol} is used as a drop tolerance to control the fill-in (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments2>__); otherwise :math:\mathrm{dtol} is not referenced.

**pstrat** : str, length 1, optional
Specifies the pivoting strategy to be adopted.

:math:\mathrm{pstrat} = \texttt{'N'}

No pivoting is carried out.

:math:\mathrm{pstrat} = \texttt{'U'}

Pivoting is carried out according to the user-defined input values of :math:\mathrm{ipivp} and :math:\mathrm{ipivq}.

:math:\mathrm{pstrat} = \texttt{'P'}

Partial pivoting by columns for stability is carried out.

:math:\mathrm{pstrat} = \texttt{'C'}

Complete pivoting by rows for sparsity, and by columns for stability, is carried out.

**milu** : str, length 1, optional
Indicates whether or not the factorization should be modified to preserve row-sums (see Choice of Arguments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments3>__).

:math:\mathrm{milu} = \texttt{'M'}

The factorization is modified.

:math:\mathrm{milu} = \texttt{'N'}

The factorization is not modified.

**ipivp** : None or int, array-like, shape :math:\left(\mathrm{n}\right), optional
If :math:\mathrm{pstrat} = \texttt{'U'}, :math:\mathrm{ipivp}[k-1] and :math:\mathrm{ipivq}[k-1] must specify the row and column indices of the element used as a pivot at elimination stage :math:k. Otherwise :math:\mathrm{ipivp} and :math:\mathrm{ipivq} need not be initialized.

**ipivq** : None or int, array-like, shape :math:\left(\mathrm{n}\right), optional
If :math:\mathrm{pstrat} = \texttt{'U'}, :math:\mathrm{ipivp}[k-1] and :math:\mathrm{ipivq}[k-1] must specify the row and column indices of the element used as a pivot at elimination stage :math:k. Otherwise :math:\mathrm{ipivp} and :math:\mathrm{ipivq} need not be initialized.

**Returns**
**a** : complex, ndarray, shape :math:\left(\mathrm{nnz}+\mathrm{nnzc}\right)
The first :math:\mathrm{nnz} entries of :math:\mathrm{a} contain the nonzero elements of :math:A and the next :math:\mathrm{nnzc} entries contain the elements of the matrix :math:C. Matrix elements are ordered by increasing row index, and by increasing column index within each row.

**irow** : int, ndarray, shape :math:\left(\mathrm{nnz}+\mathrm{nnzc}\right)
The row indices of the nonzero elements returned in :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\mathrm{nnz}+\mathrm{nnzc}\right)
The column indices of the nonzero elements returned in :math:\mathrm{a}.

**ipivp** : int, ndarray, shape :math:\left(\mathrm{n}\right)
The pivot indices. If :math:\mathrm{ipivp}[k-1] = i and :math:\mathrm{ipivq}[k-1] = j then the element in row :math:i and column :math:j was used as the pivot at elimination stage :math:k.

**ipivq** : int, ndarray, shape :math:\left(\mathrm{n}\right)
The pivot indices. If :math:\mathrm{ipivp}[k-1] = i and :math:\mathrm{ipivq}[k-1] = j then the element in row :math:i and column :math:j was used as the pivot at elimination stage :math:k.

**istr** : int, ndarray, shape :math:\left(\mathrm{n}+1\right)
:math:\mathrm{istr}[\textit{i}-1]-1, for :math:\textit{i} = 1,2,\ldots,\mathrm{n}, is the starting address in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:i of the matrix :math:C. :math:\mathrm{istr}[\mathrm{n}]-1 is the address of the last nonzero element in :math:C plus one.

**idiag** : int, ndarray, shape :math:\left(\mathrm{n}\right)
:math:\mathrm{idiag}[\textit{i}-1], for :math:\textit{i} = 1,2,\ldots,\mathrm{n}, holds the index of arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} which holds the diagonal element in row :math:i of the matrix :math:C.

**nnzc** : int
The number of nonzero elements in the matrix :math:C.

**npivm** : int
If :math:\mathrm{npivm} > 0 it gives the number of pivots which were modified during the factorization to ensure that :math:M exists.

If :math:\mathrm{npivm} = -1 no pivot modifications were required, but a local restart occurred (see Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments25>__).

The quality of the preconditioner will generally depend on the returned value of :math:\mathrm{npivm}.

If :math:\mathrm{npivm} is large the preconditioner may not be satisfactory.

In this case it may be advantageous to call complex_gen_precon_ilu again with an increased value of :math:\mathrm{lfill}, a reduced value of :math:\mathrm{dtol}, or set :math:\mathrm{pstrat} = \texttt{'C'}.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments4>__.

.. _f11dn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq \mathrm{n}^2

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{milu} \neq \texttt{'M'} or :math:\texttt{'N'}: :math:\mathrm{milu} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{pstrat} \neq \texttt{'N'}, :math:\texttt{'U'}, :math:\texttt{'P'} or :math:\texttt{'C'}: :math:\mathrm{pstrat} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{dtol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dtol}\geq 0.0

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{icol}[\textit{i}-1]\leq \mathrm{n}, for :math:\textit{i} = 1,2,\ldots,\mathrm{nnz}

(errno :math:2)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{irow}[\textit{i}-1]\leq \mathrm{n}, for :math:\textit{i} = 1,2,\ldots,\mathrm{nnz}

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipivq} is repeated.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipivq} lies outside the range :math:\left[1, \mathrm{n}\right].

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipivp} is repeated.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipivp} lies outside the range :math:\left[1, \mathrm{n}\right].

(errno :math:4)
The number of nonzero entries in the decomposition is too large. The decomposition has been terminated before completion. Either increase :math:\textit{la}, or reduce the fill by reducing :math:\mathrm{lfill}, or increasing :math:\mathrm{dtol}.

(errno :math:5)
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG <https://www.nag.com>__ for assistance.

(errno :math:14)
Either :math:\mathrm{n} or the pair :math:\mathrm{ipivp} and :math:\mathrm{ipivq}, and not all three, must be provided.

.. _f11dn-py2-py-notes:

**Notes**
complex_gen_precon_ilu computes an incomplete :math:LU factorization (see Meijerink and Van der Vorst (1977) and Meijerink and Van der Vorst (1981)) of a complex sparse non-Hermitian :math:n\times n matrix :math:A.
The factorization is intended primarily for use as a preconditioner with one of the iterative solvers :meth:complex_gen_solve_ilu or :meth:complex_gen_basic_solver.

The decomposition is written in the form

.. math::
A = M+R\text{,}

where

.. math::
M = PLDUQ

and :math:L is lower triangular with unit diagonal elements, :math:D is diagonal, :math:U is upper triangular with unit diagonals, :math:P and :math:Q are permutation matrices, and :math:R is a remainder matrix.

The amount of fill-in occurring in the factorization can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill :math:\mathrm{lfill}, or the drop tolerance :math:\mathrm{dtol}.

The argument :math:\mathrm{pstrat} defines the pivoting strategy to be used.
The options currently available are no pivoting, user-defined pivoting, partial pivoting by columns for stability, and complete pivoting by rows for sparsity and by columns for stability.
The factorization may optionally be modified to preserve the row-sums of the original matrix.

The sparse matrix :math:A is represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__).
The array :math:\mathrm{a} stores all the nonzero elements of the matrix :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.
Multiple nonzero elements may not be specified for the same row and column index.

The preconditioning matrix :math:M is returned in terms of the CS representation of the matrix

.. math::
C = L+D^{-1}+U-2I\text{.}

Further algorithmic details are given in Algorithmic Details <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments25>__.

.. _f11dn-py2-py-references:

**References**
Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148--162

Meijerink, J and Van der Vorst, H, 1981, Guidelines for the usage of incomplete decompositions in solving sets of linear equations as they occur in practical problems, J. Comput. Phys. (44), 134--155

--------
:meth:naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main
"""
raise NotImplementedError

[docs]def complex_gen_precon_ilu_solve(trans, a, irow, icol, ipivp, ipivq, istr, idiag, y, check='N'):
r"""
complex_gen_precon_ilu_solve solves a system of complex linear equations involving the incomplete :math:LU preconditioning matrix generated by :meth:complex_gen_precon_ilu.

.. _f11dp-py2-py-doc:

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

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

.. _f11dp-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether or not the matrix :math:M is transposed.

:math:\mathrm{trans} = \texttt{'N'}

:math:Mx = y is solved.

:math:\mathrm{trans} = \texttt{'T'}

:math:M^\mathrm{T}x = y is solved.

**a** : complex, array-like, shape :math:\left(\textit{la}\right)
The values returned in the array :math:\mathrm{a} by a previous call to :meth:complex_gen_precon_ilu.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

**ipivp** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

**ipivq** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

**istr** : int, array-like, shape :math:\left(n+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

**idiag** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

**y** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:y.

**check** : str, length 1, optional
Specifies whether or not the CS representation of the matrix :math:M should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried on the values of :math:\textit{n}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dpf.html#fcomments2>__.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
The solution vector :math:x.

.. _f11dp-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, :math:\mathrm{ipivq}[i-1] is a repeated value: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ipivq}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ipivq}[i-1]\geq 1 and :math:\mathrm{ipivq}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{ipivp}[i-1] is a repeated value: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ipivp}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ipivp}[i-1]\geq 1 and :math:\mathrm{ipivp}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr}[i-1] is inconsistent with :math:\mathrm{irow}: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{idiag}[i-1] appears to be incorrect: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[i-1],\mathrm{icol}[i-1]) is a duplicate: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr} appears to be invalid.

.. _f11dp-py2-py-notes:

**Notes**
complex_gen_precon_ilu_solve solves a system of complex linear equations

.. math::
Mx = y\text{, or }\quad M^\mathrm{T}x = y\text{,}

according to the value of the argument :math:\mathrm{trans}, where the matrix :math:M = PLDUQ corresponds to an incomplete :math:LU decomposition of a complex sparse matrix stored in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__), as generated by :meth:complex_gen_precon_ilu.

In the above decomposition :math:L is a lower triangular sparse matrix with unit diagonal elements, :math:D is a diagonal matrix, :math:U is an upper triangular sparse matrix with unit diagonal elements and, :math:P and :math:Q are permutation matrices. :math:L, :math:D and :math:U are supplied to complex_gen_precon_ilu_solve through the matrix

.. math::
C = L+D^{-1}+U-2I

which is an :math:\textit{n} by :math:\textit{n} sparse matrix, stored in CS format, as returned by :meth:complex_gen_precon_ilu.
The permutation matrices :math:P and :math:Q are returned from :meth:complex_gen_precon_ilu via the arrays :math:\mathrm{ipivp} and :math:\mathrm{ipivq}.

It is envisaged that a common use of complex_gen_precon_ilu_solve will be to carry out the preconditioning step required in the application of :meth:complex_gen_basic_solver to sparse complex linear systems. complex_gen_precon_ilu_solve is used for this purpose by the Black Box function :meth:complex_gen_solve_ilu.

complex_gen_precon_ilu_solve may also be used in combination with :meth:complex_gen_precon_ilu to solve a sparse system of complex linear equations directly (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments4>__).
"""
raise NotImplementedError

[docs]def complex_gen_solve_ilu(method, nnz, a, irow, icol, ipivp, ipivq, istr, idiag, b, m, tol, maxitn, x):
r"""
complex_gen_solve_ilu 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 incomplete :math:LU preconditioning.

.. _f11dq-py2-py-doc:

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

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

.. _f11dq-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'RGMRES'}

Restarted generalized minimum residual method.

:math:\mathrm{method} = \texttt{'CGS'}

:math:\mathrm{method} = \texttt{'BICGSTAB'}

Bi-conjugate gradient stabilized (:math:\ell) method.

:math:\mathrm{method} = \texttt{'TFQMR'}

Transpose-free quasi-minimal residual method.

**nnz** : int
The number of nonzero elements in the matrix :math:A. This **must** be the same value as was supplied in the preceding call to :meth:complex_gen_precon_ilu.

**a** : complex, array-like, shape :math:\left(\textit{la}\right)
The values returned in the array :math:\mathrm{a} by a previous call to :meth:complex_gen_precon_ilu.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**ipivp** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**ipivq** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**istr** : int, array-like, shape :math:\left(n+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**idiag** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} by a previous call to :meth:complex_gen_precon_ilu.

:math:\mathrm{ipivp} and :math:\mathrm{ipivq} are restored on exit.

**b** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

**m** : int
If :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m} is the dimension of the restart subspace.

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m} is the order :math:\ell of the polynomial BI-CGSTAB method.

Otherwise, :math:\mathrm{m} is not referenced.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },10\epsilon,\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : complex, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11dq-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m}\geq 1 and :math:\mathrm{m}\leq \mathrm{min}\left(n, \langle\mathit{\boldsymbol{value}}\rangle\right).

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\texttt{'CGS'} or :math:\texttt{'BICGSTAB'}.

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq n^2.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[i-1],\mathrm{icol}[i-1]) is a duplicate: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
The CS representation of the preconditioner is invalid.

(errno :math:6)
Algorithmic breakdown. A solution is returned, although it is possible that it is completely inaccurate.

(errno :math:7)
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG <https://www.nag.com>__ for assistance.

**Warns**
**NagAlgorithmicWarning**
(errno :math:4)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

.. _f11dq-py2-py-notes:

**Notes**
complex_gen_solve_ilu solves a complex sparse non-Hermitian linear system of equations

.. math::
Ax = b\text{,}

using a preconditioned RGMRES (see Saad and Schultz (1986)), CGS (see Sonneveld (1989)), BI-CGSTAB(:math:\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_ilu uses the incomplete :math:LU factorization determined by :meth:complex_gen_precon_ilu as the preconditioning matrix.
A call to complex_gen_solve_ilu must always be preceded by a call to :meth:complex_gen_precon_ilu.
Alternative preconditioners for the same storage scheme are available by calling :meth:complex_gen_solve_jacssor.

The matrix :math:A, and the preconditioning matrix :math:M, are represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}, as returned from :meth:complex_gen_precon_ilu.
The array :math:\mathrm{a} holds the nonzero entries in these matrices, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

complex_gen_solve_ilu is a Black Box function which calls :meth:complex_gen_basic_setup, :meth:complex_gen_basic_solver and :meth: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.

.. _f11dq-py2-py-references:

**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 :math:\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

--------
:meth:naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main
"""
raise NotImplementedError

[docs]def complex_gen_precon_ssor_solve(trans, a, irow, icol, rdiag, omega, y, check='N'):
r"""
complex_gen_precon_ssor_solve solves a system of linear equations involving the preconditioning matrix corresponding to SSOR applied to a complex sparse non-Hermitian matrix, represented in coordinate storage format.

.. _f11dr-py2-py-doc:

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

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

.. _f11dr-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether or not the matrix :math:M is transposed.

:math:\mathrm{trans} = \texttt{'N'}

:math:Mx = y is solved.

:math:\mathrm{trans} = \texttt{'T'}

:math:M^\mathrm{H}x = y is solved.

**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements in the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**rdiag** : complex, array-like, shape :math:\left(n\right)
The elements of the diagonal matrix :math:D^{-1}, where :math:D is the diagonal part of :math:A.

**omega** : float
The relaxation parameter :math:\omega.

**y** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:y.

**check** : str, length 1, optional
Specifies whether or not the CS representation of the matrix :math:M should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow}, :math:\mathrm{icol} and :math:\mathrm{omega}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11drf.html#fcomments2>__.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
The solution vector :math:x.

.. _f11dr-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{check} \neq \texttt{'C'} or :math:\texttt{'N'}: :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{trans} \neq \texttt{'N'} or :math:\texttt{'T'}: :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{omega} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0 < \mathrm{omega} < 2.0

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n^2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:4)
The matrix :math:A has no diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

.. _f11dr-py2-py-notes:

**Notes**
complex_gen_precon_ssor_solve solves a system of linear equations

.. math::
Mx = y\text{, or }\quad M^\mathrm{H}x = y\text{,}

according to the value of the argument :math:\mathrm{trans}, where the matrix

.. math::
M = \frac{1}{{\omega \left(2-\omega \right)}}\left(D+\omega L\right)D^{-1}\left(D+\omega U\right)

corresponds to symmetric successive-over-relaxation (SSOR) Young (1971) applied to a linear system :math:Ax = b, where :math:A is a complex sparse non-Hermitian matrix stored in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__).

In the definition of :math:M given above :math:D is the diagonal part of :math:A, :math:L is the strictly lower triangular part of :math:A, :math:U is the strictly upper triangular part of :math:A, and :math:\omega is a user-defined relaxation parameter.

It is envisaged that a common use of complex_gen_precon_ssor_solve will be to carry out the preconditioning step required in the application of :meth:complex_gen_basic_solver to sparse linear systems. complex_gen_precon_ssor_solve is also used for this purpose by the Black Box function :meth:complex_gen_solve_jacssor.

.. _f11dr-py2-py-references:

**References**
Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def complex_gen_solve_jacssor(method, precon, a, irow, icol, omega, b, m, tol, maxitn, x):
r"""
complex_gen_solve_jacssor 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, without preconditioning, with Jacobi, or with SSOR preconditioning.

.. _f11ds-py2-py-doc:

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

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

.. _f11ds-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'RGMRES'}

Restarted generalized minimum residual method.

:math:\mathrm{method} = \texttt{'CGS'}

:math:\mathrm{method} = \texttt{'BICGSTAB'}

Bi-conjugate gradient stabilized (:math:\ell) method.

:math:\mathrm{method} = \texttt{'TFQMR'}

Transpose-free quasi-minimal residual method.

**precon** : str, length 1
Specifies the type of preconditioning to be used.

:math:\mathrm{precon} = \texttt{'N'}

No preconditioning.

:math:\mathrm{precon} = \texttt{'J'}

Jacobi.

:math:\mathrm{precon} = \texttt{'S'}

Symmetric successive-over-relaxation (SSOR).

**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**omega** : float
If :math:\mathrm{precon} = \texttt{'S'}, :math:\mathrm{omega} is the relaxation parameter :math:\omega to be used in the SSOR method. Otherwise :math:\mathrm{omega} need not be initialized and is not referenced.

**b** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

**m** : int
If :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m} is the dimension of the restart subspace.

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m} is the order :math:\ell of the polynomial BI-CGSTAB method.

Otherwise, :math:\mathrm{m} is not referenced.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },10\epsilon,\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : complex, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11ds-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0 < \mathrm{m}\leq \mathrm{min}\left(n, \langle\mathit{\boldsymbol{value}}\rangle\right).

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\texttt{'CGS'} or :math:\texttt{'BICGSTAB'}.

(errno :math:1)
On entry, :math:\mathrm{omega} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0 < \mathrm{omega} < 2.0

(errno :math:1)
On entry, :math:\mathrm{precon} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{precon} = \texttt{'N'}, :math:\texttt{'J'} or :math:\texttt{'S'}.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \textit{nnz}\leq n^2.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
The matrix :math:A has a zero diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
The matrix :math:A has no diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:6)
Algorithmic breakdown. A solution is returned, although it is possible that it is completely inaccurate.

(errno :math:7)
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG <https://www.nag.com>__ for assistance.

**Warns**
**NagAlgorithmicWarning**
(errno :math:4)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

.. _f11ds-py2-py-notes:

**Notes**
complex_gen_solve_jacssor solves a complex sparse non-Hermitian system of linear equations:

.. math::
Ax = b\text{,}

using an RGMRES (see Saad and Schultz (1986)), CGS (see Sonneveld (1989)), BI-CGSTAB(:math:\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_jacssor allows the following choices for the preconditioner:

-   no preconditioning;

-   Jacobi preconditioning (see Young (1971));

-   symmetric successive-over-relaxation (SSOR) preconditioning (see Young (1971)).

For incomplete :math:LU (ILU) preconditioning see :meth:complex_gen_solve_ilu.

The matrix :math:A is represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}.
The array :math:\mathrm{a} holds the nonzero entries in the matrix, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

complex_gen_solve_jacssor is a Black Box function which calls :meth:complex_gen_basic_setup, :meth:complex_gen_basic_solver and :meth: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.

.. _f11ds-py2-py-references:

**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 :math:\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

Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def complex_gen_precon_bdilu(n, nnz, a, irow, icol, istb, indb, lfill, dtol, milu, ipivp, ipivq, pstrat=None):
r"""
complex_gen_precon_bdilu computes a block diagonal incomplete :math:LU factorization of a complex sparse non-Hermitian matrix, represented in coordinate storage format.
The diagonal blocks may be composed of arbitrary rows and the corresponding columns, and may overlap.
This factorization can be used to provide a block Jacobi or additive Schwarz preconditioner, for use in combination with :meth:complex_gen_solve_bdilu or :meth:complex_gen_basic_solver.

.. _f11dt-py2-py-doc:

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

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

.. _f11dt-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the order of the matrix :math:A.

**nnz** : int
The number of nonzero elements in the matrix :math:A.

**a** : complex, array-like, shape :math:\left(\textit{la}\right)
The nonzero elements in the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**istb** : int, array-like, shape :math:\left(\textit{nb}+1\right)
:math:\mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}, holds the indices in arrays :math:\mathrm{indb}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq} and :math:\mathrm{idiag} that, on successful exit from this function, define block :math:\textit{b}. :math:\mathrm{istb}[{\textit{nb}+1}-1] holds the sum of the number of rows in all blocks plus :math:\mathrm{istb}[0].

**indb** : int, array-like, shape :math:\left(\textit{lindb}\right)
:math:\mathrm{indb} must hold the row indices appearing in each diagonal block, stored consecutively. Thus the elements :math:\mathrm{indb}[\mathrm{istb}[b-1]-1] to :math:\mathrm{indb}[\mathrm{istb}[b]-2] are the row indices in the :math:\textit{b}\ th block, for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

**lfill** : int, array-like, shape :math:\left(\textit{nb}\right)
If :math:\mathrm{lfill}[b-1]\geq 0 its value is the maximum level of fill allowed in the decomposition of the block :math:b (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments2>__). A negative value of :math:\mathrm{lfill}[b-1] indicates that :math:\mathrm{dtol}[b-1] will be used to control the fill in block :math:b instead.

**dtol** : float, array-like, shape :math:\left(\textit{nb}\right)
If :math:\mathrm{lfill}[b-1] < 0 then :math:\mathrm{dtol}[b-1] is used as a drop tolerance in block :math:b to control the fill-in (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments2>__); otherwise :math:\mathrm{dtol}[b-1] is not referenced.

**milu** : str, length 1, array-like, shape :math:\left(\textit{nb}\right)
:math:\mathrm{milu}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}, indicates whether or not the factorization in block :math:\textit{b} should be modified to preserve row-sums (see Further Comments for complex_gen_precon_ilu <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments3>__).

:math:\mathrm{milu}[b-1] = \texttt{'M'}

The factorization is modified.

:math:\mathrm{milu}[b-1] = \texttt{'N'}

The factorization is not modified.

**ipivp** : int, array-like, shape :math:\left(\textit{lindb}\right)
If :math:\mathrm{pstrat}[b-1] = \texttt{'U'}, :math:\mathrm{ipivp}[\mathrm{istb}[b-1]+k-2] and :math:\mathrm{ipivq}[\mathrm{istb}[b-1]+k-2] must specify the row and column indices of the element used as a pivot at elimination stage :math:k of the factorization of the block. Otherwise :math:\mathrm{ipivp} and :math:\mathrm{ipivq} need not be initialized.

**ipivq** : int, array-like, shape :math:\left(\textit{lindb}\right)
If :math:\mathrm{pstrat}[b-1] = \texttt{'U'}, :math:\mathrm{ipivp}[\mathrm{istb}[b-1]+k-2] and :math:\mathrm{ipivq}[\mathrm{istb}[b-1]+k-2] must specify the row and column indices of the element used as a pivot at elimination stage :math:k of the factorization of the block. Otherwise :math:\mathrm{ipivp} and :math:\mathrm{ipivq} need not be initialized.

**pstrat** : None or str, length 1, array-like, shape :math:\left(\textit{nb}\right), optional
Note: if this argument is **None** then a default value will be used, determined as follows: :math:\texttt{'C'}.

:math:\mathrm{pstrat}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}, specifies the pivoting strategy to be adopted in the block as follows:

:math:\mathrm{pstrat}[b-1] = \texttt{'N'}

No pivoting is carried out.

:math:\mathrm{pstrat}[b-1] = \texttt{'U'}

Pivoting is carried out according to the user-defined input values of :math:\mathrm{ipivp} and :math:\mathrm{ipivq}.

:math:\mathrm{pstrat}[b-1] = \texttt{'P'}

Partial pivoting by columns for stability is carried out.

:math:\mathrm{pstrat}[b-1] = \texttt{'C'}

Complete pivoting by rows for sparsity, and by columns for stability, is carried out.

**Returns**
**a** : complex, ndarray, shape :math:\left(\textit{la}\right)
The first :math:\mathrm{nnz} entries of :math:\mathrm{a} contain the nonzero elements of :math:A and the next :math:\mathrm{nnzc} entries contain the elements of the matrices :math:C_{\textit{b}}, for :math:\textit{b} = 1,2,\ldots,\textit{nb} stored consecutively. Within each block the matrix elements are ordered by increasing row index, and by increasing column index within each row.

**irow** : int, ndarray, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements returned in :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements returned in :math:\mathrm{a}.

**ipivp** : int, ndarray, shape :math:\left(\textit{lindb}\right)
The row and column indices of the pivot elements, arranged consecutively for each block, as for :math:\mathrm{indb}. If :math:\mathrm{ipivp}[\mathrm{istb}[b-1]+k-2] = i and :math:\mathrm{ipivq}[\mathrm{istb}[b-1]+k-2] = j, the element in row :math:i and column :math:j of :math:A_b was used as the pivot at elimination stage :math:k.

**ipivq** : int, ndarray, shape :math:\left(\textit{lindb}\right)
The row and column indices of the pivot elements, arranged consecutively for each block, as for :math:\mathrm{indb}. If :math:\mathrm{ipivp}[\mathrm{istb}[b-1]+k-2] = i and :math:\mathrm{ipivq}[\mathrm{istb}[b-1]+k-2] = j, the element in row :math:i and column :math:j of :math:A_b was used as the pivot at elimination stage :math:k.

**istr** : int, ndarray, shape :math:\left(\textit{lindb}+1\right)
:math:\mathrm{istr}[\mathrm{istb}[\textit{b}-1]+\textit{k}-2], gives the index in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:\textit{k} of the matrix :math:C_{\textit{b}}, for :math:\textit{k} = 1,2,\ldots,\mathrm{istb}[{\textit{b}+1}-1]-\mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

:math:\mathrm{istr}[\mathrm{istb}[\textit{nb}]-1] contains :math:\mathrm{nnz}+\mathrm{nnzc}+1.

**idiag** : int, ndarray, shape :math:\left(\textit{lindb}\right)
:math:\mathrm{idiag}[\mathrm{istb}[\textit{b}-1]+\textit{k}-2], gives the index in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of the diagonal element in row :math:\textit{k} of the matrix :math:C_{\textit{b}}, for :math:\textit{k} = 1,2,\ldots,\mathrm{istb}[{\textit{b}+1}-1]-\mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

**nnzc** : int
The sum total number of nonzero elements in the matrices :math:C_{\textit{b}}, for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

**npivm** : int, ndarray, shape :math:\left(\textit{nb}\right)
If :math:\mathrm{npivm}[b-1] > 0 it gives the number of pivots which were modified during the factorization to ensure that :math:M_b exists.

If :math:\mathrm{npivm}[\textit{b}-1] = -1 no pivot modifications were required, but a local restart occurred (see Further Comments for complex_gen_precon_ilu <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dnf.html#fcomments25>__). The quality of the preconditioner will generally depend on the returned values of :math:\mathrm{npivm}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

If :math:\mathrm{npivm}[b-1] is large, for some :math:b, the preconditioner may not be satisfactory.

In this case it may be advantageous to call complex_gen_precon_bdilu again with an increased value of :math:\mathrm{lfill}[b-1], a reduced value of :math:\mathrm{dtol}[b-1], or :math:\mathrm{pstrat}[b-1] = \texttt{'C'}.

.. _f11dt-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:1)
On entry, :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \textit{nb}\leq \mathrm{n}.

(errno :math:1)
On entry, :math:\mathrm{istb}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istb}[0]\geq 1.

(errno :math:1)
On entry, for :math:b = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istb}[b] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{istb}[b-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istb}[\textit{b}] > \mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

(errno :math:1)
On entry, :math:\mathrm{indb}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{indb}[\textit{m}-1]\leq \mathrm{n}, for :math:\textit{m} = 1,2,\ldots,\mathrm{istb}[\textit{nb}]-1

(errno :math:1)
On entry, :math:\textit{lindb} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istb}[\textit{nb}]-1 = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{lindb}\geq \mathrm{istb}[\textit{nb}]-1.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq \mathrm{n}^2.

(errno :math:1)
On entry, :math:\mathrm{dtol}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dtol}[\textit{b}-1]\geq 0.0, for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

(errno :math:1)
On entry, :math:\mathrm{pstrat}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{pstrat}[b-1] = \texttt{'N'}, :math:\texttt{'U'}, :math:\texttt{'P'} or :math:\texttt{'C'} for all :math:b.

(errno :math:1)
On entry, :math:\mathrm{milu}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{milu}[b-1] = \texttt{'M'} or :math:\texttt{'N'} for all :math:b.

(errno :math:2)
On entry, :math:\mathrm{irow}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{irow}[\textit{i}-1]\leq \mathrm{n}, for :math:\textit{i} = 1,2,\ldots,\mathrm{nnz}.

(errno :math:2)
On entry, :math:\mathrm{icol}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{icol}[\textit{j}-1]\leq \mathrm{n}, for :math:\textit{j} = 1,2,\ldots,\mathrm{nnz}.

(errno :math:2)
On entry, element :math:\langle\mathit{\boldsymbol{value}}\rangle of :math:\mathrm{a} was out of order.

(errno :math:2)
On entry, location :math:\langle\mathit{\boldsymbol{value}}\rangle of :math:\left(\mathrm{irow}, \mathrm{icol}\right) was a duplicate.

(errno :math:3)
On entry, the user-supplied value of :math:\mathrm{ipivp} for block :math:\langle\mathit{\boldsymbol{value}}\rangle lies outside its range.

(errno :math:3)
On entry, the user-supplied value of :math:\mathrm{ipivp} for block :math:\langle\mathit{\boldsymbol{value}}\rangle was repeated.

(errno :math:3)
On entry, the user-supplied value of :math:\mathrm{ipivq} for block :math:\langle\mathit{\boldsymbol{value}}\rangle lies outside its range.

(errno :math:3)
On entry, the user-supplied value of :math:\mathrm{ipivq} for block :math:\langle\mathit{\boldsymbol{value}}\rangle was repeated.

(errno :math:4)
The number of nonzero entries in the decomposition is too large.

The decomposition has been terminated before completion.

Either increase :math:\textit{la}, or reduce the fill by reducing :math:\mathrm{lfill}, or increasing :math:\mathrm{dtol}.

.. _f11dt-py2-py-notes:

**Notes**
complex_gen_precon_bdilu computes an incomplete :math:LU factorization (see Meijerink and Van der Vorst (1977) and Meijerink and Van der Vorst (1981)) of the (possibly overlapping) diagonal blocks :math:A_b, :math:b = 1,2,\ldots,\textit{nb}, of a complex sparse non-Hermitian :math:n\times n matrix :math:A.
The factorization is intended primarily for use as a block Jacobi or additive Schwarz preconditioner (see Saad (1996)), with one of the iterative solvers :meth:complex_gen_solve_bdilu and :meth:complex_gen_basic_solver.

The :math:\textit{nb} diagonal blocks need not consist of consecutive rows and columns of :math:A, but may be composed of arbitrarily indexed rows, and the corresponding columns, as defined in the arguments :math:\mathrm{indb} and :math:\mathrm{istb}.
Any given row or column index may appear in more than one diagonal block, resulting in overlap.
Each diagonal block :math:A_b, :math:b = 1,2,\ldots,\textit{nb}, is factorized as:

.. math::
A_b = M_b+R_b

where

.. math::
M_b = P_bL_bD_bU_bQ_b

and :math:L_b is lower triangular with unit diagonal elements, :math:D_b is diagonal, :math:U_b is upper triangular with unit diagonals, :math:P_b and :math:Q_b are permutation matrices, and :math:R_b is a remainder matrix.

The amount of fill-in occurring in the factorization of block :math:b can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill :math:\mathrm{lfill}[b-1], or the drop tolerance :math:\mathrm{dtol}[b-1].

The parameter :math:\mathrm{pstrat}[b-1] defines the pivoting strategy to be used in block :math:b.
The options currently available are no pivoting, user-defined pivoting, partial pivoting by columns for stability, and complete pivoting by rows for sparsity and by columns for stability.
The factorization may optionally be modified to preserve the row-sums of the original block matrix.

The sparse matrix :math:A is represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__).
The array :math:\mathrm{a} stores all the nonzero elements of the matrix :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.
Multiple nonzero elements may not be specified for the same row and column index.

The preconditioning matrices :math:M_b, :math:b = 1,2,\ldots,\textit{nb}, are returned in terms of the CS representations of the matrices

.. math::
C_b = L_b+D^{-1}_b+U_b-2I\text{.}

.. _f11dt-py2-py-references:

**References**
Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148--162

Meijerink, J and Van der Vorst, H, 1981, Guidelines for the usage of incomplete decompositions in solving sets of linear equations as they occur in practical problems, J. Comput. Phys. (44), 134--155

Saad, Y, 1996, Iterative Methods for Sparse Linear Systems, PWS Publishing Company, Boston, MA
"""
raise NotImplementedError

[docs]def complex_gen_solve_bdilu(method, nnz, a, irow, icol, istb, indb, ipivp, ipivq, istr, idiag, b, m, tol, maxitn, x):
r"""
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.

.. _f11du-py2-py-doc:

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

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

.. _f11du-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'RGMRES'}

Restarted generalized minimum residual method.

:math:\mathrm{method} = \texttt{'CGS'}

:math:\mathrm{method} = \texttt{'BICGSTAB'}

Bi-conjugate gradient stabilized (:math:\ell) method.

:math:\mathrm{method} = \texttt{'TFQMR'}

Transpose-free quasi-minimal residual method.

**nnz** : int
The value of :math:\mathrm{nnz} as supplied to a previous call to :meth:complex_gen_precon_bdilu

**a** : complex, array-like, shape :math:\left(\textit{la}\right)
The value of :math:\mathrm{a} returned by a previous call to :meth:complex_gen_precon_bdilu

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The value of :math:\mathrm{irow} returned by a previous call to :meth:complex_gen_precon_bdilu

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The value of :math:\mathrm{icol} returned by a previous call to :meth:complex_gen_precon_bdilu

**istb** : int, array-like, shape :math:\left(\textit{nb}+1\right)
The value of :math:\mathrm{istb} as supplied to a previous call to :meth:complex_gen_precon_bdilu

**indb** : int, array-like, shape :math:\left(\textit{lindb}\right)
The value of :math:\mathrm{indb} as supplied to a previous call to :meth:complex_gen_precon_bdilu

**ipivp** : int, array-like, shape :math:\left(\textit{lindb}\right)
The value of :math:\mathrm{ipivp} returned by a previous call to :meth:complex_gen_precon_bdilu

**ipivq** : int, array-like, shape :math:\left(\textit{lindb}\right)
The value of :math:\mathrm{ipivq} returned by a previous call to :meth:complex_gen_precon_bdilu

**istr** : int, array-like, shape :math:\left(\textit{lindb}+1\right)
The value of :math:\mathrm{istr} returned by a previous call to :meth:complex_gen_precon_bdilu

**idiag** : int, array-like, shape :math:\left(\textit{lindb}\right)
The value of :math:\mathrm{idiag} returned by a previous call to :meth:complex_gen_precon_bdilu

**b** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

**m** : int
If :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\mathrm{m} is the dimension of the restart subspace.

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:\mathrm{m} is the order :math:\ell of the polynomial BI-CGSTAB method.

Otherwise, :math:\mathrm{m} is not referenced.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : complex, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11du-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq n^2.

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:1)
On entry, :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \textit{nb}\leq n.

(errno :math:1)
On entry, :math:\mathrm{istb}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istb}[0]\geq 1.

(errno :math:1)
On entry, for :math:b = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istb}[b] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{istb}[b-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istb}[\textit{b}] > \mathrm{istb}[\textit{b}-1], for :math:\textit{b} = 1,2,\ldots,\textit{nb}.

(errno :math:1)
On entry, :math:\mathrm{indb}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{indb}[\textit{m}-1]\leq n, for :math:\textit{m} = 1,2,\ldots,\mathrm{istb}[\textit{nb}]-1

(errno :math:1)
On entry, :math:\textit{lindb} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istb}[\textit{nb}]-1 = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nb} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{lindb}\geq \mathrm{istb}[\textit{nb}]-1.

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'RGMRES'}, :math:\texttt{'CGS'} or :math:\texttt{'BICGSTAB'}.

(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{method} = \texttt{'RGMRES'}, :math:1\leq \mathrm{m}\leq \mathrm{min}\left(n, \langle\mathit{\boldsymbol{value}}\rangle\right).

If :math:\mathrm{method} = \texttt{'BICGSTAB'}, :math:1\leq \mathrm{m}\leq \mathrm{min}\left(n, \langle\mathit{\boldsymbol{value}}\rangle\right).

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:2)
On entry, :math:\mathrm{irow}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{irow}[\textit{i}-1]\leq n, for :math:\textit{i} = 1,2,\ldots,\mathrm{nnz}.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:complex_gen_precon_bdilu and complex_gen_solve_bdilu.

(errno :math:2)
On entry, :math:\mathrm{icol}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{icol}[\textit{i}-1]\leq n, for :math:\textit{i} = 1,2,\ldots,\mathrm{nnz}.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:complex_gen_precon_bdilu and complex_gen_solve_bdilu.

(errno :math:2)
On entry, element :math:\langle\mathit{\boldsymbol{value}}\rangle of :math:\mathrm{a} was out of order.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:complex_gen_precon_bdilu and complex_gen_solve_bdilu.

(errno :math:2)
On entry, location :math:\langle\mathit{\boldsymbol{value}}\rangle of :math:\left(\mathrm{irow}, \mathrm{icol}\right) was a duplicate.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:complex_gen_precon_bdilu and complex_gen_solve_bdilu.

(errno :math:3)
The CS representation of the preconditioner is invalid.

Check that :math:\mathrm{a}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipivp}, :math:\mathrm{ipivq}, :math:\mathrm{istr} and :math:\mathrm{idiag} have not been corrupted between calls to :meth:complex_gen_precon_bdilu and complex_gen_solve_bdilu.

(errno :math:4)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
Algorithmic breakdown. A solution is returned, although it is possible that it is completely inaccurate.

.. _f11du-py2-py-notes:

**Notes**
complex_gen_solve_bdilu solves a complex sparse non-Hermitian linear system of equations

.. math::
Ax = b\text{,}

using a preconditioned RGMRES (see Saad and Schultz (1986)), CGS (see Sonneveld (1989)), BI-CGSTAB(:math:\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 :math:LU factorization determined by :meth:complex_gen_precon_bdilu as the preconditioning matrix.
A call to complex_gen_solve_bdilu must always be preceded by a call to :meth:complex_gen_precon_bdilu.
Alternative preconditioners for the same storage scheme are available by calling :meth:complex_gen_solve_ilu or :meth:complex_gen_solve_jacssor.

The matrix :math:A, and the preconditioning matrix :math:M, are represented in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}, as returned from :meth:complex_gen_precon_bdilu.
The array :math:\mathrm{a} holds the nonzero entries in these matrices, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

complex_gen_solve_bdilu is a Black Box function which calls :meth:complex_gen_basic_setup, :meth:complex_gen_basic_solver and :meth: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.

.. _f11du-py2-py-references:

**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 :math:\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
"""
raise NotImplementedError

[docs]def complex_gen_precon_jacobi(store, trans, init, niter, a, irow, icol, b, diag, check='N'):
r"""
complex_gen_precon_jacobi computes the **approximate** solution of a complex, Hermitian or non-Hermitian, sparse system of linear equations applying a number of Jacobi iterations.
It is expected that complex_gen_precon_jacobi will be used as a preconditioner for the iterative solution of complex sparse systems of equations.

.. _f11dx-py2-py-doc:

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

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

.. _f11dx-py2-py-parameters:

**Parameters**
**store** : str, length 1
Specifies whether the matrix :math:A is stored using symmetric coordinate storage (SCS) (applicable only to a Hermitian matrix :math:A) or coordinate storage (CS) (applicable to both Hermitian and non-Hermitian matrices).

:math:\mathrm{store} = \texttt{'N'}

The complete matrix :math:A is stored in CS format.

:math:\mathrm{store} = \texttt{'S'}

The lower triangle of the Hermitian matrix :math:A is stored in SCS format.

**trans** : str, length 1
If :math:\mathrm{store} = \texttt{'N'}, specifies whether the approximate solution of :math:Ax = b or of :math:A^\mathrm{H}x = b is required.

:math:\mathrm{trans} = \texttt{'N'}

The approximate solution of :math:Ax = b is calculated.

:math:\mathrm{trans} = \texttt{'T'}

The approximate solution of :math:A^\mathrm{H}x = b is calculated.

Suggested value: if the matrix :math:A is Hermitian and stored in CS format, it is recommended that :math:\mathrm{trans} = \texttt{'N'} for reasons of efficiency.

**init** : str, length 1
On first entry, :math:\mathrm{init} should be set to 'I', unless the diagonal elements of :math:A are already stored in the array :math:\mathrm{diag}. If :math:\mathrm{diag} already contains the diagonal of :math:A, it must be set to 'N'.

:math:\mathrm{init} = \texttt{'N'}

:math:\mathrm{diag} must contain the diagonal of :math:A.

:math:\mathrm{init} = \texttt{'I'}

:math:\mathrm{diag} will store the diagonal of :math:A on exit.

Suggested value: :math:\mathrm{init} = \texttt{'I'} on first entry; :math:\mathrm{init} = \texttt{'N'}, subsequently, unless :math:\mathrm{diag} has been overwritten.

**niter** : int
The number of Jacobi iterations requested.

**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
If :math:\mathrm{store} = \texttt{'N'}, the nonzero elements in the matrix :math:A (CS format).

If :math:\mathrm{store} = \texttt{'S'}, the nonzero elements in the lower triangle of the matrix :math:A (SCS format).

In both cases, the elements of either :math:A or of its lower triangle must be ordered by increasing row index and by increasing column index within each row.

Multiple entries for the same row and columns indices are not permitted.

The function :meth:complex_gen_sort or :meth:complex_herm_sort may be used to reorder the elements in this way for CS and SCS storage, respectively.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
If :math:\mathrm{store} = \texttt{'N'}, the row indices of the nonzero elements supplied in :math:\mathrm{a}.

If :math:\mathrm{store} = \texttt{'S'}, the row and column indices of the nonzero elements of the lower triangle of the matrix :math:A supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
If :math:\mathrm{store} = \texttt{'N'}, the column indices of the nonzero elements supplied in :math:\mathrm{a}.

If :math:\mathrm{store} = \texttt{'S'}, the row and column indices of the nonzero elements of the lower triangle of the matrix :math:A supplied in :math:\mathrm{a}.

**b** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

**diag** : complex, array-like, shape :math:\left(n\right)
If :math:\mathrm{init} = \texttt{'N'}, the diagonal elements of :math:A.

**check** : str, length 1, optional
Specifies whether or not the CS or SCS representation of the matrix :math:A should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried out on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow}, :math:\mathrm{icol}; if :math:\mathrm{init} = \texttt{'N'}, :math:\mathrm{diag} is also checked.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11dxf.html#fcomments2>__.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
The approximate solution vector :math:x_{\mathrm{niter}}.

**diag** : complex, ndarray, shape :math:\left(n\right)
If :math:\mathrm{init} = \texttt{'N'}, unchanged on exit.

If :math:\mathrm{init} = \texttt{'I'}, the diagonal elements of :math:A.

.. _f11dx-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{niter} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{niter}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{check} \neq \texttt{'N'} or :math:\texttt{'C'}: :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{init} \neq \texttt{'N'} or :math:\texttt{'I'}: :math:\mathrm{init} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{trans} \neq \texttt{'N'} or :math:\texttt{'T'}: :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{store} \neq \texttt{'N'} or :math:\texttt{'S'}: :math:\mathrm{store} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n^2

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n\times \left(n+1\right)/2

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[\textit{I}-1]\geq 1 and :math:\mathrm{irow}[\textit{I}-1]\leq n.

(errno :math:4)
On entry, the element :math:\mathrm{diag}[\textit{I}-1] is zero: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:5)
On entry, the diagonal element of the :math:\textit{I}\ th row is zero or missing: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

.. _f11dx-py2-py-notes:

**Notes**
complex_gen_precon_jacobi computes the **approximate** solution of the complex sparse system of linear equations :math:Ax = b using :math:\mathrm{niter} iterations of the Jacobi algorithm (see also Golub and Van Loan (1996) and Young (1971)):

.. math::
x_{{k+1}} = x_k+D^{-1}\left(b-Ax_k\right)

where :math:k = 1,2,\ldots,\mathrm{niter} and :math:x_0 = 0.

complex_gen_precon_jacobi can be used both for non-Hermitian and Hermitian systems of equations.
For Hermitian matrices, either all nonzero elements of the matrix :math:A can be supplied using coordinate storage (CS), or only the nonzero elements of the lower triangle of :math:A, using symmetric coordinate storage (SCS) (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html>__).

It is expected that complex_gen_precon_jacobi will be used as a preconditioner for the iterative solution of complex sparse systems of equations, using either the suite comprising the functions :meth:complex_herm_basic_setup, :meth:complex_herm_basic_solver and :meth:complex_herm_basic_diag, for Hermitian systems, or the suite comprising the functions :meth:complex_gen_basic_setup, :meth:complex_gen_basic_solver and :meth:complex_gen_basic_diag, for non-Hermitian systems of equations.

.. _f11dx-py2-py-references:

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

Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def real_symm_basic_setup(method, precon, n, tol, maxitn, anorm, sigmax, maxits, monit, sigcmp='N', norm=None, weight='N', iterm=1, sigtol=0.01):
r"""
real_symm_basic_setup is a setup function, the first in a suite of three functions for the iterative solution of a symmetric system of simultaneous linear equations. real_symm_basic_setup must be called before the iterative solver, :meth:real_symm_basic_solver.
The third function in the suite, :meth:real_symm_basic_diag, can be used to return additional information about the computation.

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

.. _f11gd-py2-py-doc:

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

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

.. _f11gd-py2-py-parameters:

**Parameters**
**method** : str
The iterative method to be used.

:math:\mathrm{method} = \texttt{'CG'}

:math:\mathrm{method} = \texttt{'SYMMLQ'}

Lanczos method (SYMMLQ).

:math:\mathrm{method} = \texttt{'MINRES'}

Minimum residual method (MINRES).

**precon** : str, length 1
Determines whether preconditioning is used.

:math:\mathrm{precon} = \texttt{'N'}

No preconditioning.

:math:\mathrm{precon} = \texttt{'P'}

Preconditioning.

**n** : int
:math:n, the order of the matrix :math:A.

**tol** : float
The tolerance :math:\tau for the termination criterion.

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon }}, {\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision.

Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations.

**anorm** : float
If :math:\mathrm{anorm} > 0.0, the value of :math:\left\lVert A\right\rVert_p to be used in the termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__ (:math:\mathrm{iterm} = 1).

If :math:\mathrm{anorm}\leq 0.0, :math:\mathrm{iterm} = 1 and :math:\mathrm{norm} = \texttt{'1'} or :math:\texttt{'I'}, :math:\left\lVert A\right\rVert_1 = \left\lVert A\right\rVert_\infty is estimated internally by :meth:real_symm_basic_solver.

If :math:\mathrm{iterm} = 2, :math:\mathrm{anorm} is not referenced.

It has no effect if :math:\mathrm{method} = \texttt{'MINRES'}.

**sigmax** : float
If :math:\mathrm{sigmax} > 0.0, the value of :math:\sigma_1\left(\bar{A}\right) = \left\lVert E^{-1}AE^{-\mathrm{T}}\right\rVert_2.

If :math:\mathrm{sigmax}\leq 0.0, :math:\sigma_1\left(\bar{A}\right) is estimated by :meth:real_symm_basic_solver when either :math:\mathrm{sigcmp} = \texttt{'S'} or termination criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe3>__ (:math:\mathrm{iterm} = 2) is employed, though it will be used only in the latter case.

Otherwise, or if :math:\mathrm{method} = \texttt{'MINRES'}, :math:\mathrm{sigmax} is not referenced.

**maxits** : int
The maximum iteration number :math:k = \mathrm{maxits} for which :math:\sigma_1\left(T_k\right) is computed by bisection (see also :ref:Notes <f11gd-py2-py-notes>). If :math:\mathrm{sigcmp} = \texttt{'N'} or :math:\mathrm{sigmax} > 0.0, or if :math:\mathrm{method} = \texttt{'MINRES'}, :math:\mathrm{maxits} is not referenced.

Suggested value: :math:\mathrm{maxits} = \mathrm{min}\left(10, n\right) when :math:\mathrm{sigtol} is of the order of its default value :math:\left(0.01\right).

**monit** : int
If :math:\mathrm{monit} > 0, the frequency at which a monitoring step is executed by :meth:real_symm_basic_solver: the current solution and residual iterates will be returned by :meth:real_symm_basic_solver and a call to :meth:real_symm_basic_diag made possible every :math:\mathrm{monit} iterations, starting from the (:math:\mathrm{monit})th. Otherwise, no monitoring takes place.

There are some additional computational costs involved in monitoring the solution and residual vectors when the Lanczos method (SYMMLQ) is used.

**sigcmp** : str, length 1, optional
Determines whether an estimate of :math:\sigma_1\left(\bar{A}\right) = \left\lVert E^{-1}AE^{-\mathrm{T}}\right\rVert_2, the largest singular value of the preconditioned matrix of the coefficients, is to be computed using the bisection method on the sequence of tridiagonal matrices :math:\left\{T_k\right\} generated during the iteration. Note that :math:\bar{A} = A when a preconditioner is not used.

If :math:\mathrm{sigmax} > 0.0 (see :math:\mathrm{sigmax}), i.e., when :math:\sigma_1\left(\bar{A}\right) is supplied, the value of :math:\mathrm{sigcmp} is ignored.

:math:\mathrm{sigcmp} = \texttt{'S'}

:math:\sigma_1\left(\bar{A}\right) is to be computed using the bisection method.

:math:\mathrm{sigcmp} = \texttt{'N'}

The bisection method is not used.

If the termination criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe3>__ is used, requiring :math:\sigma_1\left(\bar{A}\right), an inexpensive estimate is computed and used (see :ref:Notes <f11gd-py2-py-notes>).

It is not used if :math:\mathrm{method} = \texttt{'MINRES'}.

**norm** : None or str, length 1, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:\mathrm{iterm} = 1: :math:{ \texttt{'I'} }; otherwise: :math:{ \texttt{'2'} }.

If :math:\mathrm{method} = \texttt{'CG'} or :math:\texttt{'SYMMLQ'}, :math:\mathrm{norm} defines the matrix and vector norm to be used in the termination criteria.

:math:\mathrm{norm} = \texttt{'1'}

Use the :math:l_1 norm.

:math:\mathrm{norm} = \texttt{'I'}

Use the :math:l_{\infty } norm.

:math:\mathrm{norm} = \texttt{'2'}

Use the :math:l_2 norm.

It has no effect if :math:\mathrm{method} = \texttt{'MINRES'}.

**weight** : str, length 1, optional
Specifies whether a vector :math:w of user-supplied weights is to be used in the vector norms used in the computation of termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__ (:math:\mathrm{iterm} = 1): :math:\left\lVert v\right\rVert_p^{\left(w\right)} = \left\lVert v^{\left(w\right)}\right\rVert_p, where :math:v_{\textit{i}}^{\left(w\right)} = w_{\textit{i}}v_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n. The suffix :math:p = 1,2,\infty denotes the vector norm used, as specified by the argument :math:\mathrm{norm}. Note that weights cannot be used when :math:\mathrm{iterm} = 2, i.e., when criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe3>__ is used.

:math:\mathrm{weight} = \texttt{'W'}

User-supplied weights are to be used and must be supplied on initial entry to :meth:real_symm_basic_solver.

:math:\mathrm{weight} = \texttt{'N'}

All weights are implicitly set equal to one. Weights do not need to be supplied on initial entry to :meth:real_symm_basic_solver.

It has no effect if :math:\mathrm{method} = \texttt{'MINRES'}.

**iterm** : int, optional
Defines the termination criterion to be used.

:math:\mathrm{iterm} = 1

Use the termination criterion defined in (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__ (both conjugate gradient and Lanczos (SYMMLQ) methods).

:math:\mathrm{iterm} = 2

Use the termination criterion defined in (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe3>__ (Lanczos method (SYMMLQ) only).

It has no effect if :math:\mathrm{method} = \texttt{'MINRES'}.

**sigtol** : float, optional
The tolerance used in assessing the convergence of the estimate of :math:\sigma_1\left(\bar{A}\right) = \left\lVert \bar{A}\right\rVert_2 when the bisection method is used.

If :math:\mathrm{sigtol}\leq 0.0, the default value :math:\mathrm{sigtol} = 0.01 is used.

The actual value used is :math:\mathrm{max}\left(\mathrm{sigtol}, \epsilon \right).

If :math:\mathrm{sigcmp} = \texttt{'N'} or :math:\mathrm{sigmax} > 0.0, :math:\mathrm{sigtol} is not referenced.

It has no effect if :math:\mathrm{method} = \texttt{'MINRES'}.

**Returns**
**comm** : dict, communication object
Communication structure.

.. _f11gd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-14)
On entry, :math:\mathrm{monit} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{monit}\leq \mathrm{maxitn}.

(errno :math:-13)
On entry, :math:\mathrm{sigcmp} = \texttt{'S'}, :math:\mathrm{sigmax}\leq 0.0, :math:\mathrm{maxits} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{sigcmp} = \texttt{'S'} and :math:\mathrm{sigmax}\leq 0.0, :math:\mathrm{maxits} \leq \mathrm{maxitn}.

(errno :math:-13)
On entry, :math:\mathrm{sigcmp} = \texttt{'S'}, :math:\mathrm{sigmax}\leq 0.0 and :math:\mathrm{maxits} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{sigcmp} = \texttt{'S'} and :math:\mathrm{sigmax}\leq 0.0, :math:\mathrm{maxits} \geq 1.

(errno :math:-12)
On entry, :math:\mathrm{sigcmp} = \texttt{'S'}, :math:\mathrm{sigmax}\leq 0.0 and :math:\mathrm{sigtol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{sigcmp} = \texttt{'S'} and :math:\mathrm{sigmax}\leq 0.0, :math:\mathrm{sigtol} < 1.0.

(errno :math:-10)
On entry, :math:\mathrm{iterm} = 1, :math:\mathrm{norm} = \texttt{'2'} and :math:\mathrm{anorm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 1 and :math:\mathrm{norm} = \texttt{'2'}, :math:\mathrm{anorm} > 0.0.

(errno :math:-9)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn} > 0.

(errno :math:-8)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:-7)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} > 0.

(errno :math:-6)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{method} = \texttt{'CG'}.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{method} \neq \texttt{'CG'}.

(errno :math:-6)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{norm} = \texttt{'2'}.

(errno :math:-6)
On entry, :math:\mathrm{iterm} = 2 and :math:\mathrm{weight} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{weight} = \texttt{'N'}.

(errno :math:-6)
On entry, :math:\mathrm{iterm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iterm} = 1 or :math:2.

(errno :math:-5)
On entry, :math:\mathrm{weight} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{weight} = \texttt{'N'} or :math:\texttt{'W'}.

(errno :math:-4)
On entry, :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{norm} = \texttt{'1'}, :math:\texttt{'I'} or :math:\texttt{'2'}.

(errno :math:-3)
On entry, :math:\mathrm{sigcmp} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{sigcmp} = \texttt{'S'} or :math:\texttt{'N'}.

(errno :math:-2)
On entry, :math:\mathrm{precon} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{precon} = \texttt{'N'} or :math:\texttt{'P'}.

(errno :math:-1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'CG'}, :math:\texttt{'SYMMLQ'} or :math:\texttt{'MINRES'}.

(errno :math:1)
real_symm_basic_setup has been called out of sequence: either real_symm_basic_setup has been called twice or :meth:real_symm_basic_solver has not terminated its current task.

.. _f11gd-py2-py-notes:

**Notes**
The suite consisting of the functions real_symm_basic_setup, :meth:real_symm_basic_solver and :meth:real_symm_basic_diag is designed to solve the symmetric system of simultaneous linear equations :math:Ax = b of order :math:n, where :math:n is large and the matrix of the coefficients :math:A is sparse.

real_symm_basic_setup is a setup function which must be called before :meth:real_symm_basic_solver, the iterative solver.
The third function in the suite, :meth:real_symm_basic_diag can be used to return additional information about the computation.
One of the following methods can be used:

For this method (see Hestenes and Stiefel (1952), Golub and Van Loan (1996), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)), the matrix :math:A should ideally be positive definite.
The application of the Conjugate Gradient method to indefinite matrices may lead to failure or to lack of convergence.

(#) **Lanczos Method (SYMMLQ)**

This method, based upon the algorithm SYMMLQ (see Paige and Saunders (1975) and Barrett et al. (1994)), is suitable for both positive definite and indefinite matrices.
It is more robust than the Conjugate Gradient method but less efficient when :math:A is positive definite.

(#) **Minimum Residual Method (MINRES)**

This method may be used when the matrix is indefinite.
It seeks to reduce the norm of the residual at each iteration and often takes fewer iterations than the other methods.
It does however require slightly more memory.

The CG and SYMMLQ methods start from the residual :math:r_0 = b-Ax_0, where :math:x_0 is an initial estimate for the solution (often :math:x_0 = 0), and generate an orthogonal basis for the Krylov subspace :math:\mathrm{span}\left\{A^{\textit{k}}r_0\right\}, for :math:\textit{k} = 0,1,\ldots,, by means of three-term recurrence relations (see Golub and Van Loan (1996)).
A sequence of symmetric tridiagonal matrices :math:\left\{T_k\right\} is also generated.
Here and in the following, the index :math:k denotes the iteration count.
The resulting symmetric tridiagonal systems of equations are usually more easily solved than the original problem.
A sequence of solution iterates :math:\left\{x_k\right\} is thus generated such that the sequence of the norms of the residuals :math:\left\{\left\lVert r_k\right\rVert \right\} converges to a required tolerance.
Note that, in general, the convergence is not monotonic.

In exact arithmetic, after :math:n iterations, this process is equivalent to an orthogonal reduction of :math:A to symmetric tridiagonal form, :math:T_n = Q^\mathrm{T}AQ; the solution :math:x_n would thus achieve exact convergence.
In finite-precision arithmetic, cancellation and round-off errors accumulate causing loss of orthogonality.
These methods must, therefore, be viewed as genuinely iterative methods, able to converge to a solution **within a prescribed tolerance**.

The orthogonal basis is not formed explicitly in either method.
The basic difference between the Conjugate Gradient and Lanczos methods lies in the method of solution of the resulting symmetric tridiagonal systems of equations: the conjugate gradient method is equivalent to carrying out an :math:LDL^\mathrm{T} (Cholesky) factorization whereas the Lanczos method (SYMMLQ) uses an :math:LQ factorization.

Faster convergence for all the methods can be achieved using a **preconditioner** (see Golub and Van Loan (1996) and Barrett et al. (1994)).
A preconditioner maps the original system of equations onto a different system, say

.. math::
\bar{A}\bar{x} = \bar{b}\text{,}

with, hopefully, better characteristics with respect to its speed of convergence: for example, the condition number of the matrix of the coefficients can be improved or eigenvalues in its spectrum can be made to coalesce.
An orthogonal basis for the Krylov subspace :math:\mathrm{span}\left\{\bar{A}^{\textit{k}}\bar{r}_0\right\}, for :math:\textit{k} = 0,1,\ldots,, is generated and the solution proceeds as outlined above.
The algorithms used are such that the solution and residual iterates of the original system are produced, not their preconditioned counterparts.
Note that an unsuitable preconditioner or no preconditioning at all may result in a very slow rate, or lack, of convergence.
However, preconditioning involves a trade-off between the reduction in the number of iterations required for convergence and the additional computational costs per iteration.
Also, setting up a preconditioner may involve non-negligible overheads.

A preconditioner must be **symmetric and positive definite**, i.e., representable by :math:M = EE^\mathrm{T}, where :math:M is nonsingular, and such that :math:\bar{A} = E^{-1}AE^{-\mathrm{T}}\sim I_n in (1) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe1>__, where :math:I_n is the identity matrix of order :math:n.
Also, we can define :math:\bar{r} = E^{-1}r and :math:\bar{x} = E^\mathrm{T}x.
These are formal definitions, used only in the design of the algorithms; in practice, only the means to compute the matrix-vector products :math:v = Au and to solve the preconditioning equations :math:Mv = u are required, that is, explicit information about :math:M, :math:E or their inverses is not required at any stage.

The first termination criterion

.. math::
\left\lVert r_k\right\rVert_p\leq \tau \left({\left\lVert b\right\rVert_p+\left\lVert A\right\rVert_p}\times {\left\lVert x_k\right\rVert_p}\right)

is available for both conjugate gradient and Lanczos (SYMMLQ) methods.
In (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__, :math:p = 1,\infty or :math:2 and :math:\tau denotes a user-specified tolerance subject to :math:\mathrm{max}\left(10, {\sqrt{n}}\right)\epsilon \leq \tau < 1, where :math:\epsilon is the machine precision.
Facilities are provided for the estimation of the norm of the matrix of the coefficients :math:\left\lVert A\right\rVert_1 = \left\lVert A\right\rVert_\infty, when this is not known in advance, used in (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__, by applying Higham's method (see Higham (1988)).
Note that :math:\left\lVert A\right\rVert_2 cannot be estimated internally.
This criterion uses an error bound derived from **backward** error analysis to ensure that the computed solution is the exact solution of a problem as close to the original as the termination tolerance requires.
Termination criteria employing bounds derived from **forward** error analysis could be used, but any such criteria would require information about the condition number :math:\kappa \left(A\right) which is not easily obtainable.

The second termination criterion

.. math::
\left\lVert \bar{r}_k\right\rVert_2\leq \tau \mathrm{max}\left(1.0, {\left\lVert b\right\rVert_2/\left\lVert r_0\right\rVert_2}\right)\left({\left\lVert \bar{r}_0\right\rVert_2+\sigma_1\left(\bar{A}\right)}\times {\left\lVert \Delta \bar{x}_k\right\rVert_2}\right)

is available only for the Lanczos method (SYMMLQ).
In (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe3>__, :math:\sigma_1\left(\bar{A}\right) = \left\lVert \bar{A}\right\rVert_2 is the largest singular value of the (preconditioned) iteration matrix :math:\bar{A}.
This termination criterion monitors the progress of the solution of the preconditioned system of equations and is less expensive to apply than criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__.
When :math:\sigma_1\left(\bar{A}\right) is not supplied, facilities are provided for its estimation by :math:\sigma_1\left(\bar{A}\right)\sim \mathrm{max}_k\sigma_1\left(T_k\right).
The interlacing property :math:\sigma_1\left(T_{{k-1}}\right)\leq \sigma_1\left(T_k\right) and Gerschgorin's theorem provide lower and upper bounds from which :math:\sigma_1\left(T_k\right) can be easily computed by bisection.
Alternatively, the less expensive estimate :math:\sigma_1\left(\bar{A}\right)\sim \mathrm{max}_k\left\lVert T_k\right\rVert_1 can be used, where :math:\sigma_1\left(\bar{A}\right)\leq \left\lVert T_k\right\rVert_1 by Gerschgorin's theorem.
Note that only order of magnitude estimates are required by the termination criterion.

Termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__ is the recommended choice, despite its (small) additional costs per iteration when using the Lanczos method (SYMMLQ).
Also, if the norm of the initial estimate is much larger than the norm of the solution, that is, if :math:\left\lVert x_0\right\rVert ≫\left\lVert x\right\rVert, a dramatic loss of significant digits could result in complete lack of convergence.
The use of criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__ will enable the detection of such a situation, and the iteration will be restarted at a suitable point.
No such restart facilities are provided for criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe3>__.

Optionally, a vector :math:w of user-specified weights can be used in the computation of the vector norms in termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#eqnf11gdfe2>__, i.e., :math:\left\lVert v\right\rVert_p^{\left(w\right)} = \left\lVert v^{\left(w\right)}\right\rVert_p, where :math:{\left(v^{\left(w\right)}\right)}_{\textit{i}} = w_{\textit{i}}v_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n.
Note that the use of weights increases the computational costs.

The MINRES algorithm terminates when the norm of the residual of the preconditioned system :math:F, :math:\left\lVert F\right\rVert_2\leq \tau \times \left\lVert \bar{A}\right\rVert_2\times \left\lVert x_k\right\rVert_2, where :math:\bar{A} is the preconditioned matrix.

The termination criteria discussed are not robust in the presence of a non-trivial nullspace of :math:A, i.e., when :math:A is singular.
It is then possible for :math:\left\lVert x_k\right\rVert_p to grow without limit, spuriously satisfying the termination criterion.
If singularity is suspected, more robust functions can be found in submodule :mod:~naginterfaces.library.opt.

The sequence of calls to the functions comprising the suite is enforced: first, the setup function real_symm_basic_setup must be called, followed by the solver :meth:real_symm_basic_solver.
The diagnostic function :meth:real_symm_basic_diag can be called either when :meth:real_symm_basic_solver is carrying out a monitoring step or after :meth:real_symm_basic_solver has completed its tasks.
Incorrect sequencing will raise an error condition.

.. _f11gd-py2-py-references:

**References**
Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Dias da Cunha, R and Hopkins, T, 1994, PIM 1.1 --- the parallel iterative method package for systems of linear equations user's guide --- Fortran 77 version, Technical Report, Computing Laboratory, University of Kent at Canterbury, Kent, UK

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

Hestenes, M and Stiefel, E, 1952, Methods of conjugate gradients for solving linear systems, J. Res. Nat. Bur. Stand. (49), 409--436

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

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617--629
"""
raise NotImplementedError

[docs]def real_symm_basic_solver(irevcm, u, v, wgt, comm):
r"""
real_symm_basic_solver is an iterative solver for a symmetric system of simultaneous linear equations; real_symm_basic_solver is the second in a suite of three functions, where the first function, :meth:real_symm_basic_setup, must be called prior to real_symm_basic_solver to set up the suite, and the third function in the suite, :meth:real_symm_basic_diag, can be used to return additional information about the computation.

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

.. _f11ge-py2-py-doc:

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

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

.. _f11ge-py2-py-parameters:

**Parameters**
**irevcm** : int
On initial entry: :math:\mathrm{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.

:math:\mathrm{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. real_symm_basic_solver will then return with the termination code :math:\mathrm{irevcm} = 4. Note that before calling real_symm_basic_solver with :math:\mathrm{irevcm} = 5 the calling program must have performed the tasks required by the value of :math:\mathrm{irevcm} returned by the previous call to real_symm_basic_solver, otherwise subsequently returned values may be invalid.

:math:\mathrm{irevcm} = 6

Immediate termination: real_symm_basic_solver will return immediately with termination code :math:\mathrm{irevcm} = 4 and with any useful information available. This includes the last iterate of the solution and, for conjugate gradient only, the last iterate of the residual vector. The residual vector is generally not available when the Lanczos method (SYMMLQ) is used. real_symm_basic_solver will then return with the termination code :math:\mathrm{irevcm} = 4.

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

Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

**u** : float, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: an initial estimate, :math:x_0, of the solution of the system of equations :math:Ax = b.

On intermediate entry: must remain unchanged.

On intermediate exit: the returned value of :math:\mathrm{irevcm} determines the contents of :math:\mathrm{u} in the following way.

If :math:\mathrm{irevcm} = 1 or :math:2, :math:\mathrm{u} holds the vector :math:u on which the operation specified by :math:\mathrm{irevcm} is to be carried out.

If :math:\mathrm{irevcm} = 3, :math:\mathrm{u} holds the current iterate of the solution vector.

On final exit: if :math:\mathrm{errno} = 3 or -i, the array :math:\mathrm{u} is unchanged from the initial entry to real_symm_basic_solver. If :math:\mathrm{errno} = 1, the array :math:\mathrm{u} is unchanged from the last entry to real_symm_basic_solver. Otherwise, :math:\mathrm{u} holds the last iterate of the solution of the system of equations, for all returned values of :math:\textit{errno}.

**v** : float, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: the right-hand side :math:b of the system of equations :math:Ax = b.

On intermediate entry: the returned value of :math:\mathrm{irevcm} determines the contents of :math:\mathrm{v} in the following way.

If :math:\mathrm{irevcm} = 1 or :math:2, :math:\mathrm{v} must store the vector :math:v, the result of the operation specified by the value of :math:\mathrm{irevcm} returned by the previous call to real_symm_basic_solver.

If :math:\mathrm{irevcm} = 3, :math:\mathrm{v} must remain unchanged.

On intermediate exit: if :math:\mathrm{irevcm} = 3, :math:\mathrm{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 :math:\mathrm{errno} = 3 or -i, the array :math:\mathrm{v} is unchanged from the last entry to real_symm_basic_solver. If :math:\mathrm{errno} = 1, the array :math:\mathrm{v} is unchanged from the initial entry to real_symm_basic_solver. If the function exits successfully or :math:\mathrm{errno} = 2, the array :math:\mathrm{v} contains the true residual vector of the system of equations (see also :ref:Exceptions <f11ge-py2-py-errors>). Otherwise, :math:\mathrm{v} stores the last iterate of the residual vector unless the Lanczos method (SYMMLQ) was used and :math:\mathrm{errno} >= 5, in which case :math:\mathrm{v} is set to :math:0.0.

**wgt** : float, array-like, shape :math:\left(\textit{n}\right)
The user-supplied weights, if these are to be used in the computation of the vector norms in the termination criterion (see :ref:Notes for real_symm_basic_setup <f11gd-py2-py-notes> and :ref:Parameters for real_symm_basic_setup <f11gd-py2-py-parameters>).

Weights are NOT used in the MINRES algorithm.

**comm** : dict, communication object, modified in place
Communication structure.

This argument must have been initialized by a prior call to :meth:real_symm_basic_setup.

**Returns**
**irevcm** : int
On intermediate exit: has the following meanings.

:math:\mathrm{irevcm} = 1

The calling program must compute the matrix-vector product :math:v = Au, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively.

:math:\mathrm{irevcm} = 2

The calling program must solve the preconditioning equation :math:Mv = u, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively.

:math:\mathrm{irevcm} = 3

Monitoring step: the solution and residual at the current iteration are returned in the arrays :math:\mathrm{u} and :math:\mathrm{v}, respectively. No action by the calling program is required. To return additional information :meth:real_symm_basic_diag can be called at this step.

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

.. _f11ge-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On intermediate re-entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: either :math:\mathrm{irevcm} must be unchanged from its previous exit value or :math:\mathrm{irevcm} = 5 or :math:6.

(errno :math:-1)
On initial entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irevcm} = 0.

(errno :math:3)
Either :meth:real_symm_basic_setup was not called before calling this function or it has returned an error.

(errno :math:6)
The preconditioner appears not to be positive definite. The computation cannot continue.

(errno :math:9)
The matrix of the coefficients :math:A appears to be singular. The computation cannot continue.

(errno :math:10)
The weights in array :math:\mathrm{wgt} are all zero.

**Warns**
**NagAlgorithmicWarning**
(errno :math:1)
real_symm_basic_solver has already completed its tasks. You need to set a new problem.

(errno :math:2)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

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

(errno :math:4)
User-requested tidy termination. The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:7)
The matrix of the coefficients :math:A appears not to be positive definite. The computation cannot continue.

(errno :math:8)
User-requested immediate termination.

.. _f11ge-py2-py-notes:

**Notes**
real_symm_basic_solver solves the symmetric system of linear simultaneous equations :math:Ax = b using the preconditioned conjugate gradient method (see Hestenes and Stiefel (1952), Golub and Van Loan (1996), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)), a preconditioned Lanczos method based upon the algorithm SYMMLQ (see Paige and Saunders (1975) and Barrett et al. (1994)), or the MINRES algorithm (see Paige and Saunders (1975)).

For a general description of the methods employed you are referred to :ref:Notes for real_symm_basic_setup <f11gd-py2-py-notes>.

real_symm_basic_solver can solve the system after the first function in the suite, :meth:real_symm_basic_setup, has been called to initialize the computation and specify the method of solution.
The third function in the suite, :meth:real_symm_basic_diag, can be used to return additional information generated by the computation during monitoring steps and after real_symm_basic_solver has completed its tasks.

real_symm_basic_solver uses **reverse communication**, i.e., real_symm_basic_solver returns repeatedly to the calling program with the argument :math:\mathrm{irevcm} (see :ref:Parameters <f11ge-py2-py-parameters>) set to specified values which require the calling program to carry out a specific task: either to compute the matrix-vector product :math:v = Au; to solve the preconditioning equation :math:Mv = u; to notify the completion of the computation; or, to allow the calling program to monitor the solution.
Through the argument :math:\mathrm{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.

(#) Enhanced user interaction: you can closely monitor 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.

.. _f11ge-py2-py-references:

**References**
Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Dias da Cunha, R and Hopkins, T, 1994, PIM 1.1 --- the parallel iterative method package for systems of linear equations user's guide --- Fortran 77 version, Technical Report, Computing Laboratory, University of Kent at Canterbury, Kent, UK

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

Hestenes, M and Stiefel, E, 1952, Methods of conjugate gradients for solving linear systems, J. Res. Nat. Bur. Stand. (49), 409--436

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

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617--629
"""
raise NotImplementedError

[docs]def real_symm_basic_diag(comm):
r"""
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, :meth:real_symm_basic_setup, is a setup function, the second function, :meth:real_symm_basic_solver is the proper iterative solver.

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

.. _f11gf-py2-py-doc:

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

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

.. _f11gf-py2-py-parameters:

**Parameters**
**comm** : dict, communication object
Communication structure.

This argument must have been initialized by a prior call to :meth:real_symm_basic_setup.

**Returns**
**itn** : int
The number of iterations carried out by :meth:real_symm_basic_solver.

**stplhs** : float
The current value of the left-hand side of the termination criterion used by :meth:real_symm_basic_solver.

**stprhs** : float
The current value of the right-hand side of the termination criterion used by :meth:real_symm_basic_solver.

**anorm** : float
For CG and SYMMLQ methods, the norm :math:\left\lVert A\right\rVert_1 = \left\lVert A\right\rVert_\infty when either it has been supplied to :meth:real_symm_basic_setup or it has been estimated by :meth:real_symm_basic_solver (see also :ref:Notes for real_symm_basic_setup <f11gd-py2-py-notes> and :ref:Parameters for real_symm_basic_setup <f11gd-py2-py-parameters>). Otherwise, :math:\mathrm{anorm} = 0.0 is returned.

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

**sigmax** : float
For CG and SYMMLQ methods, the current estimate of the largest singular value :math:\sigma_1\left(\bar{A}\right) of the preconditioned iteration matrix :math:\bar{A} = E^{-1}AE^{-\mathrm{T}}, when either it has been supplied to :meth:real_symm_basic_setup or it has been estimated by :meth:real_symm_basic_solver (see also :ref:Notes for real_symm_basic_setup <f11gd-py2-py-notes> and :ref:Parameters for real_symm_basic_setup <f11gd-py2-py-parameters>). Note that if :math:\mathrm{its} < \mathrm{itn} then :math:\mathrm{sigmax} contains the final estimate. If, on final exit from :meth:real_symm_basic_solver, :math:\mathrm{its} = \mathrm{itn}, the estimation of :math:\sigma_1\left(\bar{A}\right) may have not converged; in this case you should look at the value returned in :math:\mathrm{sigerr}. Otherwise, :math:\mathrm{sigmax} = 0.0 is returned.

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

**its** : int
For CG and SYMMLQ methods, the number of iterations employed so far in the computation of the estimate of :math:\sigma_1\left(\bar{A}\right), the largest singular value of the preconditioned matrix :math:\bar{A} = E^{-1}AE^{-\mathrm{T}}, when :math:\sigma_1\left(\bar{A}\right) has been estimated by :meth:real_symm_basic_solver using the bisection method (see also :ref:Notes for real_symm_basic_setup <f11gd-py2-py-notes>, :ref:Parameters for real_symm_basic_setup <f11gd-py2-py-parameters> and Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11gdf.html#fcomments>__). Otherwise, :math:\mathrm{its} = 0 is returned.

**sigerr** : float
For CG and SYMMLQ methods, if :math:\sigma_1\left(\bar{A}\right) has been estimated by :meth:real_symm_basic_solver using bisection,

.. math::
\mathrm{sigerr} = \mathrm{max}\left(\frac{{\left\lvert \sigma_1^{\left(k\right)}-\sigma_1^{\left(k-1\right)}\right\rvert }}{{\sigma_1^{\left(k\right)}}}, \frac{{\left\lvert \sigma_1^{\left(k\right)}-\sigma_1^{\left(k-2\right)}\right\rvert }}{{\sigma_1^{\left(k\right)}}}\right)\text{,}

where :math:k = \mathrm{its} denotes the iteration number. The estimation has converged if :math:\mathrm{sigerr}\leq {\textit{sigtol}} where :math:\textit{sigtol} is an input argument to :meth:real_symm_basic_setup. Otherwise, :math:\mathrm{sigerr} = 0.0 is returned.

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

.. _f11gf-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
real_symm_basic_diag has been called out of sequence.

.. _f11gf-py2-py-notes:

**Notes**
real_symm_basic_diag returns information about the solution process.
It can be called both during a monitoring step of the solver :meth: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 :meth:real_symm_basic_setup and :meth:real_symm_basic_solver.

.. _f11gf-py2-py-references:

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

[docs]def complex_herm_basic_setup(method, precon, n, tol, maxitn, anorm, sigmax, maxits, monit, sigcmp='N', norm=None, weight='N', iterm=1, sigtol=0.01):
r"""
complex_herm_basic_setup is a setup function, the first in a suite of three functions for the iterative solution of a complex Hermitian system of simultaneous linear equations. complex_herm_basic_setup must be called before :meth:complex_herm_basic_solver, the iterative solver.
The third function in the suite, :meth:complex_herm_basic_diag, can be used to return additional information about the computation.

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

.. _f11gr-py2-py-doc:

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

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

.. _f11gr-py2-py-parameters:

**Parameters**
**method** : str
The iterative method to be used.

:math:\mathrm{method} = \texttt{'CG'}

:math:\mathrm{method} = \texttt{'SYMMLQ'}

Lanczos method (SYMMLQ).

**precon** : str, length 1
Determines whether preconditioning is used.

:math:\mathrm{precon} = \texttt{'N'}

No preconditioning.

:math:\mathrm{precon} = \texttt{'P'}

Preconditioning.

**n** : int
:math:n, the order of the matrix :math:A.

**tol** : float
The tolerance :math:\tau for the termination criterion.

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon }}, {\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision.

Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations.

**anorm** : float
If :math:\mathrm{anorm} > 0.0, the value of :math:\left\lVert A\right\rVert_p to be used in the termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__ (:math:\mathrm{iterm} = 1).

If :math:\mathrm{anorm}\leq 0.0, :math:\mathrm{iterm} = 1 and :math:\mathrm{norm} = \texttt{'1'} or :math:\texttt{'I'}, :math:\left\lVert A\right\rVert_1 = \left\lVert A\right\rVert_\infty is estimated internally by :meth:complex_herm_basic_solver.

If :math:\mathrm{iterm} = 2, :math:\mathrm{anorm} is not referenced.

**sigmax** : float
If :math:\mathrm{sigmax} > 0.0, the value of :math:\sigma_1\left(\bar{A}\right) = \left\lVert E^{-1}AE^{-\mathrm{H}}\right\rVert_2.

If :math:\mathrm{sigmax}\leq 0.0, :math:\sigma_1\left(\bar{A}\right) is estimated by :meth:complex_herm_basic_solver when either :math:\mathrm{sigcmp} = \texttt{'S'} or termination criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe3>__ (:math:\mathrm{iterm} = 2) is employed, though it will be used only in the latter case.

Otherwise, :math:\mathrm{sigmax} is not referenced.

**maxits** : int
The maximum iteration number :math:k = \mathrm{maxits} for which :math:\sigma_1\left(T_k\right) is computed by bisection (see also :ref:Notes <f11gr-py2-py-notes>). If :math:\mathrm{sigcmp} = \texttt{'N'} or :math:\mathrm{sigmax} > 0.0, :math:\mathrm{maxits} is not referenced.

Suggested value: :math:\mathrm{maxits} = \mathrm{min}\left(10, n\right) when :math:\mathrm{sigtol} is of the order of its default value :math:\left(0.01\right).

**monit** : int
If :math:\mathrm{monit} > 0, the frequency at which a monitoring step is executed by :meth:complex_herm_basic_solver: the current solution and residual iterates will be returned by :meth:complex_herm_basic_solver and a call to :meth:complex_herm_basic_diag made possible every :math:\mathrm{monit} iterations, starting from iteration number :math:\mathrm{monit}. Otherwise, no monitoring takes place. There are some additional computational costs involved in monitoring the solution and residual vectors when the Lanczos method (SYMMLQ) is used.

**sigcmp** : str, length 1, optional
Determines whether an estimate of :math:\sigma_1\left(\bar{A}\right) = \left\lVert E^{-1}AE^{-\mathrm{H}}\right\rVert_2, the largest singular value of the preconditioned matrix of the coefficients, is to be computed using the bisection method on the sequence of tridiagonal matrices :math:\left\{T_k\right\} generated during the iteration. Note that :math:\bar{A} = A when a preconditioner is not used.

If :math:\mathrm{sigmax} > 0.0 (see :math:\mathrm{sigmax}), i.e., when :math:\sigma_1\left(\bar{A}\right) is supplied, the value of :math:\mathrm{sigcmp} is ignored.

:math:\mathrm{sigcmp} = \texttt{'S'}

:math:\sigma_1\left(\bar{A}\right) is to be computed using the bisection method.

:math:\mathrm{sigcmp} = \texttt{'N'}

The bisection method is not used.

If the termination criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe3>__ is used, requiring :math:\sigma_1\left(\bar{A}\right), an inexpensive estimate is computed and used (see :ref:Notes <f11gr-py2-py-notes>).

**norm** : None or str, length 1, optional
Note: if this argument is **None** then a default value will be used, determined as follows: if :math:\mathrm{iterm} = 1: :math:{ \texttt{'I'} }; otherwise: :math:{ \texttt{'2'} }.

Defines the matrix and vector norm to be used in the termination criteria.

:math:\mathrm{norm} = \texttt{'1'}

Use the :math:l_1 norm.

:math:\mathrm{norm} = \texttt{'I'}

Use the :math:l_{\infty } norm.

:math:\mathrm{norm} = \texttt{'2'}

Use the :math:l_2 norm.

**weight** : str, length 1, optional
Specifies whether a vector :math:w of user-supplied weights is to be used in the vector norms used in the computation of termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__ (:math:\mathrm{iterm} = 1): :math:\left\lVert v\right\rVert_p^{\left(w\right)} = \left\lVert v^{\left(w\right)}\right\rVert_p, where :math:v_{\textit{i}}^{\left(w\right)} = w_{\textit{i}}v_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n. The suffix :math:p = 1,2,\infty denotes the vector norm used, as specified by the argument :math:\mathrm{norm}. Note that weights cannot be used when :math:\mathrm{iterm} = 2, i.e., when criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe3>__ is used.

:math:\mathrm{weight} = \texttt{'W'}

User-supplied weights are to be used and must be supplied on initial entry to :meth:complex_herm_basic_solver.

:math:\mathrm{weight} = \texttt{'N'}

All weights are implicitly set equal to one. Weights do not need to be supplied on initial entry to :meth:complex_herm_basic_solver.

**iterm** : int, optional
Defines the termination criterion to be used.

:math:\mathrm{iterm} = 1

Use the termination criterion defined in (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__ (both conjugate gradient and Lanczos (SYMMLQ) methods).

:math:\mathrm{iterm} = 2

Use the termination criterion defined in (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe3>__ (Lanczos method (SYMMLQ) only).

**sigtol** : float, optional
The tolerance used in assessing the convergence of the estimate of :math:\sigma_1\left(\bar{A}\right) = \left\lVert \bar{A}\right\rVert_2 when the bisection method is used.

If :math:\mathrm{sigtol}\leq 0.0, the default value :math:\mathrm{sigtol} = 0.01 is used.

The actual value used is :math:\mathrm{max}\left(\mathrm{sigtol}, \epsilon \right).

If :math:\mathrm{sigcmp} = \texttt{'N'} or :math:\mathrm{sigmax} > 0.0, :math:\mathrm{sigtol} is not referenced.

**Returns**
**comm** : dict, communication object
Communication structure.

.. _f11gr-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-14)
On entry, :math:\mathrm{monit} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{monit}\leq \mathrm{maxitn}.

(errno :math:-13)
On entry, :math:\mathrm{maxits} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{sigcmp} = \langle\mathit{\boldsymbol{value}}\rangle, and :math:\mathrm{sigmax} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{sigcmp} = \texttt{'S'} and :math:\mathrm{sigmax}\leq 0.0, :math:1\leq \mathrm{maxits}\leq \mathrm{maxitn}.

(errno :math:-12)
On entry, :math:\mathrm{sigcmp} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{sigtol} = \langle\mathit{\boldsymbol{value}}\rangle, and :math:\mathrm{sigmax} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{sigcmp} = \texttt{'S'} and :math:\mathrm{sigmax}\leq 0.0, :math:\mathrm{sigtol} < 1.0.

(errno :math:-10)
On entry, :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{iterm} = \langle\mathit{\boldsymbol{value}}\rangle, and :math:\mathrm{anorm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 1 and :math:\mathrm{norm} = \texttt{'2'} or :math:\texttt{'I'}, :math:\mathrm{anorm} > 0.0.

(errno :math:-9)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn} > 0.

(errno :math:-8)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:-7)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} > 0.

(errno :math:-6)
On entry, :math:\mathrm{iterm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{iterm} = 1 or :math:2.

(errno :math:-6)
On entry, :math:\mathrm{iterm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{method} = \texttt{'SYMMLQ'}.

(errno :math:-6)
On entry, :math:\mathrm{iterm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{norm} = \texttt{'2'} or :math:\texttt{'I'}.

(errno :math:-5)
On entry, :math:\mathrm{weight} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{weight} = \texttt{'N'} or :math:\texttt{'W'}.

(errno :math:-5)
On entry, :math:\mathrm{iterm} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{weight} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if :math:\mathrm{iterm} = 2, :math:\mathrm{weight} = \texttt{'N'}.

(errno :math:-4)
On entry, :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{norm} = \texttt{'1'}, :math:\texttt{'I'} or :math:\texttt{'2'}.

(errno :math:-3)
On entry, :math:\mathrm{sigcmp} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{sigcmp} = \texttt{'N'} or :math:\texttt{'S'}.

(errno :math:-2)
On entry, :math:\mathrm{precon} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{precon} = \texttt{'N'} or :math:\texttt{'P'}.

(errno :math:-1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'CG'} or :math:\texttt{'SYMMLQ'}.

(errno :math:1)
complex_herm_basic_setup has been called out of sequence: either complex_herm_basic_setup has been called twice or :meth:complex_herm_basic_solver has not terminated its current task.

.. _f11gr-py2-py-notes:

**Notes**
The suite consisting of the functions complex_herm_basic_setup, :meth:complex_herm_basic_solver and :meth:complex_herm_basic_diag is designed to solve the complex Hermitian system of simultaneous linear equations :math:Ax = b of order :math:n, where :math:n is large and the matrix of the coefficients :math:A is sparse.

complex_herm_basic_setup is a setup function which must be called before the iterative solver :meth:complex_herm_basic_solver. :meth:complex_herm_basic_diag, the third function in the suite, can be used to return additional information about the computation.
Either of two methods can be used:

For this method (see Hestenes and Stiefel (1952), Golub and Van Loan (1996), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)), the matrix :math:A should ideally be positive definite.
The application of the Conjugate Gradient method to indefinite matrices may lead to failure or to lack of convergence.

(#) **Lanczos Method (SYMMLQ)**

This method, based upon the algorithm SYMMLQ (see Paige and Saunders (1975) and Barrett et al. (1994)), is suitable for both positive definite and indefinite matrices.
It is more robust than the Conjugate Gradient method but less efficient when :math:A is positive definite.

Both CG and SYMMLQ methods start from the residual :math:r_0 = b-Ax_0, where :math:x_0 is an initial estimate for the solution (often :math:x_0 = 0), and generate an orthogonal basis for the Krylov subspace :math:\mathrm{span}\left\{A^{\textit{k}}r_0\right\}, for :math:\textit{k} = 0,1,\ldots,, by means of three-term recurrence relations (see Golub and Van Loan (1996)).
A sequence of real symmetric tridiagonal matrices :math:\left\{T_k\right\} is also generated.
Here and in the following, the index :math:k denotes the iteration count.
The resulting real symmetric tridiagonal systems of equations are usually more easily solved than the original problem.
A sequence of solution iterates :math:\left\{x_k\right\} is thus generated such that the sequence of the norms of the residuals :math:\left\{\left\lVert r_k\right\rVert \right\} converges to a required tolerance.
Note that, in general, the convergence is not monotonic.

In exact arithmetic, after :math:n iterations, this process is equivalent to an orthogonal reduction of :math:A to real symmetric tridiagonal form, :math:T_n = Q^\mathrm{H}AQ; the solution :math:x_n would thus achieve exact convergence.
In finite-precision arithmetic, cancellation and round-off errors accumulate causing loss of orthogonality.
These methods must, therefore, be viewed as genuinely iterative methods, able to converge to a solution **within a prescribed tolerance**.

The orthogonal basis is not formed explicitly in either method.
The basic difference between the two methods lies in the method of solution of the resulting real symmetric tridiagonal systems of equations: the conjugate gradient method is equivalent to carrying out an :math:LDL^\mathrm{H} (Cholesky) factorization whereas the Lanczos method (SYMMLQ) uses an :math:LQ factorization.

Faster convergence can be achieved using a **preconditioner** (see Golub and Van Loan (1996) and Barrett et al. (1994)).
A preconditioner maps the original system of equations onto a different system, say

.. math::
\bar{A}\bar{x} = \bar{b}\text{,}

with, hopefully, better characteristics with respect to its speed of convergence: for example, the condition number of the matrix of the coefficients can be improved or eigenvalues in its spectrum can be made to coalesce.
An orthogonal basis for the Krylov subspace :math:\mathrm{span}\left\{\bar{A}^{\textit{k}}\bar{r}_0\right\}, for :math:\textit{k} = 0,1,\ldots,, is generated and the solution proceeds as outlined above.
The algorithms used are such that the solution and residual iterates of the original system are produced, not their preconditioned counterparts.
Note that an unsuitable preconditioner or no preconditioning at all may result in a very slow rate, or lack, of convergence.
However, preconditioning involves a trade-off between the reduction in the number of iterations required for convergence and the additional computational costs per iteration.
Also, setting up a preconditioner may involve non-negligible overheads.

A preconditioner must be **Hermitian and positive definite**, i.e., representable by :math:M = EE^\mathrm{H}, where :math:M is nonsingular, and such that :math:\bar{A} = E^{-1}AE^{-\mathrm{H}}\sim I_n in (1) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe1>__, where :math:I_n is the identity matrix of order :math:n.
Also, we can define :math:\bar{r} = E^{-1}r and :math:\bar{x} = E^\mathrm{H}x.
These are formal definitions, used only in the design of the algorithms; in practice, only the means to compute the matrix-vector products :math:v = Au and to solve the preconditioning equations :math:Mv = u are required, that is, explicit information about :math:M, :math:E or their inverses is not required at any stage.

The first termination criterion

.. math::
\left\lVert r_k\right\rVert_p\leq \tau \left({\left\lVert b\right\rVert_p+\left\lVert A\right\rVert_p}\times {\left\lVert x_k\right\rVert_p}\right)

is available for both conjugate gradient and Lanczos (SYMMLQ) methods.
In (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__, :math:p = 1,\infty or :math:2 and :math:\tau denotes a user-specified tolerance subject to :math:\mathrm{max}\left(10, {\sqrt{n}}\right)\epsilon \leq \tau < 1, where :math:\epsilon is the machine precision.
Facilities are provided for the estimation of the norm of the matrix of the coefficients :math:\left\lVert A\right\rVert_1 = \left\lVert A\right\rVert_\infty, when this is not known in advance, used in (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__, by applying Higham's method (see Higham (1988)).
Note that :math:\left\lVert A\right\rVert_2 cannot be estimated internally.
This criterion uses an error bound derived from **backward** error analysis to ensure that the computed solution is the exact solution of a problem as close to the original as the termination tolerance requires.
Termination criteria employing bounds derived from **forward** error analysis could be used, but any such criteria would require information about the condition number :math:\kappa \left(A\right) which is not easily obtainable.

The second termination criterion

.. math::
\left\lVert \bar{r}_k\right\rVert_2\leq \tau \mathrm{max}\left(1.0, {\left\lVert b\right\rVert_2/\left\lVert r_0\right\rVert_2}\right)\left({\left\lVert \bar{r}_0\right\rVert_2+\sigma_1\left(\bar{A}\right)}\times {\left\lVert \Delta \bar{x}_k\right\rVert_2}\right)

is available only for the Lanczos method (SYMMLQ).
In (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe3>__, :math:\sigma_1\left(\bar{A}\right) = \left\lVert \bar{A}\right\rVert_2 is the largest singular value of the (preconditioned) iteration matrix :math:\bar{A}.
This termination criterion monitors the progress of the solution of the preconditioned system of equations and is less expensive to apply than criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__.
When :math:\sigma_1\left(\bar{A}\right) is not supplied, facilities are provided for its estimation by :math:\sigma_1\left(\bar{A}\right)\sim \mathrm{max}_k\sigma_1\left(T_k\right).
The interlacing property :math:\sigma_1\left(T_{{k-1}}\right)\leq \sigma_1\left(T_k\right) and Gerschgorin's theorem provide lower and upper bounds from which :math:\sigma_1\left(T_k\right) can be easily computed by bisection.
Alternatively, the less expensive estimate :math:\sigma_1\left(\bar{A}\right)\sim \mathrm{max}_k\left\lVert T_k\right\rVert_1 can be used, where :math:\sigma_1\left(\bar{A}\right)\leq \left\lVert T_k\right\rVert_1 by Gerschgorin's theorem.
Note that only order of magnitude estimates are required by the termination criterion.

Termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__ is the recommended choice, despite its (small) additional costs per iteration when using the Lanczos method (SYMMLQ).
Also, if the norm of the initial estimate is much larger than the norm of the solution, that is, if :math:\left\lVert x_0\right\rVert ≫\left\lVert x\right\rVert, a dramatic loss of significant digits could result in complete lack of convergence.
The use of criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__ will enable the detection of such a situation, and the iteration will be restarted at a suitable point.
No such restart facilities are provided for criterion (3) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe3>__.

Optionally, a vector :math:w of user-specified weights can be used in the computation of the vector norms in termination criterion (2) <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#eqnf11grfe2>__, i.e., :math:\left\lVert v\right\rVert_p^{\left(w\right)} = \left\lVert v^{\left(w\right)}\right\rVert_p, where :math:{\left(v^{\left(w\right)}\right)}_{\textit{i}} = w_{\textit{i}}v_{\textit{i}}, for :math:\textit{i} = 1,2,\ldots,n.
Note that the use of weights increases the computational costs.

The sequence of calls to the functions comprising the suite is enforced: first, the setup function complex_herm_basic_setup must be called, followed by the solver :meth:complex_herm_basic_solver. :meth:complex_herm_basic_diag can be called either when :meth:complex_herm_basic_solver is carrying out a monitoring step or after :meth:complex_herm_basic_solver has completed its tasks.
Incorrect sequencing will raise an error condition.

.. _f11gr-py2-py-references:

**References**
Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Dias da Cunha, R and Hopkins, T, 1994, PIM 1.1 --- the parallel iterative method package for systems of linear equations user's guide --- Fortran 77 version, Technical Report, Computing Laboratory, University of Kent at Canterbury, Kent, UK

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

Hestenes, M and Stiefel, E, 1952, Methods of conjugate gradients for solving linear systems, J. Res. Nat. Bur. Stand. (49), 409--436

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

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617--629
"""
raise NotImplementedError

[docs]def complex_herm_basic_solver(irevcm, u, v, wgt, comm):
r"""
complex_herm_basic_solver is an iterative solver for a complex Hermitian system of simultaneous linear equations; complex_herm_basic_solver is the second in a suite of three functions, where the first function, :meth:complex_herm_basic_setup, must be called prior to complex_herm_basic_solver to set up the suite, and the third function in the suite, :meth:complex_herm_basic_diag, can be used to return additional information about the computation.

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

.. _f11gs-py2-py-doc:

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

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

.. _f11gs-py2-py-parameters:

**Parameters**
**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: :math:\mathrm{irevcm} must either be unchanged from its previous exit value, or can have one of the following values.

:math:\mathrm{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_herm_basic_solver will then return with the termination code :math:\mathrm{irevcm} = 4. Note that before calling complex_herm_basic_solver with :math:\mathrm{irevcm} = 5 the calling program must have performed the tasks required by the value of :math:\mathrm{irevcm} returned by the previous call to complex_herm_basic_solver, otherwise subsequently returned values may be invalid.

:math:\mathrm{irevcm} = 6

Immediate termination: complex_herm_basic_solver will return immediately with termination code :math:\mathrm{irevcm} = 4 and with any useful information available. This includes the last iterate of the solution and, for conjugate gradient only, the last iterate of the residual vector. The residual vector is generally not available when the Lanczos method (SYMMLQ) is used. complex_herm_basic_solver will then return with the termination code :math:\mathrm{irevcm} = 4.

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

Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

**u** : complex, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: an initial estimate, :math:x_0, of the solution of the system of equations :math:Ax = b.

On intermediate entry: must remain unchanged.

On intermediate exit: the returned value of :math:\mathrm{irevcm} determines the contents of :math:\mathrm{u} in the following way.

If :math:\mathrm{irevcm} = 1 or :math:2, :math:\mathrm{u} holds the vector :math:u on which the operation specified by :math:\mathrm{irevcm} is to be carried out.

If :math:\mathrm{irevcm} = 3, :math:\mathrm{u} holds the current iterate of the solution vector.

On final exit: if :math:\mathrm{errno} = 3 or -i, the array :math:\mathrm{u} is unchanged from the initial entry to complex_herm_basic_solver. If :math:\mathrm{errno} = 1, the array :math:\mathrm{u} is unchanged from the last entry to complex_herm_basic_solver. Otherwise, :math:\mathrm{u} holds the last iterate of the solution of the system of equations, for all returned values of :math:\textit{errno}.

**v** : complex, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: the right-hand side :math:b of the system of equations :math:Ax = b.

On intermediate entry: the returned value of :math:\mathrm{irevcm} determines the contents of :math:\mathrm{v} in the following way.

If :math:\mathrm{irevcm} = 1 or :math:2, :math:\mathrm{v} must store the vector :math:v, the result of the operation specified by the value of :math:\mathrm{irevcm} returned by the previous call to complex_herm_basic_solver

If :math:\mathrm{irevcm} = 3, :math:\mathrm{v} must remain unchanged.

On intermediate exit: if :math:\mathrm{irevcm} = 3, :math:\mathrm{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 :math:\mathrm{errno} = 3 or 0, the array :math:\mathrm{v} is unchanged from the last entry to complex_herm_basic_solver. If :math:\mathrm{errno} = 1, the array :math:\mathrm{v} is unchanged from the initial entry to complex_herm_basic_solver. If the function exits successfully or :math:\mathrm{errno} = 2, the array :math:\mathrm{v} contains the true residual vector of the system of equations (see also :ref:Exceptions <f11gs-py2-py-errors>). Otherwise, :math:\mathrm{v} stores the last iterate of the residual vector unless the Lanczos method (SYMMLQ) was used and :math:\mathrm{errno} >= 5, in which case :math:\mathrm{v} is set to :math:0.0.

**wgt** : float, array-like, shape :math:\left(\textit{n}\right)
The user-supplied weights, if these are to be used in the computation of the vector norms in the termination criterion (see :ref:Notes for complex_herm_basic_setup <f11gr-py2-py-notes> and :ref:Parameters for complex_herm_basic_setup <f11gr-py2-py-parameters>).

**comm** : dict, communication object, modified in place
Communication structure.

This argument must have been initialized by a prior call to :meth:complex_herm_basic_setup.

**Returns**
**irevcm** : int
On intermediate exit: has the following meanings.

:math:\mathrm{irevcm} = 1

The calling program must compute the matrix-vector product :math:v = Au, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively.

:math:\mathrm{irevcm} = 2

The calling program must solve the preconditioning equation :math:Mv = u, where :math:u and :math:v are stored in :math:\mathrm{u} and :math:\mathrm{v}, respectively.

:math:\mathrm{irevcm} = 3

Monitoring step: the solution and residual at the current iteration are returned in the arrays :math:\mathrm{u} and :math:\mathrm{v}, respectively. No action by the calling program is required. To return additional information :meth:complex_herm_basic_diag can be called at this step.

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

.. _f11gs-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:-1)
On intermediate re-entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: either :math:\mathrm{irevcm} must be unchanged from its previous exit value or :math:\mathrm{irevcm} = 5 or :math:6.

(errno :math:-1)
On initial entry, :math:\mathrm{irevcm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irevcm} = 0.

(errno :math:3)
Either :meth:complex_herm_basic_setup was not called before calling complex_herm_basic_solver or it has returned an error.

(errno :math:9)
The matrix of the coefficients :math:A appears to be singular. The computation cannot continue.

**Warns**
**NagAlgorithmicWarning**
(errno :math:1)
complex_herm_basic_solver has already completed its tasks. You need to set a new problem.

(errno :math:2)
The required accuracy could not be obtained. However, a reasonable accuracy may have been achieved.

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

(errno :math:4)
User-requested tidy termination. The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
The preconditioner appears not to be positive definite. The computation cannot continue.

(errno :math:7)
The matrix of the coefficients :math:A appears not to be positive definite. The computation cannot continue.

(errno :math:8)
User-requested immediate termination.

(errno :math:10)
The weights in array :math:\mathrm{wgt} are all zero.

.. _f11gs-py2-py-notes:

**Notes**
complex_herm_basic_solver solves the complex Hermitian system of linear simultaneous equations :math:Ax = b using either the preconditioned conjugate gradient method (see Hestenes and Stiefel (1952), Golub and Van Loan (1996), Barrett et al. (1994) and Dias da Cunha and Hopkins (1994)) or a preconditioned Lanczos method based upon the algorithm SYMMLQ (see Paige and Saunders (1975) and Barrett et al. (1994)).

For a general description of the methods employed you are referred to :ref:Notes for complex_herm_basic_setup <f11gr-py2-py-notes>.

complex_herm_basic_solver can solve the system after the first function in the suite, :meth:complex_herm_basic_setup, has been called to initialize the computation and specify the method of solution.
The third function in the suite, :meth:complex_herm_basic_diag, can be used to return additional information generated by the computation during monitoring steps and after complex_herm_basic_solver has completed its tasks.

complex_herm_basic_solver uses **reverse communication**, i.e., complex_herm_basic_solver returns repeatedly to the calling program with the argument :math:\mathrm{irevcm} (see :ref:Parameters <f11gs-py2-py-parameters>) set to specified values which require the calling program to carry out a specific task: either to compute the matrix-vector product :math:v = Au; to solve the preconditioning equation :math:Mv = u; to notify the completion of the computation; or, to allow the calling program to monitor the solution.
Through the argument :math:\mathrm{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.

(#) 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.

.. _f11gs-py2-py-references:

**References**
Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Dias da Cunha, R and Hopkins, T, 1994, PIM 1.1 --- the parallel iterative method package for systems of linear equations user's guide --- Fortran 77 version, Technical Report, Computing Laboratory, University of Kent at Canterbury, Kent, UK

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

Hestenes, M and Stiefel, E, 1952, Methods of conjugate gradients for solving linear systems, J. Res. Nat. Bur. Stand. (49), 409--436

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

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617--629
"""
raise NotImplementedError

[docs]def complex_herm_basic_diag(comm):
r"""
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, :meth:complex_herm_basic_setup, is a setup function, the second function, :meth: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.

.. _f11gt-py2-py-doc:

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

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

.. _f11gt-py2-py-parameters:

**Parameters**
**comm** : dict, communication object
Communication structure.

This argument must have been initialized by a prior call to :meth:complex_herm_basic_solver.

**Returns**
**itn** : int
The number of iterations carried out by :meth:complex_herm_basic_solver.

**stplhs** : float
The current value of the left-hand side of the termination criterion used by :meth:complex_herm_basic_solver.

**stprhs** : float
The current value of the right-hand side of the termination criterion used by :meth:complex_herm_basic_solver.

**anorm** : float
The norm :math:\left\lVert A\right\rVert_1 = \left\lVert A\right\rVert_\infty when either it has been supplied to :meth:complex_herm_basic_setup or it has been estimated by :meth:complex_herm_basic_solver (see also :ref:Notes for complex_herm_basic_setup <f11gr-py2-py-notes> and :ref:Parameters for complex_herm_basic_setup <f11gr-py2-py-parameters>).

Otherwise, :math:\mathrm{anorm} = 0.0 is returned.

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

**its** : int
The number of iterations employed so far in the computation of the estimate of :math:\sigma_1\left(\bar{A}\right), the largest singular value of the preconditioned matrix :math:\bar{A} = E^{-1}AE^{{-\mathrm{H}}}, when :math:\sigma_1\left(\bar{A}\right) has been estimated by :meth:complex_herm_basic_solver using the bisection method (see also :ref:Notes for complex_herm_basic_setup <f11gr-py2-py-notes>, :ref:Parameters for complex_herm_basic_setup <f11gr-py2-py-parameters> and Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11grf.html#fcomments>__). Otherwise, :math:\mathrm{its} = 0 is returned.

**sigerr** : float
If :math:\sigma_1\left(\bar{A}\right) has been estimated by :meth:complex_herm_basic_solver using bisection,

.. math::
\mathrm{sigerr} = \mathrm{max}\left(\frac{{\left\lvert \sigma_1^{\left(k\right)}-\sigma_1^{\left(k-1\right)}\right\rvert }}{{\sigma_1^{\left(k\right)}}}, \frac{{\left\lvert \sigma_1^{\left(k\right)}-\sigma_1^{\left(k-2\right)}\right\rvert }}{{\sigma_1^{\left(k\right)}}}\right)\text{,}

where :math:k = \mathrm{its} denotes the iteration number. The estimation has converged if :math:\mathrm{sigerr}\leq {\textit{sigtol}} where :math:\textit{sigtol} is an input argument to :meth:complex_herm_basic_setup.

Otherwise, :math:\mathrm{sigerr} = 0.0 is returned.

.. _f11gt-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
complex_herm_basic_diag has been called out of sequence.

.. _f11gt-py2-py-notes:

**Notes**
complex_herm_basic_diag returns information about the solution process.
It can be called both during a monitoring step of the solver :meth: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 :meth:complex_herm_basic_setup and :meth:complex_herm_basic_solver.

.. _f11gt-py2-py-references:

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

[docs]def real_symm_precon_ichol(nnz, a, irow, icol, lfill, dtol, mic, dscale, ipiv, pstrat='M'):
r"""
real_symm_precon_ichol computes an incomplete Cholesky factorization of a real sparse symmetric matrix, represented in symmetric coordinate storage format.
This factorization may be used as a preconditioner in combination with :meth:real_symm_solve_ichol or :meth:real_symm_basic_solver.

.. _f11ja-py2-py-doc:

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

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

.. _f11ja-py2-py-parameters:

**Parameters**
**nnz** : int
The number of nonzero elements in the lower triangular part of the matrix :math:A.

**a** : float, array-like, shape :math:\left(\textit{la}\right)
The nonzero elements in the lower triangular part of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_symm_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**lfill** : int
If :math:\mathrm{lfill}\geq 0 its value is the maximum level of fill allowed in the decomposition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jaf.html#fcomments2>__). A negative value of :math:\mathrm{lfill} indicates that :math:\mathrm{dtol} will be used to control the fill instead.

**dtol** : float
If :math:\mathrm{lfill} < 0, :math:\mathrm{dtol} is used as a drop tolerance to control the fill-in (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jaf.html#fcomments2>__); otherwise :math:\mathrm{dtol} is not referenced.

**mic** : str, length 1
Indicates whether or not the factorization should be modified to preserve row sums (see Choice of Arguments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jaf.html#fcomments3>__).

:math:\mathrm{mic} = \texttt{'M'}

The factorization is modified.

:math:\mathrm{mic} = \texttt{'N'}

The factorization is not modified.

**dscale** : float
The diagonal scaling parameter. All diagonal elements are multiplied by the factor (:math:1+\mathrm{dscale}) at the start of the factorization. This can be used to ensure that the preconditioner is positive definite. See Choice of Arguments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jaf.html#fcomments3>__.

**ipiv** : int, array-like, shape :math:\left(n\right)
If :math:\mathrm{pstrat} = \texttt{'U'}, :math:\mathrm{ipiv}[i-1] must specify the row index of the diagonal element used as a pivot at elimination stage :math:i. Otherwise :math:\mathrm{ipiv} need not be initialized.

**pstrat** : str, length 1, optional
Specifies the pivoting strategy to be adopted.

:math:\mathrm{pstrat} = \texttt{'N'}

No pivoting is carried out.

:math:\mathrm{pstrat} = \texttt{'M'}

Diagonal pivoting aimed at minimizing fill-in is carried out, using the Markowitz strategy.

:math:\mathrm{pstrat} = \texttt{'U'}

Diagonal pivoting is carried out according to the user-defined input value of :math:\mathrm{ipiv}.

**Returns**
**a** : float, ndarray, shape :math:\left(\textit{la}\right)
The first :math:\mathrm{nnz} elements of :math:\mathrm{a} contain the nonzero elements of :math:A and the next :math:\mathrm{nnzc} elements contain the elements of the lower triangular matrix :math:C. Matrix elements are ordered by increasing row index, and by increasing column index within each row.

**irow** : int, ndarray, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements returned in :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements returned in :math:\mathrm{a}.

**ipiv** : int, ndarray, shape :math:\left(n\right)
The pivot indices. If :math:\mathrm{ipiv}[i-1] = j then the diagonal element in row :math:j was used as the pivot at elimination stage :math:i.

**istr** : int, ndarray, shape :math:\left(n+1\right)
:math:\mathrm{istr}[\textit{i}-1]-1, for :math:\textit{i} = 1,2,\ldots,n, is the starting address in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:i of the matrix :math:C. :math:\mathrm{istr}[n]-1 is the address of the last nonzero element in :math:C plus one.

**nnzc** : int
The number of nonzero elements in the lower triangular matrix :math:C.

**npivm** : int
The number of pivots which were modified during the factorization to ensure that :math:M was positive definite. The quality of the preconditioner will generally depend on the returned value of :math:\mathrm{npivm}. If :math:\mathrm{npivm} is large the preconditioner may not be satisfactory. In this case it may be advantageous to call real_symm_precon_ichol again with an increased value of either :math:\mathrm{lfill} or :math:\mathrm{dscale}. See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jaf.html#fcomments4>__.

.. _f11ja-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq n\times \left(n+1\right)/2.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:1)
On entry, :math:\mathrm{pstrat} \neq \texttt{'N'}, :math:\texttt{'U'} or :math:\texttt{'M'}: :math:\mathrm{pstrat} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{mic} \neq \texttt{'M'} or :math:\texttt{'N'}: :math:\mathrm{mic} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{dtol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dtol}\geq 0.0.

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipiv} is repeated.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipiv} lies outside the range :math:\left[1, n\right].

(errno :math:4)
The number of nonzero entries in the decomposition is too large. The decomposition has been terminated before completion. Either increase :math:\textit{la}, or reduce the fill by setting :math:\mathrm{pstrat} = \texttt{'M'}, reducing :math:\mathrm{lfill}, or increasing :math:\mathrm{dtol}.

(errno :math:5)
A serious error has occurred in an internal call. Check all function calls and array sizes. Seek expert help.

.. _f11ja-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

real_symm_precon_ichol computes an incomplete Cholesky factorization (see Meijerink and Van der Vorst (1977)) of a real sparse symmetric :math:n\times n matrix :math:A.
It is designed specifically for positive definite matrices, but may also work for some mildly indefinite cases.
The factorization is intended primarily for use as a preconditioner with one of the symmetric iterative solvers :meth:real_symm_solve_ichol or :meth:real_symm_basic_solver.

The decomposition is written in the form

.. math::
A = M+R

where

.. math::
M = PLDL^\mathrm{T}P^\mathrm{T}

and :math:P is a permutation matrix, :math:L is lower triangular with unit diagonal elements, :math:D is diagonal and :math:R is a remainder matrix.

The amount of fill-in occurring in the factorization can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill :math:\mathrm{lfill}, or the drop tolerance :math:\mathrm{dtol}.
The factorization may be modified in order to preserve row sums, and the diagonal elements may be perturbed to ensure that the preconditioner is positive definite.
Diagonal pivoting may optionally be employed, either with a user-defined ordering, or using the Markowitz strategy (see Markowitz (1957)), which aims to minimize fill-in.
For further details see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jaf.html#fcomments>__.

The sparse matrix :math:A is represented in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__).
The array :math:\mathrm{a} stores all the nonzero elements of the lower triangular part of :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.
Multiple nonzero elements may not be specified for the same row and column index.

The preconditioning matrix :math:M is returned in terms of the SCS representation of the lower triangular matrix

.. math::
C = L+D^{-1}-I\text{.}

.. _f11ja-py2-py-references:

**References**
Chan, T F, 1991, Fourier analysis of relaxed incomplete factorization preconditioners, SIAM J. Sci. Statist. Comput. (12(2)), 668--680

Markowitz, H M, 1957, The elimination form of the inverse and its application to linear programming, Management Sci. (3), 255--269

Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148--162

Salvini, S A and Shaw, G J, 1995, An evaluation of new NAG Library solvers for large sparse symmetric linear systems, NAG Technical Report TR1/95

Van der Vorst, H A, 1990, The convergence behaviour of preconditioned CG and CG-S in the presence of rounding errors, Lecture Notes in Mathematics, (eds O Axelsson and L Y Kolotilina) (1457), Springer--Verlag
"""
raise NotImplementedError

[docs]def real_symm_precon_ichol_solve(a, irow, icol, ipiv, istr, y, check='N'):
r"""
real_symm_precon_ichol_solve solves a system of linear equations involving the incomplete Cholesky preconditioning matrix generated by :meth:real_symm_precon_ichol.

.. _f11jb-py2-py-doc:

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

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

.. _f11jb-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(\textit{la}\right)
The values returned in the array :math:\mathrm{a} by a previous call to :meth:real_symm_precon_ichol.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:real_symm_precon_ichol.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:real_symm_precon_ichol.

**ipiv** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:real_symm_precon_ichol.

**istr** : int, array-like, shape :math:\left(n+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:real_symm_precon_ichol.

**y** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:y.

**check** : str, length 1, optional
Specifies whether or not the input data should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried out on the values of :math:\textit{n}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr}.

:math:\mathrm{check} = \texttt{'N'}

No checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jbf.html#fcomments2>__.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
The solution vector :math:x.

.. _f11jb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, :math:\mathrm{ipiv}[i-1] is a repeated value: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ipiv}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ipiv}[i-1]\geq 1 and :math:\mathrm{ipiv}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr}[i-1] is inconsistent with :math:\mathrm{irow}: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr} appears to be invalid.

.. _f11jb-py2-py-notes:

**Notes**
real_symm_precon_ichol_solve solves a system of linear equations

.. math::
Mx = y

involving the preconditioning matrix :math:M = PLDL^\mathrm{T}P^\mathrm{T}, corresponding to an incomplete Cholesky decomposition of a sparse symmetric matrix stored in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__), as generated by :meth:real_symm_precon_ichol.

In the above decomposition :math:L is a lower triangular sparse matrix with unit diagonal, :math:D is a diagonal matrix and :math:P is a permutation matrix. :math:L and :math:D are supplied to real_symm_precon_ichol_solve through the matrix

.. math::
C = L+D^{-1}-I

which is a lower triangular :math:\textit{n} by :math:\textit{n} sparse matrix, stored in SCS format, as returned by :meth:real_symm_precon_ichol.
The permutation matrix :math:P is returned from :meth:real_symm_precon_ichol via the array :math:\mathrm{ipiv}.

It is envisaged that a common use of real_symm_precon_ichol_solve will be to carry out the preconditioning step required in the application of :meth:real_symm_basic_solver to sparse symmetric linear systems. real_symm_precon_ichol_solve is used for this purpose by the Black Box function :meth:real_symm_solve_ichol.

real_symm_precon_ichol_solve may also be used in combination with :meth:real_symm_precon_ichol to solve a sparse symmetric positive definite system of linear equations directly (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jaf.html#fcomments4>__).
"""
raise NotImplementedError

[docs]def real_symm_solve_ichol(method, nnz, a, irow, icol, ipiv, istr, b, tol, maxitn, x):
r"""
real_symm_solve_ichol solves a real sparse symmetric system of linear equations, represented in symmetric coordinate storage format, using a conjugate gradient or Lanczos method, with incomplete Cholesky preconditioning.

.. _f11jc-py2-py-doc:

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

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

.. _f11jc-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'CG'}

:math:\mathrm{method} = \texttt{'SYMMLQ'}

Lanczos method (SYMMLQ).

**nnz** : int
The number of nonzero elements in the lower triangular part of the matrix :math:A. This **must** be the same value as was supplied in the preceding call to :meth:real_symm_precon_ichol.

**a** : float, array-like, shape :math:\left(\textit{la}\right)
The values returned in the array :math:\mathrm{a} by a previous call to :meth:real_symm_precon_ichol.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:real_symm_precon_ichol.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:real_symm_precon_ichol.

**ipiv** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:real_symm_precon_ichol.

**istr** : int, array-like, shape :math:\left(n+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:real_symm_precon_ichol.

**b** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },10\epsilon,\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : float, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11jc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'CG'} or :math:\texttt{'SYMMLQ'}.

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq n\times \left(n+1\right)/2.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[i-1],\mathrm{icol}[i-1]) is a duplicate: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq \mathrm{irow}[i-1].

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
The SCS representation of the preconditioner is invalid.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
The preconditioner appears not to be positive definite. The computation cannot continue.

(errno :math:7)
The matrix of the coefficients :math:\mathrm{a} appears not to be positive definite. The computation cannot continue.

(errno :math:8)
A serious error has occurred in an internal call: :math:\mathrm{IREVCM} = \langle\mathit{\boldsymbol{value}}\rangle. Check all function calls and array sizes. Seek expert help.

(errno :math:8)
A serious error has occurred in an internal call: :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle. Check all function calls and array sizes. Seek expert help.

**Warns**
**NagAlgorithmicWarning**
(errno :math:4)
The required accuracy could not be obtained. However a reasonable accuracy has been achieved.

.. _f11jc-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

real_symm_solve_ichol solves a real sparse symmetric linear system of equations

.. math::
Ax = b\text{,}

using a preconditioned conjugate gradient method (see Meijerink and Van der Vorst (1977)), or a preconditioned Lanczos method based on the algorithm SYMMLQ (see Paige and Saunders (1975)).
The conjugate gradient method is more efficient if :math:A is positive definite, but may fail to converge for indefinite matrices.
In this case the Lanczos method should be used instead.
For further details see Barrett et al. (1994).

real_symm_solve_ichol uses the incomplete Cholesky factorization determined by :meth:real_symm_precon_ichol as the preconditioning matrix.
A call to real_symm_solve_ichol must always be preceded by a call to :meth:real_symm_precon_ichol.
Alternative preconditioners for the same storage scheme are available by calling :meth:real_symm_solve_jacssor.

The matrix :math:A, and the preconditioning matrix :math:M, are represented in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}, as returned from :meth:real_symm_precon_ichol.
The array :math:\mathrm{a} holds the nonzero entries in the lower triangular parts of these matrices, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

.. _f11jc-py2-py-references:

**References**
Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148--162

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617--629

Salvini, S A and Shaw, G J, 1995, An evaluation of new NAG Library solvers for large sparse symmetric linear systems, NAG Technical Report TR1/95
"""
raise NotImplementedError

[docs]def real_symm_precon_ssor_solve(a, irow, icol, rdiag, omega, y, check='N'):
r"""
real_symm_precon_ssor_solve solves a system of linear equations involving the preconditioning matrix corresponding to SSOR applied to a real sparse symmetric matrix, represented in symmetric coordinate storage format.

.. _f11jd-py2-py-doc:

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

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

.. _f11jd-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements in the lower triangular part of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_symm_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**rdiag** : float, array-like, shape :math:\left(n\right)
The elements of the diagonal matrix :math:D^{-1}, where :math:D is the diagonal part of :math:A.

**omega** : float
The relaxation parameter :math:\omega.

**y** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:y.

**check** : str, length 1, optional
Specifies whether or not the input data should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried out on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow}, :math:\mathrm{icol} and :math:\mathrm{omega}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jdf.html#fcomments2>__.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
The solution vector :math:x.

.. _f11jd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{check} \neq \texttt{'C'} or :math:\texttt{'N'}: :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{omega} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0 < \mathrm{omega} < 2.0

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n\times \left(n+1\right)/2

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:4)
The matrix :math:A has no diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

.. _f11jd-py2-py-notes:

**Notes**
real_symm_precon_ssor_solve solves a system of equations

.. math::
Mx = y

involving the preconditioning matrix

.. math::
M = \frac{1}{{\omega \left(2-\omega \right)}}\left(D+\omega L\right)D^{-1}\left(D+\omega L\right)^\mathrm{T}

corresponding to symmetric successive-over-relaxation (SSOR) (see Young (1971)) on a linear system :math:Ax = b, where :math:A is a sparse symmetric matrix stored in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__).

In the definition of :math:M given above :math:D is the diagonal part of :math:A, :math:L is the strictly lower triangular part of :math:A, and :math:\omega is a user-defined relaxation parameter.

It is envisaged that a common use of real_symm_precon_ssor_solve will be to carry out the preconditioning step required in the application of :meth:real_symm_basic_solver to sparse linear systems. real_symm_precon_ssor_solve is also used for this purpose by the Black Box function :meth:real_symm_solve_jacssor.

.. _f11jd-py2-py-references:

**References**
Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def real_symm_solve_jacssor(method, precon, a, irow, icol, omega, b, tol, maxitn, x):
r"""
real_symm_solve_jacssor solves a real sparse symmetric system of linear equations, represented in symmetric coordinate storage format, using a conjugate gradient or Lanczos method, without preconditioning, with Jacobi or with SSOR preconditioning.

.. _f11je-py2-py-doc:

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

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

.. _f11je-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'CG'}

:math:\mathrm{method} = \texttt{'SYMMLQ'}

Lanczos method (SYMMLQ).

**precon** : str, length 1
Specifies the type of preconditioning to be used.

:math:\mathrm{precon} = \texttt{'N'}

No preconditioning.

:math:\mathrm{precon} = \texttt{'J'}

Jacobi.

:math:\mathrm{precon} = \texttt{'S'}

Symmetric successive-over-relaxation (SSOR).

**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the lower triangular part of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_symm_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**omega** : float
If :math:\mathrm{precon} = \texttt{'S'}, :math:\mathrm{omega} is the relaxation parameter :math:\omega to be used in the SSOR method. Otherwise :math:\mathrm{omega} need not be initialized.

**b** : float, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },10\epsilon,\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : float, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : float, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11je-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'CG'} or :math:\texttt{'SYMMLQ'}.

(errno :math:1)
On entry, :math:\mathrm{omega} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{omega} > 0.0 and :math:\mathrm{omega} < 2.0.

(errno :math:1)
On entry, :math:\mathrm{precon} \neq \texttt{'N'}, :math:\texttt{'J'} or :math:\texttt{'S'}: :math:\mathrm{precon} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n\times \left(n+1\right)/2.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
The matrix :math:A has a zero diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
The matrix :math:A has no diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:4)
The required accuracy could not be obtained. However a reasonable accuracy has been achieved.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
The preconditioner appears not to be positive definite. The computation cannot continue.

(errno :math:7)
The matrix of the coefficients :math:\mathrm{a} appears not to be positive definite. The computation cannot continue.

(errno :math:8)
A serious error has occurred in an internal call: :math:\mathrm{IREVCM} = \langle\mathit{\boldsymbol{value}}\rangle. Check all function calls and array sizes. Seek expert help.

(errno :math:8)
A serious error has occurred in an internal call: :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle. Check all function calls and array sizes. Seek expert help.

.. _f11je-py2-py-notes:

**Notes**
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

real_symm_solve_jacssor solves a real sparse symmetric linear system of equations

.. math::
Ax = b\text{,}

using a preconditioned conjugate gradient method (see Barrett et al. (1994)), or a preconditioned Lanczos method based on the algorithm SYMMLQ (see Paige and Saunders (1975)).
The conjugate gradient method is more efficient if :math:A is positive definite, but may fail to converge for indefinite matrices.
In this case the Lanczos method should be used instead.
For further details see Barrett et al. (1994).

The function allows the following choices for the preconditioner:

no preconditioning;

Jacobi preconditioning (see Young (1971));

symmetric successive-over-relaxation (SSOR) preconditioning (see Young (1971)).

For incomplete Cholesky (IC) preconditioning see :meth:real_symm_solve_ichol.

The matrix :math:A is represented in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}.
The array :math:\mathrm{a} holds the nonzero entries in the lower triangular part of the matrix, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

.. _f11je-py2-py-references:

**References**
Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617--629

Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def complex_herm_precon_ichol(nnz, a, irow, icol, lfill, dtol, mic, dscale, ipiv, pstrat='M'):
r"""
complex_herm_precon_ichol computes an incomplete Cholesky factorization of a complex sparse Hermitian matrix, represented in symmetric coordinate storage format.
This factorization may be used as a preconditioner in combination with :meth:complex_herm_solve_ilu.

.. _f11jn-py2-py-doc:

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

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

.. _f11jn-py2-py-parameters:

**Parameters**
**nnz** : int
The number of nonzero elements in the lower triangular part of the matrix :math:A.

**a** : complex, array-like, shape :math:\left(\textit{la}\right)
The nonzero elements in the lower triangular part of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_herm_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements supplied in :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements supplied in :math:\mathrm{a}.

**lfill** : int
If :math:\mathrm{lfill}\geq 0 its value is the maximum level of fill allowed in the decomposition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jnf.html#fcomments2>__). A negative value of :math:\mathrm{lfill} indicates that :math:\mathrm{dtol} will be used to control the fill instead.

**dtol** : float
If :math:\mathrm{lfill} < 0, :math:\mathrm{dtol} is used as a drop tolerance to control the fill-in (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jnf.html#fcomments2>__); otherwise :math:\mathrm{dtol} is not referenced.

**mic** : str, length 1
Indicates whether or not the factorization should be modified to preserve row sums (see Choice of Arguments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jnf.html#fcomments3>__).

:math:\mathrm{mic} = \texttt{'M'}

The factorization is modified.

:math:\mathrm{mic} = \texttt{'N'}

The factorization is not modified.

**dscale** : float
The diagonal scaling parameter. All diagonal elements are multiplied by the factor (:math:1.0+\mathrm{dscale}) at the start of the factorization. This can be used to ensure that the preconditioner is positive definite. See also Choice of Arguments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jnf.html#fcomments3>__.

**ipiv** : int, array-like, shape :math:\left(n\right)
If :math:\mathrm{pstrat} = \texttt{'U'}, :math:\mathrm{ipiv}[i-1] must specify the row index of the diagonal element to be used as a pivot at elimination stage :math:i. Otherwise :math:\mathrm{ipiv} need not be initialized.

**pstrat** : str, length 1, optional
Specifies the pivoting strategy to be adopted.

:math:\mathrm{pstrat} = \texttt{'N'}

No pivoting is carried out.

:math:\mathrm{pstrat} = \texttt{'M'}

Diagonal pivoting aimed at minimizing fill-in is carried out, using the Markowitz strategy (see Markowitz (1957)).

:math:\mathrm{pstrat} = \texttt{'U'}

Diagonal pivoting is carried out according to the user-defined input array :math:\mathrm{ipiv}.

**Returns**
**a** : complex, ndarray, shape :math:\left(\textit{la}\right)
The first :math:\mathrm{nnz} elements of :math:\mathrm{a} contain the nonzero elements of :math:A and the next :math:\mathrm{nnzc} elements contain the elements of the lower triangular matrix :math:C. Matrix elements are ordered by increasing row index, and by increasing column index within each row.

**irow** : int, ndarray, shape :math:\left(\textit{la}\right)
The row indices of the nonzero elements returned in :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{la}\right)
The column indices of the nonzero elements returned in :math:\mathrm{a}.

**ipiv** : int, ndarray, shape :math:\left(n\right)
The pivot indices. If :math:\mathrm{ipiv}[i-1] = j, the diagonal element in row :math:j was used as the pivot at elimination stage :math:i.

**istr** : int, ndarray, shape :math:\left(n+1\right)
:math:\mathrm{istr}[\textit{i}-1]-1, for :math:\textit{i} = 1,2,\ldots,n, is the starting address in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:i of the matrix :math:C. :math:\mathrm{istr}[n]-1 is the address of the last nonzero element in :math:C plus one.

**nnzc** : int
The number of nonzero elements in the lower triangular matrix :math:C.

**npivm** : int
The number of pivots which were modified during the factorization to ensure that :math:M was positive definite. The quality of the preconditioner will generally depend on the returned value of :math:\mathrm{npivm}. If :math:\mathrm{npivm} is large the preconditioner may not be satisfactory. In this case it may be advantageous to call complex_herm_precon_ichol again with an increased value of either :math:\mathrm{lfill} or :math:\mathrm{dscale}. See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jnf.html#fcomments3>__.

.. _f11jn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq n\times \left(n+1\right)/2

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:1)
On entry, :math:\mathrm{pstrat} \neq \texttt{'N'}, :math:\texttt{'U'} or :math:\texttt{'M'}: :math:\mathrm{pstrat} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{mic} \neq \texttt{'M'} or :math:\texttt{'N'}: :math:\mathrm{mic} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{dtol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dtol}\geq 0.0

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:2)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[\textit{I}-1]\geq 1 and :math:\mathrm{irow}[\textit{I}-1]\leq n.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipiv} is repeated.

(errno :math:3)
On entry, a user-supplied value of :math:\mathrm{ipiv} lies outside the range :math:\left[1, n\right].

(errno :math:4)
The number of nonzero entries in the decomposition is too large. The decomposition has been terminated before completion. Either increase :math:\textit{la}, or reduce the fill by setting :math:\mathrm{pstrat} = \texttt{'M'}, reducing :math:\mathrm{lfill}, or increasing :math:\mathrm{dtol}.

(errno :math:5)
A serious error has occurred in an internal call. Check all function calls and array sizes. Seek expert help.

.. _f11jn-py2-py-notes:

**Notes**
complex_herm_precon_ichol computes an incomplete Cholesky factorization (see Meijerink and Van der Vorst (1977)) of a complex sparse Hermitian :math:n\times n matrix :math:A.
It is designed specifically for positive definite matrices, but may also work for some mildly indefinite cases.
The factorization is intended primarily for use as a preconditioner with the complex Hermitian iterative solver :meth:complex_herm_solve_ilu.

The decomposition is written in the form

.. math::
A = M+R

where

.. math::
M = PLDL^\mathrm{H}P^\mathrm{T}

and :math:P is a permutation matrix, :math:L is lower triangular complex with unit diagonal elements, :math:D is real diagonal and :math:R is a remainder matrix.

The amount of fill-in occurring in the factorization can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill :math:\mathrm{lfill}, or the drop tolerance :math:\mathrm{dtol}.
The factorization may be modified in order to preserve row sums, and the diagonal elements may be perturbed to ensure that the preconditioner is positive definite.
Diagonal pivoting may optionally be employed, either with a user-defined ordering, or using the Markowitz strategy (see Markowitz (1957)), which aims to minimize fill-in.
For further details see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11jnf.html#fcomments>__.

The sparse matrix :math:A is represented in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__).
The array :math:\mathrm{a} stores all the nonzero elements of the lower triangular part of :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.
Multiple nonzero elements may not be specified for the same row and column index.

The preconditioning matrix :math:M is returned in terms of the SCS representation of the lower triangular matrix

.. math::
C = L+D^{-1}-I\text{.}

.. _f11jn-py2-py-references:

**References**
Chan, T F, 1991, Fourier analysis of relaxed incomplete factorization preconditioners, SIAM J. Sci. Statist. Comput. (12(2)), 668--680

Markowitz, H M, 1957, The elimination form of the inverse and its application to linear programming, Management Sci. (3), 255--269

Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148--162

Salvini, S A and Shaw, G J, 1995, An evaluation of new NAG Library solvers for large sparse symmetric linear systems, NAG Technical Report TR1/95

Van der Vorst, H A, 1990, The convergence behaviour of preconditioned CG and CG-S in the presence of rounding errors, Lecture Notes in Mathematics, (eds O Axelsson and L Y Kolotilina) (1457), Springer--Verlag
"""
raise NotImplementedError

[docs]def complex_herm_precon_ilu_solve(a, irow, icol, ipiv, istr, y, check='N'):
r"""
complex_herm_precon_ilu_solve solves a system of complex linear equations involving the incomplete Cholesky preconditioning matrix generated by :meth:complex_herm_precon_ichol.

.. _f11jp-py2-py-doc:

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

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

.. _f11jp-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(\textit{la}\right)
The values returned in the array :math:\mathrm{a} by a previous call to :meth:complex_herm_precon_ichol.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:complex_herm_precon_ichol.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:complex_herm_precon_ichol.

**ipiv** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:complex_herm_precon_ichol.

**istr** : int, array-like, shape :math:\left(n+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:complex_herm_precon_ichol.

**y** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:y.

**check** : str, length 1, optional
Specifies whether or not the input data should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried out on the values of :math:\textit{n}, :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
The solution vector :math:x.

.. _f11jp-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, :math:\mathrm{ipiv}[i-1] is a repeated value: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{ipiv}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{ipiv}[i-1]\geq 1 and :math:\mathrm{ipiv}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr}[i-1] is inconsistent with :math:\mathrm{irow}: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr} appears to be invalid.

.. _f11jp-py2-py-notes:

**Notes**
complex_herm_precon_ilu_solve solves a system of linear equations

.. math::
Mx = y

involving the preconditioning matrix :math:M = PLDL^\mathrm{H}P^\mathrm{T}, corresponding to an incomplete Cholesky decomposition of a complex sparse Hermitian matrix stored in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__), as generated by :meth:complex_herm_precon_ichol.

In the above decomposition :math:L is a complex lower triangular sparse matrix with unit diagonal, :math:D is a real diagonal matrix and :math:P is a permutation matrix. :math:L and :math:D are supplied to complex_herm_precon_ilu_solve through the matrix

.. math::
C = L+D^{-1}-I

which is a lower triangular :math:n\times n complex sparse matrix, stored in SCS format, as returned by :meth:complex_herm_precon_ichol.
The permutation matrix :math:P is returned from :meth:complex_herm_precon_ichol via the array :math:\mathrm{ipiv}.

complex_herm_precon_ilu_solve may also be used in combination with :meth:complex_herm_precon_ichol to solve a sparse complex Hermitian positive definite system of linear equations directly (see :meth:complex_herm_precon_ichol).
"""
raise NotImplementedError

[docs]def complex_herm_solve_ilu(method, nnz, a, irow, icol, ipiv, istr, b, tol, maxitn, x):
r"""
complex_herm_solve_ilu solves a complex sparse Hermitian system of linear equations, represented in symmetric coordinate storage format, using a conjugate gradient or Lanczos method, with incomplete Cholesky preconditioning.

.. _f11jq-py2-py-doc:

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

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

.. _f11jq-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'CG'}

:math:\mathrm{method} = \texttt{'SYMMLQ'}

Lanczos method (SYMMLQ).

**nnz** : int
The number of nonzero elements in the lower triangular part of the matrix :math:A. This **must** be the same value as was supplied in the preceding call to :meth:complex_herm_precon_ichol.

**a** : complex, array-like, shape :math:\left(\textit{la}\right)
The values returned in the array :math:\mathrm{a} by a previous call to :meth:complex_herm_precon_ichol.

**irow** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:complex_herm_precon_ichol.

**icol** : int, array-like, shape :math:\left(\textit{la}\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:complex_herm_precon_ichol.

**ipiv** : int, array-like, shape :math:\left(n\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:complex_herm_precon_ichol.

**istr** : int, array-like, shape :math:\left(n+1\right)
The values returned in arrays :math:\mathrm{irow}, :math:\mathrm{icol}, :math:\mathrm{ipiv} and :math:\mathrm{istr} by a previous call to :meth:complex_herm_precon_ichol.

**b** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },10\epsilon,\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : complex, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert_\infty, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

.. _f11jq-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{method} = \texttt{'CG'} or :math:\texttt{'SYMMLQ'}.

(errno :math:1)
On entry, :math:\textit{la} = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{la}\geq 2\times \mathrm{nnz}.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\leq n\times \left(n+1\right)/2.

(errno :math:1)
On entry, :math:\mathrm{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[i-1],\mathrm{icol}[i-1]) is a duplicate: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq \mathrm{irow}[i-1].

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
On entry, :math:\mathrm{istr} appears to be invalid.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
The preconditioner appears not to be positive definite. The computation cannot continue.

(errno :math:7)
The matrix of the coefficients :math:\mathrm{a} appears not to be positive definite. The computation cannot continue.

(errno :math:8)
A serious error, code :math:\langle\mathit{\boldsymbol{value}}\rangle, has occurred in an internal call. Check all function calls and array sizes. Seek expert help.

**Warns**
**NagAlgorithmicWarning**
(errno :math:4)
The required accuracy could not be obtained. However a reasonable accuracy has been achieved.

.. _f11jq-py2-py-notes:

**Notes**
complex_herm_solve_ilu solves a complex sparse Hermitian linear system of equations

.. math::
Ax = b\text{,}

using a preconditioned conjugate gradient method (see Meijerink and Van der Vorst (1977)), or a preconditioned Lanczos method based on the algorithm SYMMLQ (see Paige and Saunders (1975)).
The conjugate gradient method is more efficient if :math:A is positive definite, but may fail to converge for indefinite matrices.
In this case the Lanczos method should be used instead.
For further details see Barrett et al. (1994).

complex_herm_solve_ilu uses the incomplete Cholesky factorization determined by :meth:complex_herm_precon_ichol as the preconditioning matrix.
A call to complex_herm_solve_ilu must always be preceded by a call to :meth:complex_herm_precon_ichol.
Alternative preconditioners for the same storage scheme are available by calling :meth:complex_herm_solve_jacssor.

The matrix :math:A and the preconditioning matrix :math:M are represented in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}, as returned from :meth:complex_herm_precon_ichol.
The array :math:\mathrm{a} holds the nonzero entries in the lower triangular parts of these matrices, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

.. _f11jq-py2-py-references:

**References**
Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148--162

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617--629
"""
raise NotImplementedError

[docs]def complex_herm_precon_ssor_solve(a, irow, icol, rdiag, omega, y, check='N'):
r"""
complex_herm_precon_ssor_solve solves a system of linear equations involving the preconditioning matrix corresponding to SSOR applied to a complex sparse Hermitian matrix, represented in symmetric coordinate storage format.

.. _f11jr-py2-py-doc:

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

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

.. _f11jr-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements in the lower triangular part of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_herm_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**rdiag** : float, array-like, shape :math:\left(n\right)
The elements of the diagonal matrix :math:D^{-1}, where :math:D is the diagonal part of :math:A. Note that since :math:A is Hermitian the elements of :math:D^{-1} are necessarily real.

**omega** : float
The relaxation parameter :math:\omega.

**y** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:y.

**check** : str, length 1, optional
Specifies whether or not the input data should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried out on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow}, :math:\mathrm{icol} and :math:\mathrm{omega}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
The solution vector :math:x.

.. _f11jr-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:\mathrm{omega} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0 < \mathrm{omega} < 2.0.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n\times \left(n+1\right)/2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{icol}[i-1]\leq \mathrm{irow}[i-1].

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{irow}[\textit{i}-1]\leq n.

(errno :math:4)
The matrix :math:A has no diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

.. _f11jr-py2-py-notes:

**Notes**
complex_herm_precon_ssor_solve solves a system of equations

.. math::
Mx = y

involving the preconditioning matrix

.. math::
M = \frac{1}{{\omega \left(2-\omega \right)}}\left(D+\omega L\right)D^{-1}\left(D+\omega L\right)^H

corresponding to symmetric successive-over-relaxation (SSOR) (see Young (1971)) on a linear system :math:Ax = b, where :math:A is a sparse complex Hermitian matrix stored in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__).

In the definition of :math:M given above :math:D is the diagonal part of :math:A, :math:L is the strictly lower triangular part of :math:A and :math:\omega is a user-defined relaxation parameter.
Note that since :math:A is Hermitian the matrix :math:D is necessarily real.

.. _f11jr-py2-py-references:

**References**
Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def complex_herm_solve_jacssor(method, precon, a, irow, icol, omega, b, tol, maxitn, x):
r"""
complex_herm_solve_jacssor solves a complex sparse Hermitian system of linear equations, represented in symmetric coordinate storage format, using a conjugate gradient or Lanczos method, without preconditioning, with Jacobi or with SSOR preconditioning.

.. _f11js-py2-py-doc:

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

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

.. _f11js-py2-py-parameters:

**Parameters**
**method** : str
Specifies the iterative method to be used.

:math:\mathrm{method} = \texttt{'CG'}

:math:\mathrm{method} = \texttt{'SYMMLQ'}

Lanczos method (SYMMLQ).

**precon** : str, length 1
Specifies the type of preconditioning to be used.

:math:\mathrm{precon} = \texttt{'N'}

No preconditioning.

:math:\mathrm{precon} = \texttt{'J'}

Jacobi.

:math:\mathrm{precon} = \texttt{'S'}

Symmetric successive-over-relaxation (SSOR).

**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the lower triangular part of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_herm_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**omega** : float
If :math:\mathrm{precon} = \texttt{'S'}, :math:\mathrm{omega} is the relaxation parameter :math:\omega to be used in the SSOR method. Otherwise :math:\mathrm{omega} need not be initialized.

**b** : complex, array-like, shape :math:\left(n\right)
The right-hand side vector :math:b.

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

.. math::
\left\lVert r_k\right\rVert_\infty\leq \tau \times \left(\left\lVert b\right\rVert_\infty+\left\lVert A\right\rVert_\infty\left\lVert x_k\right\rVert_\infty\right)\text{.}

If :math:\mathrm{tol}\leq 0.0, :math:\tau = \mathrm{max}\left({\sqrt{\epsilon },10\epsilon,\sqrt{n}\epsilon }\right) is used, where :math:\epsilon is the machine precision. Otherwise :math:\tau = \mathrm{max}\left({\mathrm{tol},10\epsilon }, {\sqrt{n}\epsilon }\right) is used.

**maxitn** : int
The maximum number of iterations allowed.

**x** : complex, array-like, shape :math:\left(n\right)
An initial approximation to the solution vector :math:x.

**Returns**
**x** : complex, ndarray, shape :math:\left(n\right)
An improved approximation to the solution vector :math:x.

**rnorm** : float
The final value of the residual norm :math:\left\lVert r_k\right\rVert, where :math:k is the output value of :math:\mathrm{itn}.

**itn** : int
The number of iterations carried out.

**rdiag** : float, ndarray, shape :math:\left(n\right)
The elements of the diagonal matrix :math:D^{-1}, where :math:D is the diagonal part of :math:A. Note that since :math:A is Hermitian the elements of :math:D^{-1} are necessarily real.

.. _f11js-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{maxitn} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{maxitn}\geq 1.

(errno :math:1)
On entry, :math:\mathrm{tol} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{tol} < 1.0.

(errno :math:1)
On entry, :math:\mathrm{method} \neq \texttt{'CG'} or :math:\texttt{'SYMMLQ'}: :math:\mathrm{method} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\mathrm{omega} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0 < \mathrm{omega} < 2.0.

(errno :math:1)
On entry, :math:\mathrm{precon} \neq \texttt{'N'}, :math:\texttt{'J'} or :math:\texttt{'S'}: :math:\mathrm{precon} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n\times \left(n+1\right)/2

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

(errno :math:3)
The matrix :math:A has a zero diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
The matrix :math:A has no diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:4)
The required accuracy could not be obtained. However, a reasonable accuracy has been achieved and further iterations could not improve the result.

(errno :math:5)
The solution has not converged after :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
The preconditioner appears not to be positive definite. The computation cannot continue.

(errno :math:7)
The matrix of the coefficients :math:\mathrm{a} appears not to be positive definite. The computation cannot continue.

(errno :math:8)
A serious error, code :math:\langle\mathit{\boldsymbol{value}}\rangle, has occurred in an internal call. Check all function calls and array sizes. Seek expert help.

(errno :math:9)
The matrix :math:A has a non-real diagonal entry in row :math:\langle\mathit{\boldsymbol{value}}\rangle.

.. _f11js-py2-py-notes:

**Notes**
complex_herm_solve_jacssor solves a complex sparse Hermitian linear system of equations

.. math::
Ax = b\text{,}

using a preconditioned conjugate gradient method (see Barrett et al. (1994)), or a preconditioned Lanczos method based on the algorithm SYMMLQ (see Paige and Saunders (1975)).
The conjugate gradient method is more efficient if :math:A is positive definite, but may fail to converge for indefinite matrices.
In this case the Lanczos method should be used instead.
For further details see Barrett et al. (1994).

complex_herm_solve_jacssor allows the following choices for the preconditioner:

-   no preconditioning;

-   Jacobi preconditioning (see Young (1971));

-   symmetric successive-over-relaxation (SSOR) preconditioning (see Young (1971)).

For incomplete Cholesky (IC) preconditioning see :meth:complex_herm_solve_ilu.

The matrix :math:A is represented in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__) in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol}.
The array :math:\mathrm{a} holds the nonzero entries in the lower triangular part of the matrix, while :math:\mathrm{irow} and :math:\mathrm{icol} hold the corresponding row and column indices.

.. _f11js-py2-py-references:

**References**
Barrett, R, Berry, M, Chan, T F, Demmel, J, Donato, J, Dongarra, J, Eijkhout, V, Pozo, R, Romine, C and Van der Vorst, H, 1994, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia

Paige, C C and Saunders, M A, 1975, Solution of sparse indefinite systems of linear equations, SIAM J. Numer. Anal. (12), 617--629

Young, D, 1971, Iterative Solution of Large Linear Systems, Academic Press, New York
"""
raise NotImplementedError

[docs]def direct_real_gen_setup(spec, n, icolzp, irowix, iprm):
r"""
direct_real_gen_setup computes a column permutation suitable for :math:LU factorization (by :meth:direct_real_gen_lu) of a real sparse matrix in compressed column (Harwell--Boeing) format and applies it to the matrix.
This function must be called prior to :meth:direct_real_gen_lu.

.. _f11md-py2-py-doc:

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

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

.. _f11md-py2-py-parameters:

**Parameters**
**spec** : str, length 1
Indicates the permutation to be applied.

:math:\mathrm{spec} = \texttt{'N'}

The identity permutation is used (i.e., the columns are not permuted).

:math:\mathrm{spec} = \texttt{'U'}

The permutation in the :math:\mathrm{iprm} array is used, as supplied by you.

:math:\mathrm{spec} = \texttt{'M'}

The permutation computed by the COLAMD algorithm is used

**n** : int
:math:n, the order of the matrix :math:A.

**icolzp** : int, array-like, shape :math:\left(\max\left(1,\left(\mathrm{n}+1\right)\right)\right)
The new column index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**irowix** : int, array-like, shape :math:\left(\max\left(1,\left(\mathrm{icolzp}[{ \max\left(1,\left(\mathrm{n}+1\right)\right) - 1 }]-1\right)\right)\right)
:math:\mathrm{irowix}[i-1] contains the row index in :math:A for element :math:A\left(i\right). See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**iprm** : int, array-like, shape :math:\left(\max\left(1,\left(7\times \mathrm{n}\right)\right)\right)
The first :math:\mathrm{n} entries contain the column permutation if supplied by the user. This will be used if :math:\mathrm{spec} = \texttt{'U'}, and ignored otherwise. If used, it must consist of a permutation of all the integers in the range :math:\left[0, \left(\mathrm{n}-1\right)\right], the leftmost column of the matrix :math:A denoted by :math:0 and the rightmost by :math:\mathrm{n}-1. Labelling columns in this way, :math:\mathrm{iprm}[i] = j means that column :math:i-1 of :math:A is in position :math:j in :math:AP_c, where :math:P_rAP_c = LU expresses the factorization to be performed.

**Returns**
**iprm** : int, ndarray, shape :math:\left(\max\left(1,\left(7\times \mathrm{n}\right)\right)\right)
The column permutation given or computed is returned in the second :math:\mathrm{n} entries. The rest of the array contains data structures that will be used by other functions in the suite. The function computes the column elimination tree for :math:A and a post-order permutation on the tree. It then compounds the :math:\mathrm{iprm} permutation given or computed by the COLAMD algorthm with the post-order permutation and this permutation is returned in the first :math:\mathrm{n} entries. This whole array is needed by the :math:LU factorization function :meth:direct_real_gen_lu and associated functions :meth:direct_real_gen_solve, :meth:direct_real_gen_refine and :meth:direct_real_gen_diag and should be passed to them unchanged.

.. _f11md-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{spec} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{spec} = \texttt{'N'}, :math:\texttt{'U'} or :math:\texttt{'M'}.

(errno :math:2)
Incorrect column permutations in array :math:\mathrm{iprm}.

(errno :math:3)
COLAMD algorithm failed.

(errno :math:4)
Incorrect specification of argument :math:\mathrm{icolzp}.

(errno :math:5)
Incorrect specification of argument :math:\mathrm{irowix}.

.. _f11md-py2-py-notes:

**Notes**
Given a sparse matrix in compressed column (Harwell--Boeing) format :math:A and a choice of column permutation schemes, the function computes those data structures that will be needed by the :math:LU factorization function :meth:direct_real_gen_lu and associated functions :meth:direct_real_gen_diag, :meth:direct_real_gen_solve and :meth:direct_real_gen_refine.
The column permutation choices are:

original order (that is, no permutation);

user-supplied permutation;

a permutation, computed by the function, designed to minimize fill-in during the :math:LU factorization.

The algorithm for this computed permutation is based on the approximate minimum degree column ordering algorithm COLAMD.
The computed permutation is not sensitive to the magnitude of the nonzero values of :math:A.

.. _f11md-py2-py-references:

**References**
Amestoy, P R, Davis, T A and Duff, I S, 1996, An approximate minimum degree ordering algorithm, SIAM J. Matrix Anal. Appl. (17), 886--905

Gilbert, J R and Larimore, S I, 2004, A column approximate minimum degree ordering algorithm, ACM Trans. Math. Software (30,3), 353--376

Gilbert, J R, Larimore, S I and Ng, E G, 2004, Algorithm 836: COLAMD, an approximate minimum degree ordering algorithm, ACM Trans. Math. Software (30, 3), 377--380
"""
raise NotImplementedError

[docs]def direct_real_gen_lu(irowix, a, iprm, thresh, nzlmx, nzlumx, nzumx):
r"""
direct_real_gen_lu computes the :math:LU factorization of a real sparse matrix in compressed column (Harwell--Boeing), column-permuted format.

.. _f11me-py2-py-doc:

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

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

.. _f11me-py2-py-parameters:

**Parameters**
**irowix** : int, array-like, shape :math:\left(:\right)
The row index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**a** : float, array-like, shape :math:\left(:\right)
The array of nonzero values in the sparse matrix :math:A.

**iprm** : int, array-like, shape :math:\left(7\times n\right)
Contains the column permutation which defines the permutation :math:P_c and associated data structures as computed by function :meth:direct_real_gen_setup.

**thresh** : float
The diagonal pivoting threshold, :math:t. At step :math:j of the Gaussian elimination, if :math:\left\lvert A_{{jj}}\right\rvert \geq t\left(\textit{max}_{{i\geq j}}\left\lvert A_{{ij}}\right\rvert \right), use :math:A_{{jj}} as a pivot, otherwise use :math:\textit{max}_{{i\geq j}}\left\lvert A_{{ij}}\right\rvert. A value of :math:t = 1 corresponds to partial pivoting, a value of :math:t = 0 corresponds to always choosing the pivot on the diagonal (unless it is zero).

Suggested value: :math:\mathrm{thresh} = 1.0. Smaller values may result in a faster factorization, but the benefits are likely to be small in most cases. It might be possible to use :math:\mathrm{thresh} = 0.0 if you are confident about the stability of the factorization, for example, if :math:A is diagonally dominant.

**nzlmx** : int
Indicates the available size of array :math:\mathrm{il}. The dimension of :math:\mathrm{il} should be at least :math:7\times n+\mathrm{nzlmx}+4. A good range for :math:\mathrm{nzlmx} that works for many problems is :math:\textit{nnz} to :math:8\times \textit{nnz}, where :math:\textit{nnz} is the number of nonzeros in the sparse matrix :math:A. If, on exit, :math:\mathrm{errno} = 2, the given :math:\mathrm{nzlmx} was too small and you should attempt to provide more storage and call the function again.

**nzlumx** : int
Indicates the available size of array :math:\mathrm{lval}. The dimension of :math:\mathrm{lval} should be at least :math:\mathrm{nzlumx}.

**nzumx** : int
Indicates the available sizes of arrays :math:\mathrm{iu} and :math:\mathrm{uval}. The dimension of :math:\mathrm{iu} should be at least :math:2\times n+\mathrm{nzumx}+1 and the dimension of :math:\mathrm{uval} should be at least :math:\mathrm{nzumx}. A good range for :math:\mathrm{nzumx} that works for many problems is :math:\textit{nnz} to :math:8\times \textit{nnz}, where :math:\textit{nnz} is the number of nonzeros in the sparse matrix :math:A. If, on exit, :math:\mathrm{errno} = 3, the given :math:\mathrm{nzumx} was too small and you should attempt to provide more storage and call the function again.

**Returns**
**iprm** : int, ndarray, shape :math:\left(7\times n\right)
Part of the array is modified to record the row permutation :math:P_r determined by pivoting.

**nzlumx** : int
If :math:\mathrm{errno} = 4, the given :math:\mathrm{nzlumx} was too small and is reset to a value that will be sufficient. You should then provide the indicated storage and call the function again.

**il** : int, ndarray, shape :math:\left(7\times n+\mathrm{nzlmx}+4\right)
Encapsulates the sparsity pattern of matrix :math:L.

**lval** : float, ndarray, shape :math:\left(\mathrm{nzlumx}\right)
Records the nonzero values of matrix :math:L and some of the nonzero values of matrix :math:U.

**iu** : int, ndarray, shape :math:\left(2\times n+\mathrm{nzumx}+1\right)
Encapsulates the sparsity pattern of matrix :math:U.

**uval** : float, ndarray, shape :math:\left(\mathrm{nzumx}\right)
Records some of the nonzero values of matrix :math:U.

**nnzl** : int
The number of nonzero values in the matrix :math:L.

**nnzu** : int
The number of nonzero values in the matrix :math:U.

**flop** : float
The number of floating-point operations performed.

.. _f11me-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nzumx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nzumx} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{nzlumx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nzlumx} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{nzlmx} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nzlmx} \geq 1.

(errno :math:1)
On entry, :math:\mathrm{thresh} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:0.0\leq \mathrm{thresh}\leq 1.0.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 0.

(errno :math:2)
Insufficient :math:\mathrm{nzlmx}.

(errno :math:3)
Insufficient :math:\mathrm{nzumx}.

(errno :math:4)
Insufficient :math:\mathrm{nzlumx}.

(errno :math:5)
The matrix is singular -- no factorization possible.

.. _f11me-py2-py-notes:

**Notes**
Given a real sparse matrix :math:A, direct_real_gen_lu computes an :math:LU factorization of :math:A with partial pivoting, :math:P_rAP_c = LU, where :math:P_r is a row permutation matrix (computed by direct_real_gen_lu), :math:P_c is a (supplied) column permutation matrix, :math:L is unit lower triangular and :math:U is upper triangular.
The column permutation matrix, :math:P_c, must be computed by a prior call to :meth:direct_real_gen_setup.
The matrix :math:A must be presented in the column permuted, compressed column (Harwell--Boeing) format.

The :math:LU factorization is output in the form of four one-dimensional arrays: integer arrays :math:\mathrm{il} and :math:\mathrm{iu} and real-valued arrays :math:\mathrm{lval} and :math:\mathrm{uval}.
These describe the sparsity pattern and numerical values in the :math:L and :math:U matrices.
The minimum required dimensions of these arrays cannot be given as a simple function of the size arguments (order and number of nonzero values) of the matrix :math:A.
This is due to unpredictable fill-in created by partial pivoting. direct_real_gen_lu will, on return, indicate which dimensions of these arrays were not adequate for the computation or (in the case of one of them) give a firm bound.
You should then allocate more storage and try again.

.. _f11me-py2-py-references:

**References**
Demmel, J W, Eisenstat, S C, Gilbert, J R, Li, X S and Li, J W H, 1999, A supernodal approach to sparse partial pivoting, SIAM J. Matrix Anal. Appl. (20), 720--755

Demmel, J W, Gilbert, J R and Li, X S, 1999, An asynchronous parallel supernodal algorithm for sparse gaussian elimination, SIAM J. Matrix Anal. Appl. (20), 915--952
"""
raise NotImplementedError

[docs]def direct_real_gen_solve(trans, iprm, il, lval, iu, uval, b):
r"""
direct_real_gen_solve solves a real sparse system of linear equations with multiple right-hand sides given an :math:LU factorization of the sparse matrix computed by :meth:direct_real_gen_lu.

.. _f11mf-py2-py-doc:

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

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

.. _f11mf-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether :math:AX = B or :math:A^\mathrm{T}X = B is solved.

:math:\mathrm{trans} = \texttt{'N'}

:math:AX = B is solved.

:math:\mathrm{trans} = \texttt{'T'}

:math:A^\mathrm{T}X = B is solved.

**iprm** : int, array-like, shape :math:\left(7\times n\right)
The column permutation which defines :math:P_c, the row permutation which defines :math:P_r, plus associated data structures as computed by :meth:direct_real_gen_lu.

**il** : int, array-like, shape :math:\left(:\right)
Records the sparsity pattern of matrix :math:L as computed by :meth:direct_real_gen_lu.

**lval** : float, array-like, shape :math:\left(:\right)
Records the nonzero values of matrix :math:L and some nonzero values of matrix :math:U as computed by :meth:direct_real_gen_lu.

**iu** : int, array-like, shape :math:\left(:\right)
Records the sparsity pattern of matrix :math:U as computed by :meth:direct_real_gen_lu.

**uval** : float, array-like, shape :math:\left(:\right)
Records some nonzero values of matrix :math:U as computed by :meth:direct_real_gen_lu.

**b** : float, array-like, shape :math:\left(n, \textit{nrhs}\right)
The :math:n\times \textit{nrhs} right-hand side matrix :math:B.

**Returns**
**b** : float, ndarray, shape :math:\left(n, \textit{nrhs}\right)
The :math:n\times \textit{nrhs} solution matrix :math:X.

.. _f11mf-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\textit{nrhs} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nrhs} \geq 0.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 0.

(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:2)
Incorrect row permutations in array :math:\mathrm{iprm}.

(errno :math:3)
Incorrect column permutations in array :math:\mathrm{iprm}.

.. _f11mf-py2-py-notes:

**Notes**
direct_real_gen_solve solves a real system of linear equations with multiple right-hand sides :math:AX = B or :math:A^\mathrm{T}X = B, according to the value of the argument :math:\mathrm{trans}, where the matrix factorization :math:P_rAP_c = LU corresponds to an :math:LU decomposition of a sparse matrix stored in compressed column (Harwell--Boeing) format, as computed by :meth:direct_real_gen_lu.

In the above decomposition :math:L is a lower triangular sparse matrix with unit diagonal elements and :math:U is an upper triangular sparse matrix; :math:P_r and :math:P_c are permutation matrices.
"""
raise NotImplementedError

[docs]def direct_real_gen_cond(norm, n, il, lval, iu, uval, anorm):
r"""
direct_real_gen_cond computes an estimate of the reciprocal of the condition number of a sparse matrix given an :math:LU factorization of the matrix computed by :meth:direct_real_gen_lu.

.. _f11mg-py2-py-doc:

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

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

.. _f11mg-py2-py-parameters:

**Parameters**
**norm** : str, length 1
Indicates whether :math:\kappa_1\left(A\right) or :math:\kappa_{\infty }\left(A\right) is to be estimated.

:math:\mathrm{norm} = \texttt{'1'} or :math:\texttt{'O'}

:math:\kappa_1\left(A\right) is estimated.

:math:\mathrm{norm} = \texttt{'I'}

:math:\kappa_{\infty }\left(A\right) is estimated.

**n** : int
:math:n, the order of the matrix :math:A.

**il** : int, array-like, shape :math:\left(:\right)
Records the sparsity pattern of matrix :math:L as computed by :meth:direct_real_gen_lu.

**lval** : float, array-like, shape :math:\left(:\right)
Records the nonzero values of matrix :math:L and some nonzero values of matrix :math:U as computed by :meth:direct_real_gen_lu.

**iu** : int, array-like, shape :math:\left(:\right)
Records the sparsity pattern of matrix :math:U as computed by :meth:direct_real_gen_lu.

**uval** : float, array-like, shape :math:\left(:\right)
Records some nonzero values of matrix :math:U as computed by :meth:direct_real_gen_lu.

**anorm** : float
If :math:\mathrm{norm} = \texttt{'1'} or :math:\texttt{'O'}, the :math:1-norm of the matrix :math:A.

If :math:\mathrm{norm} = \texttt{'I'}, the :math:\infty-norm of the matrix :math:A.

:math:\mathrm{anorm} may be computed by calling :meth:direct_real_gen_norm with the same value for the argument :math:\mathrm{norm}.

**Returns**
**rcond** : float
An estimate of the reciprocal of the condition number of :math:A. :math:\mathrm{rcond} is set to zero if exact singularity is detected or the estimate underflows. If :math:\mathrm{rcond} is less than machine precision, :math:A is singular to working precision.

.. _f11mg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{anorm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{anorm}\geq 0.0.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{norm} = \texttt{'1'}, :math:\texttt{'O'} or :math:\texttt{'I'}.

.. _f11mg-py2-py-notes:

**Notes**
direct_real_gen_cond estimates the condition number of a real sparse matrix :math:A, in either the :math:1-norm or the :math:\infty-norm:

.. math::
\kappa_1\left(A\right) = \left\lVert A\right\rVert_1\left\lVert A^{-1}\right\rVert_1\quad \text{ or }\quad \kappa_{\infty }\left(A\right) = \left\lVert A\right\rVert_\infty\left\lVert A^{-1}\right\rVert_\infty\text{.}

Note that :math:\kappa_{\infty }\left(A\right) = \kappa_1\left(A^\mathrm{T}\right).

Because the condition number is infinite if :math:A is singular, the function actually returns an estimate of the **reciprocal** of the condition number.

The function should be preceded by a call to :meth:direct_real_gen_norm to compute :math:\left\lVert A\right\rVert_1 or :math:\left\lVert A\right\rVert_\infty, and a call to :meth:direct_real_gen_lu to compute the :math:LU factorization of :math:A.
The function then estimates :math:\left\lVert A^{-1}\right\rVert_1 or :math:\left\lVert A^{-1}\right\rVert_\infty and computes the reciprocal of the condition number.
"""
raise NotImplementedError

[docs]def direct_real_gen_refine(trans, icolzp, irowix, a, iprm, il, lval, iu, uval, nrhs, b, x):
r"""
direct_real_gen_refine returns error bounds for the solution of a real sparse system of linear equations with multiple right-hand sides, :math:AX = B or :math:A^\mathrm{T}X = B.
It improves the solution by iterative refinement in standard precision, in order to reduce the backward error as much as possible.

.. _f11mh-py2-py-doc:

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

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

.. _f11mh-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether :math:AX = B or :math:A^\mathrm{T}X = B is solved.

:math:\mathrm{trans} = \texttt{'N'}

:math:AX = B is solved.

:math:\mathrm{trans} = \texttt{'T'}

:math:A^\mathrm{T}X = B is solved.

**icolzp** : int, array-like, shape :math:\left(n+1\right)
The new column index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**irowix** : int, array-like, shape :math:\left(\textit{asize}\right)
The row index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**a** : float, array-like, shape :math:\left(\textit{asize}\right)
The array of nonzero values in the sparse matrix :math:A.

**iprm** : int, array-like, shape :math:\left(7\times n\right)
The column permutation which defines :math:P_c, the row permutation which defines :math:P_r, plus associated data structures as computed by :meth:direct_real_gen_lu.

**il** : int, array-like, shape :math:\left(:\right)
Records the sparsity pattern of matrix :math:L as computed by :meth:direct_real_gen_lu.

**lval** : float, array-like, shape :math:\left(:\right)
Records the nonzero values of matrix :math:L and some nonzero values of matrix :math:U as computed by :meth:direct_real_gen_lu.

**iu** : int, array-like, shape :math:\left(:\right)
Records the sparsity pattern of matrix :math:U as computed by :meth:direct_real_gen_lu.

**uval** : float, array-like, shape :math:\left(:\right)
Records some nonzero values of matrix :math:U as computed by :meth:direct_real_gen_lu.

**nrhs** : int
:math:\textit{nrhs}, the number of right-hand sides in :math:B.

**b** : float, array-like, shape :math:\left(n, \mathrm{nrhs}\right)
The :math:n\times \textit{nrhs} right-hand side matrix :math:B.

**x** : float, array-like, shape :math:\left(n, \mathrm{nrhs}\right)
The :math:n\times \textit{nrhs} solution matrix :math:X, as returned by :meth:direct_real_gen_solve.

**Returns**
**x** : float, ndarray, shape :math:\left(n, \mathrm{nrhs}\right)
The :math:n\times \textit{nrhs} improved solution matrix :math:X.

**ferr** : float, ndarray, shape :math:\left(\mathrm{nrhs}\right)
:math:\mathrm{ferr}[\textit{j}-1] contains an estimated error bound for the :math:\textit{j}\ th solution vector, that is, the :math:\textit{j}\ th column of :math:X, for :math:\textit{j} = 1,2,\ldots,\textit{nrhs}.

**berr** : float, ndarray, shape :math:\left(\mathrm{nrhs}\right)
:math:\mathrm{berr}[\textit{j}-1] contains the component-wise backward error bound :math:\beta for the :math:\textit{j}\ th solution vector, that is, the :math:\textit{j}\ th column of :math:X, for :math:\textit{j} = 1,2,\ldots,\textit{nrhs}.

.. _f11mh-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{nrhs} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{nrhs} \geq 0.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 0.

(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:2)
Incorrect row permutations in array :math:\mathrm{iprm}.

(errno :math:3)
Incorrect column permutations in array :math:\mathrm{iprm}.

.. _f11mh-py2-py-notes:

**Notes**
direct_real_gen_refine returns the backward errors and estimated bounds on the forward errors for the solution of a real system of linear equations with multiple right-hand sides :math:AX = B or :math:A^\mathrm{T}X = B.
The function handles each right-hand side vector (stored as a column of the matrix :math:B) independently, so we describe the function of direct_real_gen_refine in terms of a single right-hand side :math:b and solution :math:x.

Given a computed solution :math:x, the function computes the component-wise backward error :math:\beta.
This is the size of the smallest relative perturbation in each element of :math:A and :math:b such that if :math:x is the exact solution of a perturbed system:

.. math::
\begin{array}{c} \left(A+\delta A\right) x = b + \delta b\\ \text{then }\quad \left\lvert \delta a_{{ij}}\right\rvert \leq \beta \left\lvert a_{{ij}}\right\rvert \quad \text{ and }\quad \left\lvert \delta b_i\right\rvert \leq \beta \left\lvert b_i\right\rvert \text{.} \end{array}

Then the function estimates a bound for the component-wise forward error in the computed solution, defined by:

.. math::
\mathrm{max}_i^{{}}\left\lvert x_i-\hat{x}_i\right\rvert /\mathrm{max}_i^{{}}\left\lvert x_i\right\rvert

where :math:\hat{x} is the true solution.

The function uses the :math:LU factorization :math:P_rAP_c = LU computed by :meth:direct_real_gen_lu and the solution computed by :meth:direct_real_gen_solve.

.. _f11mh-py2-py-references:

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

[docs]def direct_real_gen_matmul(trans, alpha, icolzp, irowix, a, b, beta, c=None):
r"""
direct_real_gen_matmul computes a matrix-matrix or transposed matrix-matrix product involving a real, square, sparse nonsymmetric matrix stored in compressed column (Harwell--Boeing) format.

.. _f11mk-py2-py-doc:

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

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

.. _f11mk-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether or not the matrix :math:A is transposed.

:math:\mathrm{trans} = \texttt{'N'}

:math:\alpha AB+\beta C is computed.

:math:\mathrm{trans} = \texttt{'T'}

:math:\alpha A^\mathrm{T}B+\beta C is computed.

**alpha** : float
:math:\alpha, the scalar factor in the matrix multiplication.

**icolzp** : int, array-like, shape :math:\left(n+1\right)
The new column index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**irowix** : int, array-like, shape :math:\left(\textit{asize}\right)
The row index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**a** : float, array-like, shape :math:\left(\textit{asize}\right)
The array of nonzero values in the sparse matrix :math:A.

**b** : float, array-like, shape :math:\left(n, m\right)
The :math:n\times m matrix :math:B.

**beta** : float
The scalar factor :math:\beta.

**c** : None or float, array-like, shape :math:\left(n, m\right), optional
The :math:n\times m matrix :math:C.

**Returns**
**c** : float, ndarray, shape :math:\left(n, m\right)
:math:C is overwritten by :math:\alpha AB+\beta C or :math:\alpha A^\mathrm{T}B+\beta C depending on the value of :math:\mathrm{trans}.

.. _f11mk-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:m = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:m \geq 0.

(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 0.

(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

.. _f11mk-py2-py-notes:

**Notes**
direct_real_gen_matmul computes either the matrix-matrix product :math:C←\alpha AB+\beta C, or the transposed matrix-matrix product :math:C←\alpha A^\mathrm{T}B+\beta C, according to the value of the argument :math:\mathrm{trans}, where :math:A is a real :math:n\times n sparse nonsymmetric matrix, of arbitrary sparsity pattern with :math:\textit{nnz} nonzero elements, :math:B and :math:C are :math:n\times m real dense matrices.
The matrix :math:A is stored in compressed column (Harwell--Boeing) storage format.
The array :math:\mathrm{a} stores all nonzero elements of :math:A, while arrays :math:\mathrm{icolzp} and :math:\mathrm{irowix} store the compressed column indices and row indices of :math:A respectively.
"""
raise NotImplementedError

[docs]def direct_real_gen_norm(norm, n, icolzp, irowix, a):
r"""
direct_real_gen_norm computes the :math:1-norm, the :math:\infty-norm or the maximum absolute value of the elements of a real, square, sparse matrix which is held in compressed column (Harwell--Boeing) format.

.. _f11ml-py2-py-doc:

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

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

.. _f11ml-py2-py-parameters:

**Parameters**
**norm** : str, length 1
Specifies the value to be returned in :math:\mathrm{anorm}.

:math:\mathrm{norm} = \texttt{'1'} or :math:\texttt{'O'}

The :math:1-norm :math:\left\lVert A\right\rVert_1 of the matrix is computed, that is :math:\textit{max}_{{1\leq j\leq n}}\sum_{{i = 1}}^n\left\lvert A_{{ij}}\right\rvert.

:math:\mathrm{norm} = \texttt{'I'}

The :math:\infty-norm :math:\left\lVert A\right\rVert_\infty of the matrix is computed, that is :math:\textit{max}_{{1\leq i\leq n}}\sum_{{j = 1}}^n\left\lvert A_{{ij}}\right\rvert.

:math:\mathrm{norm} = \texttt{'M'}

The value :math:\mathrm{max}_{{1\leq i,j\leq n}}\left(\left\lvert A_{{ij}}\right\rvert \right) (not a norm).

**n** : int
:math:n, the order of the matrix :math:A.

**icolzp** : int, array-like, shape :math:\left(\mathrm{n}+1\right)
The new column index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**irowix** : int, array-like, shape :math:\left(\textit{asize}\right)
The row index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**a** : float, array-like, shape :math:\left(\textit{asize}\right)
The array of nonzero values in the sparse matrix :math:A.

**Returns**
**anorm** : float
The computed quantity relating the matrix.

.. _f11ml-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n} \geq 0.

(errno :math:1)
On entry, :math:\mathrm{norm} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{norm} = \texttt{'1'}, :math:\texttt{'O'}, :math:\texttt{'I'} or :math:\texttt{'M'}.

.. _f11ml-py2-py-notes:

**Notes**
direct_real_gen_norm computes various quantities relating to norms of a real, sparse :math:n\times n matrix :math:A presented in compressed column (Harwell--Boeing) format.
"""
raise NotImplementedError

[docs]def direct_real_gen_diag(icolzp, a, iprm, il, lval, iu, uval):
r"""
direct_real_gen_diag computes the reciprocal pivot growth factor of an :math:LU factorization of a real sparse matrix in compressed column (Harwell--Boeing) format.

.. _f11mm-py2-py-doc:

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

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

.. _f11mm-py2-py-parameters:

**Parameters**
**icolzp** : int, array-like, shape :math:\left(n+1\right)
The new column index array of sparse matrix :math:A. See the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__.

**a** : float, array-like, shape :math:\left(\textit{asize}\right)
The array of nonzero values in the sparse matrix :math:A.

**iprm** : int, array-like, shape :math:\left(7\times n\right)
The column permutation which defines :math:P_c, the row permutation which defines :math:P_r, plus associated data structures as computed by :meth:direct_real_gen_lu.

**il** : int, array-like, shape :math:\left(:\right)
Records the sparsity pattern of matrix :math:L as computed by :meth:direct_real_gen_lu.

**lval** : float, array-like, shape :math:\left(:\right)
Records the nonzero values of matrix :math:L and some nonzero values of matrix :math:U as computed by :meth:direct_real_gen_lu.

**iu** : int, array-like, shape :math:\left(:\right)
Records the sparsity pattern of matrix :math:U as computed by :meth:direct_real_gen_lu.

**uval** : float, array-like, shape :math:\left(:\right)
Records some nonzero values of matrix :math:U as computed by :meth:direct_real_gen_lu.

**Returns**
**rpg** : float
The reciprocal pivot growth factor :math:\textit{max}_j\left(\left\lVert A_j\right\rVert_\infty/\left\lVert U_j\right\rVert_\infty\right). If the reciprocal pivot growth factor is much less than :math:1, the stability of the :math:LU factorization may be poor.

.. _f11mm-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n \geq 0.

(errno :math:2)
Incorrect column permutations in array :math:\mathrm{iprm}.

.. _f11mm-py2-py-notes:

**Notes**
direct_real_gen_diag computes the reciprocal pivot growth factor :math:\textit{max}_j\left(\left\lVert A_j\right\rVert_\infty/\left\lVert U_j\right\rVert_\infty\right) from the columns :math:A_j and :math:U_j of an :math:LU factorization of the matrix :math:A, :math:P_rAP_c = LU where :math:P_r is a row permutation matrix, :math:P_c is a column permutation matrix, :math:L is unit lower triangular and :math:U is upper triangular as computed by :meth:direct_real_gen_lu.
"""
raise NotImplementedError

[docs]def real_gen_matvec(trans, a, irow, icol, x, check='N'):
r"""
real_gen_matvec computes a matrix-vector or transposed matrix-vector product involving a real sparse nonsymmetric matrix stored in coordinate storage format.

.. _f11xa-py2-py-doc:

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

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

.. _f11xa-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether or not the matrix :math:A is transposed.

:math:\mathrm{trans} = \texttt{'N'}

:math:y = Ax is computed.

:math:\mathrm{trans} = \texttt{'T'}

:math:y = A^\mathrm{T}x is computed.

**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements in the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**x** : float, array-like, shape :math:\left(n\right)
The vector :math:x.

**check** : str, length 1, optional
Specifies whether or not the CS representation of the matrix :math:A, values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow} and :math:\mathrm{icol} should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow} and :math:\mathrm{icol}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11xaf.html#fcomments2>__.

**Returns**
**y** : float, ndarray, shape :math:\left(n\right)
The vector :math:y.

.. _f11xa-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n^2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

.. _f11xa-py2-py-notes:

**Notes**
real_gen_matvec computes either the matrix-vector product :math:y = Ax, or the transposed matrix-vector product :math:y = A^\mathrm{T}x, according to the value of the argument :math:\mathrm{trans}, where :math:A is an :math:n\times n sparse nonsymmetric matrix, of arbitrary sparsity pattern.
The matrix :math:A is stored in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__).
The array :math:\mathrm{a} stores all nonzero elements of :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.

It is envisaged that a common use of real_gen_matvec will be to compute the matrix-vector product required in the application of :meth:real_gen_basic_solver to sparse linear systems.

--------
:meth:naginterfaces.library.examples.sparse.real_gen_basic_solver_ex.main
"""
raise NotImplementedError

[docs]def real_symm_matvec(a, irow, icol, x, check='N'):
r"""
real_symm_matvec computes a matrix-vector product involving a real sparse symmetric matrix stored in symmetric coordinate storage format.

.. _f11xe-py2-py-doc:

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

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

.. _f11xe-py2-py-parameters:

**Parameters**
**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements in the lower triangular part of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:real_symm_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**x** : float, array-like, shape :math:\left(n\right)
The vector :math:x.

**check** : str, length 1, optional
Specifies whether or not the SCS representation of the matrix :math:A, values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow} and :math:\mathrm{icol} should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried out on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow} and :math:\mathrm{icol}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11xef.html#fcomments2>__.

**Returns**
**y** : float, ndarray, shape :math:\left(n\right)
The vector :math:y.

.. _f11xe-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n\times \left(n+1\right)/2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

.. _f11xe-py2-py-notes:

**Notes**
real_symm_matvec computes the matrix-vector product

.. math::
y = Ax

where :math:A is an :math:n\times n symmetric sparse matrix, of arbitrary sparsity pattern, stored in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__).
The array :math:\mathrm{a} stores all nonzero elements in the lower triangular part of :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.

It is envisaged that a common use of real_symm_matvec will be to compute the matrix-vector product required in the application of :meth:real_symm_basic_solver to sparse symmetric linear systems.
An illustration of this usage appears in :meth:real_symm_precon_ssor_solve.
"""
raise NotImplementedError

[docs]def complex_gen_matvec(trans, a, irow, icol, x, check='N'):
r"""
complex_gen_matvec computes a matrix-vector or conjugate transposed matrix-vector product involving a complex sparse non-Hermitian matrix stored in coordinate storage format.

.. _f11xn-py2-py-doc:

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

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

.. _f11xn-py2-py-parameters:

**Parameters**
**trans** : str, length 1
Specifies whether or not the matrix :math:A is conjugate transposed.

:math:\mathrm{trans} = \texttt{'N'}

:math:y = Ax is computed.

:math:\mathrm{trans} = \texttt{'T'}

:math:y = A^\mathrm{H}x is computed.

**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements in the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_gen_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**x** : complex, array-like, shape :math:\left(n\right)
The vector :math:x.

**check** : str, length 1, optional
Specifies whether or not the CS representation of the matrix :math:A, values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow} and :math:\mathrm{icol} should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow} and :math:\mathrm{icol}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

See also Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11xnf.html#fcomments2>__.

**Returns**
**y** : complex, ndarray, shape :math:\left(n\right)
The vector :math:y.

.. _f11xn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{trans} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{trans} = \texttt{'N'} or :math:\texttt{'T'}.

(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n^2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq n.

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

.. _f11xn-py2-py-notes:

**Notes**
complex_gen_matvec computes either the matrix-vector product :math:y = Ax, or the conjugate transposed matrix-vector product :math:y = A^\mathrm{H}x, according to the value of the argument :math:\mathrm{trans}, where :math:A is a complex :math:n\times n sparse non-Hermitian matrix, of arbitrary sparsity pattern.
The matrix :math:A is stored in coordinate storage (CS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__).
The array :math:\mathrm{a} stores all the nonzero elements of :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.

It is envisaged that a common use of complex_gen_matvec will be to compute the matrix-vector product required in the application of :meth:complex_gen_basic_solver to sparse complex linear systems.

--------
:meth:naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main
"""
raise NotImplementedError

[docs]def complex_herm_matvec(a, irow, icol, x, check='N'):
r"""
complex_herm_matvec computes a matrix-vector product involving a complex sparse Hermitian matrix stored in symmetric coordinate storage format.

.. _f11xs-py2-py-doc:

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

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

.. _f11xs-py2-py-parameters:

**Parameters**
**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements in the lower triangular part of the matrix :math:A, ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function :meth:complex_herm_sort may be used to order the elements in this way.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices of the nonzero elements supplied in array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices of the nonzero elements supplied in array :math:\mathrm{a}.

**x** : complex, array-like, shape :math:\left(n\right)
The vector :math:x.

**check** : str, length 1, optional
Specifies whether or not the SCS representation of the matrix :math:A, values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow} and :math:\mathrm{icol} should be checked.

:math:\mathrm{check} = \texttt{'C'}

Checks are carried out on the values of :math:\textit{n}, :math:\textit{nnz}, :math:\mathrm{irow} and :math:\mathrm{icol}.

:math:\mathrm{check} = \texttt{'N'}

None of these checks are carried out.

**Returns**
**y** : complex, ndarray, shape :math:\left(n\right)
The vector :math:y.

.. _f11xs-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{check} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{check} = \texttt{'C'} or :math:\texttt{'N'}.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\leq n\times \left(n+1\right)/2.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:2)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:3)
On entry, the location (:math:\mathrm{irow}[\textit{I}-1],\mathrm{icol}[\textit{I}-1]) is a duplicate: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\mathrm{a}[i-1] is out of order: :math:i = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:3)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:3)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq n.

.. _f11xs-py2-py-notes:

**Notes**
complex_herm_matvec computes the matrix-vector product

.. math::
y = Ax

where :math:A is an :math:n\times n complex Hermitian sparse matrix, of arbitrary sparsity pattern, stored in symmetric coordinate storage (SCS) format (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__).
The array :math:\mathrm{a} stores all the nonzero elements in the lower triangular part of :math:A, while arrays :math:\mathrm{irow} and :math:\mathrm{icol} store the corresponding row and column indices respectively.
"""
raise NotImplementedError

r"""
sym_rcm reduces the bandwidth of a sparse symmetric matrix stored in compressed column storage format using the Reverse Cuthill--McKee algorithm.

.. _f11ye-py2-py-doc:

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

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

.. _f11ye-py2-py-parameters:

**Parameters**
**icolzp** : int, array-like, shape :math:\left(n+1\right)
:math:\mathrm{icolzp} records the index into :math:\mathrm{irowix} which starts each new column.

**irowix** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices corresponding to the nonzero elements in the matrix :math:A.

**lopts** : bool, array-like, shape :math:\left(5\right)
The options to be used by sym_rcm.

:math:\mathrm{lopts}[0] = \mathbf{True}

Row/column :math:i of the matrix :math:A will only be referenced if :math:\mathrm{mask}[i-1]\neq 0, otherwise :math:\mathrm{mask} will be ignored.

:math:\mathrm{lopts}[1] = \mathbf{True}

The final permutation will not be reversed, that is, the Cuthill--McKee ordering will be returned. The bandwidth of the non-reversed matrix will be the same but the profile will be the same or larger (see Wai-Hung and Sherman (1976)).

:math:\mathrm{lopts}[2] = \mathbf{True}

The matrix :math:A will be checked for symmetrical sparsity pattern, otherwise not.

:math:\mathrm{lopts}[3] = \mathbf{True}

The bandwidth and profile of the unpermuted matrix will be calculated, otherwise not.

:math:\mathrm{lopts}[4] = \mathbf{True}

The bandwidth and profile of the permuted matrix will be calculated, otherwise not.

**mask** : None or int, array-like, shape :math:\left(:\right), optional
Note: the required length for this argument is determined as follows: if :math:\mathrm{lopts}[0]= \mathbf{True}: :math:n; otherwise: :math:0.

:math:\mathrm{mask} is only referenced if :math:\mathrm{lopts}[0] is :math:\mathbf{True}. A value of :math:\mathrm{mask}[i-1] = 0 indicates that the node corresponding to row or column :math:i is not to be referenced. A value of :math:\mathrm{mask}[i-1]\neq 0 indicates that the node corresponding to row or column :math:i is to be referenced. In particular, rows and columns not referenced will not be permuted.

**Returns**
**perm** : int, ndarray, shape :math:\left(:\right)
This will contain the permutation vector that describes the permutation matrix :math:P for the reordering of the matrix :math:A. The elements of the permutation matrix :math:P are zero except for the unit elements in row :math:i and column :math:\mathrm{perm}[i-1], :math:i = 1,2,\ldots n.

**info** : int, ndarray, shape :math:\left(4\right)
Statistics about the matrix :math:A and the permuted matrix. The quantities below are calculated using any masking in effect otherwise the value zero is returned.

:math:\mathrm{info}[0]

The bandwidth of the matrix :math:A, if :math:\mathrm{lopts}[3] = \mathbf{True}.

:math:\mathrm{info}[1]

The profile of the matrix :math:A, if :math:\mathrm{lopts}[3] = \mathbf{True}.

:math:\mathrm{info}[2]

The bandwidth of the permuted matrix :math:PAP^\mathrm{T}, if :math:\mathrm{lopts}[4] = \mathbf{True}.

:math:\mathrm{info}[3]

The profile of the permuted matrix :math:PAP^\mathrm{T}, if :math:\mathrm{lopts}[4] = \mathbf{True}.

.. _f11ye-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:n\geq 1.

(errno :math:2)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 1.

(errno :math:3)
On entry, :math:\mathrm{irowix}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{irowix}[i-1]\leq n for all :math:i.

(errno :math:4)
On entry, :math:\mathrm{icolzp}[\langle\mathit{\boldsymbol{value}}\rangle] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{icolzp}[i-1]\leq \textit{nnz} for all :math:i.

(errno :math:5)
On entry, :math:\mathrm{icolzp}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icolzp}[0] = 1.

(errno :math:5)
On entry, :math:\mathrm{icolzp}[n] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icolzp}[n] = \textit{nnz}+1.

(errno :math:6)
On entry, the matrix :math:A is not symmetric.

Element :math:\left(\langle\mathit{\boldsymbol{value}}\rangle, \langle\mathit{\boldsymbol{value}}\rangle\right) has no symmetric element.

.. _f11ye-py2-py-notes:

**Notes**
sym_rcm takes the compressed column storage (CCS) representation (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__) of an :math:n\times n symmetric matrix :math:A and applies the Reverse Cuthill--McKee (RCM) algorithm which aims to minimize the bandwidth of the matrix :math:A by reordering the rows and columns symmetrically.
This also results in a lower profile of the matrix (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11yef.html#fcomments>__).

sym_rcm can be useful for solving systems of equations :math:Ax = b, as the permuted system :math:PAP^\mathrm{T}\left(Px\right) = Pb (where :math:P is the permutation matrix described by the vector :math:\mathrm{perm} returned by sym_rcm) may require less storage space and/or less computational steps when solving (see Wai-Hung and Sherman (1976)).

sym_rcm may be used prior to :meth:real_symm_precon_ichol and :meth:real_symm_precon_ichol_solve.

.. _f11ye-py2-py-references:

**References**
Pissanetsky, S, 1984, Sparse Matrix Technology, Academic Press

Wai-Hung, L and Sherman, A H, 1976, Comparative analysis of the Cuthill--McKee and the reverse Cuthill--McKee ordering algorithms for sparse matrices, SIAM J. Numer. Anal. (13(2)), 198--213
"""
raise NotImplementedError

[docs]def real_gen_sort(n, a, irow, icol, dup, zer):
r"""
real_gen_sort sorts the nonzero elements of a real sparse nonsymmetric matrix, represented in coordinate storage format.

.. _f11za-py2-py-doc:

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

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

.. _f11za-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the order of the matrix :math:A.

**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the matrix :math:A. These may be in any order and there may be multiple nonzero elements with the same row and column indices.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**dup** : str, length 1
Indicates how elements in :math:\mathrm{a} with duplicate row and column indices are to be treated.

:math:\mathrm{dup} = \texttt{'R'}

Duplicate entries are removed, only the first entry is kept.

:math:\mathrm{dup} = \texttt{'S'}

The relevant values in :math:\mathrm{a} are summed.

:math:\mathrm{dup} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 3 on detecting a duplicate.

**zer** : str, length 1
Indicates how elements in :math:\mathrm{a} with zero values are to be treated.

:math:\mathrm{zer} = \texttt{'R'}

The entries are removed.

:math:\mathrm{zer} = \texttt{'K'}

The entries are kept.

:math:\mathrm{zer} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 4 on detecting a zero.

**Returns**
**a** : float, ndarray, shape :math:\left(\textit{nnz}\right)
The nonzero elements ordered by increasing row index, and by increasing column index within each row. Each nonzero element has a unique row and column index.

**irow** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The first :math:\textit{nnz} elements contain the row indices corresponding to the elements returned in the array :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The first :math:\textit{nnz} elements contain the column indices corresponding to the elements returned in the array :math:\mathrm{a}.

**istr** : int, ndarray, shape :math:\left(\mathrm{n}+1\right)
:math:\mathrm{istr}[\textit{i}-1]-1, for :math:\textit{i} = 1,2,\ldots,\mathrm{n}, is the starting address in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:i of the matrix :math:A. :math:\mathrm{istr}[\mathrm{n}]-1 is the address of the last element in :math:\mathrm{a} plus one.

.. _f11za-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{zer} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zer} = \texttt{'R'}, :math:\texttt{'K'} or :math:\texttt{'F'}.

(errno :math:1)
On entry, :math:\mathrm{dup} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dup} = \texttt{'R'}, :math:\texttt{'S'} or :math:\texttt{'F'}.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq \mathrm{n}.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq \mathrm{n}.

(errno :math:3)
On entry, a duplicate entry has been found in row :math:i and column :math:j: :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:j = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:4)
On entry, a zero entry has been found in row :math:i and column :math:j: :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:j = \langle\mathit{\boldsymbol{value}}\rangle.

.. _f11za-py2-py-notes:

**Notes**
real_gen_sort takes a coordinate storage (CS) representation (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__) of a real :math:n\times n sparse nonsymmetric matrix :math:A, and reorders the nonzero elements by increasing row index and increasing column index within each row.
Entries with duplicate row and column indices may be removed.
Alternatively, duplicate entries may be summed, which facilitates spare matrix addition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11zaf.html#fcomments>__).
Any entries with zero values may optionally be removed.

real_gen_sort also returns a pointer array :math:\mathrm{istr} to the starting address of each row in :math:A.
This can be used to construct a compressed column storage (CCS) representation of the matrix (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11zaf.html#fcomments>__).
"""
raise NotImplementedError

[docs]def real_symm_sort(n, a, irow, icol, dup, zer):
r"""
real_symm_sort sorts the nonzero elements of a real sparse symmetric matrix, represented in symmetric coordinate storage format.

.. _f11zb-py2-py-doc:

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

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

.. _f11zb-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the order of the matrix :math:A.

**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the lower triangular part of the real matrix :math:A. These may be in any order and there may be multiple nonzero elements with the same row and column indices.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**dup** : str, length 1
Indicates how elements in :math:\mathrm{a} with duplicate row and column indices are to be treated.

:math:\mathrm{dup} = \texttt{'R'}

Duplicate entries are removed, only the first entry is kept.

:math:\mathrm{dup} = \texttt{'S'}

The relevant values in :math:\mathrm{a} are summed.

:math:\mathrm{dup} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 3 on detecting a duplicate.

**zer** : str, length 1
Indicates how elements in :math:\mathrm{a} with zero values are to be treated.

:math:\mathrm{zer} = \texttt{'R'}

The entries are removed.

:math:\mathrm{zer} = \texttt{'K'}

The entries are kept.

:math:\mathrm{zer} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 4 on detecting a zero.

**Returns**
**a** : float, ndarray, shape :math:\left(\textit{nnz}\right)
The lower triangular nonzero elements ordered by increasing row index, and by increasing column index within each row. Each nonzero element has a unique row and column index.

**irow** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The first :math:\textit{nnz} elements contain the row indices corresponding to the elements returned in the array :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The first :math:\textit{nnz} elements contain the column indices corresponding to the elements returned in the array :math:\mathrm{a}.

**istr** : int, ndarray, shape :math:\left(\mathrm{n}+1\right)
:math:\mathrm{istr}[\textit{i}-1]-1, for :math:\textit{i} = 1,2,\ldots,\mathrm{n}, is the starting address in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:i of the matrix :math:A. :math:\mathrm{istr}[\mathrm{n}]-1 is the address of the last element in :math:\mathrm{a} plus one.

.. _f11zb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{zer} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zer} = \texttt{'R'}, :math:\texttt{'K'} or :math:\texttt{'F'}.

(errno :math:1)
On entry, :math:\mathrm{dup} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dup} = \texttt{'R'}, :math:\texttt{'S'} or :math:\texttt{'F'}.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq \mathrm{irow}[i-1].

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq \mathrm{n}.

(errno :math:3)
On entry, a duplicate entry has been found in row :math:\textit{I} and column :math:\textit{J}: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:4)
On entry, a zero entry has been found in row :math:\textit{I} and column :math:\textit{J}: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle.

.. _f11zb-py2-py-notes:

**Notes**
real_symm_sort takes a symmetric coordinate storage (SCS) representation (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__) of a real :math:n\times n sparse symmetric matrix :math:A, and reorders the nonzero elements by increasing row index and increasing column index within each row.
Entries with duplicate row and column indices may be removed.
Alternatively, duplicate entries may be summed, which facilitates spare matrix addition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11zbf.html#fcomments>__).
Any entries with zero values may optionally be removed.

real_symm_sort also returns a pointer array :math:\mathrm{istr} to the starting address of each row in :math:A.
"""
raise NotImplementedError

[docs]def real_rect_sort(m, a, irow, n=None, icol=None, istc=None, dup='S', zer='R'):
r"""
real_rect_sort sorts the nonzero elements of a real sparse rectangular matrix, represented in coordinate storage or compressed column storage format.

.. _f11zc-py2-py-doc:

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

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

.. _f11zc-py2-py-parameters:

**Parameters**
**m** : int
:math:m, the number of rows in the matrix :math:A.

**a** : float, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the matrix :math:A. If column indices are supplied via :math:\mathrm{icol}, the elements may be in any order. If column starting addresses are supplied via :math:\mathrm{istc}, the elements must be ordered by increasing column index. There may be multiple nonzero elements with the same row and column indices.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**n** : None or int, optional
:math:n, the number of columns in the matrix :math:A.

If you are providing column starting addresses via :math:\mathrm{istc} then your supplied value of :math:\mathrm{n} will be ignored and it will be inferred from that array instead.

**icol** : None or int, array-like, shape :math:\left(\textit{nnz}\right), optional
Must be used to supply the column indices corresponding to the elements supplied in the array :math:\mathrm{a}, when :math:\mathrm{a} is represented in coordinate storage format.

**istc** : None or int, array-like, shape :math:\left(n+1\right), optional
Must be used to supply the starting address of each column, as supplied in the array :math:\mathrm{a}, when :math:\mathrm{a} is represented in compressed column storage format.

**dup** : str, length 1, optional
Indicates how elements in :math:\mathrm{a} with duplicate row and column indices are to be treated.

:math:\mathrm{dup} = \texttt{'R'}

Duplicate entries are removed, only the first entry is kept.

:math:\mathrm{dup} = \texttt{'S'}

The relevant values in :math:\mathrm{a} are summed.

:math:\mathrm{dup} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 12 on detecting a duplicate.

**zer** : str, length 1, optional
Indicates how elements in :math:\mathrm{a} with zero values are to be treated.

:math:\mathrm{zer} = \texttt{'R'}

The entries are removed.

:math:\mathrm{zer} = \texttt{'K'}

The entries are kept.

:math:\mathrm{zer} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 13 on detecting a zero.

**Returns**
**a** : float, ndarray, shape :math:\left(\textit{nnz}\right)
The nonzero elements ordered by increasing column index, and by increasing row index within each column. Each nonzero element has a unique row and column index.

**irow** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The row indices corresponding to the elements returned in the array :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The column indices corresponding to the elements returned in the array :math:\mathrm{a}.

**istc** : int, ndarray, shape :math:\left(n+1\right)
The starting address of each column, as returned in the array :math:\mathrm{a}. :math:\mathrm{istc}[n]-1 is the address of the last element in :math:\mathrm{a} plus one.

.. _f11zc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{m}\geq 1.

(errno :math:2)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:3)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 0.

(errno :math:5)
On entry, :math:\mathrm{dup} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dup} = \texttt{'R'}, :math:\texttt{'S'} or :math:\texttt{'F'}.

(errno :math:6)
On entry, :math:\mathrm{zer} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zer} = \texttt{'R'}, :math:\texttt{'K'} or :math:\texttt{'F'}.

(errno :math:7)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{m} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:1\leq \mathrm{irow}[i-1]\leq \mathrm{m}.

(errno :math:8)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:n = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: if column indices are supplied, then :math:1\leq \mathrm{icol}[i-1]\leq n.

(errno :math:9)
On entry, :math:\mathrm{istc}[0] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istc}[0] = 1.

(errno :math:10)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istc}[\textit{i}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{istc}[\textit{i}] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istc}[\textit{i}-1]\leq \mathrm{istc}[\textit{i}], for :math:\textit{i} = 1,2,\ldots,n

(errno :math:11)
On entry, :math:n = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{istc}[n] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{istc}[n] = \textit{nnz}+1.

(errno :math:12)
On entry, a duplicate entry has been found in row :math:\langle\mathit{\boldsymbol{value}}\rangle and column :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:13)
On entry, a zero entry has been found in row :math:\langle\mathit{\boldsymbol{value}}\rangle and column :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:14)
Exactly one of :math:\mathrm{icol} and :math:\mathrm{istc} must be provided.

(errno :math:15)
:math:\mathrm{n} or :math:\mathrm{istc} must be provided.

.. _f11zc-py2-py-notes:

**Notes**
real_rect_sort takes a coordinate storage (CS) representation (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__), or compressed column storage (CCS) representation (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background12>__) of a real :math:m\times n sparse rectangular matrix :math:A, and reorders the nonzero elements by increasing column index and increasing row index within each column.

Entries with duplicate row and column indices may be removed.
Alternatively, duplicate entries may be summed, which facilitates sparse matrix addition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11zcf.html#fcomments>__).
Any entries with zero values may optionally be removed.

Both CS and CCS representations of the resulting matrix are output, which allows real_rect_sort to be used to convert between the two formats (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11zcf.html#fcomments>__).
"""
raise NotImplementedError

[docs]def complex_gen_sort(n, a, irow, icol, dup, zer):
r"""
complex_gen_sort sorts the nonzero elements of a complex sparse non-Hermitian matrix, represented in coordinate storage format.

.. _f11zn-py2-py-doc:

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

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

.. _f11zn-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the order of the matrix :math:A.

**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the matrix :math:A. These may be in any order and there may be multiple nonzero elements with the same row and column indices.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**dup** : str, length 1
Indicates how elements in :math:\mathrm{a} with duplicate row and column indices are to be treated.

:math:\mathrm{dup} = \texttt{'R'}

Duplicate entries are removed, only the first entry is kept.

:math:\mathrm{dup} = \texttt{'S'}

The relevant values in :math:\mathrm{a} are summed.

:math:\mathrm{dup} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 3 on detecting a duplicate.

**zer** : str, length 1
Indicates how elements in :math:\mathrm{a} with zero values are to be treated.

:math:\mathrm{zer} = \texttt{'R'}

The entries are removed.

:math:\mathrm{zer} = \texttt{'K'}

The entries are kept.

:math:\mathrm{zer} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 4 on detecting a zero.

**Returns**
**a** : complex, ndarray, shape :math:\left(\textit{nnz}\right)
The nonzero elements ordered by increasing row index, and by increasing column index within each row. Each nonzero element has a unique row and column index.

**irow** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The first :math:\textit{nnz} elements contain the row indices corresponding to the elements returned in the array :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The first :math:\textit{nnz} elements contain the column indices corresponding to the elements returned in the array :math:\mathrm{a}.

**istr** : int, ndarray, shape :math:\left(\mathrm{n}+1\right)
:math:\mathrm{istr}[\textit{i}-1]-1, for :math:\textit{i} = 1,2,\ldots,\mathrm{n}, is the starting address in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:i of the matrix :math:A. :math:\mathrm{istr}[\mathrm{n}]-1 is the address of the last element in :math:\mathrm{a} plus one.

.. _f11zn-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{zer} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zer} = \texttt{'R'}, :math:\texttt{'K'} or :math:\texttt{'F'}.

(errno :math:1)
On entry, :math:\mathrm{dup} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dup} = \texttt{'R'}, :math:\texttt{'S'} or :math:\texttt{'F'}.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[i-1]\geq 1 and :math:\mathrm{icol}[i-1]\leq \mathrm{n}.

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq \mathrm{n}.

(errno :math:3)
On entry, a duplicate entry has been found in row :math:\textit{I} and column :math:\textit{J}: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:4)
On entry, a zero entry has been found in row :math:\textit{I} and column :math:\textit{J}: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle.

.. _f11zn-py2-py-notes:

**Notes**
complex_gen_sort takes a coordinate storage (CS) representation (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background10>__) of a sparse :math:n\times n complex non-Hermitian matrix :math:A, and reorders the nonzero elements by increasing row index and increasing column index within each row.
Entries with duplicate row and column indices may be removed.
Alternatively, duplicate entries may be summed, which facilitates spare matrix addition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11znf.html#fcomments>__).
Any entries with zero values may optionally be removed.

complex_gen_sort also returns a pointer array :math:\mathrm{istr} to the starting address of each row in :math:A.
This can be used to construct a compressed column storage (CCS) representation of the matrix (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11znf.html#fcomments>__).

--------
:meth:naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main
"""
raise NotImplementedError

[docs]def complex_herm_sort(n, a, irow, icol, dup, zer):
r"""
complex_herm_sort sorts the nonzero elements of a sparse complex Hermitian matrix, represented in symmetric coordinate storage format.

.. _f11zp-py2-py-doc:

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

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

.. _f11zp-py2-py-parameters:

**Parameters**
**n** : int
:math:n, the order of the matrix :math:A.

**a** : complex, array-like, shape :math:\left(\textit{nnz}\right)
The nonzero elements of the lower triangular part of the complex matrix :math:A. These may be in any order and there may be multiple nonzero elements with the same row and column indices.

**irow** : int, array-like, shape :math:\left(\textit{nnz}\right)
The row indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**icol** : int, array-like, shape :math:\left(\textit{nnz}\right)
The column indices corresponding to the elements supplied in the array :math:\mathrm{a}.

**dup** : str, length 1
Indicates how elements in :math:\mathrm{a} with duplicate row and column indices are to be treated.

:math:\mathrm{dup} = \texttt{'R'}

Duplicate entries are removed, only the first entry is kept.

:math:\mathrm{dup} = \texttt{'S'}

The relevant values in :math:\mathrm{a} are summed.

:math:\mathrm{dup} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 3 on detecting a duplicate.

**zer** : str, length 1
Indicates how elements in :math:\mathrm{a} with zero values are to be treated.

:math:\mathrm{zer} = \texttt{'R'}

The entries are removed.

:math:\mathrm{zer} = \texttt{'K'}

The entries are kept.

:math:\mathrm{zer} = \texttt{'F'}

The function fails with :math:\mathrm{errno} = 4 on detecting a zero.

**Returns**
**a** : complex, ndarray, shape :math:\left(\textit{nnz}\right)
The lower triangular nonzero elements ordered by increasing row index, and by increasing column index within each row. Each nonzero element has a unique row and column index.

**irow** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The first :math:\textit{nnz} elements contain the row indices corresponding to the elements returned in the array :math:\mathrm{a}.

**icol** : int, ndarray, shape :math:\left(\textit{nnz}\right)
The first :math:\textit{nnz} elements contain the column indices corresponding to the elements returned in the array :math:\mathrm{a}.

**istr** : int, ndarray, shape :math:\left(\mathrm{n}+1\right)
:math:\mathrm{istr}[\textit{i}-1]-1, for :math:\textit{i} = 1,2,\ldots,\mathrm{n}, is the starting address in the arrays :math:\mathrm{a}, :math:\mathrm{irow} and :math:\mathrm{icol} of row :math:i of the matrix :math:A. :math:\mathrm{istr}[\mathrm{n}]-1 is the address of the last element in :math:\mathrm{a} plus one.

.. _f11zp-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
On entry, :math:\mathrm{zer} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{zer} = \texttt{'R'}, :math:\texttt{'K'} or :math:\texttt{'F'}.

(errno :math:1)
On entry, :math:\mathrm{dup} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{dup} = \texttt{'R'}, :math:\texttt{'S'} or :math:\texttt{'F'}.

(errno :math:1)
On entry, :math:\textit{nnz} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{nnz}\geq 0.

(errno :math:1)
On entry, :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{n}\geq 1.

(errno :math:2)
On entry, :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{icol}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{irow}[\textit{I}-1] = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{icol}[\textit{I}-1]\geq 1 and :math:\mathrm{icol}[\textit{I}-1]\leq \mathrm{irow}[\textit{I}-1].

(errno :math:2)
On entry, :math:i = \langle\mathit{\boldsymbol{value}}\rangle, :math:\mathrm{irow}[i-1] = \langle\mathit{\boldsymbol{value}}\rangle and :math:\mathrm{n} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\mathrm{irow}[i-1]\geq 1 and :math:\mathrm{irow}[i-1]\leq \mathrm{n}.

(errno :math:3)
On entry, a duplicate entry has been found in row :math:\textit{I} and column :math:\textit{J}: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:4)
On entry, a zero entry has been found in row :math:\textit{I} and column :math:\textit{J}: :math:\textit{I} = \langle\mathit{\boldsymbol{value}}\rangle, :math:\textit{J} = \langle\mathit{\boldsymbol{value}}\rangle.

.. _f11zp-py2-py-notes:

**Notes**
complex_herm_sort takes a symmetric coordinate storage (SCS) representation (see the F11 Introduction <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11intro.html#background11>__) of a sparse :math:n\times n complex Hermitian matrix :math:A, and reorders the nonzero elements by increasing row index and increasing column index within each row.
Entries with duplicate row and column indices may be removed.
Alternatively, duplicate entries may be summed, which facilitates spare matrix addition (see Further Comments <https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f11/f11zpf.html#fcomments>__).
Any entries with zero values may optionally be removed.

complex_herm_sort also returns a pointer array :math:\mathrm{istr} to the starting address of each row in :math:A.
"""
raise NotImplementedError