naginterfaces.library.sparseig.complex_​option

naginterfaces.library.sparseig.complex_option(optstr, comm, io_manager=None)

complex_option is an option setting function in a suite of functions consisting of complex_init(), complex_iter(), complex_proc(), complex_option and complex_monit(); it supplies individual options to complex_iter() and complex_proc(). complex_option is also an option setting function in a suite of functions consisting of complex_option, complex_band_init() and complex_band_solve(); it supplies individual options to complex_band_solve().

The initialization function for the appropriate suite, complex_init() or complex_band_init(), must have been called prior to calling complex_option.

Note: this function uses optional algorithmic parameters, see also: complex_iter(), complex_proc(), complex_band_solve(), complex_init(), complex_band_init().

For full information please refer to the NAG Library document for f12ar

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f12/f12arf.html

Parameters

optstrstr

A single valid option string (as described in Notes and Other Parameters).

commdict, communication object, modified in place

Communication structure.

This argument must have been initialized by a prior call to complex_init() or complex_band_init().

io_managerFileObjManager, optional

Manager for I/O in this routine.

Other Parameters

‘Advisory’int

Default $=\text{advisory message unit number}$

The destination for advisory messages.

‘Defaults’valueless

This special keyword may be used to reset all options to their default values.

‘Exact Shifts’valueless

