NAG Library Function Document

nag_eigen_real_gen_sparse_arnoldi (f02ekc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:    $\mathbf{n}$ – IntegerInput

On entry: $n$, the order of the matrix $A$.

Constraint: $\mathbf{n}\ge 0$.

2:    $\mathbf{nnz}$ – IntegerInput

On entry: the dimension of the array a.The number of nonzero elements of the matrix $A$ and, if a nonzero shifted inverse is to be applied, all diagonal elements. Each nonzero is counted once in the latter case.

Constraint: $0\le \mathbf{nnz}\le {\mathbf{n}}^2$.

3:    $\mathbf{a}\left[\mathbf{nnz}\right]$ – doubleInput/Output

On entry: the array of nonzero elements (and diagonal elements if a nonzero inverse shift is to be applied) of the $n$ by $n$ general matrix $A$.

On exit: if a nonzero shifted inverse is to be applied then the diagonal elements of $A$ have the shift value, as supplied in sigma, subtracted.

4:    $\mathbf{icolzp}\left[\mathbf{n}+1\right]$ – const IntegerInput

On entry: $\mathbf{icolzp}\left[i-1\right]$ contains the index in a of the start of column $\mathit{i}$, for $\mathit{i}=1,2,\dots ,n$; $\mathbf{icolzp}\left[\mathbf{n}\right]$ must contain the value $\mathbf{nnz}+1$. Thus the number of nonzero elements in column $\mathit{i}$ of $A$ is $\mathbf{icolzp}\left[i\right]-\mathbf{icolzp}\left[i-1\right]$; when shifts are applied this includes diagonal elements irrespective of value. See Section 2.1.3 in the f11 Chapter Introduction.

5:    $\mathbf{irowix}\left[\mathbf{nnz}\right]$ – const IntegerInput

On entry: $\mathbf{irowix}\left[i-1\right]$ contains the row index for each entry in a. See Section 2.1.3 in the f11 Chapter Introduction.

6:    $\mathbf{nev}$ – IntegerInput

On entry: the number of eigenvalues to be computed.

Constraint: $0<\mathbf{nev}<\mathbf{n}-1$.

7:    $\mathbf{ncv}$ – IntegerInput

On entry: the dimension of the array w. The number of Arnoldi basis vectors to use during the computation.

At present there is no a priori analysis to guide the selection of ncv relative to nev. However, it is recommended that $\mathbf{ncv}\ge 2\times \mathbf{nev}+1$. If many problems of the same type are to be solved, you should experiment with increasing ncv while keeping nev fixed for a given test problem. This will usually decrease the required number of matrix-vector operations but it also increases the work and storage required to maintain the orthogonal basis vectors. The optimal ‘cross-over’ with respect to CPU time is problem dependent and must be determined empirically.

Constraint: $\mathbf{nev}+1<\mathbf{ncv}\le \mathbf{n}$.

8:    $\mathbf{sigma}$ – doubleInput

On entry: if the $\mathbf{Shifted\; Inverse\; Real}$ mode has been selected then sigma contains the real shift used; otherwise sigma is not referenced. This mode can be selected by setting the appropriate options in the user-supplied function option.

9:    $\mathbf{monit}$ – function, supplied by the userExternal Function

monit is used to monitor the progress of nag_eigen_real_gen_sparse_arnoldi (f02ekc). monit may be specified as NULLFN if no monitoring is actually required. monit is called after the solution of each eigenvalue sub-problem and also just prior to return from nag_eigen_real_gen_sparse_arnoldi (f02ekc).

The specification of monit is:

void  monit (Integer ncv, Integer niter, Integer nconv, const Complex w[], const double rzest[], Integer *istat, Nag_Comm *comm)

1:    $\mathbf{ncv}$ – IntegerInput

On entry: the dimension of the arrays w and rzest. The number of Arnoldi basis vectors used during the computation.

2:    $\mathbf{niter}$ – IntegerInput

On entry: the number of the current Arnoldi iteration.

3:    $\mathbf{nconv}$ – IntegerInput

On entry: the number of converged eigenvalues so far.

4:    $\mathbf{w}\left[\mathbf{ncv}\right]$ – const ComplexInput

On entry: the first nconv elements of w contain the converged approximate eigenvalues.

5:    $\mathbf{rzest}\left[\mathbf{ncv}\right]$ – const doubleInput

On entry: the first nconv elements of rzest contain the Ritz estimates (error bounds) on the converged approximate eigenvalues.

6:    $\mathbf{istat}$ – Integer *Input/Output

On entry: set to zero.

On exit: if set to a nonzero value nag_eigen_real_gen_sparse_arnoldi (f02ekc) returns immediately with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_USER_STOP.

7:    $\mathbf{comm}$ – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to monit.

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling nag_eigen_real_gen_sparse_arnoldi (f02ekc) you may allocate memory and initialize these pointers with various quantities for use by monit when called from nag_eigen_real_gen_sparse_arnoldi (f02ekc) (see Section 3.2.1.1 in the Essential Introduction).

10:  $\mathbf{option}$ – function, supplied by the userExternal Function

You can supply non-default options to the Arnoldi eigensolver by repeated calls to nag_real_sparse_eigensystem_option (f12adc) from within option. (Please note that it is only necessary to call nag_real_sparse_eigensystem_option (f12adc); no call to nag_real_sparse_eigensystem_init (f12aac) is required from within option.) For example, you can set the mode to $\mathbf{Shifted\; Inverse\; Real}$, you can increase the $\mathbf{Iteration\; Limit}$ beyond its default and you can print varying levels of detail on the iterative process using $\mathbf{Print\; Level}$.

If only the default options (including that the eigenvalues of largest magnitude are sought) are to be used then option may be specified as NULLFN. See Section 10 for an example of using option to set some non-default options.

The specification of option is:

void  option (Integer icom[], double com[], Integer *istat, Nag_Comm *comm)

1:    $\mathbf{icom}\left[140\right]$ – IntegerCommunication Array

On entry: contains details of the default option set. This array must be passed as argument icomm in any call to nag_real_sparse_eigensystem_option (f12adc).

On exit: contains data on the current options set which may be altered from the default set via calls to nag_real_sparse_eigensystem_option (f12adc).

2:    $\mathbf{com}\left[60\right]$ – doubleCommunication Array

On entry: contains details of the default option set. This array must be passed as argument comm in any call to nag_real_sparse_eigensystem_option (f12adc).

On exit: contains data on the current options set which may be altered from the default set via calls to nag_real_sparse_eigensystem_option (f12adc).

3:    $\mathbf{istat}$ – Integer *Input/Output

On entry: set to zero.

On exit: if set to a nonzero value nag_eigen_real_gen_sparse_arnoldi (f02ekc) returns immediately with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_USER_STOP.

4:    $\mathbf{comm}$ – Nag_Comm *

Pointer to structure of type Nag_Comm; the following members are relevant to option.

user – double *

iuser – Integer *

p – Pointer 

The type Pointer will be void *. Before calling nag_eigen_real_gen_sparse_arnoldi (f02ekc) you may allocate memory and initialize these pointers with various quantities for use by option when called from nag_eigen_real_gen_sparse_arnoldi (f02ekc) (see Section 3.2.1.1 in the Essential Introduction).

11:  $\mathbf{nconv}$ – Integer *Output

On exit: the number of converged approximations to the selected eigenvalues. On successful exit, this will normally be either nev or $\mathbf{nev}+1$ depending on the number of complex conjugate pairs of eigenvalues returned.

12:  $\mathbf{w}\left[\mathbf{ncv}\right]$ – ComplexOutput

On exit: the first nconv elements contain the converged approximations to the selected eigenvalues. Since complex conjugate pairs of eigenvalues appear together, it is possible (given an odd number of converged real eigenvalues) for nag_eigen_real_gen_sparse_arnoldi (f02ekc) to return one more eigenvalue than requested.

13:  $\mathbf{v}\left[\mathit{dim}\right]$ – doubleOutput

Note: the dimension, dim, of the array v must be at least $\mathbf{pdv}\times \mathbf{ncv}$.

On exit: contains the eigenvectors associated with the eigenvalue ${\lambda }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,\mathbf{nconv}$ (stored in w). For a real eigenvalue, ${\lambda }_j$, the corresponding eigenvector is real and is stored in $\mathbf{v}\left[\left(j-1\right)\times \mathbf{pdv}+\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,n$. For complex conjugate pairs of eigenvalues, $w_{j+1}=\stackrel{-}{w_j}$, the real and imaginary parts of the corresponding eigenvectors are stored, respectively, in $\mathbf{v}\left[\left(j-1\right)\times \mathbf{pdv}+\mathit{i}-1\right]$ and $\mathbf{v}\left[j\times \mathbf{pdv}+\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,n$. The imaginary parts stored are for the first of the conjugate pair of eigenvectors; the other eigenvector in the pair is obtained by negating these imaginary parts.

14:  $\mathbf{pdv}$ – IntegerInput

On entry: the stride separating, in the array v, real and imaginary parts of elements of a conjugate pair of eigenvectors, or separating the elements of a real eigenvector from the corresponding real parts of the next eigenvector.

Constraint: $\mathbf{pdv}\ge \mathbf{n}$.

15:  $\mathbf{resid}\left[\mathbf{nev}+1\right]$ – doubleOutput

On exit: the residual ${‖A{w}_{\mathit{i}}-{\lambda }_{\mathit{i}}{w}_{\mathit{i}}‖}_2$ for the estimates to the eigenpair ${\lambda }_{\mathit{i}}$ and $w_{\mathit{i}}$ is returned in $\mathbf{resid}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,\mathbf{nconv}$.

16:  $\mathbf{comm}$ – Nag_Comm *

The NAG communication argument (see Section 3.2.1.1 in the Essential Introduction).

17:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 3.2.1.2 in the Essential Introduction for further information.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_DIAG_ELEMENTS

On entry, in shifted inverse mode, the $j$th diagonal element of $A$ is not defined, for $j=〈\mathit{\text{value}}〉$.

NE_EIGENVALUES

The number of eigenvalues found to sufficient accuracy is zero.

NE_INT

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}>0$.

On entry, $\mathbf{nev}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nev}>0$.

On entry, $\mathbf{nnz}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nnz}>0$.

