nag_complex_sparse_eigensystem_option (f12arc) : NAG Library, Mark 26

nag_complex_sparse_eigensystem_option (f12arc) is an option setting function in a suite of functions consisting of nag_complex_sparse_eigensystem_init (f12anc), nag_complex_sparse_eigensystem_iter (f12apc), nag_complex_sparse_eigensystem_sol (f12aqc), nag_complex_sparse_eigensystem_option (f12arc) and nag_complex_sparse_eigensystem_monit (f12asc), for which it may be used to supply individual optional parameters to nag_complex_sparse_eigensystem_iter (f12apc) and nag_complex_sparse_eigensystem_sol (f12aqc). nag_complex_sparse_eigensystem_option (f12arc) is also an option setting function in a suite of functions consisting of nag_complex_sparse_eigensystem_init (f12anc), nag_complex_banded_eigensystem_init (f12atc) and nag_complex_banded_eigensystem_solve (f12auc) for which it may be used to supply individual optional parameters to nag_complex_banded_eigensystem_solve (f12auc).

The initialization function for the appropriate suite, nag_complex_sparse_eigensystem_init (f12anc) or nag_complex_banded_eigensystem_init (f12atc), must have been called prior to calling nag_complex_sparse_eigensystem_option (f12arc).

Specification

Description

nag_complex_sparse_eigensystem_option (f12arc) may be used to supply values for optional parameters to nag_complex_sparse_eigensystem_iter (f12apc) and nag_complex_sparse_eigensystem_sol (f12aqc), or to nag_complex_banded_eigensystem_solve (f12auc). It is only necessary to call nag_complex_sparse_eigensystem_option (f12arc) for those arguments whose values are to be different from their default values. One call to nag_complex_sparse_eigensystem_option (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

[=]

. 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.

nag_complex_sparse_eigensystem_option (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. nag_complex_sparse_eigensystem_option (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 nag_opt_sparse_convex_qp_option_set_string (e04nsc) for an example).

The setup function nag_complex_sparse_eigensystem_init (f12anc) must be called prior to the first call to nag_complex_sparse_eigensystem_option (f12arc) or nag_complex_banded_eigensystem_init (f12atc), and all calls to nag_complex_sparse_eigensystem_option (f12arc) must precede the first call to nag_complex_sparse_eigensystem_iter (f12apc) or nag_complex_banded_eigensystem_solve (f12auc).

A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section 11.

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

Arguments

Error Indicators and Warnings

Accuracy

Parallelism and Performance

nag_complex_sparse_eigensystem_option (f12arc) is not threaded in any implementation.

Further Comments

Example

This example solves

A x = λ B x

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}} + ρ \frac{d u}{d x}

on the interval

[0, 1]

, with zero Dirichlet boundary conditions.

10.1

Program Text

10.2

Program Data

10.3

Program Results

Optional Parameters

