# Source code for naginterfaces.library.sparseig

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

sparseig - Large Scale Eigenproblems

This module provides functions for computing **some** eigenvalues and eigenvectors of large-scale (sparse) standard and generalized eigenvalue problems.
It provides functions for:

solution of symmetric eigenvalue problems;

solution of nonsymmetric eigenvalue problems;

solution of generalized symmetric-definite eigenvalue problems;

solution of generalized nonsymmetric eigenvalue problems;

solution of polynomial eigenvalue problems;

partial singular value decomposition.

Functions are provided for both real and complex data.

ARPACK Functions
~~~~~~~~~~~~~~~~
The functions in this module whose names do not contain substring '_feast_' have all been derived from the ARPACK software suite (see Lehoucq et al. (1998)), a collection of Fortran 77 functions designed to solve large scale eigenvalue problems.
The interfaces provided in this module have been chosen to combine ease of use with the flexibility of the original ARPACK software.
The underlying iterative methods and algorithms remain essentially the same as those in ARPACK and are described fully in Lehoucq et al. (1998).

The algorithms used in the ARPACK functions are based upon an algorithmic variant of the Arnoldi process called the Implicitly Restarted Arnoldi Method.
For symmetric matrices, this reduces to a variant of the Lanczos process called the Implicitly Restarted Lanczos Method.
These variants may be viewed as a synthesis of the Arnoldi/Lanczos process with the Implicitly Shifted :math:QR technique that is suitable for large scale problems.
For many standard problems, a matrix factorization is not required.
Only the action of the matrix on a vector is needed.

The ARPACK functions can be used to find the eigenvalues with the largest and/or smallest magnitudes, real part or imaginary part.

FEAST Functions
~~~~~~~~~~~~~~~
The functions in this module whose names contain substring '_feast_' have been derived from the FEAST software suite (see Polizzi (2009)). FEAST is a general purpose eigensolver for standard, generalized and polynomial eigenvalue problems.
It is suitable for both sparse and dense matrices, and functions are available for real, complex, symmetric, Hermitian and non-Hermitian eigenvalue problems.
The FEAST algorithm requires you to specify a particular region of interest in the complex plane within which eigenvalues are sought.
The algorithm then performs a numerical quadrature computation, involving solving linear systems along a complex contour around the region of interest.

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

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

**ARPACK routines**

Standard or generalized eigenvalue problems for complex matrices

banded matrices

initialize problem and method: :meth:complex_band_init

selected eigenvalues, eigenvectors and/or Schur vectors: :meth:complex_band_solve

general matrices

initialize problem and method: :meth:complex_init

option setting: :meth:complex_option

reverse communication implicitly restarted Arnoldi method: :meth:complex_iter

reverse communication monitoring: :meth:complex_monit

selected eigenvalues, eigenvectors and/or Schur vectors of original problem: :meth:complex_proc

Standard or generalized eigenvalue problems for real nonsymmetric matrices

banded matrices

initialize problem and method: :meth:real_band_init

selected eigenvalues, eigenvectors and/or Schur vectors: :meth:real_band_solve

general matrices

initialize problem and method: :meth:real_init

option setting: :meth:real_option

reverse communication implicitly restarted Arnoldi method: :meth:real_iter

reverse communication monitoring: :meth:real_monit

selected eigenvalues, eigenvectors and/or Schur vectors of original problem: :meth:real_proc

Standard or generalized eigenvalue problems for real symmetric matrices

banded matrices

initialize problem and method: :meth:real_symm_band_init

selected eigenvalues, eigenvectors and/or Schur vectors: :meth:real_symm_band_solve

general matrices

initialize problem and method: :meth:real_symm_init

reverse communication implicitly restarted Arnoldi(Lanczos) method: :meth:real_symm_iter

reverse communication monitoring: :meth:real_symm_monit

selected eigenvalues and eigenvectors and/or Schur vectors of original problem: :meth:real_symm_proc

**NAG FEAST suite**

contour setting

elliptical contour for nonsymmetric or complex symmetric eigenvalue problems: :meth:feast_gen_contour

general contour for nonsymmetric or complex symmetric eigenvalue problems: :meth:feast_custom_contour

real symmetric/complex Hermitian eigenvalue problems: :meth:feast_symm_contour

deallocation: :meth:feast_free

initialization: :meth:feast_init

option setting: :meth:feast_option

solvers

complex Hermitian: :meth:feast_complex_herm_solve

complex nonsymmetric: :meth:feast_complex_gen_solve

complex symmetric: :meth:feast_complex_symm_solve

polynomial nonsymmetric: :meth:feast_poly_gen_solve

polynomial symmetric: :meth:feast_poly_symm_solve

real nonsymmetric: :meth:feast_real_gen_solve

real symmetric: :meth:feast_real_symm_solve

For full information please refer to the NAG Library document

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12intro.html
"""

[docs]def real_init(n, nev, ncv):
r"""
real_init is a setup function in a suite of functions consisting of real_init, :meth:real_iter, :meth:real_proc, :meth:real_option and :meth:real_monit.
It is used to find some of the eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by real nonsymmetric matrices.

The suite of functions is suitable for the solution of large sparse, standard or generalized, nonsymmetric eigenproblems where only a few eigenvalues from a selected range of the spectrum are required.

.. _f12aa-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12aaf.html

.. _f12aa-py2-py-parameters:

**Parameters**
**n** : int
The order of the matrix :math:A (and the order of the matrix :math:B for the generalized problem) that defines the eigenvalue problem.

**nev** : int
The number of eigenvalues to be computed.

**ncv** : int
The number of Arnoldi basis vectors to use during the computation.

At present there is no a priori analysis to guide the selection of :math:\mathrm{ncv} relative to :math:\mathrm{nev}.

However, it is recommended that :math:\mathrm{ncv}\geq 2\times \mathrm{nev}+1.

If many problems of the same type are to be solved, you should experiment with increasing :math:\mathrm{ncv} while keeping :math:\mathrm{nev} fixed for a given test problem.

This will usually decrease the required number of matrix-vector operations but it also increases the work and storage required to maintain the orthogonal basis vectors.

The optimal 'cross-over' with respect to CPU time is problem dependent and must be determined empirically.

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

.. _f12aa-py2-py-errors:

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

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

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

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

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

Constraint: :math:\mathrm{ncv} > \mathrm{nev}+1 and :math:\mathrm{ncv}\leq \mathrm{n}.

.. _f12aa-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, real and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real and nonsymmetric problems.

real_init is a setup function which must be called before :meth:real_iter, the reverse communication iterative solver, and before :meth:real_option, the options setting function. :meth:real_proc is a post-processing function that must be called following a successful final exit from :meth:real_iter, while :meth:real_monit can be used to return additional monitoring information during the computation.

This setup function initializes the communication arrays, sets (to their default values) all options that can be set by you via the option setting function :meth:real_option, and checks that the lengths of the communication arrays as passed by you are of sufficient length.
For details of the options available and how to set them see :ref:Other Parameters for real_option <f12ad-py2-py-other_params>.

.. _f12aa-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_iter(irevcm, resid, v, x, mx, comm, io_manager=None):
r"""
real_iter is an iterative solver in a suite of functions consisting of :meth:real_init, real_iter, :meth:real_proc, :meth:real_option and :meth:real_monit.
It is used to find some of the eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by real nonsymmetric matrices.

.. _f12ab-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12abf.html

.. _f12ab-py2-py-parameters:

**Parameters**
**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

**resid** : float, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: need not be set unless the option 'Initial Residual' has been set in a prior call to :meth:real_option in which case :math:\mathrm{resid} should contain an initial residual vector, possibly from a previous run.

On intermediate entry: must be unchanged from its previous exit. Changing :math:\mathrm{resid} to any other value between calls may result in an error exit.

On intermediate exit: contains the current residual vector.

On final exit: contains the final residual vector.

**v** : float, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right), modified in place
On initial entry: need not be set.

On intermediate entry: must be unchanged from its previous exit.

On intermediate exit: contains the current set of Arnoldi basis vectors.

On final exit: contains the final set of Arnoldi basis vectors.

**x** : float, ndarray, shape :math:\left(:\right), modified in place
Note: the required length for this argument is determined as follows: if :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)+24\right) - 1 }]=0: :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)+1\right) - 1 }]; otherwise: :math:1.

On initial entry: need not be set, it is used as a convenient mechanism for accessing elements of :math:\mathrm{comm}\ ['comm'].

On intermediate entry: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{x} need not be set.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{x} must contain the result of :math:y = \mathrm{op}\left(x\right) when :math:\mathrm{irevcm} returns the value :math:-1 or :math:+1.

It must return the real parts of the computed shifts when :math:\mathrm{irevcm} returns the value :math:3.

On intermediate exit: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{x} is not referenced.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{x} contains the vector :math:x when :math:\mathrm{irevcm} returns the value :math:-1 or :math:+1.

On final exit: does not contain useful data.

**mx** : float, ndarray, shape :math:\left(:\right), modified in place
Note: the required length for this argument is determined as follows: if :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)+24\right) - 1 }]=0: :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)+1\right) - 1 }]; otherwise: :math:1.

On initial entry: need not be set, it is used as a convenient mechanism for accessing elements of :math:\mathrm{comm}\ ['comm'].

On intermediate entry: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{mx} need not be set.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{mx} must contain the result of :math:y = Bx when :math:\mathrm{irevcm} returns the value :math:2.

It must return the imaginary parts of the computed shifts when :math:\mathrm{irevcm} returns the value :math:3.

On intermediate exit: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{mx} is not referenced.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{mx} contains the vector :math:Bx when :math:\mathrm{irevcm} returns the value :math:+1.

On final exit: does not contain any useful data.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = -1

The calling program must compute the matrix-vector product :math:y = \mathrm{op}\left(x\right), where :math:x is stored in :math:\mathrm{x} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the first element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set in a prior call to :meth:real_option. The result :math:y is returned in :math:\mathrm{x} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the second element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set. If :math:B is not symmetric semidefinite then the precomputed values in :math:\mathrm{mx} should not be used (see the explanation under :math:\mathrm{irevcm} = 2).

:math:\mathrm{irevcm} = 1

The calling program must compute the matrix-vector product :math:y = \mathrm{op}\left(x\right). This is similar to the case :math:\mathrm{irevcm} = -1 except that the result of the matrix-vector product :math:Bx (as required in some computational modes) has already been computed and is available in :math:\mathrm{mx} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the third element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set.

:math:\mathrm{irevcm} = 2

The calling program must compute the matrix-vector product :math:y = Bx, where :math:x is stored as described in the case :math:\mathrm{irevcm} = -1 and :math:y is returned in the location described by the case :math:\mathrm{irevcm} = 1. This computation is requested when solving the 'Generalized' problem using either 'Shifted Inverse Imaginary', 'Shifted Inverse Real'; in these cases :math:B is used as an inner-product space and requires that :math:B be symmetric semidefinite. If neither :math:A nor :math:B is symmetric semidefinite then the problem should be reformulated in a 'Standard' form.

:math:\mathrm{irevcm} = 3

Compute the :math:\mathrm{nshift} real and imaginary parts of the shifts where the real parts are to be returned in the first :math:\mathrm{nshift} locations of the array :math:\mathrm{x} and the imaginary parts are to be returned in the first :math:\mathrm{nshift} locations of the array :math:\mathrm{mx}. Only complex conjugate pairs of shifts may be applied and the pairs must be placed in consecutive locations. This value of :math:\mathrm{irevcm} will only arise if the option 'Supplied Shifts' is set in a prior call to :meth:real_option which is intended for experienced users only; the default and recommended option is to use exact shifts (see Lehoucq et al. (1998) for details).

:math:\mathrm{irevcm} = 4

Monitoring step: a call to :meth:real_monit can now be made to return the number of Arnoldi iterations, the number of converged Ritz values, their real and imaginary parts, and the corresponding Ritz estimates.

On final exit: :math:\mathrm{irevcm} = 5: real_iter has completed its tasks. The value of :math:\textit{errno} determines whether the iteration has been successfully completed, or whether errors have been detected. On successful completion :meth:real_proc must be called to return the requested eigenvalues and eigenvectors (and/or Schur vectors).

**nshift** : int
On intermediate exit: if the option 'Supplied Shifts' is set and :math:\mathrm{irevcm} returns a value of :math:3, :math:\mathrm{nshift} returns the number of complex shifts required.

.. _f12ab-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
The maximum number of iterations :math:\leq 0, the option 'Iteration Limit' has been set to :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
The options 'Generalized' and 'Regular' are incompatible.

(errno :math:5)
No shifts could be applied during a cycle of the implicitly restarted Arnoldi iteration.

(errno :math:6)
Could not build an Arnoldi factorization. The size of the current Arnoldi factorization :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:7)
Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:8)
Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.

**Warns**
**NagAlgorithmicWarning**
(errno :math:3)
The option 'Initial Residual' was selected but the starting vector held in :math:\mathrm{resid} is zero.

(errno :math:4)
The maximum number of iterations has been reached. The maximum number of :math:\text{iterations} = \langle\mathit{\boldsymbol{value}}\rangle. The number of converged eigenvalues :math:= \langle\mathit{\boldsymbol{value}}\rangle. See the function document for further details.

.. _f12ab-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, real and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real and nonsymmetric problems.

real_iter is a **reverse communication** function, based on the ARPACK routine **dnaupd**, using the Implicitly Restarted Arnoldi iteration method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices is provided in Lehoucq and Scott (1996).
This suite of functions offers the same functionality as the ARPACK software for real nonsymmetric problems, but the interface design is quite different in order to make the option setting clearer and to simplify the interface of real_iter.

The setup function :meth:real_init must be called before real_iter, the reverse communication iterative solver.
Options may be set for real_iter by prior calls to the option setting function :meth:real_option and a post-processing function :meth:real_proc must be called following a successful final exit from real_iter. :meth:real_monit, may be called following certain flagged, intermediate exits from real_iter to provide additional monitoring information about the computation.

real_iter uses **reverse communication**, i.e., it returns repeatedly to the calling program with the argument :math:\mathrm{irevcm} (see :ref:Parameters <f12ab-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:y = \mathrm{op}\left(x\right), where :math:\mathrm{op} is defined by the computational mode;

-   compute the matrix-vector product :math:y = Bx;

-   notify the completion of the computation;

-   allow the calling program to monitor the solution.

The problem type to be solved (standard or generalized), the spectrum of eigenvalues of interest, the mode used (regular, regular inverse, shifted inverse, shifted real or shifted imaginary) and other options can all be set using the option setting function :meth:real_option (see :ref:Other Parameters for real_option <f12ad-py2-py-other_params> for details on setting options and of the default settings).

.. _f12ab-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_proc(sigmar, sigmai, resid, v, comm, io_manager=None):
r"""
real_proc is a post-processing function in a suite of functions consisting of :meth:real_init, :meth:real_option and :meth:real_monit.
It must be called following a final exit from :meth:real_iter.

.. _f12ac-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12acf.html

.. _f12ac-py2-py-parameters:

**Parameters**
**sigmar** : float
If one of the 'Shifted Inverse Real' modes have been selected then :math:\mathrm{sigmar} contains the real part of the shift used; otherwise :math:\mathrm{sigmar} is not referenced.

**sigmai** : float
If one of the 'Shifted Inverse Real' modes have been selected then :math:\mathrm{sigmai} contains the imaginary part of the shift used; otherwise :math:\mathrm{sigmai} is not referenced.

**resid** : float, array-like, shape :math:\left(\textit{n}\right)
Must not be modified following a call to :meth:real_iter since it contains data required by real_proc.

**v** : float, array-like, shape :math:\left(\textit{n}, \textit{ncv}\right)
The :math:\textit{ncv} columns of :math:\mathrm{v} contain the Arnoldi basis vectors for :math:\mathrm{op} as constructed by :meth:real_iter.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**nconv** : int
The number of converged eigenvalues as found by :meth:real_iter.

**dr** : float, ndarray, shape :math:\left(\textit{nev}+1\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{dr} contain the real parts of the converged approximate eigenvalues.

**di** : float, ndarray, shape :math:\left(\textit{nev}+1\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{di} contain the imaginary parts of the converged approximate eigenvalues.

**z** : float, ndarray, shape :math:\left(\textit{n}, :\right)
If the default option :math:\text{‘Vectors'} = \texttt{'RITZ'} (see :meth:real_option) has been selected then :math:\mathrm{z} contains the final set of eigenvectors corresponding to the eigenvalues held in :math:\mathrm{dr} and :math:\mathrm{di}. The complex eigenvector associated with the eigenvalue with positive imaginary part is stored in two consecutive columns. The first column holds the real part of the eigenvector and the second column holds the imaginary part. The eigenvector associated with the eigenvalue with negative imaginary part is simply the complex conjugate of the eigenvector associated with the positive imaginary part.

**v** : float, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right)
If the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} has been set, or the option :math:\text{‘Vectors'} = \texttt{'RITZ'} has been set and a separate array :math:\mathrm{z} has been passed (i.e., :math:\mathrm{z} does not equal :math:\mathrm{v}), then the first :math:\mathrm{nconv} columns of :math:\mathrm{v} will contain approximate Schur vectors that span the desired invariant subspace.

.. _f12ac-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:3)
The number of eigenvalues found to sufficient accuracy, as communicated through the argument :math:\mathrm{comm}\ ['icomm'], is zero. See the function document for further details.

(errno :math:4)
Got a different count of the number of converged Ritz values than the value passed to it through the argument :math:\mathrm{comm}\ ['icomm']: number counted :math:= \langle\mathit{\boldsymbol{value}}\rangle, number expected :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:5)
During calculation of a real Schur form, there was a failure to compute :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvalues in a total of :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
The computed Schur form could not be reordered by an internal call. This function returned with :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle. Please contact NAG <https://www.nag.com>__.

(errno :math:7)
In calculating eigenvectors, an internal call returned with an error. Please contact NAG <https://www.nag.com>__.

