NAG Toolbox: nag_eigen_real_symm_sparse_arnoldi (f02fk)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{n}$ – int64int32nag_int scalar

$n$, the order of the matrix $A$.

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

2:     $\mathrm{a}\left(\mathbf{nz}\right)$ – double array

The array of nonzero elements of the lower triangular part of the $n$ by $n$ symmetric matrix $A$.

3:     $\mathrm{irow}\left(\mathbf{nz}\right)$ – int64int32nag_int array

4:     $\mathrm{icol}\left(\mathbf{nz}\right)$ – int64int32nag_int array

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 call to nag_sparse_real_symm_sort (f11zb) forces 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{nz}$.

5:     $\mathrm{nev}$ – int64int32nag_int scalar

The number of eigenvalues to be computed.

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

6:     $\mathrm{ncv}$ – int64int32nag_int scalar

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

7:     $\mathrm{sigma}$ – double scalar

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

8:     $\mathrm{monit}$ – function handle or string containing name of m-file

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

[istat, user] = monit(ncv, niter, nconv, w, rzest, istat, user)

Input Parameters

1:     $\mathrm{ncv}$ – int64int32nag_int scalar

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

2:     $\mathrm{niter}$ – int64int32nag_int scalar

The number of the current Arnoldi iteration.

3:     $\mathrm{nconv}$ – int64int32nag_int scalar

The number of converged eigenvalues so far.

4:     $\mathrm{w}\left(\mathbf{ncv}\right)$ – double array

The first nconv elements of w contain the converged approximate eigenvalues.

5:     $\mathrm{rzest}\left(\mathbf{ncv}\right)$ – double array

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

6:     $\mathrm{istat}$ – int64int32nag_int scalar

Set to zero.

7:     $\mathrm{user}$ – Any MATLAB object

monit is called from nag_eigen_real_symm_sparse_arnoldi (f02fk) with the object supplied to nag_eigen_real_symm_sparse_arnoldi (f02fk).

Output Parameters

1:     $\mathrm{istat}$ – int64int32nag_int scalar

If set to a nonzero value nag_eigen_real_symm_sparse_arnoldi (f02fk) returns immediately with $\mathbf{ifail}=\mathbf{9}$.

2:     $\mathrm{user}$ – Any MATLAB object

9:     $\mathrm{option}$ – function handle or string containing name of m-file

