NAG CL Interface
f02fkc (real_​symm_​sparse_​arnoldi)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{n}$ – Integer Input

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

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

2: $\mathbf{nnz}$ – Integer Input

On entry: the dimension of the array a. The number of nonzero elements in the lower triangular part of the matrix $A$.

Constraint: $1\le \mathbf{nnz}\le \mathbf{n}\times (\mathbf{n}+1)/2$.

3: $\mathbf{a}\left[\mathbf{nnz}\right]$ – const double Input

On entry: the array of nonzero elements of the lower triangular part of the $n\times n$ symmetric matrix $A$.

4: $\mathbf{irow}\left[\mathbf{nnz}\right]$ – const Integer Input

5: $\mathbf{icol}\left[\mathbf{nnz}\right]$ – const Integer Input

On entry: the row and column indices of the elements supplied in array a.

If $\mathbf{irow}\left[k-1\right]=i$ and $\mathbf{icol}\left[k-1\right]=j$ then $A_{ij}$ is stored in $\mathbf{a}\left[k-1\right]$. irow does not need to be ordered: an internal sort will force the correct ordering.

Constraint:

irow and icol must satisfy these constraints:

$1\le \mathbf{irow}\left[\mathit{i}\right]\le \mathbf{n}$ and $1\le \mathbf{icol}\left[\mathit{i}\right]\le \mathbf{irow}\left[\mathit{i}\right]$, for $\mathit{i}=0,1,\dots ,\mathbf{nnz}-1$.

6: $\mathbf{nev}$ – Integer Input

On entry: the number of eigenvalues to be computed.

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

7: $\mathbf{ncv}$ – Integer Input

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 computation time is problem dependent and must be determined empirically.

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

8: $\mathbf{sigma}$ – double Input

On entry: if the $\mathbf{Shifted\; Inverse}$ 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 user External Function

monit is used to monitor the progress of f02fkc. 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 f02fkc.

The specification of monit is:

copy

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

1: $\mathbf{ncv}$ – Integer Input

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

2: $\mathbf{niter}$ – Integer Input

On entry: the number of the current Arnoldi iteration.

3: $\mathbf{nconv}$ – Integer Input

On entry: the number of converged eigenvalues so far.

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

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

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

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 f02fkc 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 f02fkc you may allocate memory and initialize these pointers with various quantities for use by monit when called from f02fkc (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

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

You can supply non-default options to the Arnoldi eigensolver by repeated calls to f12fdc from within option. (Please note that it is only necessary to call f12fdc; no call to f12fac is required from within option.) For example, you can set the mode to $\mathbf{Shifted\; Inverse}$, 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.

The specification of option is:

copy

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

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

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

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

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

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

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

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

On entry: set to zero.

On exit: if set to a nonzero value f02fkc 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 f02fkc you may allocate memory and initialize these pointers with various quantities for use by option when called from f02fkc (see Section 3.1.1 in the Introduction to the NAG Library CL Interface).

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

On exit: the number of converged approximations to the selected eigenvalues. On successful exit, this will normally be nev.

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

On exit: the first nconv elements contain the converged approximations to the selected eigenvalues.

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

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 eigenvalue, ${\lambda }_j$, the corresponding eigenvector is stored in $\mathbf{v}\left[\left(j-1\right)\times \mathbf{pdv}+\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,n$.

14: $\mathbf{pdv}$ – Integer Input

On entry: the stride separating, in the array v, the elements of a real eigenvector from the corresponding elements of the next eigenvector.

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

15: $\mathbf{resid}\left[\mathbf{nev}\right]$ – double Output

On exit: the residual ${\Vert A{w}_{\mathit{i}}-{\lambda }_{\mathit{i}}{w}_{\mathit{i}}\Vert }_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.1.1 in the Introduction to the NAG Library CL Interface).

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

The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error 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_BOTH_ENDS_1

The option $\mathbf{Both\; Ends}$ has been set but only $1$ eigenvalue is requested.

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

On entry, $\mathbf{nev}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nev}<(\mathbf{n}-1)$.

On entry, $\mathbf{nnz}=⟨\mathit{\text{value}}⟩$ and $\mathbf{n}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nnz}\le \mathbf{n}\times (\mathbf{n}+1)/2$.

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

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.

A serious error, code $(⟨\mathit{\text{value}}⟩,⟨\mathit{\text{value}}⟩)$, has occurred in an internal call. Check all function calls and array sizes. If the call is correct then please contact NAG for assistance.

NE_INVALID_OPTION

The maximum number of iterations, through the optional parameter $\mathbf{Iteration\; Limit}$, has been set to a non-positive 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.

NE_SINGULAR

On entry, the matrix $(A-\sigma 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{icol}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, $\mathbf{irow}\left[i-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le \mathbf{icol}\left[i-1\right]\le \mathbf{irow}\left[i-1\right]$.

NE_SPARSE_ROW

On entry, for $i=⟨\mathit{\text{value}}⟩$, $\mathbf{irow}\left[i-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le \mathbf{irow}\left[i-1\right]\le \mathbf{n}$.

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}}⟩$.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

9.1 Additional Licensor

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

11 Optional Parameters

• Advisory
• Both Ends
• Defaults
• Iteration Limit
• Largest Algebraic
• Largest Magnitude
• List
• Monitoring
• Nolist
• Print Level
• Regular
• Regular Inverse
• Shifted Inverse
• Smallest Algebraic
• Smallest Magnitude
• Tolerance

11.1 Description of the Optional Parameters

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