Several optional parameters for the computational suite functions nag_complex_sparse_eigensystem_iter (f12apc) and nag_complex_sparse_eigensystem_sol (f12aqc), and for the banded driver nag_complex_banded_eigensystem_solve (f12auc), define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of nag_complex_sparse_eigensystem_iter (f12apc), nag_complex_sparse_eigensystem_sol (f12aqc) and nag_complex_banded_eigensystem_solve (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 nag_complex_sparse_eigensystem_option (f12arc) before a call to nag_complex_sparse_eigensystem_iter (f12apc) or nag_complex_banded_eigensystem_init (f12atc), but after a corresponding call to nag_complex_sparse_eigensystem_init (f12anc) or nag_complex_banded_eigensystem_solve (f12auc). 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 nag_complex_sparse_eigensystem_iter (f12apc), nag_complex_sparse_eigensystem_sol (f12aqc) and nag_complex_banded_eigensystem_solve (f12auc) (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:

Keywords and character values are case and white space insensitive.

Optional parameters used to specify files (e.g.,

Advisory

and

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).

(See Section 3.3.1.1 in How to Use the NAG Library and its Documentation for further information on NAG data types.)

Advisory messages are output to Nag_FileID

Advisory

during the solution of the problem.

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 nag_complex_banded_eigensystem_solve (f12auc).

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.

Supplied Shifts

are used then, during the Arnoldi iterative process, you must supply shifts through array arguments of nag_complex_sparse_eigensystem_iter (f12apc) when nag_complex_sparse_eigensystem_iter (f12apc) returns with

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).

The limit on the number of Arnoldi iterations that can be performed before nag_complex_sparse_eigensystem_iter (f12apc) or nag_complex_banded_eigensystem_solve (f12auc) exits. If not all requested eigenvalues have converged to within

Tolerance

and the number of Arnoldi iterations has reached this limit then nag_complex_sparse_eigensystem_iter (f12apc) or nag_complex_banded_eigensystem_solve (f12auc) exits with an error; nag_complex_banded_eigensystem_solve (f12auc) returns the number of converged eigenvalues, the converged eigenvalues and, if requested, the corresponding eigenvectors, while nag_complex_sparse_eigensystem_sol (f12aqc) can be called subsequent to nag_complex_sparse_eigensystem_iter (f12apc) to do the same.

The Arnoldi iterative method converges on a number of eigenvalues with given properties. The default is for nag_complex_sparse_eigensystem_iter (f12apc) or nag_complex_banded_eigensystem_solve (f12auc) 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.

Normally each optional parameter specification is not printed to

Advisory

as it is supplied. Optional parameter

List

may be used to enable printing and optional parameter

Nolist

may be used to suppress the printing.

(See Section 3.3.1.1 in How to Use the NAG Library and its Documentation for further information on NAG data types.)

Unless

Monitoring

is set to

- 1

(the default), monitoring information is output to Nag_FileID

Monitoring

during the solution of each problem; this may be the same as

Advisory

. The type of information produced is dependent on the value of

Print Level

, see the description of the optional parameter

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.

This controls the amount of printing produced by nag_complex_sparse_eigensystem_option (f12arc) as follows.

$= 0$	No output except error messages.
$> 0$	The set of selected options.
$= 2$	Problem and timing statistics on final exit from nag_complex_sparse_eigensystem_iter (f12apc) or nag_complex_banded_eigensystem_solve (f12auc).
$\geq 5$	A single line of summary output at each Arnoldi iteration.
$\geq 10$	If $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.
$\geq 20$	Problem and timing statistics on final exit from nag_complex_sparse_eigensystem_iter (f12apc). If $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.
$\geq 30$	If $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.
$\geq 40$	If $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$ .
$\geq 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, nag_complex_sparse_eigensystem_iter (f12apc) and nag_complex_banded_eigensystem_solve (f12auc) requires an initial residual vector. By default nag_complex_sparse_eigensystem_iter (f12apc) and nag_complex_banded_eigensystem_solve (f12auc) 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 nag_complex_sparse_eigensystem_iter (f12apc) and nag_complex_banded_eigensystem_solve (f12auc) 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

OP (x)

to be performed by nag_complex_banded_eigensystem_solve (f12auc) or when nag_complex_sparse_eigensystem_iter (f12apc) returns with

irevcm = - 1

1

and the matrix-vector product

B x

when nag_complex_sparse_eigensystem_iter (f12apc) returns with

irevcm = - 2

Given a

Standard

eigenvalue problem in the form

A x = λ x

then the following modes are available with the appropriate operator

OP (x)

$Regular$	$OP = A$
$Shifted Inverse$	$OP = {(A - σ I)}^{- 1}$

Given a

Generalized

eigenvalue problem in the form

A x = λ B x

then the following modes are available with the appropriate operator

OP (x)

$Regular Inverse$	$OP = B^{- 1} A$
$Shifted Inverse$	$OP = {(A - σ B)}^{- 1} B$

The problem to be solved is either a standard eigenvalue problem,

A x = λ x

, or a generalized eigenvalue problem,

A x = λ B x

. 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.

An approximate eigenvalue has deemed to have converged when the corresponding Ritz estimate is within

Tolerance

relative to the magnitude of the eigenvalue.

The function nag_complex_sparse_eigensystem_sol (f12aqc) or nag_complex_banded_eigensystem_solve (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

Vectors = NONE

should be set. To compute only the Schur vectors (at very little extra cost), the option

Vectors = SCHUR

should be set and these will be returned in the array argument v of nag_complex_sparse_eigensystem_sol (f12aqc) or nag_complex_banded_eigensystem_solve (f12auc). To compute the eigenvectors (Ritz vectors) corresponding to the eigenvalue estimates, the option

Vectors = RITZ

should be set and these will be returned in the array argument z of nag_complex_sparse_eigensystem_sol (f12aqc) or nag_complex_banded_eigensystem_solve (f12auc), if z is set equal to v (as in Section 10) then the Schur vectors in v are overwritten by the eigenvectors computed by nag_complex_sparse_eigensystem_sol (f12aqc) or nag_complex_banded_eigensystem_solve (f12auc).

NAG Library Function Document

nag_complex_sparse_eigensystem_option (f12arc)

▸▿ Contents

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

6

Error Indicators and Warnings

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

10.2

Program Data

10.3

Program Results

11

Optional Parameters

11.1

Description of the Optional Parameters

NAG Library Function Document

nag_complex_sparse_eigensystem_option (f12arc)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

11 Optional Parameters

11.1 Description of the Optional Parameters