NAG FL Interface
f02ekf (real_gen_sparse_arnoldi)
Note: this routine uses optional parameters to define choices in the problem specification. If you wish to use default
settings for all of the optional parameters, you need only read Sections 1 to 10 of this document. If, however, you wish to reset some or all of the settings this must be done by calling the option setting routine f12adf from the usersupplied subroutine option. Please refer to Section 11 for a detailed description of the specification of the optional parameters.
1
Purpose
f02ekf computes selected eigenvalues and eigenvectors of a real sparse general matrix.
2
Specification
Fortran Interface
Subroutine f02ekf ( 
n, nnz, a, icolzp, irowix, nev, ncv, sigma, monit, option, nconv, w, v, ldv, resid, iuser, ruser, ifail) 
Integer, Intent (In) 
:: 
n, nnz, icolzp(n+1), irowix(nnz), nev, ncv, ldv 
Integer, Intent (Inout) 
:: 
iuser(*), ifail 
Integer, Intent (Out) 
:: 
nconv 
Real (Kind=nag_wp), Intent (In) 
:: 
sigma 
Real (Kind=nag_wp), Intent (Inout) 
:: 
a(nnz), v(ldv,*), ruser(*) 
Real (Kind=nag_wp), Intent (Out) 
:: 
resid(nev+1) 
Complex (Kind=nag_wp), Intent (Out) 
:: 
w(ncv) 
External 
:: 
monit, option 

C Header Interface
#include <nag.h>
void 
f02ekf_ (const Integer *n, const Integer *nnz, double a[], const Integer icolzp[], const Integer irowix[], const Integer *nev, const Integer *ncv, const double *sigma, void (NAG_CALL *monit)(const Integer *ncv, const Integer *niter, const Integer *nconv, const Complex w[], const double rzest[], Integer *istat, Integer iuser[], double ruser[]), void (NAG_CALL *option)(Integer icomm[], double comm[], Integer *istat, Integer iuser[], double ruser[]), Integer *nconv, Complex w[], double v[], const Integer *ldv, double resid[], Integer iuser[], double ruser[], Integer *ifail) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
f02ekf_ (const Integer &n, const Integer &nnz, double a[], const Integer icolzp[], const Integer irowix[], const Integer &nev, const Integer &ncv, const double &sigma, void (NAG_CALL *monit)(const Integer &ncv, const Integer &niter, const Integer &nconv, const Complex w[], const double rzest[], Integer &istat, Integer iuser[], double ruser[]), void (NAG_CALL *option)(Integer icomm[], double comm[], Integer &istat, Integer iuser[], double ruser[]), Integer &nconv, Complex w[], double v[], const Integer &ldv, double resid[], Integer iuser[], double ruser[], Integer &ifail) 
}

The routine may be called by the names f02ekf or nagf_eigen_real_gen_sparse_arnoldi.
3
Description
f02ekf computes selected eigenvalues and the corresponding right eigenvectors of a real sparse general matrix
$A$:
A specified number, ${n}_{ev}$, of eigenvalues ${\lambda}_{i}$, or the shifted inverses ${\mu}_{i}=1/\left({\lambda}_{i}\sigma \right)$, may be selected either by largest or smallest modulus, largest or smallest real part, or, largest or smallest imaginary part. Convergence is generally faster when selecting larger eigenvalues, smaller eigenvalues can always be selected by choosing a zero inverse shift ($\sigma =0.0$). When eigenvalues closest to a given real value are required then the shifted inverses of largest magnitude should be selected with shift equal to the required real value.
Note that even though $A$ is real, ${\lambda}_{i}$ and ${w}_{i}$ may be complex. If ${w}_{i}$ is an eigenvector corresponding to a complex eigenvalue ${\lambda}_{i}$, then the complex conjugate vector ${\overline{w}}_{i}$ is the eigenvector corresponding to the complex conjugate eigenvalue ${\overline{\lambda}}_{i}$. The eigenvalues in a complex conjugate pair ${\lambda}_{i}$ and ${\overline{\lambda}}_{i}$ are either both selected or both not selected.
The sparse matrix
$A$ is stored in compressed column storage (CCS) format. See
Section 2.1.3 in the
F11 Chapter Introduction.
f02ekf uses an implicitly restarted Arnoldi iterative method to converge approximations to a set of required eigenvalues and corresponding eigenvectors. Further algorithmic information is given in
Section 9 while a fuller discussion is provided in the
F12 Chapter Introduction. If shifts are to be performed then operations using shifted inverse matrices are performed using a direct sparse solver; further information on the solver used is provided in the
F11 Chapter Introduction.
4
References
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Lehoucq R B, Sorensen D C and Yang C (1998) ARPACK Users' Guide: Solution of Largescale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods SIAM, Philidelphia
5
Arguments

