NAG FL Interface
f02fkf (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 as declared in the (sub)program from which f02fkf is called. The number of nonzero elements in the lower triangular part of the matrix $A$.

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

3: $\mathbf{a}\left(\mathbf{nnz}\right)$ – Real (Kind=nag_wp) array Input

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

4: $\mathbf{irow}\left(\mathbf{nnz}\right)$ – Integer array Input

5: $\mathbf{icol}\left(\mathbf{nnz}\right)$ – Integer array Input

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

If $\mathbf{irow}\left(k\right)=i$ and $\mathbf{icol}\left(k\right)=j$ then $A_{ij}$ is stored in $\mathbf{a}\left(k\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}=1,2,\dots ,\mathbf{nnz}$.

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 as declared in the (sub)program from which f02fkf is called. 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}$ – Real (Kind=nag_wp) Input

On entry: if the 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 subroutine option.

9: $\mathbf{monit}$ – Subroutine, supplied by the NAG Library or the user. External Procedure

monit is used to monitor the progress of f02fkf. monit may be the dummy subroutine f02fkz if no monitoring is actually required. (f02fkz is included in the NAG Library.) monit is called after the solution of each eigenvalue sub-problem and also just prior to return from f02fkf.

The specification of monit is:

Fortran Interface

Subroutine monit ( ncv, niter, nconv, w, rzest, istat, iuser, ruser) Integer, Intent (In) :: ncv, niter, nconv Integer, Intent (Inout) :: istat, iuser(*) Real (Kind=nag_wp), Intent (In) :: w(ncv), rzest(ncv) Real (Kind=nag_wp), Intent (Inout) :: ruser(*)

C Header Interface

void  monit_ (const Integer *ncv, const Integer *niter, const Integer *nconv, const double w[], const double rzest[], Integer *istat, Integer iuser[], double ruser[])

C++ Header Interface

#include <nag.h> extern "C" { void  monit_ (const Integer &ncv, const Integer &niter, const Integer &nconv, const double w[], const double rzest[], Integer &istat, Integer iuser[], double ruser[]) }

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)$ – Real (Kind=nag_wp) array Input

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

5: $\mathbf{rzest}\left(\mathbf{ncv}\right)$ – Real (Kind=nag_wp) array 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 f02fkf returns immediately with $\mathbf{ifail}=\mathbf{9}$.

7: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

8: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

monit is called with the arguments iuser and ruser as supplied to f02fkf. You should use the arrays iuser and ruser to supply information to monit.

monit must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which f02fkf is called. Arguments denoted as Input must not be changed by this procedure.

10: $\mathbf{option}$ – Subroutine, supplied by the NAG Library or the user. External Procedure

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

If only the default options (including that the eigenvalues of largest magnitude are sought) are to be used then option may be the dummy subroutine f02eky (f02eky is included in the NAG Library). See Section 10 for an example of using option to set some non-default options.

The specification of option is:

Fortran Interface

Subroutine option ( icomm, comm, istat, iuser, ruser) Integer, Intent (Inout) :: icomm(*), istat, iuser(*) Real (Kind=nag_wp), Intent (Inout) :: comm(*), ruser(*)

C Header Interface

void  option_ (Integer icomm[], double comm[], Integer *istat, Integer iuser[], double ruser[])

C++ Header Interface

#include <nag.h> extern "C" { void  option_ (Integer icomm[], double comm[], Integer &istat, Integer iuser[], double ruser[]) }

1: $\mathbf{icomm}\left(*\right)$ – Integer array Communication Array

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

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

2: $\mathbf{comm}\left(*\right)$ – Real (Kind=nag_wp) array Communication Array

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

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

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

On entry: set to zero.

On exit: if set to a nonzero value f02fkf returns immediately with $\mathbf{ifail}=\mathbf{10}$.

4: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

5: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

option is called with the arguments iuser and ruser as supplied to f02fkf. You should use the arrays iuser and ruser to supply information to option.

option must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which f02fkf is called.

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)$ – Real (Kind=nag_wp) array Output

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

13: $\mathbf{v}\left(\mathbf{ldv},*\right)$ – Real (Kind=nag_wp) array Output

Note: the second dimension of the array v must be at least $\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(\mathit{i},j\right)$, for $\mathit{i}=1,2,\dots ,n$.

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

On entry: the first dimension of the array v as declared in the (sub)program from which f02fkf is called.

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

15: $\mathbf{resid}\left(\mathbf{nev}\right)$ – Real (Kind=nag_wp) array Output

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}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{nconv}$.

16: $\mathbf{iuser}\left(*\right)$ – Integer array User Workspace

iuser is not used by f02fkf, but is passed directly to monit and option and may be used to pass information to these routines.

17: $\mathbf{ruser}\left(*\right)$ – Real (Kind=nag_wp) array User Workspace

ruser is not used by f02fkf, but is passed directly to monit and option and may be used to pass information to these routines.

18: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.

On exit: $\mathbf{ifail}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

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

$\mathbf{ifail}=2$

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

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

$\mathbf{ifail}=4$

On entry, for $i=〈\mathit{\text{value}}〉$, $\mathbf{irow}\left(i\right)=〈\mathit{\text{value}}〉$.
Constraint: $1\le \mathbf{irow}\left(i\right)\le \mathbf{n}$.

$\mathbf{ifail}=5$

On entry, for $i=〈\mathit{\text{value}}〉$, $\mathbf{icol}\left(i\right)=〈\mathit{\text{value}}〉$, $\mathbf{irow}\left(i\right)=〈\mathit{\text{value}}〉$.
Constraint: $1\le \mathbf{icol}\left(i\right)\le \mathbf{irow}\left(i\right)$.

$\mathbf{ifail}=6$

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

On entry, $\mathbf{nev}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nev}<\left(\mathbf{n}-1\right)$.

$\mathbf{ifail}=7$

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

$\mathbf{ifail}=8$

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

$\mathbf{ifail}=9$

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

$\mathbf{ifail}=10$

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

$\mathbf{ifail}=14$

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

$\mathbf{ifail}=20$

The maximum number of iterations, through the optional parameter Iteration Limit, has been set to a non-positive value.

$\mathbf{ifail}=21$

The option Both Ends has been set but only $1$ eigenvalue is requested.

$\mathbf{ifail}=22$

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 routine document for further details.

$\mathbf{ifail}=30$

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

$\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

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