NAG Library Routine Document
f12arf (complex_option)
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, then this routine need not be called. If, however, you wish to reset some or all of the settings please refer to Section 11 for a detailed description of the specification of the optional parameters.
1
Purpose
f12arf is an option setting routine in a suite of routines consisting of
f12anf,
f12apf,
f12aqf,
f12arf and
f12asf, for which it may be used to supply individual optional parameters to
f12apf and
f12aqf.
f12arf is also an option setting routine in a suite of routines consisting of
f12anf,
f12atf and
f12auf for which it may be used to supply individual optional parameters to
f12auf.
The initialization routine for the appropriate suite,
f12anf or
f12atf,
must have been called prior to calling
f12arf.
2
Specification
Fortran Interface
Integer, Intent (Inout)  ::  icomm(*), ifail  Complex (Kind=nag_wp), Intent (Inout)  ::  comm(*)  Character (*), Intent (In)  ::  str 

3
Description
f12arf may be used to supply values for optional parameters to
f12apf and
f12aqf, or to
f12auf. It is only necessary to call
f12arf for those arguments whose values are to be different from their default values. One call to
f12arf sets one argument value.
Each optional parameter 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
$\left[=\right]$. Alphabetic characters may be upper or lower case. The string
'Pointers = Yes'
is an example of a string used to set an optional parameter. 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 integer or real value. Such numbers may be up to $16$ contiguous characters in
Fortran's I, F, E or D format.

f12arf does not have an equivalent routine from the ARPACK package which passes options by directly setting values to scalar arguments or to specific elements of array arguments.
f12arf is intended to make the passing of options more transparent and follows the same principle as the single option setting routines in
Chapter E04 (see
e04nsf for an example).
The setup routine
f12anf must be called prior to the first call to
f12arf or
f12atf, and all calls to
f12arf must precede the first call to
f12apf or
f12auf.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in
Section 11.
4
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 MCSP5471195 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 Largescale Eigenvalue Problems with Implicitly Restarted Arnoldi Methods SIAM, Philidelphia
5
Arguments
 1: $\mathbf{str}$ – Character(*)Input

On entry: a single valid option string (as described in
Section 3 and
Section 11).
 2: $\mathbf{icomm}\left(*\right)$ – Integer arrayCommunication Array

Note: the dimension of the array
icomm
must be at least
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{licomm}}\right)$ (see
f12anf).
On initial entry: must remain unchanged following a call to the setup routine
f12anf.
On exit: contains data on the current options set.
 3: $\mathbf{comm}\left(*\right)$ – Complex (Kind=nag_wp) arrayCommunication Array

Note: the dimension of the array
comm
must be at least
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{lcomm}}\right)$ (see
f12anf).
On initial entry: must remain unchanged following a call to the setup routine
f12anf.
On exit: contains data on the current options set.
 4: $\mathbf{ifail}$ – IntegerInput/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 3.4 in How to Use the NAG Library and its Documentation 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$

The string passed in
str contains an ambiguous keyword.
 ${\mathbf{ifail}}=2$

The string passed in
str contains a keyword that could not be recognized.
 ${\mathbf{ifail}}=3$

The string passed in
str contains a second keyword that could not be recognized.
 ${\mathbf{ifail}}=4$

The initialization routine
f12anf or
f12atf has not been called or a communication array has become corrupted.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
Not applicable.
8
Parallelism and Performance
f12arf is not threaded in any implementation.
None.
10
Example
This example solves $Ax=\lambda Bx$ in shiftedinverse mode, where $A$ and $B$ are derived from the finite element discretization of the onedimensional convectiondiffusion operator $\frac{{d}^{2}u}{d{x}^{2}}+\rho \frac{du}{dx}$ on the interval $\left[0,1\right]$, with zero Dirichlet boundary conditions.
10.1
Program Text
Program Text (f12arfe.f90)
10.2
Program Data
Program Data (f12arfe.d)
10.3
Program Results
Program Results (f12arfe.r)
11
Optional Parameters
Several optional parameters for the computational suite routines
f12apf and
f12aqf, and for the banded driver
f12auf, define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of
f12apf,
f12aqf and
f12auf these optional parameters have associated
default values that are appropriate for most problems. Therefore, you need only specify those optional parameters whose values are to be different from 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.
Optional parameters may be specified by calling
f12arf before a call to
f12apf or
f12atf, but after a corresponding call to
f12anf or
f12auf. One call is necessary for each optional parameter. Any optional parameters you do not specify are set to their default values. Optional parameters you do specify are unaltered by
f12apf,
f12aqf and
f12auf (unless they define invalid values) and so remain in effect for subsequent calls unless you alter them.
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{}=$ the value returned by x04abf