1:
$\mathbf{n}$ – Integer
Input

On entry: $n$, the order of the matrix $A$.
Constraint:
${\mathbf{n}}\ge 0$.

2:
$\mathbf{nnz}$ – Integer
Input

On entry: the dimension of the array
a and The number of nonzero elements of the matrix
$A$ and, if a nonzero shifted inverse is to be applied, all diagonal elements. Each nonzero is counted once in the latter case.
Constraint:
$0\le {\mathbf{nnz}}\le {{\mathbf{n}}}^{2}$.

3:
$\mathbf{a}\left({\mathbf{nnz}}\right)$ – Real (Kind=nag_wp) array
Input/Output

On entry: the array of nonzero elements (and diagonal elements if a nonzero inverse shift is to be applied) of the $n$ by $n$ general matrix $A$.
On exit: if a nonzero shifted inverse is to be applied then the diagonal elements of
$A$ have the shift value, as supplied in
sigma, subtracted.

4:
$\mathbf{icolzp}\left({\mathbf{n}}+1\right)$ – Integer array
Input

On entry:
${\mathbf{icolzp}}\left(i\right)$ contains the index in
a of the start of column
$\mathit{i}$, for
$\mathit{i}=1,2,\dots ,n$;
${\mathbf{icolzp}}\left({\mathbf{n}}+1\right)$ must contain the value
${\mathbf{nnz}}+1$. Thus the number of nonzero elements in column
$\mathit{i}$ of
$A$ is
${\mathbf{icolzp}}\left(i+1\right){\mathbf{icolzp}}\left(i\right)$; when shifts are applied this includes diagonal elements irrespective of value. See
Section 2.1.3 in the
F11 Chapter Introduction.

5:
$\mathbf{irowix}\left({\mathbf{nnz}}\right)$ – Integer array
Input

On entry:
${\mathbf{irowix}}\left(i\right)$ contains the row index for each entry in
a. See
Section 2.1.3 in the
F11 Chapter Introduction.

6:
$\mathbf{nev}$ – Integer
Input

On entry: the number of eigenvalues to be computed.
Constraint:
$0<{\mathbf{nev}}<{\mathbf{n}}1$.

7:
$\mathbf{ncv}$ – Integer
Input

On entry: the dimension of the array
w as declared in the (sub)program from which
f02ekf is called.
The number of Arnoldi basis vectors to use during the computation.
At present there is no
a priori analysis to guide the selection of
ncv relative to
nev. However, it is recommended that
${\mathbf{ncv}}\ge 2\times {\mathbf{nev}}+1$. If many problems of the same type are to be solved, you should experiment with increasing
ncv while keeping
nev fixed for a given test problem. This will usually decrease the required number of matrixvector operations but it also increases the work and storage required to maintain the orthogonal basis vectors. The optimal ‘crossover’ with respect to CPU time is problem dependent and must be determined empirically.
Constraint:
${\mathbf{nev}}+1<{\mathbf{ncv}}\le {\mathbf{n}}$.