NE_INT_2

On entry, $\mathbf{ncv}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ncv}\le \mathbf{n}$.

On entry, $\mathbf{ncv}=〈\mathit{\text{value}}〉$ and $\mathbf{nev}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ncv}>\mathbf{nev}+1$.

On entry, $\mathbf{nnz}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nnz}\le \mathbf{n}\times \mathbf{n}$.

On entry, $\mathbf{pdv}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pdv}\ge \mathbf{n}$.

NE_INTERNAL_EIGVAL_FAIL

Error in internal call to compute eigenvalues and corresponding error bounds of the current upper Hessenberg matrix.
Please contact NAG.

NE_INTERNAL_EIGVEC_FAIL

In calculating eigenvectors, an internal call returned with an error.
Please contact NAG.

NE_INTERNAL_ERROR

An internal call to nag_real_sparse_eigensystem_iter (f12abc) returned with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_OPT_INCOMPAT.
This error should not occur. Please contact NAG.

An internal call to nag_real_sparse_eigensystem_sol (f12acc) returned with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_INVALID_OPTION.

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.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 3.6.6 in the Essential Introduction for further information.

Internal inconsistency in the number of converged Ritz values. Number counted $=〈\mathit{\text{value}}〉$, number expected $=〈\mathit{\text{value}}〉$.