(errno :math:8)
Either the solver function has not been called prior to the call of this function or a communication array has become corrupted.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
On entry, :math:\text{‘Vectors'} = \texttt{'SELECT'}, but this is not yet implemented.

.. _f12ac-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, real and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real and nonsymmetric problems.

Following a call to :meth:real_iter, real_proc returns the converged approximations to eigenvalues and (optionally) the corresponding approximate eigenvectors and/or an orthonormal basis for the associated approximate invariant subspace.
The eigenvalues (and eigenvectors) are selected from those of a standard or generalized eigenvalue problem defined by real nonsymmetric matrices.
There is negligible additional cost to obtain eigenvectors; an orthonormal basis is always computed, but there is an additional storage cost if both are requested.

real_proc is based on the function **dneupd** from the ARPACK package, which uses the Implicitly Restarted Arnoldi iteration method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices is provided in Lehoucq and Scott (1996).
This suite of functions offers the same functionality as the ARPACK software for real nonsymmetric problems, but the interface design is quite different in order to make the option setting clearer and to simplify some of the interfaces.

real_proc is a post-processing function that must be called following a successful final exit from :meth:real_iter. real_proc uses data returned from :meth:real_iter and options, set either by default or explicitly by calling :meth:real_option, to return the converged approximations to selected eigenvalues and (optionally):

-   the corresponding approximate eigenvectors;

-   an orthonormal basis for the associated approximate invariant subspace;

-   both.

.. _f12ac-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_option(optstr, comm, io_manager=None):
r"""
real_option is an option setting function in a suite of functions consisting of :meth:real_init, :meth:real_iter, :meth:real_proc, real_option and :meth:real_monit; it supplies individual options to :meth:real_iter and :meth:real_proc. real_option is also an option setting function in a suite of functions consisting of real_option, :meth:real_band_init and :meth:real_band_solve; it supplies individual options to :meth:real_band_solve.

The initialization function for the appropriate suite, :meth:real_init or :meth:real_band_init, **must** have been called prior to calling real_option.

Note: this function uses optional algorithmic parameters, see also: :meth:real_iter, :meth:real_proc, :meth:real_band_solve, :meth:real_init, :meth:real_band_init.

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

**Parameters**
**optstr** : str
A single valid option string (as described in :ref:Notes <f12ad-py2-py-notes> and :ref:Other Parameters <f12ad-py2-py-other_params>).

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

This argument must have been initialized by a prior call to :meth:real_init or :meth:real_band_init.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Other Parameters**
Default :math:= \text{advisory message unit number}

**'Defaults'** : valueless
This special keyword may be used to reset all options to their default values.

**'Exact Shifts'** : valueless
Default

During the Arnoldi iterative process, shifts are applied internally as part of the implicit restarting scheme.
The shift strategy used by default and selected by the 'Exact Shifts' is strongly recommended over the alternative 'Supplied Shifts' (see Lehoucq et al. (1998) for details of shift strategies).

If 'Exact Shifts' are used then these are computed internally by the algorithm in the implicit restarting scheme.

If 'Supplied Shifts' are used then, during the Arnoldi iterative process, you must supply shifts through array arguments of :meth:real_iter when :meth:real_iter returns with :math:{\textit{irevcm}} = 3; the real and imaginary parts of the shifts are supplied in :math:\textit{x} and :math:\textit{mx} respectively (or in :math:\textit{comm} when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set). This option should only be used if you are an experienced user since this requires some algorithmic knowledge and because more operations are usually required than for the implicit shift scheme.
Details on the use of explicit shifts and further references on shift strategies are available in Lehoucq et al. (1998).

**'Supplied Shifts'** : valueless
During the Arnoldi iterative process, shifts are applied internally as part of the implicit restarting scheme.
The shift strategy used by default and selected by the 'Exact Shifts' is strongly recommended over the alternative 'Supplied Shifts' (see Lehoucq et al. (1998) for details of shift strategies).

If 'Exact Shifts' are used then these are computed internally by the algorithm in the implicit restarting scheme.

If 'Supplied Shifts' are used then, during the Arnoldi iterative process, you must supply shifts through array arguments of :meth:real_iter when :meth:real_iter returns with :math:{\textit{irevcm}} = 3; the real and imaginary parts of the shifts are supplied in :math:\textit{x} and :math:\textit{mx} respectively (or in :math:\textit{comm} when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set). This option should only be used if you are an experienced user since this requires some algorithmic knowledge and because more operations are usually required than for the implicit shift scheme.
Details on the use of explicit shifts and further references on shift strategies are available in Lehoucq et al. (1998).

**'Iteration Limit'** : int
Default :math:\text{} = 300

The limit on the number of Arnoldi iterations that can be performed before :meth:real_iter or :meth:real_band_solve exits.
If not all requested eigenvalues have converged to within 'Tolerance' and the number of Arnoldi iterations has reached this limit then :meth:real_iter or :meth:real_band_solve exits with an error; :meth:real_band_solve returns the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors, while :meth:real_proc can be called subsequent to :meth:real_iter to do the same.

**'Largest Magnitude'** : valueless
Default

The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_iter or :meth:real_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Largest Imaginary'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_iter or :meth:real_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Largest Real'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_iter or :meth:real_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Smallest Imaginary'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_iter or :meth:real_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Smallest Magnitude'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_iter or :meth:real_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Smallest Real'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_iter or :meth:real_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Nolist'** : valueless
Default

Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.

**'List'** : valueless
Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.

**'Monitoring'** : int
Default :math:\text{} = -1

If :math:i > 0, monitoring information is output to unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj) :math:i during the solution of each problem; this may be the same as the 'Advisory' unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj).
The type of information produced is dependent on the value of 'Print Level', see the description of the option 'Print Level' for details of the information produced.
Please see the FileObjManager method :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj to associate a file with a given unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj).

**'Pointers'** : valueless
Default :math:\text{} = \texttt{'NO'}

During the iterative process and reverse communication calls to :meth:real_iter, required data can be communicated to and from :meth:real_iter in one of two ways.
When :math:\text{‘Pointers'} = \texttt{'NO'} is selected (the default) then the array arguments :math:\textit{x} and :math:\textit{mx} are used to supply you with required data and used to return computed values back to :meth:real_iter.
For example, when :math:{\textit{irevcm}} = 1, :meth:real_iter returns the vector :math:x in :math:\textit{x} and the matrix-vector product :math:Bx in :math:\textit{mx} and expects the result or the linear operation :math:\mathrm{op}\left(x\right) to be returned in :math:\textit{x}.

If :math:\text{‘Pointers'} = \texttt{'YES'} is selected then the data is passed through sections of the array argument :math:\textit{comm}.
The section corresponding to :math:\textit{x} when :math:\text{‘Pointers'} = \texttt{'NO'} begins at a location given by the first element of :math:\textit{icomm}; similarly the section corresponding to :math:\textit{mx} begins at a location given by the second element of :math:\textit{icomm}.
This option allows :meth:real_iter to perform fewer copy operations on each intermediate exit and entry, but can also lead to less elegant code in the calling program.

This option has no affect on :meth:real_band_solve which sets :math:\text{‘Pointers'} = \texttt{'YES'} internally.

**'Print Level'** : int
Default :math:\text{} = 0

This controls the amount of printing produced by real_option as follows.

.. rst-class:: nag-rules-none nag-align-left

+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:i      |Output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+===============+==============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:= 0    |No output except error messages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:> 0    |The set of selected options.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:= 2    |Problem and timing statistics on final exit from :meth:real_iter or :meth:real_band_solve.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 5 |A single line of summary output at each Arnoldi iteration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 10|If :math:\text{‘Monitoring'} > 0, then at each iteration, the length and additional steps of the current Arnoldi factorization and the number of converged Ritz values; during re-orthogonalization, the norm of initial/restarted starting vector.                                                                                                                                                                                                                                                                                                                         |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 20|Problem and timing statistics on final exit from :meth:real_iter. If :math:\text{‘Monitoring'} > 0, then at each iteration, the number of shifts being applied, the eigenvalues and estimates of the Hessenberg matrix :math:H, the size of the Arnoldi basis, the wanted Ritz values and associated Ritz estimates and the shifts applied; vector norms prior to and following re-orthogonalization.                                                                                                                                                                   |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 30|If :math:\text{‘Monitoring'} > 0, then on final iteration, the norm of the residual; when computing the Schur form, the eigenvalues and Ritz estimates both before and after sorting; for each iteration, the norm of residual for compressed factorization and the compressed upper Hessenberg matrix :math:H; during re-orthogonalization, the initial/restarted starting vector; during the Arnoldi iteration loop, a restart is flagged and the number of the residual requiring iterative refinement; while applying shifts, the indices of the shifts being applied.|
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 40|If :math:\text{‘Monitoring'} > 0, then during the Arnoldi iteration loop, the Arnoldi vector number and norm of the current residual; while applying shifts, key measures of progress and the order of :math:H; while computing eigenvalues of :math:H, the last rows of the Schur and eigenvector matrices; when computing implicit shifts, the eigenvalues and Ritz estimates of :math:H.                                                                                                                                                                           |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 50|If :math:\text{‘Monitoring'} > 0, then during Arnoldi iteration loop: norms of key components and the active column of :math:H, norms of residuals during iterative refinement, the final upper Hessenberg matrix :math:H; while applying shifts: number of shifts, shift values, block indices, updated matrix :math:H; while computing eigenvalues of :math:H: the matrix :math:H, the computed eigenvalues and Ritz estimates.                                                                                                                                 |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

**'Random Residual'** : valueless
Default

To begin the Arnoldi iterative process, :meth:real_iter or :meth:real_band_solve requires an initial residual vector.
By default :meth:real_iter or :meth:real_band_solve provides its own random initial residual vector; this option can also be set using option 'Random Residual'.
Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to :meth:real_iter or :meth:real_band_solve through the array argument :math:\textit{resid}; this option can be set using option 'Initial Residual'.

**'Initial Residual'** : valueless
To begin the Arnoldi iterative process, :meth:real_iter or :meth:real_band_solve requires an initial residual vector.
By default :meth:real_iter or :meth:real_band_solve provides its own random initial residual vector; this option can also be set using option 'Random Residual'.
Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to :meth:real_iter or :meth:real_band_solve through the array argument :math:\textit{resid}; this option can be set using option 'Initial Residual'.

**'Regular'** : valueless
Default

These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed by :meth:real_band_solve or when :meth:real_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+----------------------+-------------------------------------------------------------------------------+
|'Regular'             |:math:\mathrm{op} = A                                                        |
+----------------------+-------------------------------------------------------------------------------+
|'Shifted Inverse Real'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+----------------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Regular Inverse'                        |:math:\mathrm{op} = B^{-1}A                                                                                   |
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Real' with real shift   |:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                               |
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Real' with complex shift|:math:\mathrm{op} = \text{Real}\left({\left({A-\sigma B}\right)^{-1}B}\right), where :math:\sigma is complex|
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Imaginary'              |:math:\mathrm{op} = \text{Imag}\left({\left({A-\sigma B}\right)^{-1}B}\right), where :math:\sigma is complex|
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+

**'Regular Inverse'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed by :meth:real_band_solve or when :meth:real_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+----------------------+-------------------------------------------------------------------------------+
|'Regular'             |:math:\mathrm{op} = A                                                        |
+----------------------+-------------------------------------------------------------------------------+
|'Shifted Inverse Real'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+----------------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Regular Inverse'                        |:math:\mathrm{op} = B^{-1}A                                                                                   |
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Real' with real shift   |:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                               |
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Real' with complex shift|:math:\mathrm{op} = \text{Real}\left({\left({A-\sigma B}\right)^{-1}B}\right), where :math:\sigma is complex|
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Imaginary'              |:math:\mathrm{op} = \text{Imag}\left({\left({A-\sigma B}\right)^{-1}B}\right), where :math:\sigma is complex|
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+

**'Shifted Inverse Imaginary'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed by :meth:real_band_solve or when :meth:real_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+----------------------+-------------------------------------------------------------------------------+
|'Regular'             |:math:\mathrm{op} = A                                                        |
+----------------------+-------------------------------------------------------------------------------+
|'Shifted Inverse Real'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+----------------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Regular Inverse'                        |:math:\mathrm{op} = B^{-1}A                                                                                   |
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Real' with real shift   |:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                               |
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Real' with complex shift|:math:\mathrm{op} = \text{Real}\left({\left({A-\sigma B}\right)^{-1}B}\right), where :math:\sigma is complex|
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Imaginary'              |:math:\mathrm{op} = \text{Imag}\left({\left({A-\sigma B}\right)^{-1}B}\right), where :math:\sigma is complex|
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+

**'Shifted Inverse Real'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed by :meth:real_band_solve or when :meth:real_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+----------------------+-------------------------------------------------------------------------------+
|'Regular'             |:math:\mathrm{op} = A                                                        |
+----------------------+-------------------------------------------------------------------------------+
|'Shifted Inverse Real'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+----------------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Regular Inverse'                        |:math:\mathrm{op} = B^{-1}A                                                                                   |
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Real' with real shift   |:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                               |
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Real' with complex shift|:math:\mathrm{op} = \text{Real}\left({\left({A-\sigma B}\right)^{-1}B}\right), where :math:\sigma is complex|
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+
|'Shifted Inverse Imaginary'              |:math:\mathrm{op} = \text{Imag}\left({\left({A-\sigma B}\right)^{-1}B}\right), where :math:\sigma is complex|
+-----------------------------------------+----------------------------------------------------------------------------------------------------------------+

**'Standard'** : valueless
Default

The problem to be solved is either a standard eigenvalue problem, :math:Ax = \lambda x, or a generalized eigenvalue problem, :math:Ax = \lambda Bx.
The option 'Standard' should be used when a standard eigenvalue problem is being solved and the option 'Generalized' should be used when a generalized eigenvalue problem is being solved.

**'Generalized'** : valueless
The problem to be solved is either a standard eigenvalue problem, :math:Ax = \lambda x, or a generalized eigenvalue problem, :math:Ax = \lambda Bx.
The option 'Standard' should be used when a standard eigenvalue problem is being solved and the option 'Generalized' should be used when a generalized eigenvalue problem is being solved.

**'Tolerance'** : float
Default :math:\text{} = \epsilon

An approximate eigenvalue has deemed to have converged when the corresponding Ritz estimate is within 'Tolerance' relative to the magnitude of the eigenvalue.

**'Vectors'** : valueless
Default :math:\text{} = \texttt{'RITZ'}

The function :meth:real_proc or :meth:real_band_solve can optionally compute the Schur vectors and/or the eigenvectors corresponding to the converged eigenvalues.
To turn off computation of any vectors the option :math:\text{‘Vectors'} = \texttt{'NONE'} should be set.
To compute only the Schur vectors (at very little extra cost), the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} should be set and these will be returned in the array argument :math:\textit{v} of :meth:real_proc or :meth:real_band_solve.
To compute the eigenvectors (Ritz vectors) ­corresponding to the eigenvalue estimates, the option :math:\text{‘Vectors'} = \texttt{'RITZ'} should be set and these will be returned in the array argument :math:\textit{z} of :meth:real_proc or :meth:real_band_solve, if :math:\textit{z} is set equal to :math:\textit{v} then the Schur vectors in :math:\textit{v} are overwritten by the eigenvectors computed by :meth:real_proc or :meth:real_band_solve.

**Raises**
**NagValueError**
(errno :math:1)
Ambiguous keyword: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:2)
Keyword not recognized: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:3)
Second keyword not recognized: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:4)
Either the initialization function has not been called prior to the call of this function or a communication array has become corrupted.

**Notes**
real_option may be used to supply values for options to :meth:real_iter and :meth:real_proc, or to :meth:real_band_solve.
It is only necessary to call real_option for those arguments whose values are to be different from their default values.
One call to real_option sets one argument value.

Each option is defined by a single character string consisting of one or more items.
The items associated with a given option must be separated by spaces, or equals signs :math:\left[ = \right].
Alphabetic characters may be upper or lower case.
The string

::

Iteration Limit = 500

is an example of a string used to set an option.
For each option the string contains one or more of the following items:

-   a mandatory keyword;

-   a phrase that qualifies the keyword;

-   a number that specifies an int or float value. Such numbers may be up to :math:16 contiguous characters in Fortran's I, F, E or D format.

real_option does not have an equivalent function from the ARPACK package which passes options by directly setting values to scalar arguments or to specific elements of array arguments. real_option is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in submodule :mod:~naginterfaces.library.opt.

The setup function :meth:real_init or :meth:real_band_init must be called prior to the first call to real_option, and all calls to real_option must precede the first call to :meth:real_iter or :meth:real_band_solve.

A complete list of options, their abbreviations, synonyms and default values is given in :ref:Other Parameters <f12ad-py2-py-other_params>.

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_monit(comm):
r"""
real_monit can be used to return additional monitoring information during computation.
It is in a suite of functions consisting of :meth:real_init, :meth:real_iter, :meth:real_proc, :meth:real_option and real_monit.

.. _f12ae-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12aef.html

.. _f12ae-py2-py-parameters:

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

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

**Returns**
**niter** : int
The number of the current Arnoldi iteration.

**nconv** : int
The number of converged eigenvalues so far.

**ritzr** : float, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{ritzr} contain the real parts of the converged approximate eigenvalues.

**ritzi** : float, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{ritzi} contain the imaginary parts of the converged approximate eigenvalues.

**rzest** : float, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{rzest} contain the Ritz estimates (error bounds) on the converged approximate eigenvalues.

.. _f12ae-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, real and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real and nonsymmetric problems.

On an intermediate exit from :meth:real_iter with :math:{\textit{irevcm}} = 4, real_monit may be called to return monitoring information on the progress of the Arnoldi iterative process.
The information returned by real_monit is:

-   the number of the current Arnoldi iteration;

-   the number of converged eigenvalues at this point;

-   the real and imaginary parts of the converged eigenvalues;

-   the error bounds on the converged eigenvalues.

real_monit does not have an equivalent function from the ARPACK package which prints various levels of detail of monitoring information through an output channel controlled via an argument value (see Lehoucq et al. (1998) for details of ARPACK routines). real_monit should not be called at any time other than immediately following an :math:{\textit{irevcm}} = 4 return from :meth:real_iter.

.. _f12ae-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_band_init(n, nev, ncv):
r"""
real_band_init is a setup function for :meth:real_band_solve which may be used for finding some eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by real, banded, nonsymmetric matrices.
The banded matrix must be stored using the LAPACK column ordered storage format for real banded nonsymmetric matrices (see the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__).

.. _f12af-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12aff.html

.. _f12af-py2-py-parameters:

**Parameters**
**n** : int
The order of the matrix :math:A (and the order of the matrix :math:B for the generalized problem) that defines the eigenvalue problem.

**nev** : int
The number of eigenvalues to be computed.

**ncv** : int
The number of Lanczos basis vectors to use during the computation.

At present there is no a priori analysis to guide the selection of :math:\mathrm{ncv} relative to :math:\mathrm{nev}.

However, it is recommended that :math:\mathrm{ncv}\geq 2\times \mathrm{nev}+1.

If many problems of the same type are to be solved, you should experiment with increasing :math:\mathrm{ncv} while keeping :math:\mathrm{nev} fixed for a given test problem.

This will usually decrease the required number of matrix-vector operations but it also increases the work and storage required to maintain the orthogonal basis vectors.

The optimal 'cross-over' with respect to CPU time is problem dependent and must be determined empirically.

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

.. _f12af-py2-py-errors:

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

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

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

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

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

Constraint: :math:\mathrm{ncv} > \mathrm{nev}+1 and :math:\mathrm{ncv}\leq \mathrm{n}.

.. _f12af-py2-py-notes:

**Notes**
The pair of functions real_band_init and :meth:real_band_solve together with the option setting function :meth:real_option are designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are banded real and nonsymmetric.

real_band_init is a setup function which must be called before the option setting function :meth:real_option and the solver function :meth:real_band_solve.
Internally, :meth:real_band_solve makes calls to :meth:real_iter and :meth:real_proc; the function documents for :meth:real_iter and :meth:real_proc should be consulted for details of the algorithm used.

This setup function initializes the communication arrays, sets (to their default values) all options that can be set by you via the option setting function :meth:real_option, and checks that the lengths of the communication arrays as passed by you are of sufficient length.
For details of the options available and how to set them, see :ref:Other Parameters for real_option <f12ad-py2-py-other_params>.

.. _f12af-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_band_solve(kl, ku, ab, mb, sigmar, sigmai, resid, comm, io_manager=None):
r"""
real_band_solve is the main solver function in a suite of functions consisting of :meth:real_option, :meth:real_band_init and real_band_solve.
It must be called following an initial call to :meth:real_band_init and following any calls to :meth:real_option.

real_band_solve returns approximations to selected eigenvalues, and (optionally) the corresponding eigenvectors, of a standard or generalized eigenvalue problem defined by real banded nonsymmetric matrices.
The banded matrix must be stored using the LAPACK storage format for real banded nonsymmetric matrices.

.. _f12ag-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12agf.html

.. _f12ag-py2-py-parameters:

**Parameters**
**kl** : int
The number of subdiagonals of the matrices :math:A and :math:B.

**ku** : int
The number of superdiagonals of the matrices :math:A and :math:B.

**ab** : float, array-like, shape :math:\left(2\times \mathrm{kl}+\mathrm{ku}+1, \textit{n}\right)
Must contain the matrix :math:A in LAPACK banded storage format for nonsymmetric matrices (see the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__).

**mb** : float, array-like, shape :math:\left(2\times \mathrm{kl}+\mathrm{ku}+1, \textit{n}\right)
Must contain the matrix :math:B in LAPACK banded storage format for nonsymmetric matrices (see the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__).

**sigmar** : float
If one of the 'Shifted Inverse Real' modes (see :meth:real_option) have been selected then :math:\mathrm{sigmar} must contain the real part of the shift used; otherwise :math:\mathrm{sigmar} is not referenced. the F12 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12intro.html#arpack_compmodesnonsymm>__ describes the use of shift and inverse transformations.

**sigmai** : float
If one of the 'Shifted Inverse Real' modes (see :meth:real_option) have been selected then :math:\mathrm{sigmai} must contain the imaginary part of the shift used; otherwise :math:\mathrm{sigmai} is not referenced. the F12 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12intro.html#arpack_compmodesnonsymm>__ describes the use of shift and inverse transformations.

**resid** : float, array-like, shape :math:\left(\textit{n}\right)
Need not be set unless the option 'Initial Residual' has been set in a prior call to :meth:real_option in which case :math:\mathrm{resid} must contain an initial residual vector.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**nconv** : int
The number of converged eigenvalues.

**dr** : float, ndarray, shape :math:\left(\textit{nev}+1\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{dr} contain the real parts of the converged approximate eigenvalues. The number of eigenvalues returned may be one more than the number requested by :math:\textit{nev} since complex values occur as conjugate pairs and the second in the pair can be returned in position :math:{\textit{nev}}+1 of the array.

**di** : float, ndarray, shape :math:\left(\textit{nev}+1\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{di} contain the imaginary parts of the converged approximate eigenvalues. The number of eigenvalues returned may be one more than the number requested by :math:\textit{nev} since complex values occur as conjugate pairs and the second in the pair can be returned in position :math:{\textit{nev}}+1 of the array.

**z** : float, ndarray, shape :math:\left(\textit{n}, :\right)
If the default option :math:\text{‘Vectors'} = \texttt{'RITZ'} has been selected then :math:\mathrm{z} contains the final set of eigenvectors corresponding to the eigenvalues held in :math:\mathrm{dr} and :math:\mathrm{di}. The complex eigenvector associated with the eigenvalue with positive imaginary part is stored in two consecutive columns. The first column holds the real part of the eigenvector and the second column holds the imaginary part. The eigenvector associated with the eigenvalue with negative imaginary part is simply the complex conjugate of the eigenvector associated with the positive imaginary part.

**resid** : float, ndarray, shape :math:\left(\textit{n}\right)
Contains the final residual vector.

**v** : float, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right)
If the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} or :math:\texttt{'RITZ'} (see :meth:real_option) then the first :math:\mathrm{nconv}\times n elements of :math:\mathrm{v} will contain approximate Schur vectors that span the desired invariant subspace.

The :math:i\ th Schur vector is stored in the :math:i\ th column of :math:\mathrm{v}.

.. _f12ag-py2-py-errors:

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

Constraint: :math:\mathrm{kl}\geq 0.

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

Constraint: :math:\mathrm{ku}\geq 0.

(errno :math:3)
On entry, :math:\textit{ldab} = \langle\mathit{\boldsymbol{value}}\rangle, :math:2\times \mathrm{kl}+\mathrm{ku}+1 = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldab}\geq 2\times \mathrm{kl}+\mathrm{ku}+1.

(errno :math:4)
The option 'Shifted Inverse Imaginary' has been selected and :math:\mathrm{sigmai} = \text{} zero on entry; :math:\mathrm{sigmai} must be nonzero for this mode of operation.

(errno :math:5)
The maximum number of iterations :math:\text{}\leq 0, the option 'Iteration Limit' has been set to :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:6)
The options 'Generalized' and 'Regular' are incompatible.

(errno :math:7)
The option 'Initial Residual' was selected but the starting vector held in :math:\mathrm{resid} is zero.

(errno :math:8)
Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.

(errno :math:10)
On entry, :math:\text{‘Vectors'} = \text{Select}, but this is not yet implemented.

(errno :math:11)
The number of eigenvalues found to sufficient accuracy is zero.

(errno :math:12)
Could not build an Arnoldi factorization. The size of the current Arnoldi factorization :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:13)
Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:14)
During calculation of a real Schur form, there was a failure to compute a number of eigenvalues. Please contact NAG <https://www.nag.com>__.

(errno :math:15)
The computed Schur form could not be reordered by an internal call. Please contact NAG <https://www.nag.com>__.

(errno :math:16)
Error in internal call to compute eigenvectors. Please contact NAG <https://www.nag.com>__.

(errno :math:17)
Failure during internal factorization of real banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:18)
Failure during internal solution of real banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:19)
Failure during internal factorization of complex banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:20)
Failure during internal solution of complex banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:21)
The maximum number of iterations has been reached. The maximum number of :math:\text{iterations} = \langle\mathit{\boldsymbol{value}}\rangle. The number of converged eigenvalues :math:\text{} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:22)
No shifts could be applied during a cycle of the implicitly restarted Lanczos iteration.

(errno :math:23)
Overflow occurred during transformation of Ritz values to those of the original problem.

.. _f12ag-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are banded, real and nonsymmetric.

Following a call to the initialization function :meth:real_band_init, real_band_solve returns the converged approximations to eigenvalues and (optionally) the corresponding approximate eigenvectors and/or an orthonormal basis for the associated approximate invariant subspace.
The eigenvalues (and eigenvectors) are selected from those of a standard or generalized eigenvalue problem defined by real banded nonsymmetric matrices.
There is negligible additional computational cost to obtain eigenvectors; an orthonormal basis is always computed, but there is an additional storage cost if both are requested.

The banded matrices :math:A and :math:B must be stored using the LAPACK column ordered storage format for banded nonsymmetric matrices; please refer to the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_32>__ for details on this storage format.

real_band_solve is based on the banded driver functions **dnbdr1** to **dnbdr6** from the ARPACK package, which uses the Implicitly Restarted Arnoldi iteration method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices is provided in Lehoucq and Scott (1996).
This suite of functions offers the same functionality as the ARPACK banded driver software for real nonsymmetric problems, but the interface design is quite different in order to make the option setting clearer and to combine the different drivers into a general purpose function.

real_band_solve, is a general purpose function that must be called following initialization by :meth:real_band_init. real_band_solve uses options, set either by default or explicitly by calling :meth:real_option, to return the converged approximations to selected eigenvalues and (optionally):

-   the corresponding approximate eigenvectors;

-   an orthonormal basis for the associated approximate invariant subspace;

-   both.

Please note that for 'Generalized' problems, the 'Shifted Inverse Imaginary', 'Shifted Inverse Real' inverse modes are only appropriate if either :math:A or :math:B is symmetric semidefinite.
Otherwise, if :math:A or :math:B is non-singular, the 'Standard' problem can be solved using the matrix :math:B^{-1}A (say).

.. _f12ag-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def complex_init(n, nev, ncv):
r"""
complex_init is a setup function in a suite of functions consisting of complex_init, :meth:complex_iter, :meth:complex_proc, :meth:complex_option and :meth:complex_monit.
It is used to find some of the eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by complex nonsymmetric matrices.

The suite of functions is suitable for the solution of large sparse, standard or generalized, nonsymmetric complex eigenproblems where only a few eigenvalues from a selected range of the spectrum are required.

.. _f12an-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12anf.html

.. _f12an-py2-py-parameters:

**Parameters**
**n** : int
The order of the matrix :math:A (and the order of the matrix :math:B for the generalized problem) that defines the eigenvalue problem.

**nev** : int
The number of eigenvalues to be computed.

**ncv** : int
The number of Arnoldi basis vectors to use during the computation.

At present there is no a priori analysis to guide the selection of :math:\mathrm{ncv} relative to :math:\mathrm{nev}.

However, it is recommended that :math:\mathrm{ncv}\geq 2\times \mathrm{nev}+1.

If many problems of the same type are to be solved, you should experiment with increasing :math:\mathrm{ncv} while keeping :math:\mathrm{nev} fixed for a given test problem.

This will usually decrease the required number of matrix-vector operations but it also increases the work and storage required to maintain the orthogonal basis vectors.

The optimal 'cross-over' with respect to CPU time is problem dependent and must be determined empirically.

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

.. _f12an-py2-py-errors:

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

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

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

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

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

Constraint: :math:\mathrm{ncv}\geq \mathrm{nev}+1 and :math:\mathrm{ncv}\leq \mathrm{n}.

.. _f12an-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard complex eigenvalue problem :math:Ax = \lambda x, or of a generalized complex eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, complex and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, complex and nonsymmetric problems.

complex_init is a setup function which must be called before :meth:complex_iter, the reverse communication iterative solver, and before :meth:complex_option, the options setting function. :meth:complex_proc is a post-processing function that must be called following a successful final exit from :meth:complex_iter, while :meth:complex_monit can be used to return additional monitoring information during the computation.

This setup function initializes the communication arrays, sets (to their default values) all options that can be set by you via the option setting function :meth:complex_option, and checks that the lengths of the communication arrays as passed by you are of sufficient length.
For details of the options available and how to set them see :ref:Other Parameters for complex_option <f12ar-py2-py-other_params>.

.. _f12an-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def complex_iter(irevcm, resid, v, x, mx, comm, io_manager=None):
r"""
complex_iter is an iterative solver in a suite of functions consisting of :meth:complex_init, complex_iter, :meth:complex_proc, :meth:complex_option and :meth:complex_monit.
It is used to find some of the eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by complex nonsymmetric matrices.

.. _f12ap-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12apf.html

.. _f12ap-py2-py-parameters:

**Parameters**
**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

**resid** : complex, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: need not be set unless the option 'Initial Residual' has been set in a prior call to :meth:complex_option in which case :math:\mathrm{resid} should contain an initial residual vector, possibly from a previous run.

On intermediate entry: must be unchanged from its previous exit. Changing :math:\mathrm{resid} to any other value between calls may result in an error exit.

On intermediate exit: contains the current residual vector.

On final exit: contains the final residual vector.

**v** : complex, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right), modified in place
On initial entry: need not be set.

On intermediate entry: must be unchanged from its previous exit.

On intermediate exit: contains the current set of Arnoldi basis vectors.

On final exit: contains the final set of Arnoldi basis vectors.

**x** : complex, ndarray, shape :math:\left(:\right), modified in place
Note: the required length for this argument is determined as follows: if :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{Re}\left(\mathrm{comm}\ ['comm'][0]\right)\right)+24\right) - 1 }]=0: :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{Re}\left(\mathrm{comm}\ ['comm'][0]\right)\right)+1\right) - 1 }]; otherwise: :math:1.

On initial entry: need not be set, it is used as a convenient mechanism for accessing elements of :math:\mathrm{comm}\ ['comm'].

On intermediate entry: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{x} need not be set.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{x} must contain the result of :math:y = \mathrm{op}\left(x\right) when :math:\mathrm{irevcm} returns the value :math:-1 or :math:+1.

It must return the computed shifts when :math:\mathrm{irevcm} returns the value :math:3.

On intermediate exit: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{x} is not referenced.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{x} contains the vector :math:x when :math:\mathrm{irevcm} returns the value :math:-1 or :math:+1.

On final exit: does not contain useful data.

**mx** : complex, ndarray, shape :math:\left(:\right), modified in place
Note: the required length for this argument is determined as follows: if :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{Re}\left(\mathrm{comm}\ ['comm'][0]\right)\right)+24\right) - 1 }]=0: :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{Re}\left(\mathrm{comm}\ ['comm'][0]\right)\right)+1\right) - 1 }]; otherwise: :math:1.

On initial entry: need not be set, it is used as a convenient mechanism for accessing elements of :math:\mathrm{comm}\ ['comm'].

On intermediate entry: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{mx} need not be set.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{mx} must contain the result of :math:y = Bx when :math:\mathrm{irevcm} returns the value :math:2.

On intermediate exit: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{mx} is not referenced.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{mx} contains the vector :math:Bx when :math:\mathrm{irevcm} returns the value :math:+1.

On final exit: does not contain any useful data.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = -1

The calling program must compute the matrix-vector product :math:y = \mathrm{op}\left(x\right), where :math:x is stored in :math:\mathrm{x} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the first element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set in a prior call to :meth:complex_option. The result :math:y is returned in :math:\mathrm{x} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the second element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set.

:math:\mathrm{irevcm} = 1

The calling program must compute the matrix-vector product :math:y = \mathrm{op}\left(x\right). This is similar to the case :math:\mathrm{irevcm} = -1 except that the result of the matrix-vector product :math:Bx (as required in some computational modes) has already been computed and is available in :math:\mathrm{mx} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the third element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set.

:math:\mathrm{irevcm} = 2

The calling program must compute the matrix-vector product :math:y = Bx, where :math:x is stored in :math:\mathrm{x} and :math:y is returned in :math:\mathrm{mx} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the second element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set.

:math:\mathrm{irevcm} = 3

Compute the :math:\mathrm{nshift} complex shifts. This value of :math:\mathrm{irevcm} will only arise if the option 'Supplied Shifts' is set in a prior call to :meth:complex_option which is intended for experienced users only; the default and recommended option is to use exact shifts (see Lehoucq et al. (1998) for details).

:math:\mathrm{irevcm} = 4

Monitoring step: a call to :meth:complex_monit can now be made to return the number of Arnoldi iterations, the number of converged Ritz values, the array of converged values, and the corresponding Ritz estimates.

On final exit: :math:\mathrm{irevcm} = 5: complex_iter has completed its tasks. The value of :math:\textit{errno} determines whether the iteration has been successfully completed, or whether errors have been detected. On successful completion :meth:complex_proc must be called to return the requested eigenvalues and eigenvectors (and/or Schur vectors).

