# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.3 `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`.
See Also
--------
``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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11intro.html
"""
# NAG Copyright 2017-2024.
[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://support.nag.com/numeric/nl/nagdoc_30.3/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'}`
Conjugate gradient squared method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11bdf.html#eqne2>`__.
:math:`\mathrm{iterm} = 2`
Use the termination criterion defined in `(3) <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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);
conjugate gradient squared method (CGS);
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.
**Conjugate Gradient Squared Method (CGS)**
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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11bdf.html#fcomments>`__).
Termination criterion `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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'}`
Conjugate gradient squared method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11brf.html#eqne2>`__.
:math:`\mathrm{iterm} = 2`
Use the termination criterion defined in `(3) <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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);
conjugate gradient squared method (CGS);
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.
**Conjugate Gradient Squared Method (CGS)**
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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11brf.html#fcomments>`__).
Termination criterion `(2) <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11daf.html#fcomments4>`__).
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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'}`
Conjugate gradient squared method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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'}`
Conjugate gradient squared method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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'}`
Conjugate gradient squared method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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'}`
Conjugate gradient squared method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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'}`
Conjugate gradient squared method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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'}`
Conjugate gradient squared method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11gdf.html
.. _f11gd-py2-py-parameters:
**Parameters**
**method** : str
The iterative method to be used.
:math:`\mathrm{method} = \texttt{'CG'}`
Conjugate gradient method (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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11gdf.html#eqnf11gdfe2>`__ (both conjugate gradient and Lanczos (SYMMLQ) methods).
:math:`\mathrm{iterm} = 2`
Use the termination criterion defined in `(3) <https://support.nag.com/numeric/nl/nagdoc_30.3/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:
(1) **Conjugate Gradient Method (CG)**
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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11grf.html
.. _f11gr-py2-py-parameters:
**Parameters**
**method** : str
The iterative method to be used.
:math:`\mathrm{method} = \texttt{'CG'}`
Conjugate gradient method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11grf.html#eqnf11grfe2>`__ (both conjugate gradient and Lanczos (SYMMLQ) methods).
:math:`\mathrm{iterm} = 2`
Use the termination criterion defined in `(3) <https://support.nag.com/numeric/nl/nagdoc_30.3/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:
(1) **Conjugate Gradient Method (CG)**
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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11jaf.html#fcomments>`__.
The sparse matrix :math:`A` is represented in symmetric coordinate storage (SCS) format (see `the F11 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11jcf.html
.. _f11jc-py2-py-parameters:
**Parameters**
**method** : str
Specifies the iterative method to be used.
:math:`\mathrm{method} = \texttt{'CG'}`
Conjugate gradient method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11jef.html
.. _f11je-py2-py-parameters:
**Parameters**
**method** : str
Specifies the iterative method to be used.
:math:`\mathrm{method} = \texttt{'CG'}`
Conjugate gradient method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11jnf.html#fcomments>`__.
The sparse matrix :math:`A` is represented in symmetric coordinate storage (SCS) format (see `the F11 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11jqf.html
.. _f11jq-py2-py-parameters:
**Parameters**
**method** : str
Specifies the iterative method to be used.
:math:`\mathrm{method} = \texttt{'CG'}`
Conjugate gradient method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11jsf.html
.. _f11js-py2-py-parameters:
**Parameters**
**method** : str
Specifies the iterative method to be used.
:math:`\mathrm{method} = \texttt{'CG'}`
Conjugate gradient method.
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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.
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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.
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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
[docs]def sym_rcm(icolzp, irowix, lopts, mask=None):
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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11intro.html#background10>`__), or compressed column storage (CCS) representation (see `the F11 Introduction <https://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f11/f11znf.html#fcomments>`__).
See Also
--------
: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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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://support.nag.com/numeric/nl/nagdoc_30.3/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