NE_INVALID_OPTION

The maximum number of iterations $\le 0$, the optional argument $\mathbf{Iteration\; Limit}$ has been set to $〈\mathit{\text{value}}〉$.

NE_NO_ARNOLDI_FAC

Could not build an Arnoldi factorization. The size of the current Arnoldi factorization $=〈\mathit{\text{value}}〉$.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 3.6.5 in the Essential Introduction for further information.

NE_NO_SHIFTS_APPLIED

No shifts could be applied during a cycle of the implicitly restarted Arnoldi iteration.

NE_SCHUR_EIG_FAIL

During calculation of a real Schur form, there was a failure to compute $〈\mathit{\text{value}}〉$ eigenvalues in a total of $〈\mathit{\text{value}}〉$ iterations.

NE_SCHUR_REORDER

The computed Schur form could not be reordered by an internal call.
This routine returned with $\mathbf{fail}\mathbf{.}\mathbf{code}=〈\mathit{\text{value}}〉$.
Please contact NAG.

NE_SINGULAR

On entry, the matrix $A-\sigma \times I$ is nearly numerically singular and could not be inverted. Try perturbing the value of $\sigma$. Norm of matrix $=〈\mathit{\text{value}}〉$, Reciprocal condition number $=〈\mathit{\text{value}}〉$.