8:
$\mathbf{sigma}$ – Real (Kind=nag_wp)
Input

On entry: if the
Shifted Inverse Real mode has been selected then
sigma contains the real shift used; otherwise
sigma is not referenced. This mode can be selected by setting the appropriate options in the usersupplied subroutine
option.

9:
$\mathbf{monit}$ – Subroutine, supplied by the NAG Library or the user.
External Procedure

monit is used to monitor the progress of
f02ekf.
monit may be the
dummy subroutine
f02ekz
if no monitoring is actually required.
(
f02ekz is included in the NAG Library.)
monit is called after the solution of each eigenvalue subproblem and also just prior to return from
f02ekf.
The specification of
monit is:
Fortran Interface
Integer, Intent (In) 
:: 
ncv, niter, nconv 
Integer, Intent (Inout) 
:: 
istat, iuser(*) 
Real (Kind=nag_wp), Intent (In) 
:: 
rzest(ncv) 
Real (Kind=nag_wp), Intent (Inout) 
:: 
ruser(*) 
Complex (Kind=nag_wp), Intent (In) 
:: 
w(ncv) 

C++ Header Interface
#include <nag.h> extern "C" {
}


1:
$\mathbf{ncv}$ – Integer
Input

On entry: the dimension of the arrays
w and
rzest. The number of Arnoldi basis vectors used during the computation.

2:
$\mathbf{niter}$ – Integer
Input

On entry: the number of the current Arnoldi iteration.

3:
$\mathbf{nconv}$ – Integer
Input

On entry: the number of converged eigenvalues so far.

4:
$\mathbf{w}\left({\mathbf{ncv}}\right)$ – Complex (Kind=nag_wp) array
Input

On entry: the first
nconv elements of
w contain the converged approximate eigenvalues.

5:
$\mathbf{rzest}\left({\mathbf{ncv}}\right)$ – Real (Kind=nag_wp) array
Input

On entry: the first
nconv elements of
rzest contain the Ritz estimates (error bounds) on the converged approximate eigenvalues.

6:
$\mathbf{istat}$ – Integer
Input/Output

On entry: set to zero.
On exit: if set to a nonzero value f02ekf returns immediately with ${\mathbf{ifail}}={\mathbf{9}}$.

7:
$\mathbf{iuser}\left(*\right)$ – Integer array
User Workspace

8:
$\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array
User Workspace

monit is called with the arguments
iuser and
ruser as supplied to
f02ekf. You should use the arrays
iuser and
ruser to supply information to
monit.
monit must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
f02ekf is called. Arguments denoted as
Input must
not be changed by this procedure.
Note: monit should not return floatingpoint NaN (Not a Number) or infinity values, since these are not handled by
f02ekf. If your code inadvertently
does return any NaNs or infinities,
f02ekf is likely to produce unexpected results.

10:
$\mathbf{option}$ – Subroutine, supplied by the NAG Library or the user.
External Procedure

You can supply nondefault options to the Arnoldi eigensolver by repeated calls to
f12adf from within
option. (Please note that it is only necessary to call
f12adf; no call to
f12aaf is required from within
option.) For example, you can set the mode to
Shifted Inverse Real, 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
option may be the dummy subroutine
f02eky (
f02eky is included in the NAG Library). See
Section 10 for an example of using
option to set some nondefault options.
The specification of
option is:
Fortran Interface
Integer, Intent (Inout) 
:: 
icomm(*), istat, iuser(*) 
Real (Kind=nag_wp), Intent (Inout) 
:: 
comm(*), ruser(*) 

C++ Header Interface
#include <nag.h> extern "C" {
}


1:
$\mathbf{icomm}\left(*\right)$ – Integer array
Communication Array

On entry: contains details of the default option set. This array must be passed as argument
icomm in any call to
f12adf.
On exit: contains data on the current options set which may be altered from the default set via calls to
f12adf.

2:
$\mathbf{comm}\left(*\right)$ – Real (Kind=nag_wp) array
Communication Array

