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 byreal_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 fromreal_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 problemwhere 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 thenreal_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