EPSSetThreshold#

Sets the threshold used in the threshold stopping test.

Synopsis#

#include "slepceps.h" 
PetscErrorCode EPSSetThreshold(EPS eps,PetscReal thres,PetscBool rel)

Logically Collective

Input Parameters#

  • eps - the linear eigensolver context

  • thres - the threshold value

  • rel - whether the threshold is relative or not

Options Database Keys#

  • -eps_threshold_absolute <thres> - sets an absolute threshold

  • -eps_threshold_relative <thres> - sets a relative threshold

Notes#

This function internally calls EPSSetStoppingTest() to set a special stopping test based on the threshold, where eigenvalues are computed in sequence until one of the computed eigenvalues is below the threshold thres (in magnitude). This is the interpretation in case of searching for largest eigenvalues in magnitude, see EPSSetWhichEigenpairs().

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., EPS_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 behavior. 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 thres<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.

See Also#

EPS: Eigenvalue Problem Solver, EPSGetThreshold(), EPSSetStoppingTest(), EPSSetDimensions(), EPSSetWhichEigenpairs(), EPSSetProblemType()

Level#

advanced

Location#

src/eps/interface/epsopts.c

Index of all EPS routines Table of Contents for all manual pages Index of all manual pages