**nshift** : int
On intermediate exit: if the option 'Supplied Shifts' is set and :math:\mathrm{irevcm} returns a value of :math:3, :math:\mathrm{nshift} returns the number of complex shifts required.

.. _f12ap-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
The maximum number of iterations :math:\leq 0, the option 'Iteration Limit' has been set to :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
The options 'Generalized' and 'Regular' are incompatible.

(errno :math:5)
No shifts could be applied during a cycle of the implicitly restarted Arnoldi iteration.

(errno :math:6)
Could not build an Arnoldi factorization. The size of the current Arnoldi factorization :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:7)
Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:8)
Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.

**Warns**
**NagAlgorithmicWarning**
(errno :math:3)
The option 'Initial Residual' was selected but the starting vector held in :math:\mathrm{resid} is zero.

(errno :math:4)
The maximum number of iterations has been reached. The maximum number of :math:\text{iterations} = \langle\mathit{\boldsymbol{value}}\rangle. The number of converged eigenvalues :math:= \langle\mathit{\boldsymbol{value}}\rangle. See the function document for further details.

.. _f12ap-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, complex and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, complex and nonsymmetric problems.

complex_iter is a **reverse communication** function, based on the ARPACK routine **znaupd**, using the Implicitly Restarted Arnoldi iteration method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices is provided in Lehoucq and Scott (1996).
This suite of functions offers the same functionality as the ARPACK software for complex nonsymmetric problems, but the interface design is quite different in order to make the option setting clearer and to simplify the interface of complex_iter.

The setup function :meth:complex_init must be called before complex_iter, the reverse communication iterative solver.
Options may be set for complex_iter by prior calls to the option setting function :meth:complex_option and a post-processing function :meth:complex_proc must be called following a successful final exit from complex_iter. :meth:complex_monit may be called following certain flagged, intermediate exits from complex_iter to provide additional monitoring information about the computation.

complex_iter uses **reverse communication**, i.e., it returns repeatedly to the calling program with the argument :math:\mathrm{irevcm} (see :ref:Parameters <f12ap-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:y = \mathrm{op}\left(x\right), where :math:\mathrm{op} is defined by the computational mode;

-   compute the matrix-vector product :math:y = Bx;

-   notify the completion of the computation;

-   allow the calling program to monitor the solution.

The problem type to be solved (standard or generalized), the spectrum of eigenvalues of interest, the mode used (regular, regular inverse, shifted inverse, shifted real or shifted imaginary) and other options can all be set using the option setting function :meth:complex_option (see :ref:Other Parameters for complex_option <f12ar-py2-py-other_params> for details on setting options and of the default settings).

.. _f12ap-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def complex_proc(sigma, resid, v, comm, io_manager=None):
r"""
complex_proc is a post-processing function in a suite of functions consisting of :meth:complex_init, :meth:complex_iter, complex_proc, :meth:complex_option and :meth:complex_monit.
It must be called following a final exit from :meth:complex_iter.

.. _f12aq-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12aqf.html

.. _f12aq-py2-py-parameters:

**Parameters**
**sigma** : complex
If one of the 'Shifted Inverse' (see :meth:complex_option) modes has been selected then :math:\mathrm{sigma} contains the shift used; otherwise :math:\mathrm{sigma} is not referenced.

**resid** : complex, array-like, shape :math:\left(\textit{n}\right)
Must not be modified following a call to :meth:complex_iter since it contains data required by complex_proc.

**v** : complex, array-like, shape :math:\left(\textit{n}, \textit{ncv}\right)
The :math:\textit{ncv} columns of :math:\mathrm{v} contain the Arnoldi basis vectors for :math:\mathrm{op} as constructed by :meth:complex_iter.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**nconv** : int
The number of converged eigenvalues as found by :meth:complex_option.

**d** : complex, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{d} contain the converged approximate eigenvalues.

**z** : complex, ndarray, shape :math:\left(\textit{n}, :\right)
If the default option :math:\text{‘Vectors'} = \texttt{'RITZ'} (see :meth:real_option) has been selected then :math:\mathrm{z} contains the final set of eigenvectors corresponding to the eigenvalues held in :math:\mathrm{d}. The complex eigenvector associated with an eigenvalue is stored in the corresponding of :math:\mathrm{z}.

**v** : complex, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right)
If the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} or :math:\texttt{'RITZ'} has been set and a separate array :math:\mathrm{z} has been passed (i.e., :math:\mathrm{z} does not equal :math:\mathrm{v}), then the first :math:\mathrm{nconv} columns of :math:\mathrm{v} will contain approximate Schur vectors that span the desired invariant subspace.

.. _f12aq-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:2)
On entry, :math:\text{‘Vectors'} = \text{Select}, but this is not yet implemented.

(errno :math:3)
The number of eigenvalues found to sufficient accuracy, as communicated through the argument :math:\mathrm{comm}\ ['icomm'], is zero.

(errno :math:4)
Got a different count of the number of converged Ritz values than the value passed to it through the argument :math:\mathrm{comm}\ ['icomm']: number counted :math:= \langle\mathit{\boldsymbol{value}}\rangle, number expected :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:5)
During calculation of a Schur form, there was a failure to compute :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvalues in a total of :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:6)
The computed Schur form could not be reordered by an internal call. This function returned with :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle. Please contact NAG <https://www.nag.com>__.

(errno :math:7)
In calculating eigenvectors, an internal call returned with an error. The function returned with :math:\textit{errno} = \langle\mathit{\boldsymbol{value}}\rangle. Please contact NAG <https://www.nag.com>__.

.. _f12aq-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, complex and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, complex and nonsymmetric problems.

Following a call to :meth:complex_iter, complex_proc returns the converged approximations to eigenvalues and (optionally) the corresponding approximate eigenvectors and/or an orthonormal basis for the associated approximate invariant subspace.
The eigenvalues (and eigenvectors) are selected from those of a standard or generalized eigenvalue problem defined by complex nonsymmetric matrices.
There is negligible additional cost to obtain eigenvectors; an orthonormal basis is always computed, but there is an additional storage cost if both are requested.

complex_proc is based on the function **zneupd** from the ARPACK package, which uses the Implicitly Restarted Arnoldi iteration method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices is provided in Lehoucq and Scott (1996).
This suite of functions offers the same functionality as the ARPACK software for complex nonsymmetric problems, but the interface design is quite different in order to make the option setting clearer and to simplify some of the interfaces.

complex_proc is a post-processing function that must be called following a successful final exit from :meth:complex_iter. complex_proc uses data returned from :meth:complex_iter and options, set either by default or explicitly by calling :meth:complex_option, to return the converged approximations to selected eigenvalues and (optionally):

-   the corresponding approximate eigenvectors;

-   an orthonormal basis for the associated approximate invariant subspace;

-   both.

.. _f12aq-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def complex_option(optstr, comm, io_manager=None):
r"""
complex_option is an option setting function in a suite of functions consisting of :meth:complex_init, :meth:complex_iter, :meth:complex_proc, complex_option and :meth:complex_monit; it supplies individual options to :meth:complex_iter and :meth:complex_proc. complex_option is also an option setting function in a suite of functions consisting of complex_option, :meth:complex_band_init and :meth:complex_band_solve; it supplies individual options to :meth:complex_band_solve.

The initialization function for the appropriate suite, :meth:complex_init or :meth:complex_band_init, **must** have been called prior to calling complex_option.

Note: this function uses optional algorithmic parameters, see also: :meth:complex_iter, :meth:complex_proc, :meth:complex_band_solve, :meth:complex_init, :meth:complex_band_init.

.. _f12ar-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12arf.html

.. _f12ar-py2-py-parameters:

**Parameters**
**optstr** : str
A single valid option string (as described in :ref:Notes <f12ar-py2-py-notes> and :ref:Other Parameters <f12ar-py2-py-other_params>).

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

This argument must have been initialized by a prior call to :meth:complex_init or :meth:complex_band_init.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

.. _f12ar-py2-py-other_params:

**Other Parameters**
Default :math:= \text{advisory message unit number}

**'Defaults'** : valueless
This special keyword may be used to reset all options to their default values.

**'Exact Shifts'** : valueless
Default

During the Arnoldi iterative process, shifts are applied as part of the implicit restarting scheme.
The shift strategy used by default and selected by the option 'Exact Shifts' is strongly recommended over the alternative 'Supplied Shifts' and will always be used by :meth:complex_band_solve.

If 'Exact Shifts' are used then these are computed internally by the algorithm in the implicit restarting scheme.
This strategy is generally effective and cheaper to apply in terms of number of operations than using explicit shifts.

If 'Supplied Shifts' are used then, during the Arnoldi iterative process, you must supply shifts through array arguments of :meth:complex_iter when :meth:complex_iter returns with :math:{\textit{irevcm}} = 3; the complex shifts are returned in :math:\textit{x} (or in :math:\textit{comm} when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set). This option should only be used if you are an experienced user since this requires some algorithmic knowledge and because more operations are usually required than for the implicit shift scheme.
Details on the use of explicit shifts and further references on shift strategies are available in Lehoucq et al. (1998).

**'Supplied Shifts'** : valueless
During the Arnoldi iterative process, shifts are applied as part of the implicit restarting scheme.
The shift strategy used by default and selected by the option 'Exact Shifts' is strongly recommended over the alternative 'Supplied Shifts' and will always be used by :meth:complex_band_solve.

If 'Exact Shifts' are used then these are computed internally by the algorithm in the implicit restarting scheme.
This strategy is generally effective and cheaper to apply in terms of number of operations than using explicit shifts.

If 'Supplied Shifts' are used then, during the Arnoldi iterative process, you must supply shifts through array arguments of :meth:complex_iter when :meth:complex_iter returns with :math:{\textit{irevcm}} = 3; the complex shifts are returned in :math:\textit{x} (or in :math:\textit{comm} when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set). This option should only be used if you are an experienced user since this requires some algorithmic knowledge and because more operations are usually required than for the implicit shift scheme.
Details on the use of explicit shifts and further references on shift strategies are available in Lehoucq et al. (1998).

**'Iteration Limit'** : int
Default :math:\text{} = 300

The limit on the number of Arnoldi iterations that can be performed before :meth:complex_iter or :meth:complex_band_solve exits.
If not all requested eigenvalues have converged to within 'Tolerance' and the number of Arnoldi iterations has reached this limit then :meth:complex_iter or :meth:complex_band_solve exits with an error; :meth:complex_band_solve returns the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors, while :meth:complex_proc can be called subsequent to :meth:complex_iter to do the same.

**'Largest Magnitude'** : valueless
Default

The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:complex_iter or :meth:complex_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Largest Imaginary'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:complex_iter or :meth:complex_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Largest Real'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:complex_iter or :meth:complex_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Smallest Imaginary'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:complex_iter or :meth:complex_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Smallest Magnitude'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:complex_iter or :meth:complex_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Smallest Real'** : valueless
The Arnoldi iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:complex_iter or :meth:complex_band_solve to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Real' part, 'Largest Imaginary' part, 'Smallest Magnitude', 'Smallest Real' part or 'Smallest Imaginary' part.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Nolist'** : valueless
Default

Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.

**'List'** : valueless
Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.

**'Monitoring'** : int
Default :math:\text{} = -1

If :math:i > 0, monitoring information is output to unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj) :math:i during the solution of each problem; this may be the same as the 'Advisory' unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj).
The type of information produced is dependent on the value of 'Print Level', see the description of the option 'Print Level' for details of the information produced.
Please see the FileObjManager method :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj to associate a file with a given unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj).

**'Pointers'** : valueless
Default :math:\text{} = \texttt{'NO'}

During the iterative process and reverse communication calls to :meth:complex_iter, required data can be communicated to and from :meth:complex_iter in one of two ways.
When :math:\text{‘Pointers'} = \texttt{'NO'} is selected (the default) then the array arguments :math:\textit{x} and :math:\textit{mx} are used to supply you with required data and used to return computed values back to :meth:complex_iter.
For example, when :math:{\textit{irevcm}} = 1, :meth:complex_iter returns the vector :math:x in :math:\textit{x} and the matrix-vector product :math:Bx in :math:\textit{mx} and expects the result or the linear operation :math:\mathrm{op}\left(x\right) to be returned in :math:\textit{x}.

If :math:\text{‘Pointers'} = \texttt{'YES'} is selected then the data is passed through sections of the array argument :math:\textit{comm}.
The section corresponding to :math:\textit{x} when :math:\text{‘Pointers'} = \texttt{'NO'} begins at a location given by the first element of :math:\textit{icomm}; similarly the section corresponding to :math:\textit{mx} begins at a location given by the second element of :math:\textit{icomm}.
This option allows :meth:complex_iter to perform fewer copy operations on each intermediate exit and entry, but can also lead to less elegant code in the calling program.

This option has no affect on :meth:complex_band_solve which sets :math:\text{‘Pointers'} = \texttt{'YES'} internally.

**'Print Level'** : int
Default :math:\text{} = 0

This controls the amount of printing produced by complex_option as follows.

.. rst-class:: nag-rules-none nag-align-left

+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:i      |Output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+===============+==============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:= 0    |No output except error messages.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:> 0    |The set of selected options.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:= 2    |Problem and timing statistics on final exit from :meth:complex_iter or :meth:complex_band_solve.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 5 |A single line of summary output at each Arnoldi iteration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 10|If :math:\text{‘Monitoring'} > 0, then at each iteration, the length and additional steps of the current Arnoldi factorization and the number of converged Ritz values; during re-orthogonalization, the norm of initial/restarted starting vector.                                                                                                                                                                                                                                                                                                                         |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 20|Problem and timing statistics on final exit from :meth:complex_iter. If :math:\text{‘Monitoring'} > 0, then at each iteration, the number of shifts being applied, the eigenvalues and estimates of the Hessenberg matrix :math:H, the size of the Arnoldi basis, the wanted Ritz values and associated Ritz estimates and the shifts applied; vector norms prior to and following re-orthogonalization.                                                                                                                                                                |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 30|If :math:\text{‘Monitoring'} > 0, then on final iteration, the norm of the residual; when computing the Schur form, the eigenvalues and Ritz estimates both before and after sorting; for each iteration, the norm of residual for compressed factorization and the compressed upper Hessenberg matrix :math:H; during re-orthogonalization, the initial/restarted starting vector; during the Arnoldi iteration loop, a restart is flagged and the number of the residual requiring iterative refinement; while applying shifts, the indices of the shifts being applied.|
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 40|If :math:\text{‘Monitoring'} > 0, then during the Arnoldi iteration loop, the Arnoldi vector number and norm of the current residual; while applying shifts, key measures of progress and the order of :math:H; while computing eigenvalues of :math:H, the last rows of the Schur and eigenvector matrices; when computing implicit shifts, the eigenvalues and Ritz estimates of :math:H.                                                                                                                                                                           |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 50|If :math:\text{‘Monitoring'} > 0, then during Arnoldi iteration loop: norms of key components and the active column of :math:H, norms of residuals during iterative refinement, the final upper Hessenberg matrix :math:H; while applying shifts: number of shifts, shift values, block indices, updated matrix :math:H; while computing eigenvalues of :math:H: the matrix :math:H, the computed eigenvalues and Ritz estimates.                                                                                                                                 |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

**'Random Residual'** : valueless
Default

To begin the Arnoldi iterative process, :meth:complex_iter or :meth:complex_band_solve requires an initial residual vector.
By default :meth:complex_iter or :meth:complex_band_solve provides its own random initial residual vector; this option can also be set using option 'Random Residual'.
Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to :meth:complex_iter or :meth:complex_band_solve through the array argument :math:\textit{resid}; this option can be set using option 'Initial Residual'.

**'Initial Residual'** : valueless
To begin the Arnoldi iterative process, :meth:complex_iter or :meth:complex_band_solve requires an initial residual vector.
By default :meth:complex_iter or :meth:complex_band_solve provides its own random initial residual vector; this option can also be set using option 'Random Residual'.
Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to :meth:complex_iter or :meth:complex_band_solve through the array argument :math:\textit{resid}; this option can be set using option 'Initial Residual'.

**'Regular'** : valueless
Default

These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed by :meth:complex_band_solve or when :meth:complex_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:complex_iter returns with :math:{\textit{irevcm}} = -2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+--------------------------------------------------+
|'Regular'        |:math:\mathrm{op} = A                           |
+-----------------+--------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1}|
+-----------------+--------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+---------------------------------------------------+
|'Regular Inverse'|:math:\mathrm{op} = B^{-1}A                      |
+-----------------+---------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B|
+-----------------+---------------------------------------------------+

**'Regular Inverse'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed by :meth:complex_band_solve or when :meth:complex_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:complex_iter returns with :math:{\textit{irevcm}} = -2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+--------------------------------------------------+
|'Regular'        |:math:\mathrm{op} = A                           |
+-----------------+--------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1}|
+-----------------+--------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+---------------------------------------------------+
|'Regular Inverse'|:math:\mathrm{op} = B^{-1}A                      |
+-----------------+---------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B|
+-----------------+---------------------------------------------------+

**'Shifted Inverse'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed by :meth:complex_band_solve or when :meth:complex_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:complex_iter returns with :math:{\textit{irevcm}} = -2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+--------------------------------------------------+
|'Regular'        |:math:\mathrm{op} = A                           |
+-----------------+--------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1}|
+-----------------+--------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+---------------------------------------------------+
|'Regular Inverse'|:math:\mathrm{op} = B^{-1}A                      |
+-----------------+---------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B|
+-----------------+---------------------------------------------------+

**'Standard'** : valueless
Default

The problem to be solved is either a standard eigenvalue problem, :math:Ax = \lambda x, or a generalized eigenvalue problem, :math:Ax = \lambda Bx.
The option 'Standard' should be used when a standard eigenvalue problem is being solved and the option 'Generalized' should be used when a generalized eigenvalue problem is being solved.

**'Generalized'** : valueless
The problem to be solved is either a standard eigenvalue problem, :math:Ax = \lambda x, or a generalized eigenvalue problem, :math:Ax = \lambda Bx.
The option 'Standard' should be used when a standard eigenvalue problem is being solved and the option 'Generalized' should be used when a generalized eigenvalue problem is being solved.

**'Tolerance'** : float
Default :math:\text{} = \epsilon

An approximate eigenvalue has deemed to have converged when the corresponding Ritz estimate is within 'Tolerance' relative to the magnitude of the eigenvalue.

**'Vectors'** : valueless
Default :math:\text{} = \texttt{'RITZ'}

The function :meth:complex_proc or :meth:complex_band_solve can optionally compute the Schur vectors and/or the eigenvectors corresponding to the converged eigenvalues.
To turn off computation of any vectors the option :math:\text{‘Vectors'} = \texttt{'NONE'} should be set.
To compute only the Schur vectors (at very little extra cost), the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} should be set and these will be returned in the array argument :math:\textit{v} of :meth:complex_proc or :meth:complex_band_solve.
To compute the eigenvectors (Ritz vectors) ­corresponding to the eigenvalue estimates, the option :math:\text{‘Vectors'} = \texttt{'RITZ'} should be set and these will be returned in the array argument :math:\textit{z} of :meth:complex_proc or :meth:complex_band_solve, if :math:\textit{z} is set equal to :math:\textit{v} then the Schur vectors in :math:\textit{v} are overwritten by the eigenvectors computed by :meth:complex_proc or :meth:complex_band_solve.

.. _f12ar-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Ambiguous keyword: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:2)
Keyword not recognized: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:3)
Second keyword not recognized: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:4)
Either the initialization function has not been called prior to the call of this function or a communication array has become corrupted.

.. _f12ar-py2-py-notes:

**Notes**
complex_option may be used to supply values for options to :meth:complex_iter and :meth:complex_proc, or to :meth:complex_band_solve.
It is only necessary to call complex_option for those arguments whose values are to be different from their default values.
One call to complex_option sets one argument value.

Each option is defined by a single character string consisting of one or more items.
The items associated with a given option must be separated by spaces, or equals signs :math:\left[ = \right].
Alphabetic characters may be upper or lower case.
The string

::

Iteration Limit = 500

is an example of a string used to set an option.
For each option the string contains one or more of the following items:

-   a mandatory keyword;

-   a phrase that qualifies the keyword;

-   a number that specifies an int or float value. Such numbers may be up to :math:16 contiguous characters in Fortran's I, F, E or D format.

complex_option does not have an equivalent function from the ARPACK package which passes options by directly setting values to scalar arguments or to specific elements of array arguments. complex_option is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in submodule :mod:~naginterfaces.library.opt (see :meth:opt.qpconvex2_sparse_option_string <naginterfaces.library.opt.qpconvex2_sparse_option_string> for an example).

The setup function :meth:complex_init or :meth:complex_band_init must be called prior to the first call to complex_option, and all calls to complex_option must precede the first call to :meth:complex_iter and :meth:complex_band_solve.

A complete list of options, their abbreviations, synonyms and default values is given in :ref:Other Parameters <f12ar-py2-py-other_params>.

.. _f12ar-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def complex_monit(comm):
r"""
complex_monit can be used to return additional monitoring information during computation.
It is in a suite of functions consisting of :meth:complex_init, :meth:complex_iter, :meth:complex_proc, :meth:complex_option and complex_monit.

.. _f12as-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12asf.html

.. _f12as-py2-py-parameters:

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

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

**Returns**
**niter** : int
The number of the current Arnoldi iteration.

**nconv** : int
The number of converged eigenvalues so far.

**ritz** : complex, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{ritz} contain the converged approximate eigenvalues.

**rzest** : complex, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{rzest} contain the complex Ritz estimates on the converged approximate eigenvalues.

.. _f12as-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard complex eigenvalue problem :math:Ax = \lambda x, or of a generalized complex eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse and complex.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense complex problems.

On an intermediate exit from :meth:complex_iter with :math:{\textit{irevcm}} = 4, complex_monit may be called to return monitoring information on the progress of the Arnoldi iterative process.
The information returned by complex_monit is:

-   the number of the current Arnoldi iteration;

-   the number of converged eigenvalues at this point;

-   the converged eigenvalues;

-   the error bounds on the converged eigenvalues.

complex_monit does not have an equivalent function from the ARPACK package which prints various levels of detail of monitoring information through an output channel controlled via an argument value (see Lehoucq et al. (1998) for details of ARPACK routines). complex_monit should not be called at any time other than immediately following an :math:{\textit{irevcm}} = 4 return from :meth:complex_iter.

.. _f12as-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def complex_band_init(n, nev, ncv):
r"""
complex_band_init is a setup function for :meth:complex_band_solve which may be used for finding some eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by complex, banded, non-Hermitian matrices.
The banded matrix must be stored using the LAPACK column ordered storage format for complex banded non-Hermitian matrices (see the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__).

.. _f12at-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12atf.html

.. _f12at-py2-py-parameters:

**Parameters**
**n** : int
The order of the matrix :math:A (and the order of the matrix :math:B for the generalized problem) that defines the eigenvalue problem.

**nev** : int
The number of eigenvalues to be computed.

**ncv** : int
The number of Lanczos basis vectors to use during the computation.

At present there is no a priori analysis to guide the selection of :math:\mathrm{ncv} relative to :math:\mathrm{nev}.

However, it is recommended that :math:\mathrm{ncv}\geq 2\times \mathrm{nev}+1.

If many problems of the same type are to be solved, you should experiment with increasing :math:\mathrm{ncv} while keeping :math:\mathrm{nev} fixed for a given test problem.

This will usually decrease the required number of matrix-vector operations but it also increases the work and storage required to maintain the orthogonal basis vectors.

The optimal 'cross-over' with respect to CPU time is problem dependent and must be determined empirically.

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

.. _f12at-py2-py-errors:

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

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

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

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

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

Constraint: :math:\mathrm{ncv} > \mathrm{nev}+1 and :math:\mathrm{ncv}\leq \mathrm{n}.

.. _f12at-py2-py-notes:

**Notes**
The pair of functions complex_band_init and :meth:complex_band_solve together with the option setting function :meth:complex_option are designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are banded complex and non-Hermitian.

complex_band_init is a setup function which must be called before the option setting function :meth:complex_option and the solver function :meth:complex_band_solve.
Internally, :meth:complex_band_solve makes calls to :meth:complex_iter and :meth:complex_proc; the function documents for :meth:complex_iter and :meth:complex_proc should be consulted for details of the algorithm used.

This setup function initializes the communication arrays, sets (to their default values) all options that can be set by you via the option setting function :meth:complex_option, and checks that the lengths of the communication arrays as passed by you are of sufficient length.
For details of the options available and how to set them, see :ref:Other Parameters for complex_option <f12ar-py2-py-other_params>.