On entry: contains details of the default option set. This array must be passed as argument
comm in any call to
f12adf.
On exit: contains data on the current options set which may be altered from the default set via calls to
f12adf.

3:
$\mathbf{istat}$ – Integer
Input/Output

On entry: set to zero.
On exit: if set to a nonzero value f02ekf returns immediately with ${\mathbf{ifail}}={\mathbf{10}}$.

4:
$\mathbf{iuser}\left(*\right)$ – Integer array
User Workspace

5:
$\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array
User Workspace

option is called with the arguments
iuser and
ruser as supplied to
f02ekf. You should use the arrays
iuser and
ruser to supply information to
option.
option must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which
f02ekf is called.

11:
$\mathbf{nconv}$ – Integer
Output

On exit: the number of converged approximations to the selected eigenvalues. On successful exit, this will normally be either
nev or
${\mathbf{nev}}+1$ depending on the number of complex conjugate pairs of eigenvalues returned.

12:
$\mathbf{w}\left({\mathbf{ncv}}\right)$ – Complex (Kind=nag_wp) array
Output

On exit: the first
nconv elements contain the converged approximations to the selected eigenvalues. Since complex conjugate pairs of eigenvalues appear together, it is possible (given an odd number of converged real eigenvalues) for
f02ekf to return one more eigenvalue than requested.

13:
$\mathbf{v}\left({\mathbf{ldv}},*\right)$ – Real (Kind=nag_wp) array
Output

Note: the second dimension of the array
v
must be at least
${\mathbf{ncv}}$.
On exit: contains the eigenvectors associated with the eigenvalue
${\lambda}_{\mathit{i}}$, for
$\mathit{i}=1,2,\dots ,{\mathbf{nconv}}$ (stored in
w). For a real eigenvalue,
${\lambda}_{j}$, the corresponding eigenvector is real and is stored in
${\mathbf{v}}\left(\mathit{i},j\right)$, for
$\mathit{i}=1,2,\dots ,n$. For complex conjugate pairs of eigenvalues,
${w}_{j+1}=\overline{{w}_{j}}$, the real and imaginary parts of the corresponding eigenvectors are stored, respectively, in
${\mathbf{v}}\left(\mathit{i},j\right)$ and
${\mathbf{v}}\left(\mathit{i},j\right)$, for
$\mathit{i}=1,2,\dots ,n$. The imaginary parts stored are for the first of the conjugate pair of eigenvectors; the other eigenvector in the pair is obtained by negating these imaginary parts.

14:
$\mathbf{ldv}$ – Integer
Input

On entry: the first dimension of the array
v as declared in the (sub)program from which
f02ekf is called.
Constraint:
${\mathbf{ldv}}\ge {\mathbf{n}}$.

15:
$\mathbf{resid}\left({\mathbf{nev}}+1\right)$ – Real (Kind=nag_wp) array
Output

On exit: the residual ${\Vert A{w}_{\mathit{i}}{\lambda}_{\mathit{i}}{w}_{\mathit{i}}\Vert}_{2}$ for the estimates to the eigenpair ${\lambda}_{\mathit{i}}$ and ${w}_{\mathit{i}}$ is returned in ${\mathbf{resid}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{nconv}}$.

16:
$\mathbf{iuser}\left(*\right)$ – Integer array
User Workspace

iuser is not used by
f02ekf, but is passed directly to
monit and
option and may be used to pass information to these routines.

17:
$\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array
User Workspace

ruser is not used by
f02ekf, but is passed directly to
monit and
option and may be used to pass information to these routines.

18:
$\mathbf{ifail}$ – Integer
Input/Output

On entry:
ifail must be set to
$0$,
$1\text{or}1$. If you are unfamiliar with this argument you should refer to
Section 4 in the Introduction to the NAG Library FL Interface for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is
$0$.
When the value $\mathbf{1}\text{or}\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit:
${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{n}}>0$.
 ${\mathbf{ifail}}=2$