You can supply non-default options to the Arnoldi eigensolver by repeated calls to nag_sparseig_real_symm_option (f12fd) from within option. (Please note that it is only necessary to call nag_sparseig_real_symm_option (f12fd); no call to nag_sparseig_real_symm_init (f12fa) 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 function nag_eigen_arnoldi_option (f02eky) (nag_eigen_arnoldi_option (f02eky) is included in the NAG Toolbox). See Example for an example of using option to set some non-default options.

[icomm, comm, istat, user] = option(icomm, comm, istat, user)

Input Parameters

1:     $\mathrm{icomm}\left(:\right)$ – int64int32nag_int array

Contains details of the default option set. This array must be passed as argument icomm in any call to nag_sparseig_real_symm_option (f12fd).

2:     $\mathrm{comm}\left(:\right)$ – double array

Contains details of the default option set. This array must be passed as argument comm in any call to nag_sparseig_real_symm_option (f12fd).

3:     $\mathrm{istat}$ – int64int32nag_int scalar

Set to zero.

4:     $\mathrm{user}$ – Any MATLAB object

option is called from nag_eigen_real_symm_sparse_arnoldi (f02fk) with the object supplied to nag_eigen_real_symm_sparse_arnoldi (f02fk).

Output Parameters

1:     $\mathrm{icomm}\left(:\right)$ – int64int32nag_int array

Contains data on the current options set which may be altered from the default set via calls to nag_sparseig_real_symm_option (f12fd).

2:     $\mathrm{comm}\left(:\right)$ – double array

Contains data on the current options set which may be altered from the default set via calls to nag_sparseig_real_symm_option (f12fd).

3:     $\mathrm{istat}$ – int64int32nag_int scalar

If set to a nonzero value nag_eigen_real_symm_sparse_arnoldi (f02fk) returns immediately with $\mathbf{ifail}=\mathbf{10}$.

4:     $\mathrm{user}$ – Any MATLAB object

Optional Input Parameters

1:     $\mathrm{nz}$ – int64int32nag_int scalar

Default: the dimension of the arrays irow, icol and the dimension of the array a. (An error is raised if these dimensions are not equal.)

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

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

2:     $\mathrm{user}$ – Any MATLAB object

user is not used by nag_eigen_real_symm_sparse_arnoldi (f02fk), but is passed to monit and option. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

Output Parameters

1:     $\mathrm{nconv}$ – int64int32nag_int scalar

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

2:     $\mathrm{w}\left(\mathbf{ncv}\right)$ – double array

The first nconv elements contain the converged approximations to the selected eigenvalues.

3:     $\mathrm{v}\left(\mathit{ldv},:\right)$ – double array

The first dimension of the array v will be $\mathbf{n}$.

The second dimension of the array v will be $\mathbf{ncv}$.

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

4:     $\mathrm{resid}\left(\mathbf{nev}\right)$ – double array

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

5:     $\mathrm{user}$ – Any MATLAB object

6:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

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

   $\mathbf{ifail}=2$

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

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

   $\mathbf{ifail}=4$

Constraint: $1\le \mathbf{irow}\left(i\right)\le \mathbf{n}$.

   $\mathbf{ifail}=5$

Constraint: $1\le \mathbf{icol}\left(i\right)\le \mathbf{irow}\left(i\right)$.

   $\mathbf{ifail}=6$

Constraint: $\mathbf{nev}<\left(\mathbf{n}-1\right)$.

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

   $\mathbf{ifail}=7$

Constraint: $\mathbf{ncv}>\mathbf{nev}$.

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

   $\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{ifail}=10$

User requested termination in option.

   $\mathbf{ifail}=14$

Constraint: $\mathit{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.

   $\mathbf{ifail}=30$

A serious error, code $\_$, has occurred in an internal call to $\_$. Check all function 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.

   $\mathbf{ifail}=-399$

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

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: f02fk_example

function f02fk_example


fprintf('f02fk example results\n\n');


% This example demonstrates the use of f02fk to evaluate a number of
% eigenvalues of a sparse symmetric matrix closest to a given value.

% Use existing sparse matrix to generate symmetric one.
load('west0479.mat')
W = west0479;
S = W * W';

%' Extract details of sparse matrix S.
[irow,icol,a] = find(S);
n   = int64(size(S,1));
nnz = int64(size(irow,1));

% zero out strictly upper triangle
for i = 1 : nnz 
  if (icol(i)>irow(i));
     a(i) = 0.0;
  end
end

% Use f11za to remove zero entries.
irow = int64(irow);
icol = int64(icol);
dup  = 'R';
zero = 'R';
[nnz, a, icol, irow, icolzp, ifail] = ...
  f11za(...
        n, nnz, a, icol, irow, dup, zero);

% Evaluate nev eigenvalues (w) closest to sigma.
nev   = int64(20);
ncv   = int64(60);
sigma = 50000;

[nconv, w, v, resid, user, ifail] = ...
    f02fk(...
          n, a, irow, icol, nev, ncv, sigma, 'f02fkz', @option);

fprintf('\n The %d Ritz values closest to %13.5e are:\n', nconv, sigma);

disp(w(1:nconv));

fig1 = figure;
plot(w(1:nconv),'k+');
title('Eigenvalues of WW^T (W=West0479) closest to 50000');
xlabel('index');
ylabel('eigenvalue');


function [istat, user] = monit(ncv, niter, nconv, w, rzest, istat, user);
  istat = int64(0);

function [icomm, comm, istat, user] = option(icomm, comm, istat, user);
    [icomm, comm, ifail] = f12fd('Shifted Inverse', icomm, comm);
    istat = ifail;

f02fk example results


 The 20 Ritz values closest to   5.00000e+04 are:
   1.0e+04 *

    2.5904
    2.8321
    2.9565
    2.9806
    2.9806
    2.9865
    3.1759
    3.3510
    3.4773
    3.6629
    3.6940
    4.0007
    4.0008
    4.9172
    5.3954
    5.6332
    6.0003
    6.2267
    6.8829
    7.2555

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

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