.. _f12at-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def complex_band_solve(kl, ku, ab, mb, sigma, resid, comm, io_manager=None):
r"""
complex_band_solve is the main solver function in a suite of functions consisting of :meth:complex_option, :meth:complex_band_init and complex_band_solve.
It must be called following an initial call to :meth:complex_band_init and following any calls to :meth:complex_option.

complex_band_solve returns approximations to selected eigenvalues, and (optionally) the corresponding eigenvectors, of a standard or generalized eigenvalue problem defined by complex banded non-Hermitian matrices.
The banded matrix must be stored using the LAPACK storage format for complex banded non-Hermitian matrices.

.. _f12au-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12auf.html

.. _f12au-py2-py-parameters:

**Parameters**
**kl** : int
The number of subdiagonals of the matrices :math:A and :math:B.

**ku** : int
The number of superdiagonals of the matrices :math:A and :math:B.

**ab** : complex, array-like, shape :math:\left(2\times \mathrm{kl}+\mathrm{ku}+1, \textit{n}\right)
Must contain the matrix :math:A in LAPACK banded storage format for non-Hermitian matrices (see the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__).

**mb** : complex, array-like, shape :math:\left(2\times \mathrm{kl}+\mathrm{ku}+1, \textit{n}\right)
Must contain the matrix :math:B in LAPACK banded storage format for non-Hermitian matrices (see the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__).

**sigma** : complex
If the 'Shifted Inverse' mode (see :meth:complex_option) has been selected then :math:\mathrm{sigma} must contain the shift used; otherwise :math:\mathrm{sigma} is not referenced. the F12 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12intro.html#arpack_spectraltrans>__ describes the use of shift and invert transformations.

**resid** : complex, array-like, shape :math:\left(\textit{n}\right)
Need not be set unless the option 'Initial Residual' has been set in a prior call to :meth:complex_option in which case :math:\mathrm{resid} must contain an initial residual vector.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**nconv** : int
The number of converged eigenvalues.

**d** : complex, ndarray, shape :math:\left(\textit{nev}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{d} contain the converged approximate eigenvalues.

**z** : None or complex, ndarray, shape :math:\left(\textit{n}, :\right)
If the default option :math:\text{‘Vectors'} = \texttt{'RITZ'} (see :meth:complex_option) has been selected then :math:\mathrm{z} contains the final set of eigenvectors corresponding to the eigenvalues held in :math:\mathrm{d}, otherwise :math:\mathrm{z} is not referenced. The complex eigenvector associated with an eigenvalue :math:\mathrm{d}[j] is stored in the corresponding array section of :math:\mathrm{z}, namely :math:\mathrm{z}[\textit{i}-1,\textit{j}-1], for :math:\textit{j} = 1,2,\ldots,\mathrm{nconv}, for :math:\textit{i} = 1,2,\ldots,{\textit{n}}.

**resid** : complex, ndarray, shape :math:\left(\textit{n}\right)
Contains the final residual vector. This can be used as the starting residual to improve convergence on the solution of a closely related eigenproblem. This has no relation to the error residual :math:Ax-\lambda x or :math:Ax-\lambda Bx.

**v** : complex, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right)
If the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} or :math:\texttt{'RITZ'} (see :meth:complex_option) has been set and a separate array :math:\mathrm{z} has been passed (i.e., :math:\mathrm{z} does not equal :math:\mathrm{v}), then the first :math:\mathrm{nconv} columns of :math:\mathrm{v} will contain approximate Schur vectors that span the desired invariant subspace.

The :math:j\ th Schur vector is stored in the :math:i\ th column of :math:\mathrm{v}.

.. _f12au-py2-py-errors:

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

Constraint: :math:\mathrm{kl}\geq 0.

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

Constraint: :math:\mathrm{ku}\geq 0.

(errno :math:3)
On entry, :math:\textit{ldab} = \langle\mathit{\boldsymbol{value}}\rangle, :math:2\times \mathrm{kl}+\mathrm{ku}+1 = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldab}\geq 2\times \mathrm{kl}+\mathrm{ku}+1.

(errno :math:5)
The maximum number of iterations :math:\text{}\leq 0, the option 'Iteration Limit' has been set to :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:6)
The options 'Generalized' and 'Regular' are incompatible.

(errno :math:7)
The option 'Initial Residual' was selected but the starting vector held in :math:\mathrm{resid} is zero.

(errno :math:8)
Either the initialization function has not been called prior to the first call of this function or a communication array has become corrupted.

(errno :math:10)
On entry, :math:\text{‘Vectors'} = \text{Select}, but this is not yet implemented.

(errno :math:11)
The number of eigenvalues found to sufficient accuracy is zero.

(errno :math:12)
Could not build an Arnoldi factorization. The size of the current Arnoldi factorization :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:13)
Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:14)
During calculation of a Schur form, there was a failure to compute a number of eigenvalues Please contact NAG <https://www.nag.com>__.

(errno :math:15)
The computed Schur form could not be reordered by an internal call. Please contact NAG <https://www.nag.com>__.

(errno :math:16)
Error in internal call to compute eigenvectors. Please contact NAG <https://www.nag.com>__.

(errno :math:17)
Failure during internal factorization of real banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:18)
Failure during internal solution of real banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:19)
Failure during internal factorization of complex banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:20)
Failure during internal solution of complex banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:21)
The maximum number of iterations has been reached. The maximum number of :math:\text{iterations} = \langle\mathit{\boldsymbol{value}}\rangle. The number of converged eigenvalues :math:\text{} = \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:22)
No shifts could be applied during a cycle of the implicitly restarted Arnoldi iteration.

(errno :math:23)
Overflow occurred during transformation of Ritz values to those of the original problem.

.. _f12au-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are banded, complex and non-Hermitian.

Following a call to the initialization function :meth:complex_band_init, complex_band_solve returns the converged approximations to eigenvalues and (optionally) the corresponding approximate eigenvectors and/or a unitary basis for the associated approximate invariant subspace.
The eigenvalues (and eigenvectors) are selected from those of a standard or generalized eigenvalue problem defined by complex banded non-Hermitian matrices.
There is negligible additional computational cost to obtain eigenvectors; a unitary basis is always computed, but there is an additional storage cost if both are requested.

The banded matrices :math:A and :math:B must be stored using the LAPACK column ordered storage format for banded non-Hermitian matrices; please refer to the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__ for details on this storage format.

complex_band_solve is based on the banded driver functions **znbdr1** to **znbdr4** from the ARPACK package, which uses the Implicitly Restarted Arnoldi iteration method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
An evaluation of software for computing eigenvalues of sparse non-Hermitian matrices is provided in Lehoucq and Scott (1996).
This suite of functions offers the same functionality as the ARPACK banded driver software for complex non-Hermitian problems, but the interface design is quite different in order to make the option setting clearer and to combine the different drivers into a general purpose function.

complex_band_solve, is a general purpose function that must be called following initialization by :meth:complex_band_init. complex_band_solve uses options, set either by default or explicitly by calling :meth:complex_option, to return the converged approximations to selected eigenvalues and (optionally):

-   the corresponding approximate eigenvectors;

-   a unitary basis for the associated approximate invariant subspace;

-   both.

.. _f12au-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_symm_init(n, nev, ncv):
r"""
real_symm_init is a setup function in a suite of functions consisting of real_symm_init, :meth:real_symm_iter, :meth:real_symm_proc, :meth:real_symm_option and :meth:real_symm_monit.
It is used to find some of the eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by real symmetric matrices.

The suite of functions is suitable for the solution of large sparse, standard or generalized, symmetric eigenproblems where only a few eigenvalues from a selected range of the spectrum are required.

.. _f12fa-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12faf.html

.. _f12fa-py2-py-parameters:

**Parameters**
**n** : int
The order of the matrix :math:A (and the order of the matrix :math:B for the generalized problem) that defines the eigenvalue problem.

**nev** : int
The number of eigenvalues to be computed.

**ncv** : int
The number of Lanczos basis vectors to use during the computation.

At present there is no a priori analysis to guide the selection of :math:\mathrm{ncv} relative to :math:\mathrm{nev}.

However, it is recommended that :math:\mathrm{ncv}\geq 2\times \mathrm{nev}+1.

If many problems of the same type are to be solved, you should experiment with increasing :math:\mathrm{ncv} while keeping :math:\mathrm{nev} fixed for a given test problem.

This will usually decrease the required number of matrix-vector operations but it also increases the work and storage required to maintain the orthogonal basis vectors.

The optimal 'cross-over' with respect to CPU time is problem dependent and must be determined empirically.

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

.. _f12fa-py2-py-errors:

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

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

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

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

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

Constraint: :math:\mathrm{ncv} > \mathrm{nev} and :math:\mathrm{ncv}\leq \mathrm{n}.

.. _f12fa-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, real and symmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real and symmetric problems.

real_symm_init is a setup function which must be called before :meth:real_symm_iter, the reverse communication iterative solver, and before :meth:real_symm_option, the options setting function. :meth:real_symm_proc, is a post-processing function that must be called following a successful final exit from :meth:real_symm_iter, while :meth:real_symm_monit can be used to return additional monitoring information during the computation.

This setup function initializes the communication arrays, sets (to their default values) all options that can be set by you via the option setting function :meth:real_symm_option, and checks that the lengths of the communication arrays as passed by you are of sufficient length.
For details of the options available and how to set them see :ref:Other Parameters for real_symm_option <f12fd-py2-py-other_params>.

.. _f12fa-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_symm_iter(irevcm, resid, v, x, mx, comm, io_manager=None):
r"""
real_symm_iter is an iterative solver in a suite of functions consisting of :meth:real_symm_init, real_symm_iter, :meth:real_symm_proc, :meth:real_symm_option and :meth:real_symm_monit.
It is used to find some of the eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by real symmetric matrices.

.. _f12fb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12fbf.html

.. _f12fb-py2-py-parameters:

**Parameters**
**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

**resid** : float, ndarray, shape :math:\left(\textit{n}\right), modified in place
On initial entry: need not be set unless the option 'Initial Residual' has been set in a prior call to :meth:real_symm_option in which case :math:\mathrm{resid} should contain an initial residual vector, possibly from a previous run.

On intermediate entry: must be unchanged from its previous exit. Changing :math:\mathrm{resid} to any other value between calls may result in an error exit.

On intermediate exit: contains the current residual vector.

On final exit: contains the final residual vector.

**v** : float, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right), modified in place
On initial entry: need not be set.

On intermediate entry: must be unchanged from its previous exit.

On intermediate exit: contains the current set of Arnoldi basis vectors.

On final exit: contains the final set of Arnoldi basis vectors.

**x** : float, ndarray, shape :math:\left(:\right), modified in place
Note: the required length for this argument is determined as follows: if :math:\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)\geq 1\text{ and }\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)\leq 1000: if :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)+24\right) - 1 }]=0: :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)+1\right) - 1 }]; otherwise: :math:1; otherwise: :math:0.

On initial entry: need not be set, it is used as a convenient mechanism for accessing elements of :math:\mathrm{comm}\ ['comm'].

On intermediate entry: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{x} need not be set.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{x} must contain the result of :math:y = \mathrm{op}\left(x\right) when :math:\mathrm{irevcm} returns the value :math:-1 or :math:+1.

It must return the real parts of the computed shifts when :math:\mathrm{irevcm} returns the value :math:3.

On intermediate exit: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{x} is not referenced.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{x} contains the vector :math:x when :math:\mathrm{irevcm} returns the value :math:-1 or :math:+1.

On final exit: does not contain useful data.

**mx** : float, ndarray, shape :math:\left(:\right), modified in place
Note: the required length for this argument is determined as follows: if :math:\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)\geq 1\text{ and }\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)\leq 1000: if :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)+24\right) - 1 }]=0: :math:\mathrm{comm}\ ['icomm'][{ \left(\mathrm{int}\left(\mathrm{comm}\ ['comm'][0]\right)+1\right) - 1 }]; otherwise: :math:1; otherwise: :math:0.

On initial entry: need not be set, it is used as a convenient mechanism for accessing elements of :math:\mathrm{comm}\ ['comm'].

On intermediate entry: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{mx} need not be set.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{mx} must contain the result of :math:y = Bx when :math:\mathrm{irevcm} returns the value :math:2.

It must return the imaginary parts of the computed shifts when :math:\mathrm{irevcm} returns the value :math:3.

On intermediate exit: if :math:\text{‘Pointers'} = \mathrm{YES}, :math:\mathrm{mx} is not referenced.

If :math:\text{‘Pointers'} = \mathrm{NO}, :math:\mathrm{mx} contains the vector :math:Bx when :math:\mathrm{irevcm} returns the value :math:+1.

On final exit: does not contain any useful data.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = -1

The calling program must compute the matrix-vector product :math:y = \mathrm{op}\left(x\right), where :math:x is stored in :math:\mathrm{x} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the first element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set in a prior call to :meth:real_symm_option. The result :math:y is returned in :math:\mathrm{x} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the second element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set.

:math:\mathrm{irevcm} = 1

The calling program must compute the matrix-vector product :math:y = \mathrm{op}\left(x\right). This is similar to the case :math:\mathrm{irevcm} = -1 except that the result of the matrix-vector product :math:Bx (as required in some computational modes) has already been computed and is available in :math:\mathrm{mx} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the third element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set.

:math:\mathrm{irevcm} = 2

The calling program must compute the matrix-vector product :math:y = Bx, where :math:x is stored in :math:\mathrm{x} and :math:y is returned in :math:\mathrm{mx} (by default) or in the array :math:\mathrm{comm}\ ['comm'] (starting from the location given by the second element of :math:\mathrm{comm}\ ['icomm']) when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set.

:math:\mathrm{irevcm} = 3

Compute the :math:\mathrm{nshift} real and imaginary parts of the shifts where the real parts are to be returned in the first :math:\mathrm{nshift} locations of the array :math:\mathrm{x} and the imaginary parts are to be returned in the first :math:\mathrm{nshift} locations of the array :math:\mathrm{mx}. Only complex conjugate pairs of shifts may be applied and the pairs must be placed in consecutive locations. This value of :math:\mathrm{irevcm} will only arise if the option 'Supplied Shifts' is set in a prior call to :meth:real_symm_option which is intended for experienced users only; the default and recommended option is to use exact shifts (see Lehoucq et al. (1998) for details and guidance on the choice of shift strategies).

:math:\mathrm{irevcm} = 4

Monitoring step: a call to :meth:real_symm_monit can now be made to return the number of Arnoldi iterations, the number of converged Ritz values, their real and imaginary parts, and the corresponding Ritz estimates.

On final exit: :math:\mathrm{irevcm} = 5: real_symm_iter has completed its tasks. The value of :math:\textit{errno} determines whether the iteration has been successfully completed, or whether errors have been detected. On successful completion :meth:real_symm_proc must be called to return the requested eigenvalues and eigenvectors (and/or Schur vectors).

**nshift** : int
On intermediate exit: if the option 'Supplied Shifts' is set and :math:\mathrm{irevcm} returns a value of :math:3, :math:\mathrm{nshift} returns the number of complex shifts required.

.. _f12fb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
The maximum number of iterations :math:\leq 0, the option 'Iteration Limit' has been set to :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:2)
The options 'Generalized' and 'Regular' are incompatible.

(errno :math:3)
Eigenvalues from both ends of the spectrum were requested, but the number of eigenvalues (see :math:\textit{nev} in :meth:real_symm_init) requested is one.

(errno :math:4)
The option 'Initial Residual' was selected but the starting vector held in :math:\mathrm{resid} is zero.

(errno :math:6)
No shifts could be applied during a cycle of the implicitly restarted Lanczos iteration.

(errno :math:7)
Could not build a Lanczos factorization. The size of the current Lanczos factorization :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:8)
Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:9)
Either the function was called without an initial call to the setup function or the communication arrays have become corrupted.

**Warns**
**NagAlgorithmicWarning**
(errno :math:5)
The maximum number of iterations has been reached. The maximum number of :math:\text{iterations} = \langle\mathit{\boldsymbol{value}}\rangle. The number of converged eigenvalues :math:= \langle\mathit{\boldsymbol{value}}\rangle. See the function document for further details.

.. _f12fb-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, real and symmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real and symmetric problems.

real_symm_iter is a **reverse communication** function, based on the ARPACK routine **dsaupd**, using the Implicitly Restarted Arnoldi iteration method, which for symmetric problems reduces to a variant of the Lanczos method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
An evaluation of software for computing eigenvalues of sparse symmetric matrices is provided in Lehoucq and Scott (1996).
This suite of functions offers the same functionality as the ARPACK software for real symmetric problems, but the interface design is quite different in order to make the option setting clearer and to simplify the interface of real_symm_iter.

The setup function :meth:real_symm_init must be called before real_symm_iter, the reverse communication iterative solver.
Options may be set for real_symm_iter by prior calls to the option setting function :meth:real_symm_option and a post-processing function :meth:real_symm_proc must be called following a successful final exit from real_symm_iter. :meth:real_symm_monit, may be called following certain flagged, intermediate exits from real_symm_iter to provide additional monitoring information about the computation.

real_symm_iter uses **reverse communication**, i.e., it returns repeatedly to the calling program with the argument :math:\mathrm{irevcm} (see :ref:Parameters <f12fb-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:y = \mathrm{op}\left(x\right), where :math:\mathrm{op} is defined by the computational mode;

-   compute the matrix-vector product :math:y = Bx;

-   notify the completion of the computation;

-   allow the calling program to monitor the solution.

The problem type to be solved (standard or generalized), the spectrum of eigenvalues of interest, the mode used (regular, regular inverse, shifted inverse, Buckling or Cayley) and other options can all be set using the option setting function :meth:real_symm_option.

.. _f12fb-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_symm_proc(sigma, resid, v, comm, io_manager=None):
r"""
real_symm_proc is a post-processing function in a suite of functions which includes :meth:real_symm_init, :meth:real_symm_iter, :meth:real_symm_option and :meth:real_symm_monit. real_symm_proc must be called following a final exit from :meth:real_symm_iter.

.. _f12fc-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12fcf.html

.. _f12fc-py2-py-parameters:

**Parameters**
**sigma** : float
If one of the 'Shifted Inverse' (see :meth:real_symm_option) modes has been selected then :math:\mathrm{sigma} contains the real shift used; otherwise :math:\mathrm{sigma} is not referenced.

**resid** : float, array-like, shape :math:\left(\textit{n}\right)
Must not be modified following a call to :meth:real_symm_iter since it contains data required by real_symm_proc.

**v** : float, array-like, shape :math:\left(\textit{n}, \textit{ncv}\right)
The :math:\textit{ncv} columns of :math:\mathrm{v} contain the Lanczos basis vectors for :math:\mathrm{op} as constructed by :meth:real_symm_iter.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**nconv** : int
The number of converged eigenvalues as found by :meth:real_symm_iter.

**d** : float, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{d} contain the converged approximate eigenvalues.

**z** : float, ndarray, shape :math:\left(\textit{n}, :\right)
If the default option :math:\text{‘Vectors'} = \texttt{'RITZ'} (see :meth:real_symm_option) has been selected then :math:\mathrm{z} contains the final set of eigenvectors corresponding to the eigenvalues held in :math:\mathrm{d}. The real eigenvector associated with an eigenvalue is stored in the corresponding of :math:\mathrm{z}.

**v** : float, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right)
If the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} has been set, or the option :math:\text{‘Vectors'} = \texttt{'RITZ'} has been set and a separate array :math:\mathrm{z} has been passed (i.e., :math:\mathrm{z} does not equal :math:\mathrm{v}), then the first :math:\mathrm{nconv} columns of :math:\mathrm{v} will contain approximate Schur vectors that span the desired invariant subspace.

.. _f12fc-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:2)
On entry, :math:\text{‘Vectors'} = \texttt{'SELECT'}, but this is not yet implemented.

(errno :math:3)
The number of eigenvalues found to sufficient accuracy, as communicated through the argument :math:\mathrm{comm}\ ['icomm'], is zero.

(errno :math:4)
Got a different count of the number of converged Ritz values than the value passed to it through the argument :math:\mathrm{comm}\ ['icomm']: number counted :math:= \langle\mathit{\boldsymbol{value}}\rangle, number expected :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:5)
During calculation of a tridiagonal form, there was a failure to compute :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvalues in a total of :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:8)
Either the function was called out of sequence (following an initial call to the setup function and following completion of calls to the reverse communication function) or the communication arrays have become corrupted.

.. _f12fc-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, real and symmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real and symmetric problems.

Following a call to :meth:real_symm_iter, real_symm_proc returns the converged approximations to eigenvalues and (optionally) the corresponding approximate eigenvectors and/or an orthonormal basis for the associated approximate invariant subspace.
The eigenvalues (and eigenvectors) are selected from those of a standard or generalized eigenvalue problem defined by real symmetric matrices.
There is negligible additional cost to obtain eigenvectors; an orthonormal basis is always computed, but there is an additional storage cost if both are requested.

real_symm_proc is based on the function **dseupd** from the ARPACK package, which uses the Implicitly Restarted Lanczos iteration method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
An evaluation of software for computing eigenvalues of sparse symmetric matrices is provided in Lehoucq and Scott (1996).
This suite of functions offers the same functionality as the ARPACK software for real symmetric problems, but the interface design is quite different in order to make the option setting clearer and to simplify some of the interfaces.

real_symm_proc, is a post-processing function that must be called following a successful final exit from :meth:real_symm_iter. real_symm_proc uses data returned from :meth:real_symm_iter and options, set either by default or explicitly by calling :meth:real_symm_option, to return the converged approximations to selected eigenvalues and (optionally):

-   the corresponding approximate eigenvectors;

-   an orthonormal basis for the associated approximate invariant subspace;

-   both.