On entry, ${\mathbf{nnz}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nnz}}>0$.
On entry, ${\mathbf{nnz}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nnz}}\le {\mathbf{n}}\times {\mathbf{n}}$.
 ${\mathbf{ifail}}=3$

On entry, in shifted inverse mode, the $j$th diagonal element of $A$ is not defined, for $j=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{ifail}}=4$

On entry, for $i=\u2329\mathit{\text{value}}\u232a$, ${\mathbf{icolzp}}\left(i\right)=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{icolzp}}\left(i+1\right)=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{icolzp}}\left(i\right)<{\mathbf{icolzp}}\left(i+1\right)$.
On entry, ${\mathbf{icolzp}}\left(1\right)=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{icolzp}}\left(1\right)=1$.
On entry, ${\mathbf{icolzp}}\left({\mathbf{n}}+1\right)=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{nnz}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{icolzp}}\left({\mathbf{n}}+1\right)={\mathbf{nnz}}+1$.
 ${\mathbf{ifail}}=5$

On entry, in specification of column $\u2329\mathit{\text{value}}\u232a$, and for $j=\u2329\mathit{\text{value}}\u232a$, ${\mathbf{irowix}}\left(j\right)=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{irowix}}\left(j+1\right)=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{irowix}}\left(j\right)<{\mathbf{irowix}}\left(j+1\right)$.
 ${\mathbf{ifail}}=6$

On entry, ${\mathbf{nev}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nev}}>0$.
 ${\mathbf{ifail}}=7$

On entry, ${\mathbf{ncv}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{ncv}}\le {\mathbf{n}}$.
On entry, ${\mathbf{ncv}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{nev}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{ncv}}>{\mathbf{nev}}+1$.
 ${\mathbf{ifail}}=8$

On entry, the matrix $A\sigma \times I$ is nearly numerically singular and could not be inverted. Try perturbing the value of $\sigma $. Norm of matrix $\text{}=\u2329\mathit{\text{value}}\u232a$, Reciprocal condition number $\text{}=\u2329\mathit{\text{value}}\u232a$.
On entry, the matrix $A\sigma \times I$ is numerically singular and could not be inverted. Try perturbing the value of $\sigma $.
 ${\mathbf{ifail}}=9$

User requested termination in
monit,
${\mathbf{istat}}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{ifail}}=10$

User requested termination in
option,
${\mathbf{istat}}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{ifail}}=14$

On entry, ${\mathbf{ldv}}=\u2329\mathit{\text{value}}\u232a$ and ${\mathbf{n}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{ldv}}\ge {\mathbf{n}}$.
 ${\mathbf{ifail}}=21$

The maximum number of iterations
$\text{}\le 0$, the optional parameter
Iteration Limit has been set to
$\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{ifail}}=22$

An unexpected internal error occurred when solving an eigenproblem.
This error should not occur. Please contact
NAG.
 ${\mathbf{ifail}}=23$

An unexpected internal error occurred when solving an eigenproblem.
This error should not occur. Please contact
NAG.
 ${\mathbf{ifail}}=24$

The maximum number of iterations has been reached.
The maximum number of iterations $\text{}=\u2329\mathit{\text{value}}\u232a$.
The number of converged eigenvalues $\text{}=\u2329\mathit{\text{value}}\u232a$.
See the routine document for further details.
 ${\mathbf{ifail}}=25$

No shifts could be applied during a cycle of the implicitly restarted Arnoldi iteration.
 ${\mathbf{ifail}}=26$

Could not build an Arnoldi factorization. The size of the current Arnoldi factorization $\text{}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{ifail}}=27$

Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix.
Please contact
NAG.
 ${\mathbf{ifail}}=32$

An unexpected internal error occurred when postprocessing an eigenproblem.
This error should not occur. Please contact
NAG.
 ${\mathbf{ifail}}=33$

