NAG Library Function Documentnag_real_symm_sparse_eigensystem_option (f12fdc)

Note: this function uses optional arguments to define choices in the problem specification. If you wish to use default .

1  Purpose

nag_real_symm_sparse_eigensystem_option (f12fdc) is an option setting function in a suite of functions consisting of nag_real_symm_sparse_eigensystem_init (f12fac), nag_real_symm_sparse_eigensystem_iter (f12fbc), nag_real_symm_sparse_eigensystem_sol (f12fcc), nag_real_symm_sparse_eigensystem_option (f12fdc) and nag_real_symm_sparse_eigensystem_monit (f12fec), and may be used to supply individual optional arguments to nag_real_symm_sparse_eigensystem_iter (f12fbc) and nag_real_symm_sparse_eigensystem_sol (f12fcc). The initialization function nag_real_symm_sparse_eigensystem_init (f12fac) must have been called prior to calling nag_real_symm_sparse_eigensystem_option (f12fdc).

2  Specification

#include <nag.h>
#include <nagf12.h>

void  nag_real_symm_sparse_eigensystem_option (const char *str, Integer icomm[], double comm[],  NagError *fail)

3  Description

nag_real_symm_sparse_eigensystem_option (f12fdc) may be used to supply values for optional arguments to nag_real_symm_sparse_eigensystem_iter (f12fbc) and nag_real_symm_sparse_eigensystem_sol (f12fcc). It is only necessary to call nag_real_symm_sparse_eigensystem_option (f12fdc) for those arguments whose values are to be different from their default values. One call to nag_real_symm_sparse_eigensystem_option (f12fdc) sets one argument value.
Each optional argument 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
```'Iteration Limit = 500'
```
is an example of a string used to set an optional argument. 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 double value.  Such numbers may be up to $16$ contiguous characters in   C's d or g format.
nag_real_symm_sparse_eigensystem_option (f12fdc) 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. nag_real_symm_sparse_eigensystem_option (f12fdc) is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in Chapter e04.
The setup function nag_real_symm_sparse_eigensystem_init (f12fac) must be called prior to the first call to nag_real_symm_sparse_eigensystem_option (f12fdc) and all calls to nag_real_symm_sparse_eigensystem_option (f12fdc) must precede the first call to nag_real_symm_sparse_eigensystem_iter (f12fbc), the reverse communication iterative solver.
A complete list of optional arguments, their abbreviations, synonyms and default values is given in Section 10.

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 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, Philidelphia

5  Arguments

1:     str – const char *Input
On entry: a single valid option string (as described in Section 3 and Section 10).
2:     icomm[$\mathit{dim}$] – IntegerCommunication Array
Note: the dimension, dim, of the array icomm must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{licomm}}\right)$ (see nag_real_symm_sparse_eigensystem_init (f12fac)).
On initial entry: must remain unchanged following a call to the setup function nag_real_symm_sparse_eigensystem_init (f12fac).
On exit: contains data on the current options set.
3:     comm[$\mathit{dim}$] – doubleCommunication Array
Note: the dimension, dim, of the array comm must be at least $60$.
On initial entry: must remain unchanged following a call to the setup function nag_real_symm_sparse_eigensystem_init (f12fac).
On exit: contains data on the current options set.
4:     fail – NagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_BAD_PARAM
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_OPTION
Ambiguous keyword: $〈\mathit{\text{value}}〉$
Keyword not recognized: $〈\mathit{\text{value}}〉$
Second keyword not recognized: $〈\mathit{\text{value}}〉$

Not applicable.

None.

9  Example