.. _f12fc-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_symm_option(optstr, comm, io_manager=None):
r"""
real_symm_option is an option setting function in a suite of functions consisting of :meth:real_symm_init, :meth:real_symm_iter, :meth:real_symm_proc, real_symm_option and :meth:real_symm_monit, and may be used to supply individual options to :meth:real_symm_iter and :meth:real_symm_proc.
The initialization function :meth:real_symm_init **must** have been called prior to calling real_symm_option.

Note: this function uses optional algorithmic parameters, see also: :meth:real_symm_iter, :meth:real_symm_proc, :meth:real_symm_init.

.. _f12fd-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12fdf.html

.. _f12fd-py2-py-parameters:

**Parameters**
**optstr** : str
A single valid option string (as described in :ref:Notes <f12fd-py2-py-notes> and :ref:Other Parameters <f12fd-py2-py-other_params>).

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

.. _f12fd-py2-py-other_params:

**Other Parameters**
Default :math:= \text{advisory message unit number}

**'Defaults'** : valueless
This special keyword may be used to reset all options to their default values.

**'Exact Shifts'** : valueless
Default

During the Lanczos iterative process, shifts are applied internally as part of the implicit restarting scheme.
The shift strategy used by default and selected by the 'Exact Shifts' is strongly recommended over the alternative 'Supplied Shifts' (see Lehoucq et al. (1998) for details of shift strategies).

If 'Exact Shifts' are used then these are computed internally by the algorithm in the implicit restarting scheme.

If 'Supplied Shifts' are used then, during the Lanczos iterative process, you must supply shifts through array arguments of :meth:real_symm_iter when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = 3; the real and imaginary parts of the shifts are returned in :math:\textit{x} and :math:\textit{mx} respectively (or in :math:\textit{comm} when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set). This option should only be used if you are an experienced user since this requires some algorithmic knowledge and because more operations are usually required than for the implicit shift scheme.
Details on the use of explicit shifts and further references on shift strategies are available in Lehoucq et al. (1998).

**'Supplied Shifts'** : valueless
During the Lanczos iterative process, shifts are applied internally as part of the implicit restarting scheme.
The shift strategy used by default and selected by the 'Exact Shifts' is strongly recommended over the alternative 'Supplied Shifts' (see Lehoucq et al. (1998) for details of shift strategies).

If 'Exact Shifts' are used then these are computed internally by the algorithm in the implicit restarting scheme.

If 'Supplied Shifts' are used then, during the Lanczos iterative process, you must supply shifts through array arguments of :meth:real_symm_iter when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = 3; the real and imaginary parts of the shifts are returned in :math:\textit{x} and :math:\textit{mx} respectively (or in :math:\textit{comm} when the option :math:\text{‘Pointers'} = \texttt{'YES'} is set). This option should only be used if you are an experienced user since this requires some algorithmic knowledge and because more operations are usually required than for the implicit shift scheme.
Details on the use of explicit shifts and further references on shift strategies are available in Lehoucq et al. (1998).

**'Iteration Limit'** : int
Default :math:\text{} = 300

The limit on the number of Lanczos iterations that can be performed before :meth:real_symm_iter exits.
If not all requested eigenvalues have converged to within 'Tolerance' and the number of Lanczos iterations has reached this limit then :meth:real_symm_iter exits with an error; :meth:real_symm_proc can still be called subsequently to return the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors.

**'Largest Magnitude'** : valueless
Default

The Lanczos iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_symm_iter to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Algebraic' part, 'Smallest Magnitude', or 'Smallest Algebraic' part; or eigenvalues which are from 'Both Ends' of the algebraic spectrum.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Both Ends'** : valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_symm_iter to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Algebraic' part, 'Smallest Magnitude', or 'Smallest Algebraic' part; or eigenvalues which are from 'Both Ends' of the algebraic spectrum.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Largest Algebraic'** : valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_symm_iter to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Algebraic' part, 'Smallest Magnitude', or 'Smallest Algebraic' part; or eigenvalues which are from 'Both Ends' of the algebraic spectrum.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Smallest Algebraic'** : valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_symm_iter to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Algebraic' part, 'Smallest Magnitude', or 'Smallest Algebraic' part; or eigenvalues which are from 'Both Ends' of the algebraic spectrum.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Smallest Magnitude'** : valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties.
The default is for :meth:real_symm_iter to compute the eigenvalues of largest magnitude using 'Largest Magnitude'.
Alternatively, eigenvalues may be chosen which have 'Largest Algebraic' part, 'Smallest Magnitude', or 'Smallest Algebraic' part; or eigenvalues which are from 'Both Ends' of the algebraic spectrum.

Note that these options select the eigenvalue properties for eigenvalues of :math:\mathrm{op} (and :math:B for 'Generalized' problems), the linear operator determined by the computational mode and problem type.

**'Nolist'** : valueless
Default

Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.

**'List'** : valueless
Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.

**'Monitoring'** : int
Default :math:\text{} = -1

If :math:i > 0, monitoring information is output to unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj) :math:i during the solution of each problem; this may be the same as the 'Advisory' unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj).
The type of information produced is dependent on the value of 'Print Level', see the description of the option 'Print Level' for details of the information produced.
Please see the FileObjManager method :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj to associate a file with a given unit number (see :meth:~naginterfaces.base.utils.FileObjManager.unit_from_fileobj).

**'Pointers'** : valueless
Default :math:\text{} = \mathrm{NO}

During the iterative process and reverse communication calls to :meth:real_symm_iter, required data can be communicated to and from :meth:real_symm_iter in one of two ways.
When :math:\text{‘Pointers'} = \texttt{'NO'} is selected (the default) then the array arguments :math:\textit{x} and :math:\textit{mx} are used to supply you with required data and used to return computed values back to :meth:real_symm_iter.
For example, when :math:{\textit{irevcm}} = 1, :meth:real_symm_iter returns the vector :math:x in :math:\textit{x} and the matrix-vector product :math:Bx in :math:\textit{mx} and expects the result or the linear operation :math:\mathrm{op}\left(x\right) to be returned in :math:\textit{x}.

If :math:\text{‘Pointers'} = \texttt{'YES'} is selected then the data is passed through sections of the array argument :math:\textit{comm}.
The section corresponding to :math:\textit{x} when :math:\text{‘Pointers'} = \texttt{'NO'} begins at a location given by the first element of :math:\textit{icomm}; similarly the section corresponding to :math:\textit{mx} begins at a location given by the second element of :math:\textit{icomm}.
This option allows :meth:real_symm_iter to perform fewer copy operations on each intermediate exit and entry, but can also lead to less elegant code in the calling program.

**'Print Level'** : int
Default :math:\text{} = 0

This controls the amount of printing produced by real_symm_option as follows.

.. rst-class:: nag-rules-none nag-align-left

+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:i      |Output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+===============+=============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================+
|:math:= 0    |No output except error messages. If you want to suppress all output, set :math:\text{‘Print Level'} = 0.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:> 0    |The set of selected options.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:= 2    |Problem and timing statistics on final exit from :meth:real_symm_iter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 5 |A single line of summary output at each Lanczos iteration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 10|If :math:\text{‘Monitoring'} > 0, then at each iteration, the length and additional steps of the current Lanczos factorization and the number of converged Ritz values; during re-orthogonalization, the norm of initial/restarted starting vector; on a final Lanczos iteration, the number of update iterations taken, the number of converged eigenvalues, the converged eigenvalues and their Ritz estimates.                                                                                                                          |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 20|Problem and timing statistics on final exit from :meth:real_symm_iter. If :math:\text{‘Monitoring'} > 0, then at each iteration, the number of shifts being applied, the eigenvalues and estimates of the symmetric tridiagonal matrix :math:H, the size of the Lanczos basis, the wanted Ritz values and associated Ritz estimates and the shifts applied; vector norms prior to and following re-orthogonalization.                                                                                                                  |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 30|If :math:\text{‘Monitoring'} > 0, then on final iteration, the norm of the residual; when computing the Schur form, the eigenvalues and Ritz estimates both before and after sorting; for each iteration, the norm of residual for compressed factorization and the symmetric tridiagonal matrix :math:H; during re-orthogonalization, the initial/restarted starting vector; during the Lanczos iteration loop, a restart is flagged and the number of the residual requiring iterative refinement; while applying shifts, some indices.|
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 40|If :math:\text{‘Monitoring'} > 0, then during the Lanczos iteration loop, the Lanczos vector number and norm of the current residual; while applying shifts, key measures of progress and the order of :math:H; while computing eigenvalues of :math:H, the last rows of the Schur and eigenvector matrices; when computing implicit shifts, the eigenvalues and Ritz estimates of :math:H.                                                                                                                                          |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|:math:\geq 50|If :math:\text{‘Monitoring'} > 0, then during Lanczos iteration loop: norms of key components and the active column of :math:H, norms of residuals during iterative refinement, the final symmetric tridiagonal matrix :math:H; while applying shifts: number of shifts, shift values, block indices, updated tridiagonal matrix :math:H; while computing eigenvalues of :math:H: the diagonals of :math:H, the computed eigenvalues and Ritz estimates.                                                                         |
+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Note that setting :math:\text{‘Print Level'} \geq 30 can result in very lengthy 'Monitoring' output.

**'Random Residual'** : valueless
Default

To begin the Lanczos iterative process, :meth:real_symm_iter requires an initial residual vector.
By default :meth:real_symm_iter provides its own random initial residual vector; this option can also be set using option 'Random Residual'.
Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to :meth:real_symm_iter through the array argument :math:\textit{resid}; this option can be set using option 'Initial Residual'.

**'Initial Residual'** : valueless
To begin the Lanczos iterative process, :meth:real_symm_iter requires an initial residual vector.
By default :meth:real_symm_iter provides its own random initial residual vector; this option can also be set using option 'Random Residual'.
Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to :meth:real_symm_iter through the array argument :math:\textit{resid}; this option can be set using option 'Initial Residual'.

**'Regular'** : valueless
Default

These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-------------------------------------------------------------------------------+
|'Regular'        |:math:\mathrm{op} = A                                                        |
+-----------------+-------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+-----------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Regular Inverse'|:math:\mathrm{op} = B^{-1}A                                                                              |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                          |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Buckling'       |:math:\mathrm{op} = \left({B-\sigma A}\right)^{-1}A, where :math:\sigma is real                        |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Cayley'         |:math:\mathrm{op} = \left({A-\sigma B}\right)^{-1}\left({A+\sigma B}\right), where :math:\sigma is real|
+-----------------+-----------------------------------------------------------------------------------------------------------+

**'Regular Inverse'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-------------------------------------------------------------------------------+
|'Regular'        |:math:\mathrm{op} = A                                                        |
+-----------------+-------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+-----------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Regular Inverse'|:math:\mathrm{op} = B^{-1}A                                                                              |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                          |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Buckling'       |:math:\mathrm{op} = \left({B-\sigma A}\right)^{-1}A, where :math:\sigma is real                        |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Cayley'         |:math:\mathrm{op} = \left({A-\sigma B}\right)^{-1}\left({A+\sigma B}\right), where :math:\sigma is real|
+-----------------+-----------------------------------------------------------------------------------------------------------+

**'Shifted Inverse'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-------------------------------------------------------------------------------+
|'Regular'        |:math:\mathrm{op} = A                                                        |
+-----------------+-------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+-----------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Regular Inverse'|:math:\mathrm{op} = B^{-1}A                                                                              |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                          |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Buckling'       |:math:\mathrm{op} = \left({B-\sigma A}\right)^{-1}A, where :math:\sigma is real                        |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Cayley'         |:math:\mathrm{op} = \left({A-\sigma B}\right)^{-1}\left({A+\sigma B}\right), where :math:\sigma is real|
+-----------------+-----------------------------------------------------------------------------------------------------------+

**'Buckling'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-------------------------------------------------------------------------------+
|'Regular'        |:math:\mathrm{op} = A                                                        |
+-----------------+-------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+-----------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Regular Inverse'|:math:\mathrm{op} = B^{-1}A                                                                              |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                          |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Buckling'       |:math:\mathrm{op} = \left({B-\sigma A}\right)^{-1}A, where :math:\sigma is real                        |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Cayley'         |:math:\mathrm{op} = \left({A-\sigma B}\right)^{-1}\left({A+\sigma B}\right), where :math:\sigma is real|
+-----------------+-----------------------------------------------------------------------------------------------------------+

**'Cayley'** : valueless
These options define the computational mode which in turn defines the form of operation :math:\mathrm{op}\left(x\right) to be performed when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = -1 or :math:1 and the matrix-vector product :math:Bx when :meth:real_symm_iter returns with :math:{\textit{irevcm}} = 2.

Given a 'Standard' eigenvalue problem in the form :math:Ax = \lambda x then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-------------------------------------------------------------------------------+
|'Regular'        |:math:\mathrm{op} = A                                                        |
+-----------------+-------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma I\right)^{-1} where :math:\sigma is real|
+-----------------+-------------------------------------------------------------------------------+

Given a 'Generalized' eigenvalue problem in the form :math:Ax = \lambda Bx then the following modes are available with the appropriate operator :math:\mathrm{op}\left(x\right).

.. rst-class:: nag-rules-none nag-align-left

+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Regular Inverse'|:math:\mathrm{op} = B^{-1}A                                                                              |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Shifted Inverse'|:math:\mathrm{op} = \left(A-\sigma B\right)^{-1}B, where :math:\sigma is real                          |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Buckling'       |:math:\mathrm{op} = \left({B-\sigma A}\right)^{-1}A, where :math:\sigma is real                        |
+-----------------+-----------------------------------------------------------------------------------------------------------+
|'Cayley'         |:math:\mathrm{op} = \left({A-\sigma B}\right)^{-1}\left({A+\sigma B}\right), where :math:\sigma is real|
+-----------------+-----------------------------------------------------------------------------------------------------------+

**'Standard'** : valueless
Default

The problem to be solved is either a standard eigenvalue problem, :math:Ax = \lambda x, or a generalized eigenvalue problem, :math:Ax = \lambda Bx.
The option 'Standard' should be used when a standard eigenvalue problem is being solved and the option 'Generalized' should be used when a generalized eigenvalue problem is being solved.

**'Generalized'** : valueless
The problem to be solved is either a standard eigenvalue problem, :math:Ax = \lambda x, or a generalized eigenvalue problem, :math:Ax = \lambda Bx.
The option 'Standard' should be used when a standard eigenvalue problem is being solved and the option 'Generalized' should be used when a generalized eigenvalue problem is being solved.

**'Tolerance'** : float
Default :math:\text{} = \epsilon

An approximate eigenvalue has deemed to have converged when the corresponding Ritz estimate is within 'Tolerance' relative to the magnitude of the eigenvalue.

**'Vectors'** : valueless
Default :math:\text{} = \text{RITZ}

The function :meth:real_symm_proc can optionally compute the Schur vectors and/or the eigenvectors corresponding to the converged eigenvalues.
To turn off computation of any vectors the option :math:\text{‘Vectors'} = \texttt{'NONE'} should be set.
To compute only the Schur vectors (at very little extra cost), the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} should be set and these will be returned in the array argument :math:\textit{v} of :meth:real_symm_proc.
To compute the eigenvectors (Ritz vectors) ­corresponding to the eigenvalue estimates, the option :math:\text{‘Vectors'} = \texttt{'RITZ'} should be set and these will be returned in the array argument :math:\textit{z} of :meth:real_symm_proc, if :math:\textit{z} is set equal to :math:\textit{v} then the Schur vectors in :math:\textit{v} are overwritten by the eigenvectors computed by :meth:real_symm_proc.

.. _f12fd-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Ambiguous keyword: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:2)
Keyword not recognized: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:3)
Second keyword not recognized: :math:\langle\mathit{\boldsymbol{value}}\rangle

.. _f12fd-py2-py-notes:

**Notes**
real_symm_option may be used to supply values for options to :meth:real_symm_iter and :meth:real_symm_proc.
It is only necessary to call real_symm_option for those arguments whose values are to be different from their default values.
One call to real_symm_option sets one argument value.

Each option is defined by a single character string consisting of one or more items.
The items associated with a given option must be separated by spaces, or equals signs :math:\left[ = \right].
Alphabetic characters may be upper or lower case.
The string

::

Iteration Limit = 500

is an example of a string used to set an option.
For each option the string contains one or more of the following items:

-   a mandatory keyword;

-   a phrase that qualifies the keyword;

-   a number that specifies an int or float value. Such numbers may be up to :math:16 contiguous characters in Fortran's I, F, E or D format.

real_symm_option does not have an equivalent function from the ARPACK package which passes options by directly setting values to scalar arguments or to specific elements of array arguments. real_symm_option is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in submodule :mod:~naginterfaces.library.opt.

The setup function :meth:real_symm_init must be called prior to the first call to real_symm_option and all calls to real_symm_option must precede the first call to :meth:real_symm_iter, the reverse communication iterative solver.

A complete list of options, their abbreviations, synonyms and default values is given in :ref:Other Parameters <f12fd-py2-py-other_params>.

.. _f12fd-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_symm_monit(comm):
r"""
real_symm_monit can be used to return additional monitoring information during computation.
It is in a suite of functions which includes :meth:real_symm_init, :meth:real_symm_iter, :meth:real_symm_proc and :meth:real_symm_option.

.. _f12fe-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12fef.html

.. _f12fe-py2-py-parameters:

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

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

**Returns**
**niter** : int
The number of the current Arnoldi iteration.

**nconv** : int
The number of converged eigenvalues so far.

**ritz** : float, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{ritz} contain the real converged approximate eigenvalues.

**rzest** : float, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{rzest} contain the Ritz estimates (error bounds) on the real :math:\mathrm{nconv} converged approximate eigenvalues.

.. _f12fe-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are sparse, real and symmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real and symmetric problems.

On an intermediate exit from :meth:real_symm_iter with :math:{\textit{irevcm}} = 4, real_symm_monit may be called to return monitoring information on the progress of the Arnoldi iterative process.
The information returned by real_symm_monit is:

-   the number of the current Arnoldi iteration;

-   the number of converged eigenvalues at this point;

-   the real and imaginary parts of the converged eigenvalues;

-   the error bounds on the converged eigenvalues.

real_symm_monit does not have an equivalent function from the ARPACK package which prints various levels of detail of monitoring information through an output channel controlled via an argument value (see Lehoucq et al. (1998) for details of ARPACK routines). real_symm_monit should not be called at any time other than immediately following an :math:{\textit{irevcm}} = 4 return from :meth:real_symm_iter.

.. _f12fe-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_symm_band_init(n, nev, ncv):
r"""
real_symm_band_init is a setup function for :meth:real_symm_band_solve which can be used to find some eigenvalues (and optionally the corresponding eigenvectors) of a standard or generalized eigenvalue problem defined by real, banded, symmetric matrices.
The banded matrix must be stored using the LAPACK storage format for real banded nonsymmetric matrices.

.. _f12ff-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12fff.html

.. _f12ff-py2-py-parameters:

**Parameters**
**n** : int
The order of the matrix :math:A (and the order of the matrix :math:B for the generalized problem) that defines the eigenvalue problem.

**nev** : int
The number of eigenvalues to be computed.

**ncv** : int
The number of Lanczos basis vectors to use during the computation.

At present there is no a priori analysis to guide the selection of :math:\mathrm{ncv} relative to :math:\mathrm{nev}.

However, it is recommended that :math:\mathrm{ncv}\geq 2\times \mathrm{nev}+1.

If many problems of the same type are to be solved, you should experiment with increasing :math:\mathrm{ncv} while keeping :math:\mathrm{nev} fixed for a given test problem.

This will usually decrease the required number of matrix-vector operations but it also increases the work and storage required to maintain the orthogonal basis vectors.

The optimal 'cross-over' with respect to CPU time is problem dependent and must be determined empirically.

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

.. _f12ff-py2-py-errors:

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

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

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

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

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

Constraint: :math:\mathrm{ncv} > \mathrm{nev}+1 and :math:\mathrm{ncv}\leq \mathrm{n}.

.. _f12ff-py2-py-notes:

**Notes**
The pair of functions real_symm_band_init and :meth:real_symm_band_solve together with the option setting function :meth:real_symm_option are designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are banded real and symmetric.

real_symm_band_init is a setup function which must be called before the option setting function :meth:real_symm_option and the solver function :meth:real_symm_band_solve.
Internally, :meth:real_symm_band_solve makes calls to :meth:real_symm_iter and :meth:real_symm_proc; the function documents for :meth:real_symm_iter and :meth:real_symm_proc should be consulted for details of the algorithm used.

This setup function initializes the communication arrays, sets (to their default values) all options that can be set by you via the option setting function :meth:real_symm_option, and checks that the lengths of the communication arrays as passed by you are of sufficient length.
For details of the options available and how to set them, see :ref:Other Parameters for real_symm_option <f12fd-py2-py-other_params>.

.. _f12ff-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def real_symm_band_solve(kl, ku, ab, mb, sigma, resid, comm, io_manager=None):
r"""
real_symm_band_solve is the main solver function in a suite of functions which includes :meth:real_symm_option and :meth:real_symm_band_init. real_symm_band_solve must be called following an initial call to :meth:real_symm_band_init and following any calls to :meth:real_symm_option.

real_symm_band_solve returns approximations to selected eigenvalues, and (optionally) the corresponding eigenvectors, of a standard or generalized eigenvalue problem defined by real banded symmetric matrices.
The banded matrix must be stored using the LAPACK storage format for real banded nonsymmetric matrices.

.. _f12fg-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12fgf.html

.. _f12fg-py2-py-parameters:

**Parameters**
**kl** : int
The number of subdiagonals of the matrices :math:A and :math:B.

**ku** : int
The number of superdiagonals of the matrices :math:A and :math:B. Since :math:A and :math:B are symmetric, the normal case is :math:\mathrm{ku} = \mathrm{kl}.

**ab** : float, array-like, shape :math:\left(2\times \mathrm{kl}+\mathrm{ku}+1, \textit{n}\right)
Must contain the matrix :math:A in LAPACK banded storage format for nonsymmetric matrices (see the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__).

**mb** : float, array-like, shape :math:\left(:, \textit{n}\right)
Note: the required extent for this argument in dimension 1 is determined as follows: if :math:\mathrm{comm}\ ['comm'][0]\geq 1.0\text{ and }\mathrm{comm}\ ['comm'][0]\leq 1000.0: if :math:\mathrm{comm}\ ['icomm'][28]=2\text{ or }\left(\mathrm{comm}\ ['icomm'][23]=1\text{ and }\mathrm{comm}\ ['icomm'][28]\text{ in } (3, 4, 5)\right): :math:{ 2 \times \mathrm{kl} + \mathrm{ku} + 1 }; otherwise: :math:0; otherwise: :math:0.

Must contain the matrix :math:B in LAPACK banded storage format for nonsymmetric matrices (see the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_33>__).

**sigma** : float
If one of the 'Shifted Inverse' (see :meth:real_symm_option) modes has been selected then :math:\mathrm{sigma} contains the real shift used; otherwise :math:\mathrm{sigma} is not referenced.

**resid** : float, array-like, shape :math:\left(\textit{n}\right)
Need not be set unless the option 'Initial Residual' has been set in a prior call to :meth:real_symm_option in which case :math:\mathrm{resid} must contain an initial residual vector.

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

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

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

**Returns**
**nconv** : int
The number of converged eigenvalues.

**d** : float, ndarray, shape :math:\left(\textit{ncv}\right)
The first :math:\mathrm{nconv} locations of the array :math:\mathrm{d} contain the converged approximate eigenvalues.

**z** : float, ndarray, shape :math:\left(\textit{n}, :\right)
If the default option :math:\text{‘Vectors'} = \texttt{'RITZ'} (see :meth:real_symm_option) has been selected then :math:\mathrm{z} contains the final set of eigenvectors corresponding to the eigenvalues held in :math:\mathrm{d}. The real eigenvector associated with eigenvalue :math:\textit{i}-1, for :math:\textit{i} = 1,2,\ldots,\mathrm{nconv}, is stored in the :math:\textit{i}\ th column of :math:\mathrm{z}.

**resid** : float, ndarray, shape :math:\left(\textit{n}\right)
Contains the final residual vector.

**v** : float, ndarray, shape :math:\left(\textit{n}, \textit{ncv}\right)
If the option :math:\text{‘Vectors'} = \texttt{'SCHUR'} or :math:\texttt{'RITZ'} (see :meth:real_symm_option) and a separate array :math:\mathrm{z} has been passed then the first :math:\mathrm{nconv}\times n elements of :math:\mathrm{v} will contain approximate Schur vectors that span the desired invariant subspace.

The :math:j\ th Schur vector is stored in the :math:i\ th column of :math:\mathrm{v}.

.. _f12fg-py2-py-errors:

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

Constraint: :math:\mathrm{kl}\geq 0.

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

Constraint: :math:\mathrm{ku}\geq 0.

(errno :math:3)
On entry, :math:\textit{ldab} = \langle\mathit{\boldsymbol{value}}\rangle, :math:2\times \mathrm{kl}+\mathrm{ku}+1 = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldab}\geq 2\times \mathrm{kl}+\mathrm{ku}+1.

(errno :math:4)
The maximum number of iterations :math:\leq 0, the option 'Iteration Limit' has been set to :math:\langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:5)
The options 'Generalized' and 'Regular' are incompatible.

(errno :math:6)
Eigenvalues from both ends of the spectrum were requested, but the number of eigenvalues (:math:\textit{nev} in :meth:real_symm_band_init) requested is one.

(errno :math:7)
The option 'Initial Residual' was selected but the starting vector held in :math:\mathrm{resid} is zero.

(errno :math:9)
On entry, :math:\text{‘Vectors'} = \text{Select}, but this is not yet implemented.

(errno :math:10)
The number of eigenvalues found to sufficient accuracy is zero.

(errno :math:11)
Could not build a Lanczos factorization. The size of the current Lanczos factorization :math:= \langle\mathit{\boldsymbol{value}}\rangle.

(errno :math:12)
Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:13)
During calculation of a tridiagonal form, there was a failure to compute :math:\langle\mathit{\boldsymbol{value}}\rangle eigenvalues in a total of :math:\langle\mathit{\boldsymbol{value}}\rangle iterations.

(errno :math:14)
Failure during internal factorization of banded matrix. Please contact NAG <https://www.nag.com>__.

(errno :math:15)
Failure during internal solution of banded system. Please contact NAG <https://www.nag.com>__.

(errno :math:17)
No shifts could be applied during a cycle of the implicitly restarted Lanczos iteration.

(errno :math:18)
Either an initial call to the setup function has not been made or the communication arrays have become corrupted.

(errno :math:19)
On entry, :math:\textit{ldmb} = \langle\mathit{\boldsymbol{value}}\rangle, :math:2\times \mathrm{kl}+\mathrm{ku}+1 = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:\textit{ldmb}\geq 2\times \mathrm{kl}+\mathrm{ku}+1.

**Warns**
**NagAlgorithmicWarning**
(errno :math:16)
The maximum number of iterations has been reached: there have been :math:\langle\mathit{\boldsymbol{value}}\rangle iterations. There are :math:\langle\mathit{\boldsymbol{value}}\rangle converged eigenvalues.

.. _f12fg-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, (and optionally the corresponding eigenvectors, :math:x) of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx of order :math:n, where :math:n is large and the coefficient matrices :math:A and :math:B are banded, real and symmetric.

Following a call to the initialization function :meth:real_symm_band_init, real_symm_band_solve returns the converged approximations to eigenvalues and (optionally) the corresponding approximate eigenvectors and/or an orthonormal basis for the associated approximate invariant subspace.
The eigenvalues (and eigenvectors) are selected from those of a standard or generalized eigenvalue problem defined by real banded symmetric matrices.
There is negligible additional computational cost to obtain eigenvectors; an orthonormal basis is always computed, but there is an additional storage cost if both are requested.

The banded matrices :math:A and :math:B must be stored using the LAPACK storage format for banded nonsymmetric matrices; please refer to the F07 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f07/f07intro.html#recomm_32>__ for details on this storage format.

real_symm_band_solve is based on the banded driver functions **dsbdr1** to **dsbdr6** from the ARPACK package, which uses the Implicitly Restarted Lanczos iteration method.
The method is described in Lehoucq and Sorensen (1996) and Lehoucq (2001) while its use within the ARPACK software is described in great detail in Lehoucq et al. (1998).
This suite of functions offers the same functionality as the ARPACK banded driver software for real symmetric problems, but the interface design is quite different in order to make the option setting clearer and to combine the different drivers into a general purpose function.

real_symm_band_solve, is a general purpose direct communication function that must be called following initialization by :meth:real_symm_band_init. real_symm_band_solve uses options, set either by default or explicitly by calling :meth:real_symm_option, to return the converged approximations to selected eigenvalues and (optionally):

-   the corresponding approximate eigenvectors;

-   an orthonormal basis for the associated approximate invariant subspace;

-   both.

.. _f12fg-py2-py-references:

**References**
Lehoucq, R B, 2001, Implicitly restarted Arnoldi methods and subspace iteration, SIAM Journal on Matrix Analysis and Applications (23), 551--562

Lehoucq, R B and Scott, J A, 1996, An evaluation of software for computing eigenvalues of sparse nonsymmetric matrices, Preprint MCS-P547-1195, Argonne National Laboratory

Lehoucq, R B and Sorensen, D C, 1996, Deflation techniques for an implicitly restarted Arnoldi iteration, SIAM Journal on Matrix Analysis and Applications (17), 789--821

Lehoucq, R B, Sorensen, D C and Yang, C, 1998, ARPACK Users' Guide: Solution of Large-scale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods, SIAM, Philadelphia
"""
raise NotImplementedError

[docs]def feast_init():
r"""
feast_init initializes a data structure for the NAG FEAST suite of functions consisting of feast_init, :meth:feast_option, :meth:feast_symm_contour, :meth:feast_gen_contour, :meth:feast_custom_contour, :meth:feast_real_symm_solve, :meth:feast_real_gen_solve, :meth:feast_complex_herm_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve, :meth:feast_poly_gen_solve and :meth:feast_free.
It is used to find some of the eigenvalues, and the corresponding eigenvectors, of a standard, generalized or polynomial eigenvalue problem.

The suite of functions is suitable for the solution of large, sparse eigenproblems where only those eigenvalues within a selected region of the complex plane are required.

.. _f12ja-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jaf.html

**Returns**
**handle** : Handle
Holds a handle to the internal data structure used by the NAG FEAST suite.

.. _f12ja-py2-py-notes:

**Notes**
The NAG FEAST suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, a generalized eigenvalue problem :math:Ax = \lambda Bx, where :math:A and :math:B are large and sparse, or a polynomial eigenvalue problem :math:∑_i\lambda^iA_ix = 0.
It can also be used to find eigenvalues/eigenvectors of smaller scale dense problems.
The NAG FEAST suite is based on the FEAST library, using contour integration to find the eigenvalues within a contour in the complex plane.

feast_init is a setup function which must be called before the option setting function :meth:feast_option, before the contour definition functions :meth:feast_symm_contour, :meth:feast_gen_contour or :meth:feast_custom_contour, and before the reverse communication solvers :meth:feast_real_symm_solve, :meth:feast_real_gen_solve, :meth:feast_complex_herm_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve or :meth:feast_poly_gen_solve.

This setup function initializes the handle to a data structure used internally by the NAG FEAST suite and sets (to their default values) all options that can be set by you via the option setting function :meth:feast_option.
For details of the options available and how to set them see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params>.
When the handle is no longer needed, :meth:feast_free must be called to destroy it and deallocate all the allocated memory and data within.

.. _f12ja-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112

--------
:meth:naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main
"""
raise NotImplementedError

[docs]def feast_option(handle, optstr, io_manager=None):
r"""
feast_option is part of NAG FEAST suite of functions and may be used to supply individual options to either the contour setting functions or the reverse communication solvers.

Note: this function uses optional algorithmic parameters, see also: :meth:feast_symm_contour, :meth:feast_gen_contour, :meth:feast_custom_contour, :meth:feast_real_symm_solve, :meth:feast_real_gen_solve, :meth:feast_complex_herm_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve, :meth:feast_poly_gen_solve, :meth:feast_init.

.. _f12jb-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jbf.html

.. _f12jb-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**optstr** : str
A single valid option string (as described in :ref:Notes <f12jb-py2-py-notes> and :ref:Other Parameters <f12jb-py2-py-other_params>).

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

.. _f12jb-py2-py-other_params:

**Other Parameters**
Default :math:= \text{advisory message unit number}

**'Contour Points Hermitian'** : int
Default :math:\text{} = 8

For real symmetric (:meth:feast_real_symm_solve) or Hermitian (:meth:feast_complex_herm_solve) eigenproblems, this is the number of points used on the half-contour which defines the contour integral.
If the option 'Integration Type' is set to 'Gauss' or 'Zol', the values permitted are :math:1--:math:20, :math:24, :math:32, :math:40, :math:48, :math:56.
If the option 'Integration Type' is set to 'Trap', then all values greater than or equal to :math:1 are permitted.

