naginterfaces.library.eigen.real_​symm_​sparse_​eigsys

naginterfaces.library.eigen.real_symm_sparse_eigsys(m, noits, tol, dot, image, novecs, x, monit=None, data=None)[source]

real_symm_sparse_eigsys finds eigenvalues and eigenvectors of a real sparse symmetric or generalized symmetric eigenvalue problem.

For full information please refer to the NAG Library document for f02fj

https://www.nag.com/numeric/nl/nagdoc_28.6/flhtml/f02/f02fjf.html

Parameters
mint

, the number of eigenvalues required.

noitsint

The maximum number of major iterations (eigenvalue sub-problems) to be performed. If , the value is used in place of .

tolfloat

A relative tolerance to be used in accepting eigenvalues and eigenvectors. If the eigenvalues are required to about significant figures, should be set to about . is accepted as an eigenvalue as soon as two successive approximations to differ by less than , where is the latest approximation to . Once an eigenvalue has been accepted, an eigenvector is accepted as soon as , where is the normalized residual of the current approximation to the eigenvector (see Further Comments for further information). The values of the and can be printed from . If is supplied outside the range (), where is the machine precision, the value is used in place of .

dotcallable retval = dot(z, w, data=None)

must return the value for given vectors and .

For the standard eigenvalue problem, where , must return the dot product .

Parameters
zfloat, ndarray, shape

The vector for which is required.

wfloat, ndarray, shape

The vector for which is required.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
retvalfloat

The value .

imagecallable w = image(z, data=None)

must return the vector for a given vector .

Parameters
zfloat, ndarray, shape

The vector for which is required.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
wfloat, array-like, shape

The vector .

novecsint

The number of approximate vectors that are being supplied in . If is outside the range , the value is used in place of .

xfloat, array-like, shape

If , the first columns of must contain approximations to the eigenvectors corresponding to the eigenvalues of largest absolute value of . Supplying approximate eigenvectors can be useful when reasonable approximations are known, or when real_symm_sparse_eigsys is being restarted with a larger value of . Otherwise it is not necessary to supply approximate vectors, as simultaneous iteration vectors will be generated randomly by real_symm_sparse_eigsys.

monitNone or callable monit(istate, nextit, nevals, nevecs, f, d, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

is used to monitor the progress of real_symm_sparse_eigsys. may be None if no monitoring is actually required. is called after the solution of each eigenvalue sub-problem and also just prior to return from real_symm_sparse_eigsys.

The arguments and allow selective printing by .

Parameters
istateint

Specifies the state of real_symm_sparse_eigsys.

No eigenvalue or eigenvector has just been accepted.

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

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

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

Return from real_symm_sparse_eigsys is about to occur.

nextitint

The number of the next iteration.

nevalsint

The number of eigenvalues accepted so far.

nevecsint

The number of eigenvectors accepted so far.

ffloat, ndarray, shape

A vector of error quantities measuring the state of convergence of the simultaneous iteration vectors. See and Further Comments for further details. Each element of is initially set to the value and an element remains at until the corresponding vector is tested.

dfloat, ndarray, shape

contains the latest approximation to the absolute value of the th eigenvalue of .

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

dataarbitrary, optional

User-communication data for callback functions.

Returns
mint

, the number of eigenvalues actually found. It is equal to if no exception or warning is raised on exit, and is less than if = 2, 3 or 4. See Exceptions and Further Comments for further information.

noitsint

The number of iterations actually performed.

xfloat, ndarray, shape

If the function exits successfully or = 2, 3 or 4, the first columns contain the eigenvectors corresponding to the eigenvalues returned in the first elements of ; and the next columns contain approximations to the eigenvectors corresponding to the approximate eigenvalues returned in the next elements of . Here is the value returned in , the number of eigenvalues actually found. The th column is used as workspace.

dfloat, ndarray, shape

If the function exits successfully or = 2, 3 or 4, the first elements contain the first eigenvalues in decreasing order of magnitude; and the next elements contain approximations to the next eigenvalues. Here is the value returned in , the number of eigenvalues actually found. contains the value where is the latest interval over which Chebyshev acceleration is performed.

Raises
NagValueError
(errno )

On entry, and .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

Not all requested eigenvalues and vectors have been obtained.

(errno )

Convergence of eigenvalue sub-problem occurred.

Warns
NagAlgorithmicWarning
(errno )

Not all requested eigenvalues and vectors have been obtained.

(errno )

Not all requested eigenvalues and vectors have been obtained.

(errno )

Not all requested eigenvalues and vectors have been obtained.

NagCallbackTerminateWarning
(errno )

User set negative in or .

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

real_symm_sparse_eigsys finds the eigenvalues of largest absolute value and the corresponding eigenvectors for the real eigenvalue problem

where is an matrix such that

for a given positive definite matrix . is said to be -symmetric. Different specifications of allow for the solution of a variety of eigenvalue problems. For example, when

the function finds the eigenvalues of largest absolute magnitude for the standard symmetric eigenvalue problem

The function is intended for the case where is sparse.

As a second example, when

where

the function finds the eigenvalues of largest absolute magnitude for the generalized symmetric eigenvalue problem

The function is intended for the case where and are sparse.

The function does not require explicitly, but is specified via which, given an -element vector , computes the image given by

For instance, in the above example, where , will need to solve the positive definite system of equations for .

To find the eigenvalues of smallest absolute magnitude of (3) we can choose and hence find the reciprocals of the required eigenvalues, so that will need to solve for , and correspondingly for (4) we can choose and solve for .

A table of examples of choice of is given in Table [label omitted]. It should be remembered that the function also returns the corresponding eigenvectors and that is positive definite. Throughout is assumed to be symmetric and, where necessary, nonsingularity is also assumed.

[table omitted]

The matrix also need not be supplied explicitly, but is specified via which, given -element vectors and , computes the generalized dot product .

real_symm_sparse_eigsys is based upon routine SIMITZ (see Nikolai (1979)), which is itself a derivative of the Algol procedure ritzit (see Rutishauser (1970)), and uses the method of simultaneous (subspace) iteration. (See Parlett (1998) for a description, analysis and advice on the use of the method.)

The function performs simultaneous iteration on vectors. Initial estimates to eigenvectors, corresponding to the eigenvalues of of largest absolute value, may be supplied to real_symm_sparse_eigsys. When possible should be chosen so that the th eigenvalue is not too close to the required eigenvalues, but if is initially chosen too small then real_symm_sparse_eigsys may be re-entered, supplying approximations to the eigenvectors found so far and with then increased.

At each major iteration real_symm_sparse_eigsys solves an () eigenvalue sub-problem in order to obtain an approximation to the eigenvalues for which convergence has not yet occurred. This approximation is refined by Chebyshev acceleration.

References

Nikolai, P J, 1979, Algorithm 538: Eigenvectors and eigenvalues of real generalized symmetric matrices by simultaneous iteration, ACM Trans. Math. Software (5), 118–125

Parlett, B N, 1998, The Symmetric Eigenvalue Problem, SIAM, Philadelphia

Rutishauser, H, 1969, Computational aspects of F L Bauer’s simultaneous iteration method, Numer. Math. (13), 4–13

Rutishauser, H, 1970, Simultaneous iteration method for symmetric matrices, Numer. Math. (16), 205–223