The destination for advisory messages.
This special keyword may be used to reset all optional parameters to their default values.
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 optional parameter
Exact Shifts is strongly recommended over the alternative
Supplied Shifts and will always be used by
f12auf.
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
f12apf when
f12apf returns with
${\mathbf{irevcm}}=3$; the complex shifts are
returned in
x (or in
comm when the option
${\mathbf{Pointers}}=\mathrm{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  $i$ 
Default $\text{}=300$ 
The limit on the number of Arnoldi iterations that can be performed before
f12apf or
f12auf exits. If not all requested eigenvalues have converged to within
Tolerance and the number of Arnoldi iterations has reached this limit then
f12apf or
f12auf exits with an error;
f12auf returns the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors, while
f12aqf can be called subsequent to
f12apf to do the same.
Largest Magnitude   Default 
The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for
f12apf or
f12auf 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}$ (and
$B$ for
Generalized problems), the linear operator determined by the computational mode and problem type.
Normally each optional parameter specification is not printed to
the advisory channel
as it is supplied. Optional parameter
List may be used to enable printing and optional parameter
Nolist may be used to suppress the 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.
Pointers   Default $\text{}=\mathrm{NO}$ 
During the iterative process and reverse communication calls to
f12apf, required data can be communicated to and from
f12apf in one of two ways. When
${\mathbf{Pointers}}=\mathrm{NO}$ is selected (the default) then the array arguments
x and
mx are used to supply you with required data and used to return computed values back to
f12apf. For example, when
${\mathbf{irevcm}}=1$,
f12apf returns the vector
$x$ in
x and the matrixvector product
$Bx$ in
mx and expects the result or the linear operation
$\mathrm{OP}\left(x\right)$ to be returned in
x.
If
${\mathbf{Pointers}}=\mathrm{YES}$ is selected then the data is passed through sections of the array argument
comm. The section corresponding to
x when
${\mathbf{Pointers}}=\mathrm{NO}$ begins at a location given by the first element of
icomm; similarly the section corresponding to
mx begins at a location given by the second element of
icomm. This option allows
f12apf 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
f12auf which sets
${\mathbf{Pointers}}=\mathrm{YES}$ internally.
Print Level  $i$  Default $\text{}=0$ 
This controls the amount of printing produced by
f12arf as follows.
$=0$ 
No output except error messages. 
$>0$ 
The set of selected options. 
$=2$ 
Problem and timing statistics on final exit from f12apf or f12auf. 
$\ge 5$ 
A single line of summary output at each Arnoldi iteration. 
$\ge 10$ 
If ${\mathbf{Monitoring}}>0$,
Monitoring is set, 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 f12apf. If ${\mathbf{Monitoring}}>0$,
Monitoring is set, 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$,
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 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$,
Monitoring is set, 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 Monitoring is set, 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. 
To begin the Arnoldi iterative process,
f12apf and
f12auf requires an initial residual vector. By default
f12apf and
f12auf provides its own random initial residual vector; this option can also be set using optional parameter
Random Residual. Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to
f12apf and
f12auf through the array argument
resid; this option can be set using optional parameter
Initial Residual.
These options define the computational mode which in turn defines the form of operation
$\mathrm{OP}\left(x\right)$ to be performed by
f12auf or when
f12apf returns with
${\mathbf{irevcm}}=1$ or
$1$ and the matrixvector product
$Bx$ when
f12apf returns with
${\mathbf{irevcm}}=2$.
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)$.
Given a
Generalized eigenvalue problem in the form
$Ax=\lambda Bx$ then the following modes are available with the appropriate operator
$\mathrm{OP}\left(x\right)$.
The problem to be solved is either a standard eigenvalue problem,
$Ax=\lambda x$, or a generalized eigenvalue problem,
$Ax=\lambda Bx$. The optional parameter
Standard should be used when a standard eigenvalue problem is being solved and the optional parameter
Generalized should be used when a generalized eigenvalue problem is being solved.
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.
Vectors   Default $\text{}=\mathrm{RITZ}$ 
The routine
f12aqf or
f12auf can optionally compute the Schur vectors and/or the eigenvectors corresponding to the converged eigenvalues. To turn off computation of any vectors the option
${\mathbf{Vectors}}=\mathrm{NONE}$ should be set. To compute only the Schur vectors (at very little extra cost), the option
${\mathbf{Vectors}}=\mathrm{SCHUR}$ should be set and these will be returned in the array argument
v of
f12aqf or
f12auf. To compute the eigenvectors (Ritz vectors) corresponding to the eigenvalue estimates, the option
${\mathbf{Vectors}}=\mathrm{RITZ}$ should be set and these will be returned in the array argument
z of
f12aqf or
f12auf, if
z is set equal to
v (as in
Section 10) then the Schur vectors in
v are overwritten by the eigenvectors computed by
f12aqf or
f12auf.