1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="https://slepc.upv.es/documentation/current//Users/jroman/tmp/slepc-3.23.1/docs/manualpages/EPS/EPSSetThreshold.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<link rel="stylesheet" href="/slepc.css" type="text/css">
<TITLE>EPSSetThreshold</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<div id="version" align=right><b>slepc-3.23.1 2025-05-01</b></div>
<div id="bugreport" align=right><a href="mailto:slepc-maint@upv.es?subject=Typo or Error in Documentation &body=Please describe the typo or error in the documentation: slepc-3.23.1 v3.23.1 /Users/jroman/tmp/slepc-3.23.1/docs/manualpages/EPS/EPSSetThreshold.html "><small>Report Typos and Errors</small></a></div>
<H1>EPSSetThreshold</H1>
Sets the threshold used in the threshold stopping test.
<H3><FONT COLOR="#883300">Synopsis</FONT></H3>
<PRE>
#include "slepceps.h"
<A HREF="https://petsc.org/release/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> <A HREF="../EPS/EPSSetThreshold.html#EPSSetThreshold">EPSSetThreshold</A>(<A HREF="../EPS/EPS.html#EPS">EPS</A> eps,<A HREF="https://petsc.org/release/manualpages/Sys/PetscReal.html#PetscReal">PetscReal</A> thres,<A HREF="https://petsc.org/release/manualpages/Sys/PetscBool.html#PetscBool">PetscBool</A> rel)
</PRE>
Logically Collective
<P>
<H3><FONT COLOR="#883300">Input Parameters</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>eps </B></TD><TD> - the eigenvalue solver context
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>thres </B></TD><TD> - the threshold value
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>rel </B></TD><TD> - whether the threshold is relative or not
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#883300">Options Database Keys</FONT></H3>
<TABLE border="0" cellpadding="0" cellspacing="0">
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-eps_threshold_absolute <thres> </B></TD><TD> - Sets an absolute threshold
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-eps_threshold_relative <thres> </B></TD><TD> - Sets a relative threshold
</TD></TR></TABLE>
<P>
<H3><FONT COLOR="#883300">Notes</FONT></H3>
This function internally calls <A HREF="../EPS/EPSSetStoppingTest.html#EPSSetStoppingTest">EPSSetStoppingTest</A>() 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 (in magnitude). This is
the interpretation in case of searching for largest eigenvalues in magnitude,
see <A HREF="../EPS/EPSSetWhichEigenpairs.html#EPSSetWhichEigenpairs">EPSSetWhichEigenpairs</A>().
<P>
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).
<P>
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).
<P>
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
<A HREF="https://petsc.org/release/manualpages/Sys/PETSC_FALSE.html#PETSC_FALSE">PETSC_FALSE</A>.
<P>
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.
<P>
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.
<P>
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.
<P>
If a number of wanted eigenvalues has been set with <A HREF="../EPS/EPSSetDimensions.html#EPSSetDimensions">EPSSetDimensions</A>()
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.
<P>
Use <A HREF="../EPS/EPSSetStoppingTest.html#EPSSetStoppingTest">EPSSetStoppingTest</A>() to return to the usual computation of a fixed number
of eigenvalues.
<P>
<P>
<H3><FONT COLOR="#883300">See Also</FONT></H3>
<A HREF="../EPS/EPSGetThreshold.html#EPSGetThreshold">EPSGetThreshold</A>(), <A HREF="../EPS/EPSSetStoppingTest.html#EPSSetStoppingTest">EPSSetStoppingTest</A>(), <A HREF="../EPS/EPSSetDimensions.html#EPSSetDimensions">EPSSetDimensions</A>(), <A HREF="../EPS/EPSSetWhichEigenpairs.html#EPSSetWhichEigenpairs">EPSSetWhichEigenpairs</A>(), <A HREF="../EPS/EPSSetProblemType.html#EPSSetProblemType">EPSSetProblemType</A>()
<BR><P><B></B><H3><FONT COLOR="#883300">Level</FONT></H3>advanced<BR>
<H3><FONT COLOR="#883300">Location</FONT></H3>
</B><A HREF="../../../src/eps/interface/epsopts.c.html#EPSSetThreshold">src/eps/interface/epsopts.c</A>
<BR><BR><A HREF="./index.html">Index of all EPS routines</A>
<BR><A HREF="../../../docs/manual.html">Table of Contents for all manual pages</A>
<BR><A HREF="../singleindex.html">Index of all manual pages</A>
</BODY></HTML>
|
