NAG Library Routine Document

f02fjf (real_symm_sparse_eigsys)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:     $\mathbf{n}$ – IntegerInput

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

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

2:     $\mathbf{m}$ – IntegerInput/Output

On entry: $m$, the number of eigenvalues required.

Constraint: $\mathbf{m}\ge 1$.

On exit: $m^{\prime }$, the number of eigenvalues actually found. It is equal to $m$ if $\mathbf{ifail}=\mathbf{0}$ on exit, and is less than $m$ if $\mathbf{ifail}=\mathbf{2}$, $\mathbf{3}$ or $\mathbf{4}$. See Sections 6 and 9 for further information.

3:     $\mathbf{k}$ – IntegerInput

On entry: the number of simultaneous iteration vectors to be used. Too small a value of k may inhibit convergence, while a larger value of k incurs additional storage and additional work per iteration.

Suggested value: $\mathbf{k}=\mathbf{m}+4$ will often be a reasonable choice in the absence of better information.

Constraint: $\mathbf{m}<\mathbf{k}\le \mathbf{n}$.

4:     $\mathbf{noits}$ – IntegerInput/Output

On entry: the maximum number of major iterations (eigenvalue sub-problems) to be performed. If $\mathbf{noits}\le 0$, the value $100$ is used in place of noits.

On exit: the number of iterations actually performed.

5:     $\mathbf{tol}$ – Real (Kind=nag_wp)Input

On entry: a relative tolerance to be used in accepting eigenvalues and eigenvectors. If the eigenvalues are required to about $t$ significant figures, tol should be set to about ${10}^{-t}$. $d_i$ is accepted as an eigenvalue as soon as two successive approximations to $d_i$ differ by less than $\left(\left|{\tilde{d}}_i\right|\times \mathbf{tol}\right)/10$, where ${\tilde{d}}_i$ is the latest approximation to $d_i$. Once an eigenvalue has been accepted, an eigenvector is accepted as soon as $\left(d_i{f}_i\right)/\left(d_i-d_k\right)<\mathbf{tol}$, where $f_i$ is the normalized residual of the current approximation to the eigenvector (see Section 9 for further information). The values of the $f_i$ and $d_i$ can be printed from monit. If tol is supplied outside the range ($\epsilon ,1.0$), where $\epsilon$ is the machine precision, the value $\epsilon$ is used in place of tol.

6:     $\mathbf{dot}$ – real (Kind=nag_wp) Function, supplied by the user.External Procedure

dot must return the value $w^{\mathrm{T}}Bz$ for given vectors $w$ and $z$. For the standard eigenvalue problem, where $B=I$, dot must return the dot product $w^{\mathrm{T}}z$.

The specification of dot is:

Fortran Interface

Function dot ( iflag, n, z, w, ruser, lruser, iuser, liuser) Real (Kind=nag_wp) :: dot Integer, Intent (In) :: n, lruser, liuser Integer, Intent (Inout) :: iflag, iuser(liuser) Real (Kind=nag_wp), Intent (In) :: z(n), w(n) Real (Kind=nag_wp), Intent (Inout) :: ruser(lruser)

C Header Interface

#include <nagmk26.h> double  dot (Integer *iflag, const Integer *n, const double z[], const double w[], double ruser[], const Integer *lruser, Integer iuser[], const Integer *liuser)

1:     $\mathbf{iflag}$ – IntegerInput/Output

On entry: is always non-negative.

On exit: may be used as a flag to indicate a failure in the computation of $w^{\mathrm{T}}Bz$. If iflag is negative on exit from dot, f02fjf will exit immediately with ifail set to iflag. Note that in this case dot must still be assigned a value.

2:     $\mathbf{n}$ – IntegerInput

On entry: the number of elements in the vectors $z$ and $w$ and the order of the matrix $B$.

3:     $\mathbf{z}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the vector $z$ for which $w^{\mathrm{T}}Bz$ is required.

4:     $\mathbf{w}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the vector $w$ for which $w^{\mathrm{T}}Bz$ is required.

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

dot is called with the argument ruser as supplied to f02fjf. You should use the array ruser to supply information to dot.

6:     $\mathbf{lruser}$ – IntegerInput

On entry: the dimension of the array ruser as declared in the (sub)program from which f02fjf is called.

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

dot is called with the argument iuser as supplied to f02fjf. You should use the array iuser to supply information to dot.

8:     $\mathbf{liuser}$ – IntegerInput

On entry: the dimension of the array iuser as declared in the (sub)program from which f02fjf is called.

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

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

7:     $\mathbf{image}$ – Subroutine, supplied by the user.External Procedure