**'Contour Points Non-Hermitian'** : int
Default :math:\text{} = 8

For general real (:meth:feast_real_gen_solve), symmetric complex (:meth:feast_complex_symm_solve, :meth:feast_poly_symm_solve) or general complex (:meth:feast_complex_gen_solve, :meth:feast_poly_gen_solve) eigenproblems, this is the number of integration points used on the circular or elliptical contour within which eigenvalues are sought.
If the option 'Integration Type' is set to 'Gauss', the values permitted are :math:2--:math:40 (even values only), :math:48, :math:64, :math:80, :math:96, :math:112.
If the option 'Integration Type' is set to 'Trap', then all values greater than or equal to :math:2 are permitted.
Note this option is only relevant if the contour definition functions :meth:feast_symm_contour or :meth:feast_gen_contour are used.
If a custom contour is required (using the contour setting routine :meth:feast_custom_contour) then this option is not relevant.

**'Convergence Criteria'** : str
Default :math:\text{} = \texttt{'Residual'}

These are the convergence criteria used to test for convergence of eigenpairs in the search region.

:math:\text{‘Convergence Criteria'} = \texttt{'Trace'}
The relative error of the trace of the eigenproblem in the search subspace is tested against :math:\delta.

:math:\text{‘Convergence Criteria'} = \texttt{'Residual'}
The relative maximum residual over all eigenpairs found is tested against :math:\delta.

Note: the value of :math:\delta is controlled using the option 'Tolerance'.

**'Defaults'** : valueless
This special keyword may be used to reset all options to their default values.

**'Ellipse Contour Ratio'** : int
Default :math:\text{} = 100

The ratio, as a percentage, of the length of the vertical axis to the length of the horizontal axis if an elliptical contour is to be used in the contour integral.
This option should be set prior to a call to either of the contour definition functions :meth:feast_symm_contour or :meth:feast_gen_contour.

Note: For a Hermitian eigenvalue problem, if the option 'Integration Type' is set to 'Zol' then a circular contour is used and this option is not referenced.

**'Ellipse Rotation Angle'** : int
Default :math:\text{} = 0

The rotation angle in degrees from the horizontal (between :math:-180 and :math:180) of the major axis if an elliptical contour is to be used in the contour integral.
This option should be set prior to calls to the contour definition function :meth:feast_gen_contour and the reverse communication solvers :meth:feast_real_gen_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve and :meth:feast_poly_gen_solve (which deal with problems that are neither real symmetric nor complex Hermitian).

**'Execution Mode'** : str
Default :math:\text{} = \texttt{'Normal'}

The execution mode used by the reverse communication solvers.

:math:\text{‘Execution Mode'} = \texttt{'Normal'}
Normal execution.

:math:\text{‘Execution Mode'} = \texttt{'Subspace'}
Return the search subspace and an estimate of the eigenvalues after one contour integral.

:math:\text{‘Execution Mode'} = \texttt{'Estimate'}
Return an estimate of the number of eigenvalues inside the search contour. Note that this option is not available for polynomial eigenvalue problems (:meth:feast_poly_symm_solve and :meth:feast_poly_gen_solve).

**'Integration Type'** : str
Default :math:\text{} = \texttt{'Gauss'}

The integration type.
The allowed values are 'Gauss', 'Trap' (Trapezoidal) or 'Zol' (Zolotarev).
Note that Zolotarev can only be used for real symmetric or complex Hermitian eigenproblems.
This option should be set prior to a call to either of the contour definition functions :meth:feast_symm_contour or :meth:feast_gen_contour.
If a custom contour is required (using the contour setting routine :meth:feast_custom_contour) then this option is not relevant.

**'Max Iter'** : int
Default :math:\text{} = 20

The maximum number of iterations used in the reverse communication solvers.
If this is set to a negative value then no maximum will be used.

**'Nolist'** : valueless
Default

Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.

**'List'** : valueless
Option 'List' enables printing of each option specification as it is supplied. 'Nolist' suppresses this printing.

**'Print Level'** : int
Default :math:\text{} = 0

This controls the amount of printing produced by the contour definition routines and the reverse communication solvers.

:math:\text{‘Print Level'} = \texttt{'0'}
No output.

:math:\text{‘Print Level'} = \texttt{'1'}

**'Tolerance'** : float
Default :math:\text{} = x-3, where :math:x is the value returned by :meth:machine.decimal_digits <naginterfaces.library.machine.decimal_digits>

The stopping criterion, :math:\delta, used to determine convergence of the eigensolver.
If a value of :math:k is supplied then :math:\delta = 10^{{-k}} is used.

**'Eigenvectors'** : str
Default :math:\text{} = \texttt{'Two-sided'}

Determines whether both left and right eigenvectors are computed or whether just right eigenvectors are computed.

Note: this option only applies to the solvers :meth:feast_real_gen_solve, :meth:feast_complex_gen_solve and :meth:feast_poly_gen_solve, which deal with non-symmetric eigenvalue problems. For the symmetric/Hermitian solvers (:meth:feast_real_symm_solve, :meth:feast_complex_herm_solve, :meth:feast_complex_symm_solve and :meth:feast_poly_symm_solve) the left eigenvectors can be obtained from the right eigenvectors by complex conjugation.

:math:\text{‘Eigenvectors'} = \texttt{'Two-sided'}
Both left and right eigenvectors are computed.

:math:\text{‘Eigenvectors'} = \texttt{'One-sided'}
Only right eigenvectors are computed.

**'Subspace'** : str
Default :math:\text{} = \texttt{'No'}

This option determines whether or not you will supply an initial guess for the eigenvector search subspace.

:math:\text{‘Subspace'} = \texttt{'Yes'}
The reverse communication solvers will use your initial guess for the search subspace and the eigenvalues therein. This option is useful if a previous run of the FEAST routines has yielded a partially converged answer to your eigenproblem.

:math:\text{‘Subspace'} = \texttt{'No'}
Random initial vectors will be used for the search subspace.

.. _f12jb-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Ambiguous keyword: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:2)
Keyword not recognized: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:3)
Second keyword not recognized: :math:\langle\mathit{\boldsymbol{value}}\rangle

(errno :math:4)
:math:\mathrm{handle} has not been initialized properly or is corrupted.

(errno :math:5)
One of the contour setting functions :meth:feast_symm_contour, :meth:feast_gen_contour or :meth:feast_custom_contour has already been called. All calls to feast_option must be made prior to calling the contour setting functions.

.. _f12jb-py2-py-notes:

**Notes**
After the :math:\mathrm{handle} has been initialized (e.g., :meth:feast_init has been called), feast_option may be used to supply values for options to :meth:feast_symm_contour, :meth:feast_gen_contour, :meth:feast_custom_contour, :meth:feast_real_symm_solve, :meth:feast_real_gen_solve, :meth:feast_complex_herm_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve and :meth:feast_poly_gen_solve.
It is only necessary to call feast_option for those arguments whose values are to be different from their default values.
One call to feast_option sets one argument value.

Each option is defined by a single character string consisting of one or more items.
The items associated with a given option must be separated by spaces or equals signs :math:\left[ = \right].
Alphabetic characters may be upper or lower case.
The string

::

'Integration type = Gauss'

is an example of a string used to set an option.
For each option the string contains one or more of the following items:

-   a mandatory keyword;

-   a phrase that qualifies the keyword;

-   a number that specifies an int.

The NAG FEAST suite of functions of which feast_option is a part is based on the FEAST library, which solves eigenproblems using contour integration to find eigenvalues with a given contour in the complex plane.
However, feast_option itself does not have an equivalent function in the FEAST package, which passes options by directly setting values to scalar arguments or to specific elements of array arguments. feast_option is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in submodule :mod:~naginterfaces.library.opt.

The initialization function :meth:feast_init must be called prior to the first call to feast_option and all calls to feast_option must precede the first call to the contour setting functions :meth:feast_symm_contour, :meth:feast_gen_contour and :meth:feast_custom_contour, and the reverse communication solvers :meth:feast_real_symm_solve, :meth:feast_real_gen_solve, :meth:feast_complex_herm_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve and :meth:feast_poly_gen_solve, and the deallocation function :meth:feast_free.

A complete list of options, their abbreviations, synonyms and default values is given in :ref:Other Parameters <f12jb-py2-py-other_params>.

--------
:meth:naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main
"""
raise NotImplementedError

[docs]def feast_symm_contour(handle, emin, emax):
r"""
feast_symm_contour is a setup function in a suite of functions consisting of :meth:feast_init, :meth:feast_option, feast_symm_contour, :meth:feast_real_symm_solve and :meth:feast_complex_herm_solve.
It is used to find some of the eigenvalues, and the corresponding eigenvectors, of a standard or generalized eigenvalue problem defined by real symmetric or complex Hermitian matrices.
The initialization function :meth:feast_init **must** have been called prior to calling feast_symm_contour.
In addition calls to :meth:feast_option can be made to supply individual options to feast_symm_contour.

The suite of functions is suitable for the solution of large sparse eigenproblems where only a few eigenvalues from a selected range of the spectrum are required.

.. _f12je-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jef.html

.. _f12je-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**emin** : float
The lower bound of the eigenvalue search interval.

**emax** : float
The upper bound of the eigenvalue search interval.

.. _f12je-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
:math:\mathrm{handle} has not been initialized properly or is corrupted.

(errno :math:2)
An invalid number of integration points was specified. For Gauss or Zolotarev integration, the values permitted are :math:1--:math:20, :math:24, :math:32, :math:40, :math:48, :math:56.

(errno :math:3)
On entry, :math:E_{\mathrm{min}} = \langle\mathit{\boldsymbol{value}}\rangle and :math:E_{\mathrm{max}} = \langle\mathit{\boldsymbol{value}}\rangle.

Constraint: :math:E_{\mathrm{min}} < E_{\mathrm{max}}.

.. _f12je-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, or a generalized eigenvalue problem :math:Ax = \lambda Bx, where the coefficient matrices :math:A and :math:B are sparse, real symmetric or complex Hermitian.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense, real symmetric or complex Hermitian problems.

feast_symm_contour is used to specify a search interval on the real line, :math:\left[E_{\mathrm{min}}, E_{\mathrm{max}}\right], within which eigenvalues will be sought (note that the eigenvalues of real symmetric and complex Hermitian eigenproblems are themselves real). feast_symm_contour uses this interval to define nodes and weights for an elliptical contour to be used by the solvers :meth:feast_real_symm_solve or :meth:feast_complex_herm_solve.
Since this contour is symmetric when reflected in the real line, the function needs only to define the nodes and weights for the upper half-contour.

.. _f12je-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError

[docs]def feast_gen_contour(handle, emid, r):
r"""
feast_gen_contour is a setup function in a suite of functions consisting of :meth:feast_init, :meth:feast_option, feast_gen_contour, :meth:feast_real_gen_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve and :meth:feast_poly_gen_solve.
It is used to find some of the eigenvalues, and the corresponding eigenvectors, of a standard, generalized or polynomial eigenvalue problem.
The initialization function :meth:feast_init **must** have been called prior to calling feast_gen_contour.
In addition calls to :meth:feast_option can be made to supply individual options to feast_gen_contour.

The suite of functions is suitable for the solution of large sparse eigenproblems where only a few eigenvalues from a selected range of the spectrum are required.

.. _f12jf-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jff.html

.. _f12jf-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**emid** : complex
The centre of the ellipse.

**r** : float
The radius of the horizontal axis of the ellipse (that is, the axis that would be horizontal if the rotation angle of the ellipse was set to zero).

.. _f12jf-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
:math:\mathrm{handle} has not been initialized properly or is corrupted.

(errno :math:2)
An invalid number of integration points was specified. For Gauss integration, the values permitted are :math:2--:math:40 (even values only), :math:48, :math:64, :math:80, :math:96, :math:112.

(errno :math:3)
The option 'Integration Type' was set to 'Zol'. For non-Hermitian eigenvalue problems the allowed values are 'Gauss' or 'Trap'.

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

Constraint: :math:\mathrm{r} > 0.0.

.. _f12jf-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, a generalized eigenvalue problem :math:Ax = \lambda Bx, or a polynomial eigenvalue problem :math:∑_i\lambda^iA_ix = 0, where the coefficient matrices are large and sparse.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense problems.

feast_gen_contour is used to specify a circle or ellipse in the complex plane within which eigenvalues will be sought.
By default, a circle centred at :math:\textit{emid} with a radius of :math:r is created.
Optionally, :meth:feast_option can be called prior to calling feast_gen_contour, using the options 'Ellipse Contour Ratio', 'Ellipse Rotation Angle' to change the eccentricity of the ellipse and the inclination angle of its axis. feast_gen_contour uses these details to define nodes and weights for the elliptical contour, to be used by the solvers :meth:feast_real_gen_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve or :meth:feast_poly_gen_solve.

For details of the other options available and how to set them see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params>.

.. _f12jf-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError

[docs]def feast_custom_contour(handle, nedge, tedge, zedge):
r"""
feast_custom_contour is a setup function in a suite of functions consisting of :meth:feast_init, :meth:feast_option, feast_custom_contour, :meth:feast_real_gen_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve and :meth:feast_poly_gen_solve.
It is used to find some of the eigenvalues, and the corresponding eigenvectors, of a standard, generalized or polynomial eigenvalue problem.
The initialization function :meth:feast_init **must** have been called prior to calling feast_custom_contour.
In addition calls to :meth:feast_option can be made to supply individual options to feast_custom_contour.

The suite of functions is suitable for the solution of large sparse eigenproblems where only a few eigenvalues from a selected range of the spectrum are required.

.. _f12jg-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jgf.html

.. _f12jg-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**nedge** : int, array-like, shape :math:\left(\textit{ccn}\right)
:math:\mathrm{nedge}[i-1] specifies how many integration nodes and weights feast_custom_contour should use for the :math:i\ th piece of the contour.

**tedge** : int, array-like, shape :math:\left(\textit{ccn}\right)
:math:\mathrm{tedge}[i-1] specifies what shape the :math:i\ th piece of the contour should be.

:math:\mathrm{tedge}[i-1] = 0

The :math:i\ th piece of the contour is straight.

:math:\mathrm{tedge}[i-1] > 0

The :math:i\ th piece of the contour is a (convex) half-ellipse, with :math:\mathrm{tedge}[i-1]/100 = a/b, where :math:a is the primary radius from the endpoints of the piece, and :math:b is the radius perpendicular to this. Thus, if :math:\mathrm{tedge}[i-1] = 100, then the :math:i\ th piece of the contour is a semicircle.

**zedge** : complex, array-like, shape :math:\left(\textit{ccn}\right)
:math:\mathrm{zedge} specifies the endpoints of the contour piece.

The :math:i\ th piece has endpoints at :math:\mathrm{zedge}[i-1] and :math:\mathrm{zedge}[{i+1}-1], for :math:i = 1,\ldots,\textit{ccn}-1.

The last piece has endpoints at :math:\mathrm{zedge}[\textit{ccn}-1] and :math:\mathrm{zedge}[0].

Note: the contour should be described in a clockwise direction..

.. _f12jg-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
:math:\mathrm{handle} has not been initialized properly or is corrupted.

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

Constraint: :math:\textit{ccn} > 1.

(errno :math:3)
On entry, one or more elements of :math:\mathrm{nedge} were less than or equal to zero.

(errno :math:4)
On entry, one or more elements of :math:\mathrm{tedge} were negative.

.. _f12jg-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, a generalized eigenvalue problem :math:Ax = \lambda Bx, or a polynomial eigenvalue problem :math:∑_i\lambda^iA_ix = 0, where the coefficient matrices are large and sparse.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale dense problems.

feast_custom_contour is used to specify a closed contour in the complex plane within which eigenvalues will be sought.
The contour can be made up of a combination of line segments and half ellipses. feast_custom_contour uses this information to create a polygonal representation of the contour and to then define the integration nodes and weights to be used by the solvers :meth:feast_real_gen_solve, :meth:feast_complex_symm_solve, :meth:feast_complex_gen_solve, :meth:feast_poly_symm_solve or :meth:feast_poly_gen_solve.

The arrays :math:\mathrm{zedge}, :math:\mathrm{tedge} and :math:\mathrm{nedge} are used to define the geometry of your contour.
Each array is of size :math:\textit{ccn}, where :math:\textit{ccn} is the number of pieces that make up the contour.
The entries in :math:\mathrm{zedge} specify the endpoints in the complex plane of each piece of the contour.
The entries in :math:\mathrm{tedge} specify whether each piece of the contour is a line segment or a half ellipse.
Finally, entries in :math:\mathrm{nedge} specify the number of integration points to use for each piece of the contour.
See the individual argument descriptions in :ref:Parameters <f12jg-py2-py-parameters> for further details.

Prior to calling feast_custom_contour, the option setting function :meth:feast_option can be called to specify various options for the solution of the eigenproblem.
For details of the options available and how to set them see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params>.

.. _f12jg-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112

--------
:meth:naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main
"""
raise NotImplementedError

[docs]def feast_real_symm_solve(handle, irevcm, ze, x, y, m0, d, z, eps, itera, resid, io_manager=None):
r"""
feast_real_symm_solve is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a standard or generalized eigenvalue problem defined by real symmetric matrices.
This is part of a suite of functions that also includes :meth:feast_init, :meth:feast_option and :meth:feast_symm_contour.

.. _f12jj-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jjf.html

.. _f12jj-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On initial entry: need not be set.

**x** : float, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 3, the calling program must compute :math:Az, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 4, the calling program must compute :math:Bz, storing the result in :math:x prior to re-entry.

Note: the matrices :math:x and :math:z are stored in the first :math:\mathrm{m0} columns of the arrays :math:\mathrm{x} and :math:\mathrm{z}, respectively.

**y** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit: if :math:\mathrm{irevcm} = 2, the calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

**m0** : int
On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jjf.html#fcomments>__ for further details.

On intermediate entry: :math:\mathrm{m0} must remain unchanged.

**d** : float, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{d} should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by :math:\mathrm{z}), otherwise :math:\mathrm{d} need not be set.

On final exit: the first :math:\mathrm{nconv} entries in :math:\mathrm{d} contain the eigenvalues.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then on final exit :math:\mathrm{d} contains an estimate of the eigenvalues after a single contour integral.

**z** : float, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{z} should contain an initial guess at the eigenvector search subspace, otherwise :math:\mathrm{z} need not be set.

On intermediate exit: must not be changed.

On final exit: the first :math:\mathrm{nconv} columns of :math:\mathrm{z} contain the eigenvectors corresponding to the eigenvalues found within the contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using the option setting function :meth:feast_option, then on final exit columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the current search subspace after one contour integral.

**eps** : float
On initial entry: need not be set.

**itera** : int
On initial entry: need not be set.

**resid** : float, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: need not be set.

On final exit: for :math:i = 1,\ldots,\mathrm{nconv}, :math:\mathrm{resid}[i-1] contains the relative residual, in the :math:1-norm, of the :math:i\ th eigenpair found, that is :math:\mathrm{resid}[i-1] = \left\lVert Az_i-\lambda_iBz_i\right\rVert /\left(\left\lVert Bz_i\right\rVert \times \mathrm{max}\left(\left\lvert E_{\mathrm{min}}\right\rvert, \left\lvert E_{\mathrm{max}}\right\rvert \right)\right), where :math:E_{\mathrm{min}} and :math:E_{\mathrm{max}} are the lower and upper bounds respectively of the eigenvalue search interval.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = 1

The calling program must compute a factorization of the matrix :math:\mathrm{ze}B-A suitable for solving a linear system, for example using :meth:lapacklin.zsytrf <naginterfaces.library.lapacklin.zsytrf> which computes the Bunch--Kaufman factorization. All arguments to the routine must remain unchanged.

**Note:** the factorization can be computed in single precision.

:math:\mathrm{irevcm} = 2

The calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w. The matrix :math:\mathrm{ze}B-A has previously been factorized (when :math:\mathrm{irevcm} = 1 was returned) and this factorization can be reused here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 3

The calling program must compute :math:Az, storing the result in :math:x.

:math:\mathrm{irevcm} = 4

The calling program must compute :math:Bz, storing the result in :math:x. If a standard eigenproblem is being solved (so that :math:B = I) then the calling program should set :math:x = z.

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

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On intermediate exit: contains the current point on the contour.

If :math:\mathrm{irevcm} = 1, then this must be used by the calling program to form a factorization of the matrix :math:\mathrm{ze}B-A.

**m0** : int
If the initial search subspace was found by feast_real_symm_solve to be too large, then a new smaller suitable choice is returned.

**nconv** : int
The number of eigenvalues found within the search contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set in the option setting function :meth:feast_option, then :math:\mathrm{nconv} contains a stochastic estimate of the number of eigenvalues within the search contour.

**eps** : float
The relative error on the trace. At iteration :math:k, :math:\mathrm{eps} is given by the expression :math:\left\lvert \textit{trace}_k-\textit{trace}_{{k-1}}\right\rvert /\mathrm{max}\left(\left\lvert E_{\mathrm{min}}\right\rvert, \left\lvert E_{\mathrm{max}}\right\rvert \right), where :math:\textit{trace}_k is the sum of the eigenvalues found at the :math:k\ th iteration, and :math:E_{\mathrm{min}} and :math:E_{\mathrm{max}} are the lower and upper bounds respectively of the eigenvalue search interval.

**itera** : int
The number of subspace iterations performed.

.. _f12jj-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Either the contour setting function :meth:feast_symm_contour has not been called prior to the first call of this function or the supplied :math:\mathrm{handle} has become corrupted.

(errno :math:7)
An internal error occurred in the reduced eigenvalue solver. A possible cause is that the matrix :math:B is not positive definite.

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

Constraint: :math:n\geq 1.

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

Constraint: :math:0 < \mathrm{m0}\leq n.

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

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

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

Constraint: :math:\mathrm{irevcm} = 1, :math:2, :math:3 or :math:4.

(errno :math:14)
The option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option but no nonzero elements were found in the supplied subspace.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
No eigenvalues were found within the search contour.

(errno :math:3)
The function did not converge after the maximum number of iterations.

(errno :math:4)
The size of the eigenvector search subspace, :math:\mathrm{m0}, is too small.

(errno :math:5)
The option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using :meth:feast_option. Columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the search subspace after one contour integral and :math:\mathrm{d} contains an estimate of the eigenvalues.

(errno :math:6)
The option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set using :meth:feast_option so only a stochastic estimate of the number of eigenvalues within the contour has been returned.

.. _f12jj-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx, where the coefficient matrices :math:A and :math:B are sparse, real symmetric, and :math:B is positive definite.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense, real symmetric problems.

feast_real_symm_solve is a **reverse communication** function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration.
Prior to calling feast_real_symm_solve, the contour definition function :meth:feast_symm_contour is used to specify a search interval on the real line, :math:\left[E_{\mathrm{min}}, E_{\mathrm{max}}\right], within which eigenvalues will be sought (note that the eigenvalues of real symmetric eigenproblems are themselves real). :meth:feast_symm_contour uses this interval to define nodes and weights for an elliptical contour to be used by feast_real_symm_solve.

The setup function :meth:feast_init and the contour definition function :meth:feast_symm_contour must be called before feast_real_symm_solve.
Between the calls to :meth:feast_init and :meth:feast_symm_contour, options may be set by calls to the option setting function :meth:feast_option.

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

-   compute a factorization of the matrix :math:\mathrm{ze}B-A, where :math:\mathrm{ze} is a point on the search contour;

-   solve a linear system involving :math:\mathrm{ze}B-A, using the factorization above;

-   compute the matrix product :math:x = Az;

-   compute the matrix product :math:x = Bz;

-   notify the completion of the computation.

The number of contour points, the number of iterations, and other options can all be set using the option setting function :meth:feast_option (see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params> for details on setting options and of the default settings).
The search contour itself is defined by a call to :meth:feast_symm_contour.

.. _f12jj-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError

[docs]def feast_real_gen_solve(handle, irevcm, ze, x, y, m0, d, z, eps, itera, resid, io_manager=None):
r"""
feast_real_gen_solve is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a standard or generalized eigenvalue problem defined by real nonsymmetric matrices.
This is part of a suite of functions that also includes :meth:feast_init, :meth:feast_option, :meth:feast_gen_contour and :meth:feast_custom_contour.

.. _f12jk-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jkf.html

.. _f12jk-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On initial entry: need not be set.

**x** : float, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 5, the calling program must compute :math:Az, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 6, the calling program must compute :math:A^\mathrm{T}z, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 7, the calling program must compute :math:Bz, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 8, the calling program must compute :math:B^\mathrm{T}z, storing the result in :math:x prior to re-entry.

Note: the matrices :math:x and :math:z are stored in the first :math:\mathrm{m0} columns of the arrays :math:\mathrm{x} and :math:\mathrm{z}, respectively.

**y** : complex, ndarray, shape :math:\left(n, 2\times \textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{y} should contain an initial guess at the eigenvector search subspace, otherwise :math:\mathrm{y} need not be set.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set but only right eigenvectors are to be computed, then only the first :math:\mathrm{m0} columns of :math:\mathrm{y} need to be set. However, if the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set using :meth:feast_option, so that both left and right eigenvectors are returned, then the first :math:\mathrm{m0} columns of :math:\mathrm{y} should contain the initial guess for the right eigenvector search subspace and the remaining :math:\mathrm{m0} columns should contain an initial guess for the left eigenvector search subspace.

On intermediate exit:

if :math:\mathrm{irevcm} = 2, the calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

If :math:\mathrm{irevcm} = 4, the calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

On final exit: the first :math:\mathrm{nconv} columns of :math:\mathrm{y} contain the right eigenvectors corresponding to the eigenvalues found within the contour.

Note: if the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set using :meth:feast_option, the columns :math:\mathrm{m0}+1:\mathrm{m0}+\mathrm{nconv} of :math:\mathrm{y} contain the left eigenvectors corresponding to the eigenvalues found within the contour.

Note: If the option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using the option setting function :meth:feast_option, then on final exit columns :math:1:\mathrm{m0} of :math:\mathrm{y} contain the current search subspace after one contour integral.

**m0** : int
On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jkf.html#fcomments>__ for further details.

On intermediate entry: :math:\mathrm{m0} must remain unchanged.

**d** : complex, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{d} should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by :math:\mathrm{y}), otherwise :math:\mathrm{d} need not be set.

On final exit: the first :math:\mathrm{nconv} entries in :math:\mathrm{d} contain the eigenvalues.

**z** : float, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit: must not be changed.

**eps** : float
On initial entry: need not be set.

**itera** : int
On initial entry: need not be set.

**resid** : float, ndarray, shape :math:\left(2\times \textit{m0}\right), modified in place
On initial entry: need not be set.

On final exit: for :math:i = 1,\ldots,\mathrm{nconv}, :math:\mathrm{resid}[i-1] contains the relative residual, in the :math:1-norm, of the :math:i\ th eigenpair found, that is :math:\mathrm{resid}[i-1] = \left\lVert Ay_i-\lambda_iBy_i\right\rVert /\left(\left\lVert By_i\right\rVert \times \left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right)\right), where :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

If the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set in the option setting function :meth:feast_option, the entries :math:\mathrm{m0}+1:\mathrm{m0}+\mathrm{nconv} of :math:\mathrm{resid} contain corresponding residuals for the left eigenvectors, :math:\mathrm{resid}[i-1] = \left\lVert A^\mathrm{H}y_i-\bar{\lambda }_iB^\mathrm{H}y_i\right\rVert /\left(\left\lVert B^\mathrm{H}y_i\right\rVert \times \left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right)\right).

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = 1

The calling program must compute a factorization of the matrix :math:\mathrm{ze}B-A suitable for solving a linear system, for example using :meth:sparse.complex_gen_precon_ilu <naginterfaces.library.sparse.complex_gen_precon_ilu> which computes an incomplete :math:LU factorization of a complex sparse matrix. All arguments to the routine must remain unchanged.

**Note:** the factorization can be computed in single precision.

:math:\mathrm{irevcm} = 2

The calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w. The matrix :math:\mathrm{ze}B-A has previously been factorized (when :math:\mathrm{irevcm} = 1 was returned) and this factorization can be reused here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 3

Optionally, the calling program must compute a factorization of the matrix :math:\left(\mathrm{ze}B-A\right)^\mathrm{T}. This need only be done if it is not possible to use the factorization computed when :math:\mathrm{irevcm} = 1 was returned to solve linear systems involving :math:\left(\mathrm{ze}B-A\right)^\mathrm{T}. If this factorization is to be computed, then the factorization from :math:\mathrm{irevcm} = 1 must not be overwritten.

**Note:** the factorization can be performed in single precision.

:math:\mathrm{irevcm} = 4

The calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)^\mathrm{T}w = y, overwriting :math:y with the result :math:w. If it is not possible to use the factorization of :math:\mathrm{ze}B-A (computed when :math:\mathrm{irevcm} = 1 was returned) then the factorization of :math:\left(\mathrm{ze}B-A\right)^\mathrm{T} (computed when :math:\mathrm{irevcm} = 2 was returned) should be used here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 5

The calling program must compute :math:Az, storing the result in :math:x.

:math:\mathrm{irevcm} = 6

The calling program must compute :math:A^\mathrm{T}z, storing the result in :math:x.

:math:\mathrm{irevcm} = 7

The calling program must compute :math:Bz, storing the result in :math:x. If a standard eigenproblem is being solved (so that :math:B = I) then the calling program should set :math:x = z.

:math:\mathrm{irevcm} = 8

The calling program must compute :math:B^\mathrm{T}z, storing the result in :math:x. If a standard eigenproblem is being solved (so that :math:B = I) then the calling program should set :math:x = z.

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

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On intermediate exit: contains the current point on the contour.

If :math:\mathrm{irevcm} = 1, then this must be used by the calling program to form a factorization of the matrix :math:\mathrm{ze}B-A.

If :math:\mathrm{irevcm} = 3, then, optionally, this can be used to form a factorization of :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}.

**m0** : int
If the initial search subspace was found by feast_real_gen_solve to be too large, then a new smaller suitable choice is returned.

**nconv** : int
The number of eigenvalues found within the search contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set in the option setting function :meth:feast_option, then :math:\mathrm{nconv} contains a stochastic estimate of the number of eigenvalues within the search contour.

**eps** : float
The relative error on the trace. At iteration :math:k, :math:\mathrm{eps} is given by the expression :math:\left\lvert \textit{trace}_k-\textit{trace}_{{k-1}}\right\rvert /\left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right), where :math:\textit{trace}_k is the sum of the eigenvalues found at the :math:k\ th iteration, :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

**itera** : int
The number of subspace iterations performed.

.. _f12jk-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Either one of the contour setting functions :meth:feast_gen_contour or :meth:feast_custom_contour has not been called prior to the first call of this function or the supplied :math:\mathrm{handle} has become corrupted.

(errno :math:7)
An internal error occurred in the reduced eigenvalue solver. Please contact NAG <https://www.nag.com>__.

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

Constraint: :math:n\geq 1.

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

Constraint: :math:0 < \mathrm{m0}\leq n.

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

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

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

Constraint: :math:\mathrm{irevcm} = 1, :math:2, :math:3, :math:4, :math:5, :math:6, :math:7 or :math:8.

(errno :math:14)
The function converged but the left/right eigenvector subspaces are not bi-orthonormal.

(errno :math:14)
The function converged but the right eigenvector subspace is not orthonormal.

(errno :math:15)
The option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option but no nonzero elements were found in the supplied subspace.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
No eigenvalues were found within the search contour.

(errno :math:3)
The function did not converge after the maximum number of iterations.

(errno :math:4)
The size of the eigenvector search subspace, :math:\mathrm{m0}, is too small.

(errno :math:5)
The option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using :meth:feast_option. Columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the search subspace after one contour integral and :math:\mathrm{d} contains an estimate of the eigenvalues.

(errno :math:6)
The option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set using :meth:feast_option so only a stochastic estimate of the number of eigenvalues within the contour has been returned.

.. _f12jk-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx, where the coefficient matrices :math:A and :math:B are sparse, real and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense problems.

feast_real_gen_solve is a **reverse communication** function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration.
Prior to calling feast_real_gen_solve, one of the contour definition functions :meth:feast_gen_contour or :meth:feast_custom_contour must be used to define nodes and weights for a contour around a region in the complex plane within which eigenvalues will be sought.

The setup function :meth:feast_init and the contour definition function :meth:feast_gen_contour or :meth:feast_custom_contour must be called before feast_real_gen_solve.
Between the calls to :meth:feast_init and :meth:feast_gen_contour or :meth:feast_custom_contour, options may be set by calls to the option setting function :meth:feast_option.

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

-   compute a factorization of the complex matrix :math:\mathrm{ze}B-A, where :math:\mathrm{ze} is a point on the search contour;

-   optionally, compute a factorization of the matrix :math:\left(\mathrm{ze}B-A\right)^\mathrm{H} (this need only be done if the factorization :math:\mathrm{ze}B-A does not allow linear systems involving :math:\left(\mathrm{ze}B-A\right)^\mathrm{H} to be solved);

-   solve a linear system involving :math:\mathrm{ze}B-A or :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}, using the factorizations above;

-   compute the matrix product :math:x = Az;

-   compute the matrix product :math:x = A^\mathrm{T}z;

-   compute the matrix product :math:x = Bz;

-   compute the matrix product :math:x = B^\mathrm{T}z;

-   notify the completion of the computation.

The number of contour points, the number of iterations, and other options can all be set using the option setting function :meth:feast_option (see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params> for details on setting options and of the default settings).
The search contour itself is defined by a call to :meth:feast_gen_contour or :meth:feast_custom_contour.

.. _f12jk-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError

[docs]def feast_complex_herm_solve(handle, irevcm, ze, x, y, m0, d, z, eps, itera, resid, io_manager=None):
r"""
feast_complex_herm_solve is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a standard or generalized eigenvalue problem defined by complex Hermitian matrices.
This is part of a suite of functions that also includes :meth:feast_init, :meth:feast_option and :meth:feast_symm_contour.

.. _f12jr-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jrf.html

.. _f12jr-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On initial entry: need not be set.

**x** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 5, the calling program must compute :math:Az, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 6, the calling program must compute :math:Bz, storing the result in :math:x prior to re-entry.

Note: the matrices :math:x and :math:z are stored in the first :math:\mathrm{m0} columns of the arrays :math:\mathrm{x} and :math:\mathrm{z}, respectively.

**y** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 2, the calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

If :math:\mathrm{irevcm} = 4, the calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

**m0** : int
On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jrf.html#fcomments>__ for further details.

On intermediate entry: :math:\mathrm{m0} must remain unchanged.

**d** : float, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{d} should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by :math:\mathrm{z}), otherwise :math:\mathrm{d} need not be set.

On final exit: the first :math:\mathrm{nconv} entries in :math:\mathrm{d} contain the eigenvalues.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then on final exit :math:\mathrm{d} contains an estimate of the eigenvalues after a single contour integral.

**z** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{z} should contain an initial guess at the eigenvector search subspace, otherwise :math:\mathrm{z} need not be set.

On intermediate exit: must not be changed.

On final exit: the first :math:\mathrm{nconv} columns of :math:\mathrm{z} contain the eigenvectors corresponding to the eigenvalues found within the contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using the option setting function :meth:feast_option, then on final exit columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the current search subspace after one contour integral.

**eps** : float
On initial entry: need not be set.

**itera** : int
On initial entry: need not be set.

**resid** : float, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: need not be set.

On final exit: for :math:i = 1,\ldots,\mathrm{nconv}, :math:\mathrm{resid}[i-1] contains the relative residual, in the :math:1-norm, of the :math:i\ th eigenpair found, that is :math:\mathrm{resid}[i-1] = \left\lVert Az_i-\lambda_iBz_i\right\rVert /\left(\left\lVert Bz_i\right\rVert \times \mathrm{max}\left(\left\lvert E_{\mathrm{min}}\right\rvert, \left\lvert E_{\mathrm{max}}\right\rvert \right)\right), where :math:E_{\mathrm{min}} and :math:E_{\mathrm{max}} are the lower and upper bounds respectively of the eigenvalue search interval.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = 1

The calling program must compute a factorization of the matrix :math:\mathrm{ze}B-A suitable for solving a linear system, for example using :meth:sparse.complex_gen_precon_ilu <naginterfaces.library.sparse.complex_gen_precon_ilu> which computes an incomplete :math:LU factorization of a complex sparse matrix. All arguments to the routine must remain unchanged.

**Note:** the factorization can be computed in single precision.

:math:\mathrm{irevcm} = 2

The calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w. The matrix :math:\mathrm{ze}B-A has previously been factorized (when :math:\mathrm{irevcm} = 1 was returned) and this factorization can be reused here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 3

Optionally, the calling program must compute a factorization of the matrix :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}. This need only be done if it is not possible to use the factorization computed when :math:\mathrm{irevcm} = 1 was returned to solve linear systems involving :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 4

The calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}w = y, overwriting :math:y with the result :math:w. If it is not possible to use the factorization of :math:\mathrm{ze}B-A (computed when :math:\mathrm{irevcm} = 1 was returned) then the factorization of :math:\left(\mathrm{ze}B-A\right)^\mathrm{H} (computed when :math:\mathrm{irevcm} = 2 was returned) should be used here.

:math:\mathrm{irevcm} = 5

The calling program must compute :math:Az, storing the result in :math:x.

:math:\mathrm{irevcm} = 6

The calling program must compute :math:Bz, storing the result in :math:x. If a standard eigenproblem is being solved (so that :math:B = I) then the calling program should set :math:x = z.

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

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On intermediate exit: contains the current point on the contour.

If :math:\mathrm{irevcm} = 1, then this must be used by the calling program to form a factorization of the matrix :math:\mathrm{ze}B-A.

If :math:\mathrm{irevcm} = 3, then, optionally, this can be used to form a factorization of :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}.

**m0** : int
If the initial search subspace was found by feast_complex_herm_solve to be too large, then a new smaller suitable choice is returned.

**nconv** : int
The number of eigenvalues found within the search contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set in the option setting function :meth:feast_option, then :math:\mathrm{nconv} contains a stochastic estimate of the number of eigenvalues within the search contour.

**eps** : float
The relative error on the trace. At iteration :math:k, :math:\mathrm{eps} is given by the expression :math:\left\lvert \textit{trace}_k-\textit{trace}_{{k-1}}\right\rvert /\mathrm{max}\left(\left\lvert E_{\mathrm{min}}\right\rvert, \left\lvert E_{\mathrm{max}}\right\rvert \right), where :math:\textit{trace}_k is the sum of the eigenvalues found at the :math:k\ th iteration, and :math:E_{\mathrm{min}} and :math:E_{\mathrm{max}} are the lower and upper bounds respectively of the eigenvalue search interval.

**itera** : int
The number of subspace iterations performed.

.. _f12jr-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Either the contour setting function :meth:feast_symm_contour has not been called prior to the first call of this function or the supplied :math:\mathrm{handle} has become corrupted.

(errno :math:7)
An internal error occurred in the reduced eigenvalue solver. A possible cause is that the matrix :math:B is not positive definite.

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

Constraint: :math:n\geq 1.

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

Constraint: :math:0 < \mathrm{m0}\leq n.

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

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

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

Constraint: :math:\mathrm{irevcm} = 1, :math:2, :math:3, :math:4, :math:5 or :math:6.

(errno :math:14)
The option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option but no nonzero elements were found in the supplied subspace.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
No eigenvalues were found within the search contour.

(errno :math:3)
The function did not converge after the maximum number of iterations.

(errno :math:4)
The size of the eigenvector search subspace, :math:\mathrm{m0}, is too small.

(errno :math:5)
The option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using :meth:feast_option. Columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the search subspace after one contour integral and :math:\mathrm{d} contains an estimate of the eigenvalues.

(errno :math:6)
The option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set using :meth:feast_option so only a stochastic estimate of the number of eigenvalues within the contour has been returned.

.. _f12jr-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx, where the coefficient matrices :math:A and :math:B are sparse Hermitian, and :math:B is positive definite.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense, Hermitian problems.

feast_complex_herm_solve is a **reverse communication** function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration.
Prior to calling feast_complex_herm_solve, the contour definition function :meth:feast_symm_contour is used to specify a search interval on the real line, :math:\left[E_{\mathrm{min}}, E_{\mathrm{max}}\right], within which eigenvalues will be sought (note that the eigenvalues of complex Hermitian eigenproblems are themselves real). :meth:feast_symm_contour uses this interval to define nodes and weights for an elliptical contour to be used by feast_complex_herm_solve.

The setup function :meth:feast_init and the contour definition function :meth:feast_symm_contour must be called before feast_complex_herm_solve.
Between the calls to :meth:feast_init and :meth:feast_symm_contour, options may be set by calls to the option setting function :meth:feast_option.

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

-   compute a factorization of the matrix :math:\mathrm{ze}B-A, where :math:\mathrm{ze} is a point on the search contour;

-   optionally, compute a factorization of the matrix :math:\left(\mathrm{ze}B-A\right)^\mathrm{H} (this need only be done if the factorization :math:\mathrm{ze}B-A does not allow linear systems involving :math:\left(\mathrm{ze}B-A\right)^\mathrm{H} to be solved);

-   solve a linear system involving :math:\mathrm{ze}B-A or :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}, using the factorizations above;

-   compute the matrix product :math:x = Az;

-   compute the matrix product :math:x = Bz;

-   notify the completion of the computation.

The number of contour points, the number of iterations, and other options can all be set using the option setting function :meth:feast_option (see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params> for details on setting options and of the default settings).
The search contour itself is defined by a call to :meth:feast_symm_contour.

.. _f12jr-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError

[docs]def feast_complex_symm_solve(handle, irevcm, ze, x, y, m0, d, z, eps, itera, resid, io_manager=None):
r"""
feast_complex_symm_solve is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a standard or generalized eigenvalue problem defined by complex symmetric matrices.
This is part of a suite of functions that also includes :meth:feast_init, :meth:feast_option, :meth:feast_gen_contour and :meth:feast_custom_contour.

.. _f12js-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jsf.html

.. _f12js-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On initial entry: need not be set.

**x** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 3, the calling program must compute :math:Az, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 4, the calling program must compute :math:Bz, storing the result in :math:x prior to re-entry.

Note: the matrices :math:x and :math:z are stored in the first :math:\mathrm{m0} columns of the arrays :math:\mathrm{x} and :math:\mathrm{z}, respectively.

**y** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 2, the calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

**m0** : int
On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jsf.html#fcomments>__ for further details.

On intermediate entry: :math:\mathrm{m0} must remain unchanged.

**d** : complex, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{d} should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by :math:\mathrm{z}), otherwise :math:\mathrm{d} need not be set.

On final exit: the first :math:\mathrm{nconv} entries in :math:\mathrm{d} contain the eigenvalues.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then on final exit :math:\mathrm{d} contains an estimate of the eigenvalues after a single contour integral.

**z** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{z} should contain an initial guess at the eigenvector search subspace, otherwise :math:\mathrm{z} need not be set.

On intermediate exit: must not be changed.

On final exit: the first :math:\mathrm{nconv} columns of :math:\mathrm{z} contain the eigenvectors corresponding to the eigenvalues found within the contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using the option setting function :meth:feast_option, then on final exit columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the current search subspace after one contour integral.

**eps** : float
On initial entry: need not be set.

**itera** : int
On initial entry: need not be set.

**resid** : float, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: need not be set.

On final exit: for :math:i = 1,\ldots,\mathrm{nconv}, :math:\mathrm{resid}[i-1] contains the relative residual, in the :math:1-norm, of the :math:i\ th eigenpair found, that is :math:\mathrm{resid}[i-1] = \left\lVert Az_i-\lambda_iBz_i\right\rVert /\left(\left\lVert Bz_i\right\rVert \times \left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right)\right), where :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = 1

The calling program must compute a factorization of the matrix :math:\mathrm{ze}B-A suitable for solving a linear system, for example using :meth:lapacklin.zsytrf <naginterfaces.library.lapacklin.zsytrf> which computes the Bunch--Kaufman factorization. All arguments to the routine must remain unchanged.

**Note:** the factorization can be computed in single precision.

:math:\mathrm{irevcm} = 2

The calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w. The matrix :math:\mathrm{ze}B-A has previously been factorized (when :math:\mathrm{irevcm} = 1 was returned) and this factorization can be reused here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 3

The calling program must compute :math:Az, storing the result in :math:x.

:math:\mathrm{irevcm} = 4

The calling program must compute :math:Bz, storing the result in :math:x. If a standard eigenproblem is being solved (so that :math:B = I) then the calling program should set :math:x = z.

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

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On intermediate exit: contains the current point on the contour.

If :math:\mathrm{irevcm} = 1, then this must be used by the calling program to form a factorization of the matrix :math:\mathrm{ze}B-A.

**m0** : int
If the initial search subspace was found by feast_complex_symm_solve to be too large, then a new smaller suitable choice is returned.

**nconv** : int
The number of eigenvalues found within the search contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set in the option setting function :meth:feast_option, then :math:\mathrm{nconv} contains a stochastic estimate of the number of eigenvalues within the search contour.

**eps** : float
The relative error on the trace. At iteration :math:k, :math:\mathrm{eps} is given by the expression :math:\left\lvert \textit{trace}_k-\textit{trace}_{{k-1}}\right\rvert /\left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right), where :math:\textit{trace}_k is the sum of the eigenvalues found at the :math:k\ th iteration, :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

**itera** : int
The number of subspace iterations performed.

.. _f12js-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Either the contour setting function :meth:feast_symm_contour has not been called prior to the first call of this function or the supplied :math:\mathrm{handle} has become corrupted.

(errno :math:7)
An internal error occurred in the reduced eigenvalue solver. A possible cause is that the matrix :math:B is not positive definite.

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

Constraint: :math:n\geq 1.

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

Constraint: :math:0 < \mathrm{m0}\leq n.

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

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

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

Constraint: :math:\mathrm{irevcm} = 1, :math:2, :math:3 or :math:4.

(errno :math:14)
The function converged but the eigenvector subspace is not orthonormal.

(errno :math:15)
The option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option but no nonzero elements were found in the supplied subspace.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
No eigenvalues were found within the search contour.

(errno :math:3)
The function did not converge after the maximum number of iterations.

(errno :math:4)
The size of the eigenvector search subspace, :math:\mathrm{m0}, is too small.

(errno :math:5)
The option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using :meth:feast_option. Columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the search subspace after one contour integral and :math:\mathrm{d} contains an estimate of the eigenvalues.

(errno :math:6)
The option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set using :meth:feast_option so only a stochastic estimate of the number of eigenvalues within the contour has been returned.

.. _f12js-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx, where the coefficient matrices :math:A and :math:B are sparse, complex and symmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense, symmetric problems.

feast_complex_symm_solve is a **reverse communication** function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration.
Prior to calling feast_complex_symm_solve, one of the contour definition functions :meth:feast_gen_contour or :meth:feast_custom_contour must be used to define nodes and weights for a contour around a region in the complex plane within which eigenvalues will be sought.

The setup function :meth:feast_init and the contour definition function :meth:feast_gen_contour or :meth:feast_custom_contour must be called before feast_complex_symm_solve.
Between the calls to :meth:feast_init and :meth:feast_gen_contour or :meth:feast_custom_contour, options may be set by calls to the option setting function :meth:feast_option.

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

-   compute a factorization of the matrix :math:\mathrm{ze}B-A, where :math:\mathrm{ze} is a point on the search contour;

-   solve a linear system involving :math:\mathrm{ze}B-A, using the factorization above;

-   compute the matrix product :math:x = Az;

-   compute the matrix product :math:x = Bz;

-   notify the completion of the computation.

The number of contour points, the number of iterations, and other options can all be set using the option setting function :meth:feast_option (see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params> for details on setting options and of the default settings).
The search contour itself is defined by a call to :meth:feast_gen_contour or :meth:feast_custom_contour.

.. _f12js-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError

[docs]def feast_complex_gen_solve(handle, irevcm, ze, x, y, m0, d, z, eps, itera, resid, io_manager=None):
r"""
feast_complex_gen_solve is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a standard or generalized eigenvalue problem defined by complex nonsymmetric matrices.
This is part of a suite of functions that also includes :meth:feast_init, :meth:feast_option, :meth:feast_gen_contour and :meth:feast_custom_contour.

.. _f12jt-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jtf.html

.. _f12jt-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On initial entry: need not be set.

**x** : complex, ndarray, shape :math:\left(n, 2\times \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 5, the calling program must compute :math:Az, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 6, the calling program must compute :math:A^\mathrm{H}z, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 7, the calling program must compute :math:Bz, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 8, the calling program must compute :math:B^\mathrm{H}z, storing the result in :math:x prior to re-entry.

Note: the matrices :math:x and :math:z are stored in the first :math:\mathrm{m0} columns of the arrays :math:\mathrm{x} and :math:\mathrm{z}, respectively.

**y** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 2, the calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

If :math:\mathrm{irevcm} = 4, the calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

**m0** : int
On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jtf.html#fcomments>__ for further details.

On intermediate entry: :math:\mathrm{m0} must remain unchanged.

**d** : complex, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{d} should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by :math:\mathrm{z}), otherwise :math:\mathrm{d} need not be set.

On final exit: the first :math:\mathrm{nconv} entries in :math:\mathrm{d} contain the eigenvalues.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then on final exit :math:\mathrm{d} contains an estimate of the eigenvalues after a single contour integral.

**z** : complex, ndarray, shape :math:\left(n, 2\times \textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{z} should contain an initial guess at the eigenvector search subspace, otherwise :math:\mathrm{z} need not be set.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set but only right eigenvectors are to be computed, then only the first :math:\mathrm{m0} columns of :math:\mathrm{z} need to be set. However, if the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set using :meth:feast_option, so that both left and right eigenvectors are returned, then the first :math:\mathrm{m0} columns of :math:\mathrm{z} should contain the initial guess for the right eigenvector search subspace and the remaining :math:\mathrm{m0} columns should contain an initial guess for the left eigenvector search subspace.

On intermediate exit: must not be changed.

On final exit: the first :math:\mathrm{nconv} columns of :math:\mathrm{z} contain the right eigenvectors corresponding to the eigenvalues found within the contour. If the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set in the option setting function :meth:feast_option, the columns :math:\mathrm{m0}+1:\mathrm{m0}+\mathrm{nconv} of :math:\mathrm{z} contain the left eigenvectors corresponding to the eigenvalues found within the contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using the option setting function :meth:feast_option, then on final exit columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the current search subspace after one contour integral.

**eps** : float
On initial entry: need not be set.

**itera** : int
On initial entry: need not be set.

**resid** : float, ndarray, shape :math:\left(2\times \textit{m0}\right), modified in place
On initial entry: need not be set.

On final exit: for :math:i = 1,\ldots,\mathrm{nconv}, :math:\mathrm{resid}[i-1] contains the relative residual, in the :math:1-norm, of the :math:i\ th eigenpair found, that is :math:\mathrm{resid}[i-1] = \left\lVert Az_i-\lambda_iBz_i\right\rVert /\left(\left\lVert Bz_i\right\rVert \times \left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right)\right), where :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

If the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set in the option setting function :meth:feast_option, the entries :math:\mathrm{m0}+1:\mathrm{m0}+\mathrm{nconv} of :math:\mathrm{resid} contain corresponding residuals for the left eigenvectors, :math:\mathrm{resid}[i-1] = \left\lVert A^\mathrm{H}z_i-\bar{\lambda }_iB^\mathrm{H}z_i\right\rVert /\left(\left\lVert B^\mathrm{H}z_i\right\rVert \times \left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right)\right).

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = 1

The calling program must compute a factorization of the matrix :math:\mathrm{ze}B-A suitable for solving a linear system, for example using :meth:sparse.complex_gen_precon_ilu <naginterfaces.library.sparse.complex_gen_precon_ilu> which computes an incomplete :math:LU factorization of a complex sparse matrix. All arguments to the routine must remain unchanged.

**Note:** the factorization can be computed in single precision.

:math:\mathrm{irevcm} = 2

The calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)w = y, overwriting :math:y with the result :math:w. The matrix :math:\mathrm{ze}B-A has previously been factorized (when :math:\mathrm{irevcm} = 1 was returned) and this factorization can be reused here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 3

Optionally, the calling program must compute a factorization of the matrix :math:\left(\mathrm{ze}B-A\right)^\mathrm{T}. This need only be done if it is not possible to use the factorization computed when :math:\mathrm{irevcm} = 1 was returned to solve linear systems involving :math:\left(\mathrm{ze}B-A\right)^\mathrm{T}. If this factorization is to be computed, then the factorization from :math:\mathrm{irevcm} = 1 must not be overwritten.

**Note:** the factorization can be performed in single precision.

:math:\mathrm{irevcm} = 4

The calling program must compute the solution to the linear system :math:\left(\mathrm{ze}B-A\right)^\mathrm{T}w = y, overwriting :math:y with the result :math:w. If it is not possible to use the factorization of :math:\mathrm{ze}B-A (computed when :math:\mathrm{irevcm} = 1 was returned) then the factorization of :math:\left(\mathrm{ze}B-A\right)^\mathrm{T} (computed when :math:\mathrm{irevcm} = 2 was returned) should be used here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 5

The calling program must compute :math:Az, storing the result in :math:x.

:math:\mathrm{irevcm} = 6

The calling program must compute :math:A^\mathrm{T}z, storing the result in :math:x.

:math:\mathrm{irevcm} = 7

The calling program must compute :math:Bz, storing the result in :math:x. If a standard eigenproblem is being solved (so that :math:B = I) then the calling program should set :math:x = z.

:math:\mathrm{irevcm} = 8

The calling program must compute :math:B^\mathrm{T}z, storing the result in :math:x. If a standard eigenproblem is being solved (so that :math:B = I) then the calling program should set :math:x = z.

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

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On intermediate exit: contains the current point on the contour.

If :math:\mathrm{irevcm} = 1, then this must be used by the calling program to form a factorization of the matrix :math:\mathrm{ze}B-A.

If :math:\mathrm{irevcm} = 3, then, optionally, this can be used to form a factorization of :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}.

