Skip to main content
`Ctrl`+`K`

# SVDSetThreshold

Sets the threshold used in the threshold stopping test.

## Synopsis

    #include "slepcsvd.h"
    PetscErrorCode SVDSetThreshold(SVD svd,PetscReal thres,PetscBool rel)

Logically Collective

## Input Parameters

- svd - the singular value solver context

- thres - the threshold value

- rel - whether the threshold is relative or not

## Options Database Keys

- -svd_threshold_absolute <thres> - sets an absolute threshold

- -svd_threshold_relative <thres> - sets a relative threshold

## Notes

This function internally calls `SVDSetStoppingTest()` 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 `thres`.

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.

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). Otherwise, the argument `rel` should be `PETSC_FALSE`.

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.

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.

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.

If a number of wanted singular values has been set with `SVDSetDimensions()` 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 `SVDSetStoppingTest()` to return to the usual computation of a fixed number of singular values.

## See Also

SVD: Singular Value Decomposition, `SVDGetThreshold()`, `SVDSetStoppingTest()`, `SVDSetDimensions()`, `SVDSetWhichSingularTriplets()`

## Level

advanced

## Location

src/svd/interface/svdopts.c

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