NAG Library Routine Document

f02ekf (real_gen_sparse_arnoldi)

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 as declared in the (sub)program from which f02ekf is called. 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)$ – Real (Kind=nag_wp) arrayInput/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)$ – Integer arrayInput

On entry: $\mathbf{icolzp}\left(i\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}+1\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+1\right)-\mathbf{icolzp}\left(i\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)$ – Integer arrayInput

On entry: $\mathbf{irowix}\left(i\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 as declared in the (sub)program from which f02ekf 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 CPU time is problem dependent and must be determined empirically.

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

8:     $\mathbf{sigma}$ – Real (Kind=nag_wp)Input

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

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

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

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) :: rzest(ncv) Real (Kind=nag_wp), Intent (Inout) :: ruser(*) Complex (Kind=nag_wp), Intent (In) :: w(ncv)

C Header Interface

#include <nagmk26.h> void  monit (const Integer *ncv, const Integer *niter, const Integer *nconv, const Complex w[], const double rzest[], Integer *istat, Integer iuser[], double ruser[])

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)$ – Complex (Kind=nag_wp) arrayInput

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

5:     $\mathbf{rzest}\left(\mathbf{ncv}\right)$ – Real (Kind=nag_wp) arrayInput

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

6:     $\mathbf{istat}$ – IntegerInput/Output

On entry: set to zero.

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

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

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

monit is called with the arguments iuser and ruser as supplied to f02ekf. 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 f02ekf is called. Arguments denoted as Input must not be changed by this procedure.

Note: monit should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by f02ekf. If your code inadvertently does return any NaNs or infinities, f02ekf is likely to produce unexpected results.

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 f12adf from within option. (Please note that it is only necessary to call f12adf; no call to f12aaf is required from within option.) For example, you can set the mode to Shifted Inverse Real, 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

#include <nagmk26.h> void  option (Integer icomm[], double comm[], Integer *istat, Integer iuser[], double ruser[])

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

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

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

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

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

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

3:     $\mathbf{istat}$ – IntegerInput/Output

On entry: set to zero.

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

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

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

option is called with the arguments iuser and ruser as supplied to f02ekf. 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 f02ekf is called.

11:   $\mathbf{nconv}$ – IntegerOutput

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)$ – Complex (Kind=nag_wp) arrayOutput

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 f02ekf to return one more eigenvalue than requested.

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

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 a real eigenvalue, ${\lambda }_j$, the corresponding eigenvector is real and is stored in $\mathbf{v}\left(\mathit{i},j\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(\mathit{i},j\right)$ and $\mathbf{v}\left(\mathit{i},j\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{ldv}$ – IntegerInput

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

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

15:   $\mathbf{resid}\left(\mathbf{nev}+1\right)$ – Real (Kind=nag_wp) arrayOutput

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 arrayUser Workspace

iuser is not used by f02ekf, 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) arrayUser Workspace

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

18:   $\mathbf{ifail}$ – IntegerInput/Output

On entry: ifail must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this argument, the recommended value is $0$. When the value $-\mathbf{1}\text{ 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 \mathbf{n}$.

$\mathbf{ifail}=3$

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

$\mathbf{ifail}=4$

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

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

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

$\mathbf{ifail}=5$

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

$\mathbf{ifail}=6$

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

$\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}+1$.

$\mathbf{ifail}=8$

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

$\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}=21$

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

$\mathbf{ifail}=22$

An unexpected internal error occurred when solving an eigenproblem.
This error should not occur. Please contact NAG.

$\mathbf{ifail}=23$

An unexpected internal error occurred when solving an eigenproblem.
This error should not occur. Please contact NAG.

$\mathbf{ifail}=24$

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}=25$

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

$\mathbf{ifail}=26$

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

$\mathbf{ifail}=27$

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

$\mathbf{ifail}=32$

An unexpected internal error occurred when postprocessing an eigenproblem.
This error should not occur. Please contact NAG.

$\mathbf{ifail}=33$

The number of eigenvalues found to sufficient accuracy is zero.

$\mathbf{ifail}=34$

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

$\mathbf{ifail}=35$

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.

$\mathbf{ifail}=36$

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

$\mathbf{ifail}=37$

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

$\mathbf{ifail}=-99$

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

See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-399$

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

See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (f02ekfe.f90)

10.2

Program Data

Program Data (f02ekfe.d)

10.3

Program Results

Program Results (f02ekfe.r)

11

Optional Parameters

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