naginterfaces.library.eigen.real_symm_sparse_arnoldi¶
- naginterfaces.library.eigen.real_symm_sparse_arnoldi(n, a, irow, icol, nev, ncv, sigma, monit=None, option=None, data=None, io_manager=None)[source]¶
real_symm_sparse_arnoldi
computes selected eigenvalues and eigenvectors of a real sparse symmetric matrix.Note: this function uses optional algorithmic parameters, see also:
sparseig.real_symm_init
,sparseig.real_symm_iter
,sparseig.real_symm_proc
,sparseig.real_symm_option
,sparseig.real_symm_monit
.For full information please refer to the NAG Library document for f02fk
https://www.nag.com/numeric/nl/nagdoc_28.6/flhtml/f02/f02fkf.html
- Parameters
- nint
, the order of the matrix .
- afloat, array-like, shape
The array of nonzero elements of the lower triangular part of the symmetric matrix .
- irowint, array-like, shape
The row and column indices of the elements supplied in array .
If and then is stored in . does not need to be ordered: an internal sort will force the correct ordering.
- icolint, array-like, shape
The row and column indices of the elements supplied in array .
If and then is stored in . does not need to be ordered: an internal sort will force the correct ordering.
- nevint
The number of eigenvalues to be computed.
- ncvint
The number of Arnoldi basis vectors to use during the computation.
At present there is no a priori analysis to guide the selection of relative to .
However, it is recommended that .
If many problems of the same type are to be solved, you should experiment with increasing while keeping 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 computation time is problem dependent and must be determined empirically.
- sigmafloat
If the ‘Shifted Inverse’ mode has been selected then contains the real shift used; otherwise is not referenced. This mode can be selected by setting the appropriate options in the user-supplied function .
- monitNone or callable monit(niter, nconv, w, rzest, data=None), optional
Note: if this argument is None then a NAG-supplied facility will be used.
is used to monitor the progress of
real_symm_sparse_arnoldi
. may be None if no monitoring is actually required. is called after the solution of each eigenvalue sub-problem and also just prior to return fromreal_symm_sparse_arnoldi
.- Parameters
- niterint
The number of the current Arnoldi iteration.
- nconvint
The number of converged eigenvalues so far.
- wfloat, ndarray, shape
The first elements of contain the converged approximate eigenvalues.
- rzestfloat, ndarray, shape
The first elements of contain the Ritz estimates (error bounds) on the converged approximate eigenvalues.
- dataarbitrary, optional, modifiable in place
User-communication data for callback functions.
- optionNone or callable option(comm, data=None), optional
Note: if this argument is None then a NAG-supplied facility will be used.
You can supply non-default options to the Arnoldi eigensolver by repeated calls to
sparseig.real_symm_option
from within . (Please note that it is only necessary to callsparseig.real_symm_option
; no call tosparseig.real_symm_init
is required from within .) For example, you can set the mode to ‘Shifted Inverse’, you can increase the ‘Iteration Limit’ beyond its default and you can print varying levels of detail on the iterative process using ‘Print Level’.If only the default options (including that the eigenvalues of largest magnitude are sought) are to be used then may be None.
- Parameters
- commdict, communication object, modifiable in place
Communication structure.
This argument has been initialized to hold the default option set.
If you wish to supply non-default options to the Arnoldi eigensolver, this argument may be passed as argument in a call to
sparseig.real_symm_option
.- dataarbitrary, optional, modifiable in place
User-communication data for callback functions.
- dataarbitrary, optional
User-communication data for callback functions.
- io_managerFileObjManager, optional
Manager for I/O in this routine.
- Returns
- nconvint
The number of converged approximations to the selected eigenvalues. On successful exit, this will normally be .
- wfloat, ndarray, shape
The first elements contain the converged approximations to the selected eigenvalues.
- vfloat, ndarray, shape
Contains the eigenvectors associated with the eigenvalue , for (stored in ). For eigenvalue, , the corresponding eigenvector is stored in , for .
- residfloat, ndarray, shape
The residual for the estimates to the eigenpair and is returned in , for .
- Other Parameters
- ‘Advisory’int
Default
If the option ‘List’ is set then option specifications are listed in a ‘List’ file by setting the option to a file identification (unit) number associated with advisory messages (see
FileObjManager
and theFileObjManager
methodunit_from_fileobj()
).- ‘Defaults’valueless
This special keyword may be used to reset all options to their default values.
- ‘Iteration Limit’int
Default
The limit on the number of Lanczos iterations that can be performed before
sparseig.real_symm_iter
exits. If not all requested eigenvalues have converged to within ‘Tolerance’ and the number of Lanczos iterations has reached this limit thensparseig.real_symm_iter
exits with an error;sparseig.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
sparseig.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.- ‘Both Ends’valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
sparseig.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.- ‘Largest Algebraic’valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
sparseig.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.- ‘Smallest Algebraic’valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
sparseig.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.- ‘Smallest Magnitude’valueless
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for
sparseig.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.- ‘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
If , monitoring information is output to unit number (see
unit_from_fileobj()
) during the solution of each problem; this may be the same as the ‘Advisory’ unit number (seeunit_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 theFileObjManager
methodunit_from_fileobj()
to associate a file with a given unit number (seeunit_from_fileobj()
).- ‘Print Level’int
Default
This controls the amount of printing produced by
real_symm_sparse_arnoldi
as follows.Output
No output except error messages. If you want to suppress all output, set .
The set of selected options.
Problem and timing statistics on final exit from
sparseig.real_symm_iter
.A single line of summary output at each Lanczos iteration.
If ‘Monitoring’ is set, 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.
Problem and timing statistics on final exit from
sparseig.real_symm_iter
. If , ‘Monitoring’ is set, then at each iteration, the number of shifts being applied, the eigenvalues and estimates of the symmetric tridiagonal matrix , 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.If , ‘Monitoring’ is set, 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 ; 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.
If , ‘Monitoring’ is set, 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 ; while computing eigenvalues of , the last rows of the Schur and eigenvector matrices; when computing implicit shifts, the eigenvalues and Ritz estimates of .
If ‘Monitoring’ is set, then during Lanczos iteration loop: norms of key components and the active column of , norms of residuals during iterative refinement, the final symmetric tridiagonal matrix ; while applying shifts: number of shifts, shift values, block indices, updated tridiagonal matrix ; while computing eigenvalues of : the diagonals of , the computed eigenvalues and Ritz estimates.
Note that setting can result in very lengthy ‘Monitoring’ output.
- ‘Regular’valueless
Default
These options define the computational mode which in turn defines the form of operation to be performed.
‘Regular’
‘Shifted Inverse’
where is real
‘Regular Inverse’
- ‘Regular Inverse’valueless
These options define the computational mode which in turn defines the form of operation to be performed.
‘Regular’
‘Shifted Inverse’
where is real
‘Regular Inverse’
- ‘Shifted Inverse’valueless
These options define the computational mode which in turn defines the form of operation to be performed.
‘Regular’
‘Shifted Inverse’
where is real
‘Regular Inverse’
- ‘Tolerance’float
Default
An approximate eigenvalue has deemed to have converged when the corresponding Ritz estimate is within ‘Tolerance’ relative to the magnitude of the eigenvalue.
- Raises
- NagValueError
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, for , .
Constraint: .
- (errno )
On entry, for , , .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, the matrix is numerically singular and could not be inverted. Try perturbing the value of .
- (errno )
The maximum number of iterations, through the option ‘Iteration Limit’, has been set to a non-positive value.
- (errno )
The option ‘Both Ends’ has been set but only eigenvalue is requested.
- (errno )
The maximum number of iterations has been reached.
The maximum number of iterations .
The number of converged eigenvalues .
See the function document for further details.
- (errno )
A serious error, code , has occurred in an internal call. Check all function calls and array sizes. If the call is correct then please contact NAG for assistance.
- Warns
- NagCallbackTerminateWarning
- (errno )
User requested termination in , .
- (errno )
User requested termination in , .
- Notes
real_symm_sparse_arnoldi
computes selected eigenvalues and the corresponding right eigenvectors of a real sparse symmetric matrix :A specified number, , of eigenvalues , or the shifted inverses , may be selected either by largest or smallest modulus, largest or smallest value, or, largest and smallest values (both ends). Convergence is generally faster when selecting larger eigenvalues, smaller eigenvalues can always be selected by choosing a zero inverse shift (). When eigenvalues closest to a given value are required then the shifted inverses of largest magnitude should be selected with shift equal to the required value.
The sparse matrix is stored in symmetric coordinate storage (SCS) format. See the F11 Introduction.
real_symm_sparse_arnoldi
uses an implicitly restarted Arnoldi (Lanczos) iterative method to converge approximations to a set of required eigenvalues and corresponding eigenvectors. Further algorithmic information is given in Further Comments while a fuller discussion is provided in the F12 Introduction. If shifts are to be performed then operations using shifted inverse matrices are performed using a direct sparse solver.
- References
Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
HSL, 2011, A collection of Fortran codes for large-scale scientific computation, http://www.hsl.rl.ac.uk/
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