The number of eigenvalues found to sufficient accuracy is zero.
 ${\mathbf{ifail}}=34$

Internal inconsistency in the number of converged Ritz values. Number counted $\text{}=\u2329\mathit{\text{value}}\u232a$, number expected $\text{}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{ifail}}=35$

During calculation of a real Schur form, there was a failure to compute $\u2329\mathit{\text{value}}\u232a$ eigenvalues in a total of $\u2329\mathit{\text{value}}\u232a$ iterations.
 ${\mathbf{ifail}}=36$

The computed Schur form could not be reordered by an internal call.
This routine returned with
${\mathbf{ifail}}=\u2329\mathit{\text{value}}\u232a$.
Please contact
NAG.
 ${\mathbf{ifail}}=37$

In calculating eigenvectors, an internal call returned with an error.
Please contact
NAG.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 7 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library FL Interface for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 9 in the Introduction to the NAG Library FL Interface for further information.
7
Accuracy
The relative accuracy of a Ritz value (eigenvalue approximation),
$\lambda $, is considered acceptable if its Ritz estimate
$\le {\mathbf{Tolerance}}\times \lambda $. The default value for
Tolerance is the
machine precision given by
x02ajf. The Ritz estimates are available via the
monit subroutine at each iteration in the Arnoldi process, or can be printed by setting option
Print Level to a positive value.
8
Parallelism and Performance
f02ekf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
f02ekf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
f02ekf calls routines based on the ARPACK suite in
Chapter F12. These routines use an implicitly restarted Arnoldi iterative method to converge to approximations to a set of required eigenvalues (see the
F12 Chapter Introduction).
In the default
Regular mode, only matrixvector multiplications are performed using the sparse matrix
$A$ during the Arnoldi process. Each iteration is therefore cheap computationally, relative to the alternative,
Shifted Inverse Real, mode described below. It is most efficient (i.e., the total number of iterations required is small) when the eigenvalues of largest magnitude are sought and these are distinct.
Although there is an option for returning the smallest eigenvalues using this mode (see
Smallest Magnitude option), the number of iterations required for convergence will be far greater or the method may not converge at all. However, where convergence is achieved,
Regular mode may still prove to be the most efficient since no inversions are required. Where smallest eigenvalues are sought and
Regular mode is not suitable, or eigenvalues close to a given real value are sought, the
Shifted Inverse Real mode should be used.
If the
Shifted Inverse Real mode is used (via a call to
f12adf in
option) then the matrix
$A\sigma I$ is used in linear system solves by the Arnoldi process. This is first factorized internally using the direct
$LU$ factorization routine
f11mef. The condition number of
$A\sigma I$ is then calculated by a call to
f11mgf. If the condition number is too big then the matrix is considered to be nearly singular, i.e.,
$\sigma $ is an approximate eigenvalue of
$A$, and the routine exits with an error. In this situation it is normally sufficient to perturb
$\sigma $ by a small amount and call
f02ekf again. After successful factorization, subsequent solves are performed by calls to
f11mff.
Finally, f02ekf transforms the eigenvectors. Each eigenvector $w$ (real or complex) is normalized so that ${\Vert w\Vert}_{2}=1$, and the element of largest absolute value is real.
The monitoring routine
monit provides some basic information on the convergence of the Arnoldi iterations. Much greater levels of detail on the Arnoldi process are available via option
Print Level. If this is set to a positive value then information will be printed, by default, to standard output. The
Monitoring option may be used to select a monitoring
file by setting the option to a file identification (unit) number associated with
Monitoring (see
x04acf).
10
Example
This example computes the four eigenvalues of the matrix
$A$ which lie closest to the value
$\sigma =5.5$ on the real line, and their corresponding eigenvectors, where
$A$ is the tridiagonal matrix with elements
10.1
Program Text
10.2
Program Data
10.3
Program Results
11
Optional Parameters
Internally
f02ekf calls routines from the suite
f12aaf,
f12abf,
f12acf,
f12adf and
f12aef. Several optional parameters for these computational routines define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of
f02ekf these optional parameters are also used here and have associated
default values that are usually appropriate. Therefore, you need only specify those optional parameters whose values are to be different from their default values.
Optional parameters may be specified via the usersupplied subroutine
option in the call to
f02ekf.
option must be coded such that one call to
f12adf is necessary to set each optional parameter. All optional parameters you do not specify are set to their default values.
The remainder of this section can be skipped if you wish to use the default values for all optional parameters.
The following is a list of the optional parameters available. A full description of each optional parameter is provided in
Section 11.1.
11.1
Description of the Optional Parameters
For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
 the keywords, where the minimum abbreviation of each keyword is underlined;
 a parameter value,