**m0** : int
If the initial search subspace was found by feast_complex_gen_solve to be too large, then a new smaller suitable choice is returned.

**nconv** : int
The number of eigenvalues found within the search contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set in the option setting function :meth:feast_option, then :math:\mathrm{nconv} contains a stochastic estimate of the number of eigenvalues within the search contour.

**eps** : float
The relative error on the trace. At iteration :math:k, :math:\mathrm{eps} is given by the expression :math:\left\lvert \textit{trace}_k-\textit{trace}_{{k-1}}\right\rvert /\left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right), where :math:\textit{trace}_k is the sum of the eigenvalues found at the :math:k\ th iteration, :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

**itera** : int
The number of subspace iterations performed.

.. _f12jt-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Either one of the contour setting functions :meth:feast_gen_contour or :meth:feast_custom_contour has not been called prior to the first call of this function or the supplied :math:\mathrm{handle} has become corrupted.

(errno :math:7)
An internal error occurred in the reduced eigenvalue solver. Please contact NAG <https://www.nag.com>__.

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

Constraint: :math:n\geq 1.

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

Constraint: :math:0 < \mathrm{m0}\leq n.

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

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

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

Constraint: :math:\mathrm{irevcm} = 1, :math:2, :math:3, :math:4, :math:5, :math:6, :math:7 or :math:8.