Default

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 option ‘Exact Shifts’ is strongly recommended over the alternative ‘Supplied Shifts’ and will always be used by complex_band_solve().

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 complex_iter() when complex_iter() returns with $\text{irevcm}=3$; the complex shifts are returned in $\text{x}$ (or in $\text{comm}$ when the option $\text{‘Pointers'}=\text{'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).

‘Supplied Shifts’valueless

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 option ‘Exact Shifts’ is strongly recommended over the alternative ‘Supplied Shifts’ and will always be used by complex_band_solve().

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 complex_iter() when complex_iter() returns with $\text{irevcm}=3$; the complex shifts are returned in $\text{x}$ (or in $\text{comm}$ when the option $\text{‘Pointers'}=\text{'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’int

Default $=300$

The limit on the number of Arnoldi iterations that can be performed before complex_iter() or complex_band_solve() exits. If not all requested eigenvalues have converged to within ‘Tolerance’ and the number of Arnoldi iterations has reached this limit then complex_iter() or complex_band_solve() exits with an error; complex_band_solve() returns the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors, while complex_proc() can be called subsequent to complex_iter() to do the same.

‘Largest Magnitude’valueless

Default

The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for complex_iter() or complex_band_solve() 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 $op$ (and $B$ for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.

‘Largest Imaginary’valueless

The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for complex_iter() or complex_band_solve() 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 $op$ (and $B$ for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.

‘Largest Real’valueless

The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for complex_iter() or complex_band_solve() 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 $op$ (and $B$ for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.

‘Smallest Imaginary’valueless

The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for complex_iter() or complex_band_solve() 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 $op$ (and $B$ for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.

‘Smallest Magnitude’valueless

The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for complex_iter() or complex_band_solve() 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 $op$ (and $B$ for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.

‘Smallest Real’valueless

The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for complex_iter() or complex_band_solve() 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 $op$ (and $B$ for ‘Generalized’ problems), the linear operator determined by the computational mode and problem type.

‘Nolist’valueless

Default

Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.

‘List’valueless

Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.

‘Monitoring’int

Default $=-1$

If $i>0$, monitoring information is output to unit number (see unit_from_fileobj()) $i$ during the solution of each problem; this may be the same as the ‘Advisory’ unit number (see unit_from_fileobj()). The type of information produced is dependent on the value of ‘Print Level’, see the description of the option ‘Print Level’ for details of the information produced. Please see the FileObjManager method unit_from_fileobj() to associate a file with a given unit number (see unit_from_fileobj()).

‘Pointers’valueless

Default $=\text{'NO'}$

During the iterative process and reverse communication calls to complex_iter(), required data can be communicated to and from complex_iter() in one of two ways. When $\text{‘Pointers'}=\text{'NO'}$ is selected (the default) then the array arguments $\text{x}$ and $\text{mx}$ are used to supply you with required data and used to return computed values back to complex_iter(). For example, when $\text{irevcm}=1$, complex_iter() returns the vector $x$ in $\text{x}$ and the matrix-vector product $Bx$ in $\text{mx}$ and expects the result or the linear operation $op\left(x\right)$ to be returned in $\text{x}$.

If $\text{‘Pointers'}=\text{'YES'}$ is selected then the data is passed through sections of the array argument $\text{comm}$. The section corresponding to $\text{x}$ when $\text{‘Pointers'}=\text{'NO'}$ begins at a location given by the first element of $\text{icomm}$; similarly the section corresponding to $\text{mx}$ begins at a location given by the second element of $\text{icomm}$. This option allows complex_iter() 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 complex_band_solve() which sets $\text{‘Pointers'}=\text{'YES'}$ internally.

‘Print Level’int

Default $=0$

This controls the amount of printing produced by complex_option as follows.

$i$	Output
$=0$	No output except error messages.
$>0$	The set of selected options.
$=2$	Problem and timing statistics on final exit from complex_iter() or complex_band_solve().
$\ge 5$	A single line of summary output at each Arnoldi iteration.
$\ge 10$	If $\text{‘Monitoring'}>0$, 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 complex_iter(). If $\text{‘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 re-orthogonalization.
$\ge 30$	If $\text{‘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 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 $\text{‘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 $\text{‘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.

‘Random Residual’valueless

Default

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

‘Initial Residual’valueless

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

‘Regular’valueless

Default

These options define the computational mode which in turn defines the form of operation $op\left(x\right)$ to be performed by complex_band_solve() or when complex_iter() returns with $\text{irevcm}=-1$ or $1$ and the matrix-vector product $Bx$ when complex_iter() returns with $\text{irevcm}=-2$.

Given a ‘Standard’ eigenvalue problem in the form $Ax=\lambda x$ then the following modes are available with the appropriate operator $op\left(x\right)$.

‘Regular’	$op=A$
‘Shifted Inverse’	$op={(A-\sigma I)}^{-1}$

Given a ‘Generalized’ eigenvalue problem in the form $Ax=\lambda Bx$ then the following modes are available with the appropriate operator $op\left(x\right)$.

‘Regular Inverse’	$op=B^{-1}A$
‘Shifted Inverse’	$op={(A-\sigma B)}^{-1}B$

‘Regular Inverse’valueless

These options define the computational mode which in turn defines the form of operation $op\left(x\right)$ to be performed by complex_band_solve() or when complex_iter() returns with $\text{irevcm}=-1$ or $1$ and the matrix-vector product $Bx$ when complex_iter() returns with $\text{irevcm}=-2$.

Given a ‘Standard’ eigenvalue problem in the form $Ax=\lambda x$ then the following modes are available with the appropriate operator $op\left(x\right)$.

‘Regular’	$op=A$
‘Shifted Inverse’	$op={(A-\sigma I)}^{-1}$

Given a ‘Generalized’ eigenvalue problem in the form $Ax=\lambda Bx$ then the following modes are available with the appropriate operator $op\left(x\right)$.

‘Regular Inverse’	$op=B^{-1}A$
‘Shifted Inverse’	$op={(A-\sigma B)}^{-1}B$

‘Shifted Inverse’valueless

These options define the computational mode which in turn defines the form of operation $op\left(x\right)$ to be performed by complex_band_solve() or when complex_iter() returns with $\text{irevcm}=-1$ or $1$ and the matrix-vector product $Bx$ when complex_iter() returns with $\text{irevcm}=-2$.

Given a ‘Standard’ eigenvalue problem in the form $Ax=\lambda x$ then the following modes are available with the appropriate operator $op\left(x\right)$.

‘Regular’	$op=A$
‘Shifted Inverse’	$op={(A-\sigma I)}^{-1}$

Given a ‘Generalized’ eigenvalue problem in the form $Ax=\lambda Bx$ then the following modes are available with the appropriate operator $op\left(x\right)$.

‘Regular Inverse’	$op=B^{-1}A$
‘Shifted Inverse’	$op={(A-\sigma B)}^{-1}B$

‘Standard’valueless

Default

The problem to be solved is either a standard eigenvalue problem, $Ax=\lambda x$, or a generalized eigenvalue problem, $Ax=\lambda Bx$. The option ‘Standard’ should be used when a standard eigenvalue problem is being solved and the option ‘Generalized’ should be used when a generalized eigenvalue problem is being solved.

‘Generalized’valueless

The problem to be solved is either a standard eigenvalue problem, $Ax=\lambda x$, or a generalized eigenvalue problem, $Ax=\lambda Bx$. The option ‘Standard’ should be used when a standard eigenvalue problem is being solved and the option ‘Generalized’ should be used when a generalized eigenvalue problem is being solved.

‘Tolerance’float

Default $=ϵ$

An approximate eigenvalue has deemed to have converged when the corresponding Ritz estimate is within ‘Tolerance’ relative to the magnitude of the eigenvalue.

‘Vectors’valueless

Default $=\text{'RITZ'}$

The function complex_proc() or complex_band_solve() can optionally compute the Schur vectors and/or the eigenvectors corresponding to the converged eigenvalues. To turn off computation of any vectors the option $\text{‘Vectors'}=\text{'NONE'}$ should be set. To compute only the Schur vectors (at very little extra cost), the option $\text{‘Vectors'}=\text{'SCHUR'}$ should be set and these will be returned in the array argument $\text{v}$ of complex_proc() or complex_band_solve(). To compute the eigenvectors (Ritz vectors) ­corresponding to the eigenvalue estimates, the option $\text{‘Vectors'}=\text{'RITZ'}$ should be set and these will be returned in the array argument $\text{z}$ of complex_proc() or complex_band_solve(), if $\text{z}$ is set equal to $\text{v}$ then the Schur vectors in $\text{v}$ are overwritten by the eigenvectors computed by complex_proc() or complex_band_solve().

Raises

NagValueError

(errno $1$)

Ambiguous keyword: $⟨value⟩$

(errno $2$)

Keyword not recognized: $⟨value⟩$

(errno $3$)

Second keyword not recognized: $⟨value⟩$

(errno $4$)

Either the initialization function has not been called prior to the call of this function or a communication array has become corrupted.

Notes

complex_option may be used to supply values for options to complex_iter() and complex_proc(), or to complex_band_solve(). It is only necessary to call complex_option for those arguments whose values are to be different from their default values. One call to complex_option sets one argument value.

Each option 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 option. 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 int or float value. Such numbers may be up to $16$ contiguous characters in Fortran’s I, F, E or D format.

complex_option 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. complex_option is intended to make the passing of options more transparent and follows the same principle as the single option setting functions in submodule opt (see opt.qpconvex2_sparse_option_string for an example).

The setup function complex_init() or complex_band_init() must be called prior to the first call to complex_option, and all calls to complex_option must precede the first call to complex_iter() and complex_band_solve().

A complete list of options, their abbreviations, synonyms and default values is given in Other Parameters.

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