This example solves $Ax=\lambda Bx$ in ${\mathbf{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 $\left[0,1\right]$, with zero Dirichlet boundary conditions. Data is passed to and from the reverse communication function nag_real_symm_sparse_eigensystem_iter (f12fbc) using pointers to the communication array.

9.1  Program Text

Program Text (f12fdce.c)

9.2  Program Data

Program Data (f12fdce.d)

9.3  Program Results

Program Results (f12fdce.r)

10  Optional Arguments

Several optional arguments for the computational functions nag_real_symm_sparse_eigensystem_iter (f12fbc) and nag_real_symm_sparse_eigensystem_sol (f12fcc) define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of nag_real_symm_sparse_eigensystem_iter (f12fbc) and nag_real_symm_sparse_eigensystem_sol (f12fcc) these optional arguments have associated default values that are appropriate for most problems. Therefore, you need only specify those optional arguments 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 arguments. The following is a list of the optional arguments available and a full description of each optional argument is provided in Section 10.1.
Optional arguments may be specified by calling nag_real_symm_sparse_eigensystem_option (f12fdc) before a call to nag_real_symm_sparse_eigensystem_iter (f12fbc), but after a call to nag_real_symm_sparse_eigensystem_init (f12fac). One call is necessary for each optional argument.
All optional arguments you do not specify are set to their default values. Optional arguments you do specify are unaltered by nag_real_symm_sparse_eigensystem_iter (f12fbc) and nag_real_symm_sparse_eigensystem_sol (f12fcc) (unless they define invalid values) and so remain in effect for subsequent calls unless you alter them.

10.1  Description of the Optional Arguments

For each option, we give a summary line, a description of the optional argument 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\text{​ 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 nag_machine_precision (X02AJC)).
Keywords and character values are case and white space insensitive.
Optional arguments used to specify files (e.g., ${\mathbf{Advisory}}$ and ${\mathbf{Monitoring}}$) have type Nag_FileID. This ID value must either be set to $0$ (the default value) in which case there will be no output, or will be as returned by a call of nag_open_file (x04acc).

Advisory  Default $\text{}=0$
(See Section 3.2.1.1 in the Essential Introduction for further information on NAG data types.)
Advisory messages are output to Nag_FileID ${\mathbf{Advisory}}$ during the solution of the problem.

Defaults
This special keyword may be used to reset all optional arguments to their default values.

Exact Shifts  Default

Supplied Shifts
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 ${\mathbf{Exact Shifts}}$ is strongly recommended over the alternative ${\mathbf{Supplied Shifts}}$ (see Lehoucq et al. (1998) for details of shift strategies).
If ${\mathbf{Exact Shifts}}$ are used then these are computed internally by the algorithm in the implicit restarting scheme.
If ${\mathbf{Supplied Shifts}}$ are used then, during the Lanczos iterative process, you must supply shifts through array arguments of nag_real_symm_sparse_eigensystem_iter (f12fbc) when nag_real_symm_sparse_eigensystem_iter (f12fbc) returns with ${\mathbf{irevcm}}=3$; the real and imaginary parts of the shifts are supplied in y and mx respectively. 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 nag_real_symm_sparse_eigensystem_iter (f12fbc) exits. If not all requested eigenvalues have converged to within ${\mathbf{Tolerance}}$ and the number of Lanczos iterations has reached this limit then nag_real_symm_sparse_eigensystem_iter (f12fbc) exits with an error; nag_real_symm_sparse_eigensystem_sol (f12fcc) can still be called subsequently to return the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors.

Largest Magnitude  Default

Both Ends

Largest Algebraic

Smallest Algebraic

Smallest Magnitude
The Lanczos iterative method converges on a number of eigenvalues with given properties. The default is for nag_real_symm_sparse_eigensystem_iter (f12fbc) to compute the eigenvalues of largest magnitude using ${\mathbf{Largest Magnitude}}$. Alternatively, eigenvalues may be chosen which have ${\mathbf{Largest Algebraic}}$ part, ${\mathbf{Smallest Magnitude}}$, or ${\mathbf{Smallest Algebraic}}$ part; or eigenvalues which are from ${\mathbf{Both Ends}}$ of the algebraic spectrum.
Note that these options select the eigenvalue properties for eigenvalues of $\mathrm{OP}$ (and $B$ for ${\mathbf{Generalized}}$ problems), the linear operator determined by the computational mode and problem type.

Nolist  Default

List
Normally each optional argument specification is not printed to ${\mathbf{Advisory}}$ as it is supplied. Optional argument ${\mathbf{List}}$ may be used to enable printing and optional argument ${\mathbf{Nolist}}$ may be used to suppress the printing.

Monitoring  Default $\text{}=-1$
(See Section 3.2.1.1 in the Essential Introduction for further information on NAG data types.)
Unless ${\mathbf{Monitoring}}$ is set to $-1$ (the default), monitoring information is output to Nag_FileID ${\mathbf{Monitoring}}$ during the solution of each problem; this may be the same as ${\mathbf{Advisory}}$. The type of information produced is dependent on the value of ${\mathbf{Print Level}}$, see the description of the optional argument ${\mathbf{Print Level}}$ in this section for details of the information produced. Please see nag_open_file (x04acc) to associate a file with a given Nag_FileID.

Print Level  $i$  Default $\text{}=0$
This controls the amount of printing produced by nag_real_symm_sparse_eigensystem_option (f12fdc) as follows.

$=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 nag_real_symm_sparse_eigensystem_iter (f12fbc).
$\ge 5$  A single line of summary output at each Lanczos iteration.
$\ge 10$  If   ${\mathbf{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-orthogonalisation, 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 nag_real_symm_sparse_eigensystem_iter (f12fbc). If   ${\mathbf{Monitoring}}$ is set,  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-orthogonalisation.
$\ge 30$  If   ${\mathbf{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 $H$; during re-orthogonalisation, 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}}$ 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 $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}}$ is set, 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 ${\mathbf{Monitoring}}$ output.

Random Residual  Default

Initial Residual
To begin the Lanczos iterative process, nag_real_symm_sparse_eigensystem_iter (f12fbc) requires an initial residual vector. By default nag_real_symm_sparse_eigensystem_iter (f12fbc) provides its own random initial residual vector; this option can also be set using optional argument ${\mathbf{Random Residual}}$. Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to nag_real_symm_sparse_eigensystem_iter (f12fbc) through the array argument resid; this option can be set using optional argument ${\mathbf{Initial Residual}}$.

Regular  Default

Regular Inverse

Shifted Inverse

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 nag_real_symm_sparse_eigensystem_iter (f12fbc) returns with ${\mathbf{irevcm}}=-1$ or $1$ and the matrix-vector product $Bx$ when nag_real_symm_sparse_eigensystem_iter (f12fbc) returns with ${\mathbf{irevcm}}=2$.
Given a ${\mathbf{Standard}}$ eigenvalue problem in the form $Ax=\lambda x$ then the following modes are available with the appropriate operator $\mathrm{OP}\left(x\right)$.

${\mathbf{Regular}}$  $\mathrm{OP}=A$
${\mathbf{Shifted Inverse}}$  $\mathrm{OP}={\left(A-\sigma I\right)}^{-1}$ where $\sigma $ is real
Given a ${\mathbf{Generalized}}$ eigenvalue problem in the form $Ax=\lambda Bx$ then the following modes are available with the appropriate operator $\mathrm{OP}\left(x\right)$.

${\mathbf{Regular Inverse}}$   $\mathrm{OP}={B}^{-1}A$
${\mathbf{Shifted Inverse}}$   $\mathrm{OP}={\left(A-\sigma B\right)}^{-1}B$, where $\sigma $ is real
${\mathbf{Buckling}}$  $\mathrm{OP}={\left(B-\sigma A\right)}^{-1}A$, where $\sigma $ is real
${\mathbf{Cayley}}$  $\mathrm{OP}={\left(A-\sigma B\right)}^{-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 argument ${\mathbf{Standard}}$ should be used when a standard eigenvalue problem is being solved and the optional argument ${\mathbf{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 ${\mathbf{Tolerance}}$ relative to the magnitude of the eigenvalue.

Vectors  Default $\text{}=\text{RITZ}$
The function nag_real_symm_sparse_eigensystem_sol (f12fcc) 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 nag_real_symm_sparse_eigensystem_sol (f12fcc). 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 nag_real_symm_sparse_eigensystem_sol (f12fcc), if z is set equal to v (as in Section 9) then the Schur vectors in v are overwritten by the eigenvectors computed by nag_real_symm_sparse_eigensystem_sol (f12fcc).
{"extraction_info": {"found_math": true, "script_math_tex": 0, "script_math_asciimath": 0, "math_annotations": 0, "math_alttext": 0, "mathml": 119, "mathjax_tag": 0, "mathjax_inline_tex": 0, "mathjax_display_tex": 0, "mathjax_asciimath": 0, "img_math": 0, "codecogs_latex": 0, "wp_latex": 0, "mimetex.cgi": 0, "/images/math/codecogs": 0, "mathtex.cgi": 0}, "config": {"markdown_headings": false, "markdown_code": true, "boilerplate_config": {"ratio_threshold": 0.18, "absolute_threshold": 10, "end_threshold": 15, "enable": true}, "remove_buttons": true, "remove_image_figures": true, "remove_link_clusters": true, "table_config": {"min_rows": 2, "min_cols": 3, "format": "github"}, "remove_chinese": true, "remove_edit_buttons": true, "extract_latex": true}, "english_confidence": 0.6098495721817017, "perplexity_flag": "middle"}