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
|
<!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/SVD/SVDSetThreshold.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<link rel="stylesheet" href="/slepc.css" type="text/css">
<TITLE>SVDSetThreshold</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/SVD/SVDSetThreshold.html "><small>Report Typos and Errors</small></a></div>
<H1>SVDSetThreshold</H1>
Sets the threshold used in the threshold stopping test.
<H3><FONT COLOR="#883300">Synopsis</FONT></H3>
<PRE>
#include "slepcsvd.h"
<A HREF="https://petsc.org/release/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</A> <A HREF="../SVD/SVDSetThreshold.html#SVDSetThreshold">SVDSetThreshold</A>(<A HREF="../SVD/SVD.html#SVD">SVD</A> svd,<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>svd </B></TD><TD> - the singular value 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>-svd_threshold_absolute <thres> </B></TD><TD> - Sets an absolute threshold
</TD></TR>
<TR><TD WIDTH=40></TD><TD ALIGN=LEFT VALIGN=TOP><B>-svd_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="../SVD/SVDSetStoppingTest.html#SVDSetStoppingTest">SVDSetStoppingTest</A>() to set a special stopping
test based on the threshold, where singular values are computed in sequence
until one of the computed singular values is below the threshold.
<P>
If the solver is configured to compute smallest singular values, then the
threshold must be interpreted in the opposite direction, i.e., the computation
will stop when one of the computed singular values is above the threshold.
<P>
In the case of largest singular values, the threshold can be made relative
with respect to the largest singular value (i.e., the matrix norm).
<P>
The test against the threshold is done for converged singular values, which
implies that the final number of converged singular values will be at least
one more than the actual number of values below/above the threshold.
<P>
Since the number of computed singular values is not known a priori, the solver
will need to reallocate the basis of vectors internally, to have enough room
to accommodate all the singular vectors. 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 singular values, to minimize
the number of reallocations.
<P>
This functionality is most useful when computing largest singular values. A
typical use case is to compute a low rank approximation of a matrix. Suppose
we know that singular values decay abruptly around a certain index k, which
is unknown. Then using a small relative threshold such as 0.2 will guarantee that
the computed singular vectors capture the numerical rank k. However, if the matrix
does not have low rank, i.e., singular values decay progressively, then a
value of 0.2 will imply a very high cost, both computationally and in memory.
<P>
If a number of wanted singular values has been set with <A HREF="../SVD/SVDSetDimensions.html#SVDSetDimensions">SVDSetDimensions</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="../SVD/SVDSetStoppingTest.html#SVDSetStoppingTest">SVDSetStoppingTest</A>() to return to the usual computation of a fixed number
of singular values.
<P>
<P>
<H3><FONT COLOR="#883300">See Also</FONT></H3>
<A HREF="../SVD/SVDGetThreshold.html#SVDGetThreshold">SVDGetThreshold</A>(), <A HREF="../SVD/SVDSetStoppingTest.html#SVDSetStoppingTest">SVDSetStoppingTest</A>(), <A HREF="../SVD/SVDSetDimensions.html#SVDSetDimensions">SVDSetDimensions</A>(), <A HREF="../SVD/SVDSetWhichSingularTriplets.html#SVDSetWhichSingularTriplets">SVDSetWhichSingularTriplets</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/svd/interface/svdopts.c.html#SVDSetThreshold">src/svd/interface/svdopts.c</A>
<BR><BR><A HREF="./index.html">Index of all SVD 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>
|
