Add docs for findtruncated

Author: mtfishman

docs/src/dev_interface.md

@@ -10,4 +10,6 @@ MatrixAlgebraKit.jl provides a developer interface for specifying custom algorit
 ```@docs; canonical=false
 MatrixAlgebraKit.default_algorithm
 MatrixAlgebraKit.select_algorithm
+MatrixAlgebraKit.findtruncated
+MatrixAlgebraKit.findtruncated_sorted
 ```

src/MatrixAlgebraKit.jl

@@ -31,7 +31,8 @@ export LAPACK_HouseholderQR, LAPACK_HouseholderLQ,
 export truncrank, trunctol, truncabove, TruncationKeepSorted, TruncationKeepFiltered
 
 VERSION >= v"1.11.0-DEV.469" &&
-    eval(Expr(:public, :default_algorithm, :select_algorithm))
+    eval(Expr(:public, :default_algorithm, :findtruncated, :findtruncated_sorted,
+              :select_algorithm))
 
 include("common/defaults.jl")
 include("common/initialization.jl")

src/implementations/truncation.jl

@@ -170,6 +170,27 @@ end
 # findtruncated
 # -------------
 # specific implementations for finding truncated values
+@doc """
+    MatrixAlgebraKit.findtruncated(values::AbstractVector, strategy::TruncationStrategy)
+
+Generic interface for finding truncated values of the spectrum of a decomposition
+based on the `strategy`. The output should be a collection of indices specifying
+which values to keep. `MatrixAlgebraKit.findtruncated` is used inside of the default
+implementation of [`truncate!`](@ref) to perform the truncation. It does not assume that the
+values are sorted. For a version that assumes the values are reverse sorted by
+absolute value (which is the standard case for SVD) see
+[`MatrixAlgebraKit.findtruncated_sorted`](@ref).
+""" findtruncated
+
+@doc """
+    MatrixAlgebraKit.findtruncated_sorted(values::AbstractVector, strategy::TruncationStrategy)
+
+Like [`MatrixAlgebraKit.findtruncated`](@ref) but assumes that the values are sorted in reverse order by
+absolute value. However, note that this assumption is not checked, so passing values that are not sorted
+in that way can silently give unexpected results. This is used in the default implementation of
+[`svd_trunc!`](@ref).
+""" findtruncated_sorted
+
 findtruncated(values::AbstractVector, ::NoTruncation) = Colon()
 
 # TODO: this may also permute the eigenvalues, decide if we want to allow this or not