#include "slepceps.h" PetscErrorCode EPSSetThreshold(EPS eps,PetscReal thres,PetscBool rel)Logically Collective
| eps | - the eigenvalue solver context | |
| thres | - the threshold value | |
| rel | - whether the threshold is relative or not |
| -eps_threshold_absolute <thres> | - Sets an absolute threshold | |
| -eps_threshold_relative <thres> | - Sets a relative threshold |
If the solver is configured to compute smallest magnitude eigenvalues, then the threshold must be interpreted in the opposite direction, i.e., the computation will stop when one of the computed values is above the threshold (in magnitude).
The threshold can also be used when computing largest/smallest real eigenvalues (i.e, rightmost or leftmost), in which case the threshold is allowed to be negative. The solver will stop when one of the computed eigenvalues is above or below the threshold (considering the real part of the eigenvalue). This mode is allowed only in problem types whose eigenvalues are always real (e.g., HEP).
In the case of largest magnitude eigenvalues, the threshold can be made relative with respect to the dominant eigenvalue. Otherwise, the argument rel should be PETSC_FALSE.
An additional use case is with target magnitude selection of eigenvalues (e.g., with shift-and-invert), but this must be used with caution to avoid unexpected behaviour. With an absolute threshold, the solver will assume that leftmost eigenvalues are being computed (e.g., with target=0 for a problem with real positive eigenvalues). In case of a relative threshold, a value of threshold<1 implies that the wanted eigenvalues are the largest ones, and otherwise the solver assumes that smallest eigenvalues are being computed.
The test against the threshold is done for converged eigenvalues, which implies that the final number of converged eigenvalues will be at least one more than the actual number of values below/above the threshold.
Since the number of computed eigenvalues is not known a priori, the solver will need to reallocate the basis of vectors internally, to have enough room to accommodate all the eigenvectors. Hence, this option must be used with caution to avoid out-of-memory problems. The recommendation is to set the value of ncv to be larger than the estimated number of eigenvalues, to minimize the number of reallocations.
If a number of wanted eigenvalues has been set with EPSSetDimensions() it is also taken into account and the solver will stop when one of the two conditions (threshold or number of converged values) is met.
Use EPSSetStoppingTest() to return to the usual computation of a fixed number of eigenvalues.