image must return the vector $w=Cz$ for a given vector $z$.

The specification of image is:

Fortran Interface

Subroutine image ( iflag, n, z, w, ruser, lruser, iuser, liuser) Integer, Intent (In) :: n, lruser, liuser Integer, Intent (Inout) :: iflag, iuser(liuser) Real (Kind=nag_wp), Intent (In) :: z(n) Real (Kind=nag_wp), Intent (Inout) :: ruser(lruser) Real (Kind=nag_wp), Intent (Out) :: w(n)

C Header Interface

#include <nagmk26.h> void  image (Integer *iflag, const Integer *n, const double z[], double w[], double ruser[], const Integer *lruser, Integer iuser[], const Integer *liuser)

1:     $\mathbf{iflag}$ – IntegerInput/Output

On entry: is always non-negative.

On exit: may be used as a flag to indicate a failure in the computation of $w$. If iflag is negative on exit from image, f02fjf will exit immediately with ifail set to iflag.

2:     $\mathbf{n}$ – IntegerInput

On entry: $n$, the number of elements in the vectors $w$ and $z$, and the order of the matrix $C$.

3:     $\mathbf{z}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: the vector $z$ for which $Cz$ is required.

4:     $\mathbf{w}\left(\mathbf{n}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: the vector $w=Cz$.

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

image is called with the argument ruser as supplied to f02fjf. You should use the array ruser to supply information to image.

6:     $\mathbf{lruser}$ – IntegerInput

On entry: the dimension of the array ruser as declared in the (sub)program from which f02fjf is called.

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

image is called with the argument iuser as supplied to f02fjf. You should use the array iuser to supply information to image.

8:     $\mathbf{liuser}$ – IntegerInput

On entry: the dimension of the array iuser as declared in the (sub)program from which f02fjf is called.

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

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

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

monit is used to monitor the progress of f02fjf. monit may be the dummy subroutine f02fjz if no monitoring is actually required. (f02fjz is included in the NAG Library.) monit is called after the solution of each eigenvalue sub-problem and also just prior to return from f02fjf. The arguments istate and nextit allow selective printing by monit.

The specification of monit is:

Fortran Interface

Subroutine monit ( istate, nextit, nevals, nevecs, k, f, d) Integer, Intent (In) :: istate, nextit, nevals, nevecs, k Real (Kind=nag_wp), Intent (In) :: f(k), d(k)

C Header Interface

#include <nagmk26.h> void  monit (const Integer *istate, const Integer *nextit, const Integer *nevals, const Integer *nevecs, const Integer *k, const double f[], const double d[])

1:     $\mathbf{istate}$ – IntegerInput

On entry: specifies the state of f02fjf.

$\mathbf{istate}=0$

No eigenvalue or eigenvector has just been accepted.

$\mathbf{istate}=1$

One or more eigenvalues have been accepted since the last call to monit.

$\mathbf{istate}=2$

One or more eigenvectors have been accepted since the last call to monit.

$\mathbf{istate}=3$

One or more eigenvalues and eigenvectors have been accepted since the last call to monit.

$\mathbf{istate}=4$

Return from f02fjf is about to occur.

2:     $\mathbf{nextit}$ – IntegerInput

On entry: the number of the next iteration.

3:     $\mathbf{nevals}$ – IntegerInput

On entry: the number of eigenvalues accepted so far.

4:     $\mathbf{nevecs}$ – IntegerInput

On entry: the number of eigenvectors accepted so far.

5:     $\mathbf{k}$ – IntegerInput

On entry: $k$, the number of simultaneous iteration vectors.

6:     $\mathbf{f}\left(\mathbf{k}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: a vector of error quantities measuring the state of convergence of the simultaneous iteration vectors. See tol and Section 9 for further details. Each element of f is initially set to the value $4.0$ and an element remains at $4.0$ until the corresponding vector is tested.

7:     $\mathbf{d}\left(\mathbf{k}\right)$ – Real (Kind=nag_wp) arrayInput

On entry: $\mathbf{d}\left(i\right)$ contains the latest approximation to the absolute value of the $i$th eigenvalue of $C$.

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

9:     $\mathbf{novecs}$ – IntegerInput

On entry: the number of approximate vectors that are being supplied in x. If novecs is outside the range $\left(0,\mathbf{k}\right)$, the value $0$ is used in place of novecs.

10:   $\mathbf{x}\left(\mathbf{ldx},\mathbf{k}\right)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: if $0<\mathbf{novecs}\le \mathbf{k}$, the first novecs columns of x must contain approximations to the eigenvectors corresponding to the novecs eigenvalues of largest absolute value of $C$. Supplying approximate eigenvectors can be useful when reasonable approximations are known, or when f02fjf is being restarted with a larger value of k. Otherwise it is not necessary to supply approximate vectors, as simultaneous iteration vectors will be generated randomly by f02fjf.

On exit: if $\mathbf{ifail}=\mathbf{0}$, $\mathbf{2}$, $\mathbf{3}$ or $\mathbf{4}$, the first $m^{\prime }$ columns contain the eigenvectors corresponding to the eigenvalues returned in the first $m^{\prime }$ elements of d; and the next $k-m^{\prime }-1$ columns contain approximations to the eigenvectors corresponding to the approximate eigenvalues returned in the next $k-m^{\prime }-1$ elements of d. Here $m^{\prime }$ is the value returned in m, the number of eigenvalues actually found. The $k$th column is used as workspace.

11:   $\mathbf{ldx}$ – IntegerInput

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

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

12:   $\mathbf{d}\left(\mathbf{k}\right)$ – Real (Kind=nag_wp) arrayOutput

On exit: if $\mathbf{ifail}=\mathbf{0}$, $\mathbf{2}$, $\mathbf{3}$ or $\mathbf{4}$, the first $m^{\prime }$ elements contain the first $m^{\prime }$ eigenvalues in decreasing order of magnitude; and the next $k-m^{\prime }-1$ elements contain approximations to the next $k-m^{\prime }-1$ eigenvalues. Here $m^{\prime }$ is the value returned in m, the number of eigenvalues actually found. $\mathbf{d}\left(k\right)$ contains the value $e$ where $\left(-e,e\right)$ is the latest interval over which Chebyshev acceleration is performed.

13:   $\mathbf{work}\left(\mathbf{lwork}\right)$ – Real (Kind=nag_wp) arrayWorkspace

14:   $\mathbf{lwork}$ – IntegerInput

On entry: the dimension of the array work as declared in the (sub)program from which f02fjf is called.

Constraint: $\mathbf{lwork}\ge 3\times \mathbf{k}+\max \left(\mathbf{k}\times \mathbf{k},2\times \mathbf{n}\right)$.

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

ruser is not used by f02fjf, but is passed directly to dot and image and may be used to pass information to these routines.

16:   $\mathbf{lruser}$ – IntegerInput

On entry: the dimension of the array ruser as declared in the (sub)program from which f02fjf is called.

Constraint: $\mathbf{lruser}\ge 1$.

17:   $\mathbf{iuser}\left(\mathbf{liuser}\right)$ – Integer arrayUser Workspace

iuser is not used by f02fjf, but is passed directly to dot and image and may be used to pass information to these routines.

18:   $\mathbf{liuser}$ – IntegerInput

On entry: the dimension of the array iuser as declared in the (sub)program from which f02fjf is called.

Constraint: $\mathbf{liuser}\ge 1$.

19:   $\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, because for this routine the values of the output arguments may be useful even if $\mathbf{ifail}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }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{k}=〈\mathit{\text{value}}〉$ and $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{k}\le \mathbf{n}$.

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

On entry, $\mathbf{liuser}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{liuser}\ge 1$.

On entry, $\mathbf{lruser}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{lruser}\ge 1$.

On entry, lwork is too small. Minimum size required: $〈\mathit{\text{value}}〉$.

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}\ge 1$.

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$ and $\mathbf{k}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}<\mathbf{k}$.

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

$\mathbf{ifail}=2$

Not all requested eigenvalues and vectors have been obtained.

Approximations to the $r$th eigenvalue are oscillating rapidly indicating that severe cancellation is occurring in the $r$th eigenvector and so m is returned as $\left(r-1\right)$. A restart with a larger value of k may permit convergence.

$\mathbf{ifail}=3$

Not all requested eigenvalues and vectors have been obtained.

The rate of convergence of the remaining eigenvectors suggests that more than noits iterations would be required and so the input value of m has been reduced. A restart with a larger value of k may permit convergence.

$\mathbf{ifail}=4$

Not all requested eigenvalues and vectors have been obtained.

noits iterations have been performed. A restart, possibly with a larger value of k, may permit convergence.

$\mathbf{ifail}=5$

Convergence of eigenvalue sub-problem occurred.

Not all requested eigenvalues and vectors have been obtained.

$\mathbf{ifail}<0$

User set iflag negative in dot or image.

$\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 (f02fjfe.f90)

10.2

Program Data

Program Data (f02fjfe.d)

10.3

Program Results

Program Results (f02fjfe.r)