where the letters $a$, $i$ and $r$ denote options that take character, integer and real values respectively;
 the default value, where the symbol $\epsilon $ is a generic notation for machine precision (see x02ajf).
Keywords and character values are case and white space insensitive.
Advisory  $i$  Default $\text{}=0$

If the optional parameter
List is set then optional parameter specifications are listed in a
List file by setting the option to a file identification (unit) number associated with advisory messages (see
x04abf and
x04acf).
This special keyword may be used to reset all optional parameters to their default values.
Iteration Limit  $i$ 
Default $\text{}=300$

The limit on the number of Arnoldi iterations that can be performed before f02ekf exits with
${\mathbf{ifail}}\ne {\mathbf{0}}$.
Largest Magnitude   Default 
The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is 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 $\mathrm{OP}$ the linear operator determined by the computational mode and problem type.
Optional parameter
List enables printing of each optional parameter specification as it is supplied.
Nolist suppresses this printing.
Monitoring  $i$  Default $\text{}=1$ 
If
$i>0$, monitoring information is output to channel number
$i$ during the solution of each problem; this may be the same as the
Advisory channel number. The type of information produced is dependent on the value of
Print Level, see the description of the optional parameter
Print Level for details of the information produced. Please see
x04acf to associate a file with a given channel number.
Print Level  $i$  Default $\text{}=0$ 
This controls the amount of printing produced by
f02ekf as follows.
$=0$  No output except error messages. 
$>0$  The set of selected options. 
$=2$  Problem and timing statistics when all calls to f12abf have been completed. 
$\ge 5$  A single line of summary output at each Arnoldi iteration. 
$\ge 10$ 
If ${\mathbf{Monitoring}}>0$, then at each iteration, the length and additional steps of the current Arnoldi factorization and the number of converged Ritz values; during reorthogonalization, the norm of initial/restarted starting vector. 
$\ge 20$  Problem and timing statistics on final exit from f12abf. If ${\mathbf{Monitoring}}>0$, then at each iteration, the number of shifts being applied, the eigenvalues and estimates of the Hessenberg matrix $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 reorthogonalization. 
$\ge 30$  If ${\mathbf{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 $H$; during reorthogonalization, 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. 
$\ge 40$  If ${\mathbf{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 $H$; while computing eigenvalues of $H$, the last rows of the Schur and eigenvector matrices; when computing implicit shifts, the eigenvalues and Ritz estimates of $H$. 
$\ge 50$  If ${\mathbf{Monitoring}}>0$, then during Arnoldi iteration loop: norms of key components and the active column of $H$, norms of residuals during iterative refinement, the final upper Hessenberg matrix $H$; while applying shifts: number of shifts, shift values, block indices, updated matrix $H$; while computing eigenvalues of $H$: the matrix $H$, the computed eigenvalues and Ritz estimates. 
These options define the computational mode which in turn defines the form of operation $\mathrm{OP}\left(x\right)$ to be performed.
Given a standard eigenvalue problem in the form
$Ax=\lambda x$ then the following modes are available with the appropriate operator
$\mathrm{OP}\left(x\right)$.
Tolerance  $r$ 
Default $\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.