Skip to main content
`Ctrl`+`K`

# 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