On entry, the matrix $A-\sigma \times I$ is numerically singular and could not be inverted. Try perturbing the value of $\sigma$.

NE_SPARSE_COL

On entry, for $i=〈\mathit{\text{value}}〉$, $\mathbf{icolzp}\left[i-1\right]=〈\mathit{\text{value}}〉$ and $\mathbf{icolzp}\left[i\right]=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{icolzp}\left[i-1\right]<\mathbf{icolzp}\left[i\right]$.

On entry, $\mathbf{icolzp}\left[0\right]=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{icolzp}\left[0\right]=1$.

On entry, $\mathbf{icolzp}\left[\mathbf{n}\right]=〈\mathit{\text{value}}〉$ and $\mathbf{nnz}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{icolzp}\left[\mathbf{n}\right]=\mathbf{nnz}+1$.

NE_SPARSE_ROW

On entry, in specification of column $〈\mathit{\text{value}}〉$, and for $j=〈\mathit{\text{value}}〉$, $\mathbf{irowix}\left[j-1\right]=〈\mathit{\text{value}}〉$ and $\mathbf{irowix}\left[j\right]=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{irowix}\left[j-1\right]<\mathbf{irowix}\left[j\right]$.

NE_TOO_MANY_ITER

The maximum number of iterations has been reached.
The maximum number of iterations $=〈\mathit{\text{value}}〉$.
The number of converged eigenvalues $=〈\mathit{\text{value}}〉$.
See the function document for further details.

NE_USER_STOP

User requested termination in monit, $\mathbf{istat}=〈\mathit{\text{value}}〉$.

User requested termination in option, $\mathbf{istat}=〈\mathit{\text{value}}〉$.

NE_ZERO_RESID

An internal call to nag_real_sparse_eigensystem_iter (f12abc) returned with $\mathbf{fail}\mathbf{.}\mathbf{code}=$ NE_ZERO_INIT_RESID.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (f02ekce.c)

10.2  Program Data

Program Data (f02ekce.d)

10.3  Program Results

Program Results (f02ekce.r)

11  Optional Arguments

• Advisory
• Defaults
• Iteration Limit
• Largest Imaginary
• Largest Magnitude
• Largest Real
• List
• Monitoring
• Nolist
• Print Level
• Regular
• Shifted Inverse Real
• Smallest Imaginary
• Smallest Magnitude
• Smallest Real
• Tolerance

11.1  Description of the Optional Arguments

• 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 nag_machine_precision (X02AJC)).