# -*- coding: utf-8 -*-
r"""
Module Summary
--------------
Interfaces for the NAG Mark 30.0 `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.
See Also
--------
``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_30/flhtml/f12/f12intro.html
"""
# NAG Copyright 2017-2024.
[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_30/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_30/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_30/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`.
.. _f12ad-py2-py-doc:
For full information please refer to the NAG Library document for f12ad
https://www.nag.com/numeric/nl/nagdoc_30/flhtml/f12/f12adf.html
.. _f12ad-py2-py-parameters:
**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.
.. _f12ad-py2-py-other_params:
**Other Parameters**
**'Advisory'** : int
Default :math:`= \text{advisory message unit number}`
The destination for advisory messages.
**'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`.
.. _f12ad-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.
.. _f12ad-py2-py-notes:
**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>`.
.. _f12ad-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_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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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**
**'Advisory'** : int
Default :math:`= \text{advisory message unit number}`
The destination for advisory messages.
**'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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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**
**'Advisory'** : int
Default :math:`= \text{advisory message unit number}`
The destination for advisory messages.
**'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_30/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_30/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_30/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_30/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_30/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_30/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_30/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
See Also
--------
: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_30/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**
**'Advisory'** : int
Default :math:`= \text{advisory message unit number}`
The destination for advisory messages.
**'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'}`
Print runtime comments to the advisory channel.
**'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>`.
See Also
--------
: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_30/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_30/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_30/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
See Also
--------
: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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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_30/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
See Also
--------
: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_30/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_30/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