(errno :math:14)
The function converged but the left/right eigenvector subspaces are not bi-orthonormal.

(errno :math:14)
The function converged but the right eigenvector subspace is not orthonormal.

(errno :math:15)
The option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option but no nonzero elements were found in the supplied subspace.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
No eigenvalues were found within the search contour.

(errno :math:3)
The function did not converge after the maximum number of iterations.

(errno :math:4)
The size of the eigenvector search subspace, :math:\mathrm{m0}, is too small.

(errno :math:5)
The option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using :meth:feast_option. Columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the search subspace after one contour integral and :math:\mathrm{d} contains an estimate of the eigenvalues.

(errno :math:6)
The option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set using :meth:feast_option so only a stochastic estimate of the number of eigenvalues within the contour has been returned.

.. _f12jt-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a standard eigenvalue problem :math:Ax = \lambda x, or of a generalized eigenvalue problem :math:Ax = \lambda Bx, where the coefficient matrices :math:A and :math:B are sparse, complex and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense problems.

feast_complex_gen_solve is a **reverse communication** function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration.
Prior to calling feast_complex_gen_solve, one of the contour definition functions :meth:feast_gen_contour or :meth:feast_custom_contour must be used to define nodes and weights for a contour around a region in the complex plane within which eigenvalues will be sought.

The setup function :meth:feast_init and one of the contour definition functions :meth:feast_gen_contour or :meth:feast_custom_contour must be called before feast_complex_gen_solve.
Between the calls to :meth:feast_init and :meth:feast_gen_contour or :meth:feast_custom_contour, options may be set by calls to the option setting function :meth:feast_option.

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

-   compute a factorization of the matrix :math:\mathrm{ze}B-A, where :math:\mathrm{ze} is a point on the search contour;

-   optionally, compute a factorization of the matrix :math:\left(\mathrm{ze}B-A\right)^\mathrm{H} (this need only be done if the factorization :math:\mathrm{ze}B-A does not allow linear systems involving :math:\left(\mathrm{ze}B-A\right)^\mathrm{H} to be solved);

-   solve a linear system involving :math:\mathrm{ze}B-A or :math:\left(\mathrm{ze}B-A\right)^\mathrm{H}, using the factorizations above;

-   compute the matrix product :math:x = Az;

-   compute the matrix product :math:x = Bz;

-   compute the matrix product :math:x = A^\mathrm{H}z;

-   compute the matrix product :math:x = B^\mathrm{H}z;

-   notify the completion of the computation.

The number of contour points, the number of iterations, and other options can all be set using the option setting function :meth:feast_option (see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params> for details on setting options and of the default settings).
The search contour itself is defined by a call to either :meth:feast_gen_contour (for elliptical contours) or :meth:feast_custom_contour (for general contours).

.. _f12jt-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError

[docs]def feast_poly_symm_solve(handle, irevcm, deg, ze, x, y, m0, d, z, eps, itera, resid, io_manager=None):
r"""
feast_poly_symm_solve is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a polynomial eigenvalue problem defined by complex symmetric matrices.
This is part of a suite of functions that also includes :meth:feast_init, :meth:feast_option, :meth:feast_gen_contour and :meth:feast_custom_contour.

.. _f12ju-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12juf.html

.. _f12ju-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**deg** : int
The degree, :math:p, of the polynomial eigenvalue problem.

**ze** : complex
On initial entry: need not be set.

**x** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 3, the calling program must compute :math:A_kz, storing the result in :math:x prior to re-entry.

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

Note: the matrices :math:x and :math:z are stored in the first :math:\mathrm{m0} columns of the arrays :math:\mathrm{x} and :math:\mathrm{z}, respectively.

**y** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 2, the calling program must compute the solution to the linear system :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

**m0** : int
On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12juf.html#fcomments>__ for further details.

On intermediate entry: :math:\mathrm{m0} must remain unchanged.

**d** : complex, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{d} should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by :math:\mathrm{z}), otherwise :math:\mathrm{d} need not be set.

On final exit: the first :math:\mathrm{nconv} entries in :math:\mathrm{d} contain the eigenvalues.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then on final exit :math:\mathrm{d} contains an estimate of the eigenvalues after a single contour integral.

**z** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{z} should contain an initial guess at the eigenvector search subspace, otherwise :math:\mathrm{z} need not be set.

On intermediate exit: must not be changed.

On final exit: the first :math:\mathrm{nconv} columns of :math:\mathrm{z} contain the eigenvectors corresponding to the eigenvalues found within the contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using the option setting function :meth:feast_option, then on final exit columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the current search subspace after one contour integral.

**eps** : float
On initial entry: need not be set.

**itera** : int
On initial entry: need not be set.

**resid** : float, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: need not be set.

On final exit: for :math:i = 1,\ldots,\mathrm{nconv}, :math:\mathrm{resid}[i-1] contains the relative residual, in the :math:1-norm, of the :math:i\ th eigenpair found, that is :math:\mathrm{resid}[i-1] = \left\lVert \left(∑_{{j = 0}}^p\lambda_i^jA_j\right)z_i\right\rVert /\left(\left\lVert \lambda^pA_pz_i\right\rVert \times \left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right)\right), where :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = 1

The calling program must compute a factorization of the matrix :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i suitable for solving a linear system, for example using :meth:sparse.complex_gen_precon_ilu <naginterfaces.library.sparse.complex_gen_precon_ilu> which computes an incomplete :math:LU factorization of a complex sparse matrix. All arguments to the routine must remain unchanged.

**Note:** the factorization can be computed in single precision.

:math:\mathrm{irevcm} = 2

The calling program must compute the solution to the linear system :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)w = y, overwriting :math:y with the result :math:w. The matrix :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i has previously been factorized (when :math:\mathrm{irevcm} = 1 was returned) and this factorization can be reused here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 3

The calling program must compute :math:A_kz, storing the result in :math:x.

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

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On intermediate exit: contains the current point on the contour.

If :math:\mathrm{irevcm} = 1, then this must be used by the calling program to form a factorization of the matrix :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i.

**k** : int
On intermediate exit:

if :math:\mathrm{irevcm} = 3, denotes which of the coefficient matrices :math:A_k needs to be used to form :math:A_kz.

**m0** : int
If the initial search subspace was found by feast_poly_symm_solve to be too large, then a new smaller suitable choice is returned.

**nconv** : int
The number of eigenvalues found within the search contour.

**eps** : float
The relative error on the trace. At iteration :math:k, :math:\mathrm{eps} is given by the expression :math:\left\lvert \textit{trace}_k-\textit{trace}_{{k-1}}\right\rvert /\left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right), where :math:\textit{trace}_k is the sum of the eigenvalues found at the :math:k\ th iteration, :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

**itera** : int
The number of subspace iterations performed.

.. _f12ju-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Either the contour setting function :meth:feast_symm_contour has not been called prior to the first call of this function or the supplied :math:\mathrm{handle} has become corrupted.

(errno :math:7)
An internal error occurred in the reduced eigenvalue solver. Please contact NAG <https://www.nag.com>__.

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

Constraint: :math:n\geq 1.

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

Constraint: :math:0 < \mathrm{m0}\leq n.

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

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

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

Constraint: :math:\mathrm{irevcm} = 1, :math:2, :math:3, :math:4, :math:5 or :math:6.

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

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

(errno :math:15)
The option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option but no nonzero elements were found in the supplied subspace.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
No eigenvalues were found within the search contour.

(errno :math:3)
The function did not converge after the maximum number of iterations.

(errno :math:4)
The size of the eigenvector search subspace, :math:\mathrm{m0}, is too small.

(errno :math:5)
The option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using :meth:feast_option. Columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the search subspace after one contour integral and :math:\mathrm{d} contains an estimate of the eigenvalues.

(errno :math:6)
The option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set using :meth:feast_option. :math:\mathrm{nconv} contains a stochastic estimate of the number of eigenvalues within the contour.

.. _f12ju-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a polynomial eigenvalue problem :math:∑_{{i = 0}}^p\lambda^iA_ix = 0 where the coefficient matrices :math:A_i are sparse, complex and symmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense problems.

feast_poly_symm_solve is a **reverse communication** function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration.
Prior to calling feast_poly_symm_solve, one of the contour definition functions :meth:feast_gen_contour or :meth:feast_custom_contour must be used to define nodes and weights for a contour around a region in the complex plane within which eigenvalues will be sought. :meth:feast_gen_contour or :meth:feast_custom_contour uses this interval to define nodes and weights for the contour to be used by feast_poly_symm_solve.

The setup function :meth:feast_init and one of the contour definition functions :meth:feast_gen_contour or :meth:feast_custom_contour must be called before feast_poly_symm_solve.
Between the calls to :meth:feast_init and :meth:feast_gen_contour or :meth:feast_custom_contour, options may be set by calls to the option setting function :meth:feast_option.

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

-   compute a factorization of the matrix :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i, where :math:\mathrm{ze} is a point on the search contour;

-   solve a linear system involving :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i using the factorizations above;

-   compute the matrix product :math:x = A_kz, for a given value of :math:k;

-   notify the completion of the computation.

The number of contour points, the number of iterations, and other options can all be set using the option setting function :meth:feast_option (see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params> for details on setting options and of the default settings).
The search contour itself is defined by a call to :meth:feast_gen_contour or :meth:feast_custom_contour.

.. _f12ju-py2-py-references:

**References**
Gavin, B, Międlar, A and Polizzi, E, 2018, FEAST Eigensolver for Nonlinear Eigenvalue Problems, J. Comput. Phys. (27), 107

Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError

[docs]def feast_poly_gen_solve(handle, irevcm, deg, ze, x, y, m0, d, z, eps, itera, resid, io_manager=None):
r"""
feast_poly_gen_solve is an iterative solver used to find some of the eigenvalues and the corresponding eigenvectors of a polynomial eigenvalue problem defined by complex nonsymmetric matrices.
This is part of a suite of functions that also includes :meth:feast_init, :meth:feast_option, :meth:feast_gen_contour and :meth:feast_custom_contour.

.. _f12jv-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jvf.html

.. _f12jv-py2-py-parameters:

**Parameters**
**handle** : Handle
The handle to the internal data structure used by the NAG FEAST suite. It needs to be initialized by :meth:feast_init. **It must not be changed between calls to the NAG FEAST suite.**

**irevcm** : int
On initial entry: :math:\mathrm{irevcm} = 0, otherwise an error condition will be raised.

On intermediate entry: must be unchanged from its previous exit value. Changing :math:\mathrm{irevcm} to any other value between calls will result in an error.

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**deg** : int
The degree, :math:p, of the polynomial eigenvalue problem.

**ze** : complex
On initial entry: need not be set.

**x** : complex, ndarray, shape :math:\left(n, 2\times \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 5, the calling program must compute :math:A_kz, storing the result in :math:x prior to re-entry.

If :math:\mathrm{irevcm} = 6, the calling program must compute :math:A_k^\mathrm{H}z, storing the result in :math:x prior to re-entry.

Note: the matrices :math:x and :math:z are stored in the first :math:\mathrm{m0} columns of the arrays :math:\mathrm{x} and :math:\mathrm{z}, respectively.

**y** : complex, ndarray, shape :math:\left(n, \textit{m0}\right), modified in place
On initial entry: need not be set.

On intermediate exit:

if :math:\mathrm{irevcm} = 2, the calling program must compute the solution to the linear system :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

If :math:\mathrm{irevcm} = 4, the calling program must compute the solution to the linear system :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H}w = y, overwriting :math:y with the result :math:w, prior to re-entry. The linear system has :math:\mathrm{m0} right-hand sides.

**m0** : int
On initial entry: the size of the search subspace used to find the eigenvalues. This should exceed the number of eigenvalues within the search contour. See Further Comments <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jvf.html#fcomments>__ for further details.

On intermediate entry: :math:\mathrm{m0} must remain unchanged.

**d** : complex, ndarray, shape :math:\left(\textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{d} should contain an initial guess at the eigenvalues lying within the eigenvector search subspace (this subspace should be specified by :math:\mathrm{z}), otherwise :math:\mathrm{d} need not be set.

On final exit: the first :math:\mathrm{nconv} entries in :math:\mathrm{d} contain the eigenvalues.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then on final exit :math:\mathrm{d} contains an estimate of the eigenvalues after a single contour integral.

**z** : complex, ndarray, shape :math:\left(n, 2\times \textit{m0}\right), modified in place
On initial entry: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option, then :math:\mathrm{z} should contain an initial guess at the eigenvector search subspace, otherwise :math:\mathrm{z} need not be set.

Note: if the option :math:\text{‘Subspace'} = \texttt{'Yes'} was set but only right eigenvectors are to be computed, then only the first :math:\mathrm{m0} columns of :math:\mathrm{z} need to be set. However, if the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set using :meth:feast_option, so that both left and right eigenvectors are returned, then the first :math:\mathrm{m0} columns of :math:\mathrm{z} should contain the initial guess for the right eigenvector search subspace and the remaining :math:\mathrm{m0} columns should contain an initial guess for the left eigenvector search subspace.

On intermediate exit: must not be changed.

On final exit: the first :math:\mathrm{nconv} columns of :math:\mathrm{z} contain the right eigenvectors corresponding to the eigenvalues found within the contour. If the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set in the option setting function :meth:feast_option, the columns :math:\mathrm{m0}+1:\mathrm{m0}+\mathrm{nconv} of :math:\mathrm{z} contain the left eigenvectors corresponding to the eigenvalues found within the contour.

Note: if the option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using the option setting function :meth:feast_option, then on final exit columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the current search subspace after one contour integral.

**eps** : float
On initial entry: need not be set.

**itera** : int
On initial entry: need not be set.

**resid** : float, ndarray, shape :math:\left(2\times \textit{m0}\right), modified in place
On initial entry: need not be set.

On final exit: for :math:i = 1,\ldots,\mathrm{nconv}, :math:\mathrm{resid}[i-1] contains the relative residual, in the :math:1-norm, of the :math:i\ th eigenpair found, that is :math:\mathrm{resid}[i-1] = \left\lVert \left(∑_{{j = 0}}^p\lambda_i^jA_j\right)z_i\right\rVert /\left(\left\lVert \lambda^pA_pz_i\right\rVert \times \left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right)\right), where :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

If the option :math:\text{‘Eigenvectors'} = \texttt{'Two-sided'} was set in the option setting function :meth:feast_option, the entries :math:\mathrm{m0}+1:\mathrm{m0}+\mathrm{nconv} of :math:\mathrm{resid} contain corresponding residuals for the left eigenvectors, :math:\mathrm{resid}[i-1] = \left\lVert \left(∑_{{j = 0}}^p\lambda_i^jA_j\right)^\mathrm{H}z_i\right\rVert /\left(\left\lVert \lambda^pA_p^\mathrm{H}z_i\right\rVert \times \left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right)\right).

**io_manager** : FileObjManager, optional
Manager for I/O in this routine.

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

:math:\mathrm{irevcm} = 1

The calling program must compute a factorization of the matrix :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i suitable for solving a linear system, for example using :meth:sparse.complex_gen_precon_ilu <naginterfaces.library.sparse.complex_gen_precon_ilu> which computes an incomplete :math:LU factorization of a complex sparse matrix. All arguments to the routine must remain unchanged.

**Note:** the factorization can be computed in single precision.

:math:\mathrm{irevcm} = 2

The calling program must compute the solution to the linear system :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)w = y, overwriting :math:y with the result :math:w. The matrix :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i has previously been factorized (when :math:\mathrm{irevcm} = 1 was returned) and this factorization can be reused here.

**Note:** the solve can be performed in single precision.

:math:\mathrm{irevcm} = 3

Optionally, the calling program must compute a factorization of the matrix :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H}. This need only be done if it is not possible to use the factorization computed when :math:\mathrm{irevcm} = 1 was returned to solve linear systems involving :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H}. If this factorization is to be computed, then the factorization from :math:\mathrm{irevcm} = 1 must not be overwritten.

**Note:** the factorization can be performed in single precision.

:math:\mathrm{irevcm} = 4

The calling program must compute the solution to the linear system :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H}w = y, overwriting :math:y with the result :math:w. If it is not possible to use the factorization of :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i (computed when :math:\mathrm{irevcm} = 1 was returned) then the factorization of :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H} (computed when :math:\mathrm{irevcm} = 2 was returned) should be used here.

**Note:** the factorization can be performed in single precision.

:math:\mathrm{irevcm} = 5

The calling program must compute :math:A_kz, storing the result in :math:x.

:math:\mathrm{irevcm} = 6

The calling program must compute :math:A_k^\mathrm{H}z, storing the result in :math:x.

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

Note: the matrices :math:x, :math:y and :math:z referred to in this section are all of size :math:n\times \mathrm{m0} and are stored in the arrays :math:\mathrm{x}, :math:\mathrm{y} and :math:\mathrm{z}, respectively.

**ze** : complex
On intermediate exit: contains the current point on the contour.

If :math:\mathrm{irevcm} = 1, then this must be used by the calling program to form a factorization of the matrix :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i.

If :math:\mathrm{irevcm} = 3, then, optionally, this can be used to form a factorization of :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H}.

**k** : int
On intermediate exit:

if :math:\mathrm{irevcm} = 5, denotes which of the coefficient matrices :math:A_k needs to be used to form :math:A_kz.

If :math:\mathrm{irevcm} = 6, denotes which of the coefficient matrices :math:A_k needs to be used to form :math:A_k^\mathrm{H}z.

**m0** : int
If the initial search subspace was found by feast_poly_gen_solve to be too large, then a new smaller suitable choice is returned.

**nconv** : int
The number of eigenvalues found within the search contour.

**eps** : float
The relative error on the trace. At iteration :math:k, :math:\mathrm{eps} is given by the expression :math:\left\lvert \textit{trace}_k-\textit{trace}_{{k-1}}\right\rvert /\left(\left\lvert E_{\mathrm{mid}}\right\rvert +r\right), where :math:\textit{trace}_k is the sum of the eigenvalues found at the :math:k\ th iteration, :math:E_{\mathrm{mid}} is the centre of mass of the contour and :math:r is the radius of the circle, centred at :math:E_{\mathrm{mid}} which just encloses the contour.

**itera** : int
The number of subspace iterations performed.

.. _f12jv-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
Either one of the contour setting functions :meth:feast_gen_contour or :meth:feast_custom_contour has not been called prior to the first call of this function or the supplied :math:\mathrm{handle} has become corrupted.

(errno :math:7)
An internal error occurred in the reduced eigenvalue solver. Please contact NAG <https://www.nag.com>__.

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

Constraint: :math:n\geq 1.

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

Constraint: :math:0 < \mathrm{m0}\leq n.

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

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

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

Constraint: :math:\mathrm{irevcm} = 1, :math:2, :math:3, :math:4, :math:5 or :math:6.

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

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

(errno :math:15)
The option :math:\text{‘Subspace'} = \texttt{'Yes'} was set using the option setting function :meth:feast_option but no nonzero elements were found in the supplied subspace.

**Warns**
**NagAlgorithmicWarning**
(errno :math:2)
No eigenvalues were found within the search contour.

(errno :math:3)
The function did not converge after the maximum number of iterations.

(errno :math:4)
The size of the eigenvector search subspace, :math:\mathrm{m0}, is too small.

(errno :math:5)
The option :math:\text{‘Execution Mode'} = \texttt{'Subspace'} was set using :meth:feast_option. Columns :math:1:\mathrm{m0} of :math:\mathrm{z} contain the search subspace after one contour integral and :math:\mathrm{d} contains an estimate of the eigenvalues.

(errno :math:6)
The option :math:\text{‘Execution Mode'} = \texttt{'Estimate'} was set using :meth:feast_option. :math:\mathrm{nconv} contains a stochastic estimate of the number of eigenvalues within the contour.

.. _f12jv-py2-py-notes:

**Notes**
The suite of functions is designed to calculate some of the eigenvalues, :math:\lambda, and the corresponding eigenvectors, :math:x, of a polynomial eigenvalue problem :math:∑_{{i = 0}}^p\lambda^iA_ix = 0 where the coefficient matrices :math:A_i are sparse, complex and nonsymmetric.
The suite can also be used to find selected eigenvalues/eigenvectors of smaller scale, dense problems.

feast_poly_gen_solve is a **reverse communication** function, based on the FEAST eigensolver, described in Polizzi (2009), which finds eigenvalues using contour integration.
Prior to calling feast_poly_gen_solve, one of the contour definition functions :meth:feast_gen_contour or :meth:feast_custom_contour must be used to define nodes and weights for a contour around a region in the complex plane within which eigenvalues will be sought. :meth:feast_gen_contour or :meth:feast_custom_contour uses this interval to define nodes and weights for the contour to be used by feast_poly_gen_solve.

The setup function :meth:feast_init and one of the contour definition functions :meth:feast_gen_contour or :meth:feast_custom_contour must be called before feast_poly_gen_solve.
Between the calls to :meth:feast_init and :meth:feast_gen_contour or :meth:feast_custom_contour, options may be set by calls to the option setting function :meth:feast_option.

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

-   compute a factorization of the matrix :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i, where :math:\mathrm{ze} is a point on the search contour;

-   optionally, compute a factorization of the matrix :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H} (this need only be done if the factorization :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i does not allow linear systems involving :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H} to be solved);

-   solve a linear system involving :math:∑_{{i = 0}}^p\mathrm{ze}^iA_i or :math:\left(∑_{{i = 0}}^p\mathrm{ze}^iA_i\right)^\mathrm{H}, using the factorizations above;

-   compute the matrix product :math:x = A_kz, for a given value of :math:k;

-   compute the matrix product :math:x = A^\mathrm{H}_kz, for a given value of :math:k;

-   notify the completion of the computation.

The number of contour points, the number of iterations, and other options can all be set using the option setting function :meth:feast_option (see :ref:Other Parameters for feast_option <f12jb-py2-py-other_params> for details on setting options and of the default settings).
The search contour itself is defined by a call to :meth:feast_gen_contour or :meth:feast_custom_contour.

.. _f12jv-py2-py-references:

**References**
Gavin, B, Międlar, A and Polizzi, E, 2018, FEAST Eigensolver for Nonlinear Eigenvalue Problems, J. Comput. Phys. (27), 107

Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112

--------
:meth:naginterfaces.library.examples.sparseig.feast_poly_gen_solve_ex.main
"""
raise NotImplementedError

[docs]def feast_free(handle):
r"""
feast_free part of the NAG FEAST suite.
It is used to deallocate the memory used within the problem handle and to destroy the handle itself.

.. _f12jz-py2-py-doc:

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12jzf.html

.. _f12jz-py2-py-parameters:

**Parameters**
**handle** : Handle, modified in place
On entry: the handle to the problem. It needs to be initialized (e.g., by :meth:feast_init) and to hold a problem formulation compatible with feast_free. It **must not** be changed between calls to the NAG FEAST suite.

On exit: the handle is destroyed and set to a null Handle.

.. _f12jz-py2-py-errors:

**Raises**
**NagValueError**
(errno :math:1)
The supplied :math:\mathrm{handle} was not initialized or has become corrupted.

.. _f12jz-py2-py-notes:

**Notes**
Each initialized problem handle (e.g., by :meth:feast_init) should be deallocated to avoid memory leaks.
Therefore, feast_free should be called on all the handles which are no longer needed, typically after obtaining results from the solver.
Please note that passing a handle which has not been properly initialized might cause unpredictable behaviour, including a crash of your program.
See the F12 Introduction <https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/f12/f12intro.html#feast>__ for more details about the NAG FEAST suite.

.. _f12jz-py2-py-references:

**References**
Polizzi, E, 2009, Density-Matrix-Based Algorithms for Solving Eigenvalue Problems, Phys. Rev. B. (79), 115112
"""
raise NotImplementedError