# NAG CL Interfacef12arc (complex_​option)

Note: this function 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 function 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.

Settings help

CL Name Style:

## 1Purpose

f12arc is an option setting function in a suite of functions consisting of f12anc, f12apc, f12aqc, f12arc and f12asc; it supplies individual optional parameters to f12apc and f12aqc. f12arc is also an option setting function in a suite of functions consisting of f12arc, f12atc and f12auc; it supplies individual optional parameters to f12auc.
The initialization function for the appropriate suite, f12anc or f12atc, must have been called prior to calling f12arc.

## 2Specification

 #include
 void f12arc (const char *str, Integer icomm[], Complex comm[], NagError *fail)
The function may be called by the names: f12arc, nag_sparseig_complex_option or nag_complex_sparse_eigensystem_option.

## 3Description

f12arc may be used to supply values for optional parameters to f12apc and f12aqc, or to f12auc. It is only necessary to call f12arc for those arguments whose values are to be different from their default values. One call to f12arc 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
`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 double value. Such numbers may be up to $16$ contiguous characters in C's d or g format.
f12arc 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. f12arc is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in Chapter E04 (see e04nsc for an example).
The setup function f12anc or f12atc must be called prior to the first call to f12arc, and all calls to f12arc must precede the first call to f12apc and f12auc.
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 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, Philadelphia

## 5Arguments

1: $\mathbf{str}$const char * Input
On entry: a single valid option string (as described in Section 3 and Section 11).
2: $\mathbf{icomm}\left[\mathit{dim}\right]$Integer Communication Array
Note: the actual argument supplied must be the array icomm supplied to the initialization routines f12anc f12atc.
On initial entry: must remain unchanged following a call to the setup function f12anc or f12atc.
On exit: contains data on the current options set.
3: $\mathbf{comm}\left[\mathit{dim}\right]$Complex Communication Array
Note: the actual argument supplied must be the array comm supplied to the initialization routines f12anc f12atc.
On initial entry: must remain unchanged following a call to the setup function f12anc or f12atc.
On exit: contains data on the current options set.
4: $\mathbf{fail}$NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

## 6Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
NE_BAD_PARAM
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_INITIALIZATION
Either the initialization function has not been called prior to the call of this function or a communication array has become corrupted.
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.
See Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
NE_INVALID_OPTION
Ambiguous keyword: $⟨\mathit{\text{value}}⟩$
Keyword not recognized: $⟨\mathit{\text{value}}⟩$
Second keyword not recognized: $⟨\mathit{\text{value}}⟩$
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library CL Interface for further information.

Not applicable.

## 8Parallelism and Performance

f12arc is not threaded in any implementation.

None.

## 10Example

This example solves $Ax=\lambda Bx$ in shifted-inverse mode, where $A$ and $B$ are derived from the finite element discretization of the one-dimensional convection-diffusion 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.1Program Text

Program Text (f12arce.c)

### 10.2Program Data

Program Data (f12arce.d)

### 10.3Program Results

Program Results (f12arce.r)

## 11Optional Parameters

Several optional parameters for the computational suite functions f12apc and f12aqc, and for the banded driver f12auc, define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of f12apc, f12aqc and f12auc 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 f12arc before a call to f12apc or f12auc, but after a corresponding call to f12anc or f12atc. 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 f12apc, f12aqc and f12auc (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 X02AJC).
Keywords and character values are case and white space insensitive.
Optional parameters 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 x04acc.
 Advisory Default $\text{}=0$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface 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 parameters to their default values.
 Exact Shifts Default
 Supplied Shifts
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 ${\mathbf{Exact Shifts}}$ is strongly recommended over the alternative ${\mathbf{Supplied Shifts}}$ and will always be used by f12auc.
If ${\mathbf{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 ${\mathbf{Supplied Shifts}}$ are used then, during the Arnoldi iterative process, you must supply shifts through array arguments of f12apc when f12apc returns with ${\mathbf{irevcm}}=3$; the complex shifts are supplied in y. 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 f12apc or f12auc exits. If not all requested eigenvalues have converged to within ${\mathbf{Tolerance}}$ and the number of Arnoldi iterations has reached this limit then f12apc or f12auc exits with an error; f12auc returns the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors, while f12aqc can be called subsequent to f12apc to do the same.
 Largest Magnitude Default
 Largest Imaginary
 Largest Real
 Smallest Imaginary
 Smallest Magnitude
 Smallest Real
The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for f12apc or f12auc to compute the eigenvalues of largest magnitude using ${\mathbf{Largest Magnitude}}$. Alternatively, eigenvalues may be chosen which have ${\mathbf{Largest Real}}$ part, ${\mathbf{Largest Imaginary}}$ part, ${\mathbf{Smallest Magnitude}}$, ${\mathbf{Smallest Real}}$ part or ${\mathbf{Smallest Imaginary}}$ part.
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
Optional parameter ${\mathbf{List}}$ enables printing of each optional parameter specification as it is supplied. ${\mathbf{Nolist}}$ suppresses this printing.
 Monitoring Default $\text{}=-1$
(See Section 3.1.1 in the Introduction to the NAG Library CL Interface 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 parameter ${\mathbf{Print Level}}$ in this section for details of the information produced. Please see x04acc to associate a file with a given Nag_FileID.
 Print Level $i$ Default $\text{}=0$
This controls the amount of printing produced by f12arc as follows.
$\mathbit{i}$ Output
$=0$ No output except error messages.
$>0$ The set of selected options.
$=2$ Problem and timing statistics on final exit from f12apc or f12auc.
$\ge 5$ A single line of summary output at each Arnoldi iteration.
$\ge 10$ If ${\mathbf{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 re-orthogonalization, the norm of initial/restarted starting vector.
$\ge 20$ Problem and timing statistics on final exit from f12apc. If ${\mathbf{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 re-orthogonalization.
$\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 compressed upper Hessenberg matrix $H$; during re-orthogonalization, 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}}$ 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 ${\mathbf{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.
 Random Residual Default
 Initial Residual
To begin the Arnoldi iterative process, f12apc or f12auc requires an initial residual vector. By default f12apc or f12auc provides its own random initial residual vector; this option can also be set using optional parameter ${\mathbf{Random Residual}}$. Alternatively, you can supply an initial residual vector (perhaps from a previous computation) to f12apc or f12auc through the array argument resid; this option can be set using optional parameter ${\mathbf{Initial Residual}}$.
 Regular Default
 Regular Inverse
 Shifted Inverse
These options define the computational mode which in turn defines the form of operation $\mathrm{op}\left(x\right)$ to be performed by f12auc or when f12apc returns with ${\mathbf{irevcm}}=-1$ or $1$ and the matrix-vector product $Bx$ when f12apc 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}$
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$
 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 ${\mathbf{Standard}}$ should be used when a standard eigenvalue problem is being solved and the optional parameter ${\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{}=\mathrm{RITZ}$
The function f12aqc or f12auc 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 f12aqc or f12auc. 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 f12aqc or f12auc, if z is set equal to v then the Schur vectors in v are overwritten by the eigenvectors computed by f12aqc or f12auc.