Note:this routine usesoptional parametersto 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.
f12fdf is an option setting routine in a suite of routines consisting of f12faf,f12fbf,f12fcf,f12fdfandf12fef, and may be used to supply individual optional parameters to f12fbfandf12fcf. The initialization routine f12fafmust have been called prior to calling f12fdf.
The routine may be called by the names f12fdf or nagf_sparseig_real_symm_option.
3Description
f12fdf may be used to supply values for optional parameters to f12fbfandf12fcf. It is only necessary to call f12fdf for those arguments whose values are to be different from their default values. One call to f12fdf 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 $[=]$. Alphabetic characters may be upper or lower case. The string
Iteration Limit = 500
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.
f12fdf 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. f12fdf is intended to make the passing of options more transparent and follows the same principle as the single option setting routines in Chapter E04.
The setup routine f12faf must be called prior to the first call to f12fdf and all calls to f12fdf must precede the first call to f12fbf, the reverse communication iterative solver.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section 11.
4References
Lehoucq R B (2001) Implicitly restarted Arnoldi methods and subspace iteration SIAM Journal on Matrix Analysis and Applications23 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 Applications17 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
5Arguments
1: $\mathbf{str}$ – Character(*)Input
On entry: a single valid option string (as described in Section 3 and Section 11).
Note: the actual argument supplied must be the array icomm supplied to the initialization routine f12faf.
On initial entry: must remain unchanged following a call to the setup routine f12faf.
On exit: contains data on the current options set.
3: $\mathbf{comm}\left(*\right)$ – Real (Kind=nag_wp) arrayCommunication Array
Note: the actual argument supplied must be the array comm supplied to the initialization routine f12faf.
On initial entry: must remain unchanged following a call to the setup routine f12faf.
On exit: contains data on the current options set.
4: $\mathbf{ifail}$ – IntegerInput/Output
On entry: ifail must be set to $0$, $\mathrm{-1}$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $\mathrm{-1}$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $\mathrm{-1}$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ 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).
6Error Indicators and Warnings
If on entry ${\mathbf{ifail}}=0$ or $\mathrm{-1}$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Keyword not recognized: $\u27e8\mathit{\text{value}}\u27e9$
${\mathbf{ifail}}=3$
Second keyword not recognized: $\u27e8\mathit{\text{value}}\u27e9$
${\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.
7Accuracy
Not applicable.
8Parallelism and Performance
Background information to multithreading can be found in the Multithreading documentation.
f12fdf is not threaded in any implementation.
9Further Comments
None.
10Example
This example solves $Ax=\lambda Bx$ in Shifted Inverse mode, where $A$ and $B$ are obtained from the standard central difference discretization of the one-dimensional Laplacian operator $\frac{{\partial}^{2}u}{\partial {x}^{2}}$ on $[0,1]$, with zero Dirichlet boundary conditions. Data is passed to and from the reverse communication routine f12fbf using pointers to the communication array.
Several optional parameters for the computational routines f12fbfandf12fcf define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of f12fbfandf12fcf 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 f12fdf before a call to f12fbf, but after a call to f12faf. One call is necessary for each optional parameter.
All optional parameters you do not specify are set to their default values. Optional parameters you do specify are unaltered by f12fbfandf12fcf (unless they define invalid values) and so remain in effect for subsequent calls unless you alter them.
11.1Description 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{advisory message unit number}$
The destination for advisory messages.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
ExactShifts
Default
SuppliedShifts
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 f12fbf when f12fbf returns with ${\mathbf{irevcm}}=3$; the real and imaginary parts of the shifts are
returned in x and mx respectively (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 Lanczos iterations that can be performed before f12fbf exits. If not all requested eigenvalues have converged to within Tolerance and the number of Lanczos iterations has reached this limit then f12fbf exits with an error; f12fcf can still be called subsequently to return the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors.
LargestMagnitude
Default
Both Ends
LargestAlgebraic
SmallestAlgebraic
SmallestMagnitude
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for f12fbf 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 $\mathrm{op}$ (and $B$ for Generalized problems), the linear operator determined by the computational mode and problem type.
Nolist
Default
List
Optional parameter List enables printing of each optional parameter specification as it is supplied. Nolist suppresses this printing.
Monitoring
$i$
Default $\text{}=\mathrm{-1}$
If $i>0$, monitoring information is output to unit number $i$ during the solution of each problem; this may be the same as the Advisory unit 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 unit number.
Pointers
Default $\text{}=\mathrm{NO}$
During the iterative process and reverse communication calls to f12fbf, required data can be communicated to and from f12fbf 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 f12fbf. For example, when ${\mathbf{irevcm}}=1$, f12fbf returns the vector $x$ in x and the matrix-vector 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 f12fbf to perform fewer copy operations on each intermediate exit and entry, but can also lead to less elegant code in the calling program.
PrintLevel
$i$
Default $\text{}=0$
This controls the amount of printing produced by f12fdf as follows.
$\mathit{i}$
Output
$=0$
No output except error messages. If you want to suppress all output, set ${\mathbf{Print\; Level}}=0$.
$>0$
The set of selected options.
$=2$
Problem and timing statistics on final exit from f12fbf.
$\ge 5$
A single line of summary output at each Lanczos iteration.
$\ge 10$
If
${\mathbf{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.
$\ge 20$
Problem and timing statistics on final exit from f12fbf. If
${\mathbf{Monitoring}}>0$,
then at each iteration, the number of shifts being applied, the eigenvalues and estimates of the symmetric tridiagonal matrix $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.
$\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 symmetric tridiagonal matrix $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.
$\ge 40$
If
${\mathbf{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 $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 Lanczos iteration loop: norms of key components and the active column of $H$, norms of residuals during iterative refinement, the final symmetric tridiagonal matrix $H$; while applying shifts: number of shifts, shift values, block indices, updated tridiagonal matrix $H$; while computing eigenvalues of $H$: the diagonals of $H$, the computed eigenvalues and Ritz estimates.
Note that setting ${\mathbf{Print\; Level}}\ge 30$ can result in very lengthy Monitoring output.
RandomResidual
Default
Initial Residual
To begin the Lanczos iterative process, f12fbf requires an initial residual vector. By default f12fbf 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 f12fbf through the array argument resid; this option can be set using optional parameter Initial Residual.
Regular
Default
RegularInverse
ShiftedInverse
Buckling
Cayley
These options define the computational mode which in turn defines the form of operation $\mathrm{op}\left(x\right)$ to be performed when f12fbf returns with ${\mathbf{irevcm}}=\mathrm{-1}$ or $1$ and the matrix-vector product $Bx$ when f12fbf 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)$.
$\mathrm{op}={(A-\sigma I)}^{\mathrm{-1}}$ where $\sigma $ is real
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)$.
$\mathrm{op}={\left(A-\sigma B\right)}^{\mathrm{-1}}\left(A+\sigma B\right)$, where $\sigma $ is real
Standard
Default
Generalized
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{}=\text{RITZ}$
The routine f12fcf 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 f12fcf. 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 f12fcf, if z is set equal to v then the Schur vectors in v are overwritten by the eigenvectors computed by f12fcf.