Refactor truncation names

Author: lkdvos

src/MatrixAlgebraKit.jl

@@ -28,16 +28,14 @@ export left_polar!, right_polar!
 export left_orth, right_orth, left_null, right_null
 export left_orth!, right_orth!, left_null!, right_null!
 
-export LAPACK_HouseholderQR, LAPACK_HouseholderLQ,
-       LAPACK_Simple, LAPACK_Expert,
-       LAPACK_QRIteration, LAPACK_Bisection, LAPACK_MultipleRelativelyRobustRepresentations,
-       LAPACK_DivideAndConquer, LAPACK_Jacobi,
-       LQViaTransposedQR,
-       CUSOLVER_Simple,
-       CUSOLVER_HouseholderQR, CUSOLVER_QRIteration, CUSOLVER_SVDPolar, CUSOLVER_Jacobi, CUSOLVER_Randomized, CUSOLVER_DivideAndConquer,
-       ROCSOLVER_HouseholderQR, ROCSOLVER_QRIteration, ROCSOLVER_Jacobi, ROCSOLVER_DivideAndConquer, ROCSOLVER_Bisection,
-       DiagonalAlgorithm
-export truncrank, trunctol, truncabove, TruncationKeepSorted, TruncationKeepFiltered, truncerror
+export LAPACK_HouseholderQR, LAPACK_HouseholderLQ, LAPACK_Simple, LAPACK_Expert, LAPACK_QRIteration, LAPACK_Bisection, LAPACK_MultipleRelativelyRobustRepresentations, LAPACK_DivideAndConquer, LAPACK_Jacobi
+export LQViaTransposedQR
+export DiagonalAlgorithm
+export CUSOLVER_Simple, CUSOLVER_HouseholderQR, CUSOLVER_QRIteration, CUSOLVER_SVDPolar, CUSOLVER_Jacobi, CUSOLVER_Randomized, CUSOLVER_DivideAndConquer
+export ROCSOLVER_HouseholderQR, ROCSOLVER_QRIteration, ROCSOLVER_Jacobi,
+       ROCSOLVER_DivideAndConquer, ROCSOLVER_Bisection
+
+export notrunc, truncrank, trunctol, truncerror, truncfilter
 
 VERSION >= v"1.11.0-DEV.469" &&
     eval(Expr(:public, :default_algorithm, :findtruncated, :findtruncated_sorted,

src/implementations/orthnull.jl

@@ -207,7 +207,7 @@ function null_truncation_strategy(; atol=nothing, rtol=nothing, maxnullity=nothi
     end
     atol = @something atol 0
     rtol = @something rtol 0
-    trunc = TruncationKeepBelow(atol, rtol)
+    trunc = trunctol(; atol, rtol, rev=false)
     return !isnothing(maxnullity) ? trunc & truncrank(maxnullity; rev=false) : trunc
 end
 

src/implementations/truncation.jl

@@ -28,82 +28,78 @@ end
 
 # findtruncated
 # -------------
+# Generic fallback
+function findtruncated_sorted(values::AbstractVector, strategy::TruncationStrategy)
+    return findtruncated(values, strategy)
+end
+
 # specific implementations for finding truncated values
 findtruncated(values::AbstractVector, ::NoTruncation) = Colon()
 
-function findtruncated(values::AbstractVector, strategy::TruncationKeepSorted)
+function findtruncated(values::AbstractVector, strategy::TruncationByOrder)
     howmany = min(strategy.howmany, length(values))
-    return partialsortperm(values, 1:howmany; by=strategy.by, rev=strategy.rev)
+    return partialsortperm(values, 1:howmany; strategy.by, strategy.rev)
 end
-function findtruncated_sorted(values::AbstractVector, strategy::TruncationKeepSorted)
+function findtruncated_sorted(values::AbstractVector, strategy::TruncationByOrder)
     howmany = min(strategy.howmany, length(values))
     return 1:howmany
 end
 
-# TODO: consider if worth using that values are sorted when filter is `<` or `>`.
-function findtruncated(values::AbstractVector, strategy::TruncationKeepFiltered)
+function findtruncated(values::AbstractVector, strategy::TruncationByFilter)
     ind = findall(strategy.filter, values)
     return ind
 end
 
-function findtruncated(values::AbstractVector, strategy::TruncationKeepBelow)
-    atol = max(strategy.atol, strategy.rtol * norm(values, strategy.p))
-    return findall(≤(atol) ∘ strategy.by, values)
-end
-function findtruncated_sorted(values::AbstractVector, strategy::TruncationKeepBelow)
-    atol = max(strategy.atol, strategy.rtol * norm(values, strategy.p))
-    i = searchsortedfirst(values, atol; by=strategy.by, rev=true)
-    return i:length(values)
-end
-
-function findtruncated(values::AbstractVector, strategy::TruncationKeepAbove)
+function findtruncated(values::AbstractVector, strategy::TruncationByValue)
     atol = max(strategy.atol, strategy.rtol * norm(values, strategy.p))
-    return findall(≥(atol) ∘ strategy.by, values)
+    filter = (strategy.rev ? ≥(atol) : ≤(atol)) ∘ strategy.by
+    return findall(filter, values)
 end
-function findtruncated_sorted(values::AbstractVector, strategy::TruncationKeepAbove)
+function findtruncated_sorted(values::AbstractVector, strategy::TruncationByValue)
     atol = max(strategy.atol, strategy.rtol * norm(values, strategy.p))
-    i = searchsortedlast(values, atol; by=strategy.by, rev=true)
-    return 1:i
-end
-
-function findtruncated(values::AbstractVector, strategy::TruncationIntersection)
-    inds = map(Base.Fix1(findtruncated, values), strategy.components)
-    return intersect(inds...)
-end
-function findtruncated_sorted(values::AbstractVector, strategy::TruncationIntersection)
-    inds = map(Base.Fix1(findtruncated_sorted, values), strategy.components)
-    return intersect(inds...)
+    if strategy.rev
+        i = searchsortedlast(values, atol; by=strategy.by, rev=true)
+        return 1:i
+    else
+        i = searchsortedfirst(values, atol; by=strategy.by, rev=true)
+        return i:length(values)
+    end
 end
 
-function findtruncated(values::AbstractVector, strategy::TruncationError)
+function findtruncated(values::AbstractVector, strategy::TruncationByError)
     I = sortperm(values; by=abs, rev=true)
-    I′ = _truncerr_impl(values, I, strategy)
+    I′ = _truncerr_impl(values, I; strategy.atol, strategy.rtol, strategy.p)
     return I[I′]
 end
-function findtruncated_sorted(values::AbstractVector, strategy::TruncationError)
+function findtruncated_sorted(values::AbstractVector, strategy::TruncationByError)
     I = eachindex(values)
-    I′ = _truncerr_impl(values, I, strategy)
+    I′ = _truncerr_impl(values, I; strategy.atol, strategy.rtol, strategy.p)
     return I[I′]
 end
-function _truncerr_impl(values::AbstractVector, I, strategy::TruncationError)
-    Nᵖ = sum(Base.Fix2(^, strategy.p) ∘ abs, values)
-    ϵᵖ = max(strategy.atol^strategy.p, strategy.rtol^strategy.p * Nᵖ)
+function _truncerr_impl(values::AbstractVector, I; atol::Real=0, rtol::Real=0, p::Real=2)
+    by = Base.Fix2(^, p) ∘ abs
+    Nᵖ = sum(by, values)
+    ϵᵖ = max(atol^p, rtol^p * Nᵖ)
+
+    # fast path to avoid checking all values
     ϵᵖ ≥ Nᵖ && return Base.OneTo(0)
 
     truncerrᵖ = zero(real(eltype(values)))
     rank = length(values)
     for i in reverse(I)
-        truncerrᵖ += abs(values[i])^strategy.p
-        if truncerrᵖ ≥ ϵᵖ
-            break
-        else
-            rank -= 1
-        end
+        truncerrᵖ += by(values[i])
+        truncerrᵖ ≥ ϵᵖ && break
+        rank -= 1
     end
+
     return Base.OneTo(rank)
 end
 
-# Generic fallback
-function findtruncated_sorted(values::AbstractVector, strategy::TruncationStrategy)
-    return findtruncated(values, strategy)
+function findtruncated(values::AbstractVector, strategy::TruncationIntersection)
+    inds = map(Base.Fix1(findtruncated, values), strategy.components)
+    return intersect(inds...)
+end
+function findtruncated_sorted(values::AbstractVector, strategy::TruncationIntersection)
+    inds = map(Base.Fix1(findtruncated_sorted, values), strategy.components)
+    return intersect(inds...)
 end

src/interface/truncation.jl

@@ -14,14 +14,14 @@ function TruncationStrategy(; atol=nothing, rtol=nothing, maxrank=nothing)
     elseif isnothing(maxrank)
         atol = @something atol 0
         rtol = @something rtol 0
-        return TruncationKeepAbove(atol, rtol)
+        return trunctol(; atol, rtol)
     else
         if isnothing(atol) && isnothing(rtol)
             return truncrank(maxrank)
         else
             atol = @something atol 0
             rtol = @something rtol 0
-            return truncrank(maxrank) & TruncationKeepAbove(atol, rtol)
+            return truncrank(maxrank) & trunctol(; atol, rtol)
         end
     end
 end
@@ -42,87 +42,102 @@ Truncation strategy that does nothing, and keeps all the values.
 notrunc() = NoTruncation()
 
 """
-    TruncationKeepSorted(howmany::Int, by::Function, rev::Bool)
+    TruncationByOrder(howmany::Int, by::Function, rev::Bool)
 
 Truncation strategy to keep the first `howmany` values when sorted according to `by` in increasing (decreasing) order if `rev` is false (true).
+
 See also [`truncrank`](@ref).
 """
-struct TruncationKeepSorted{F} <: TruncationStrategy
+struct TruncationByOrder{F} <: TruncationStrategy
     howmany::Int
     by::F
     rev::Bool
 end
 
 """
-    truncrank(howmany::Int; by=abs, rev=true)
+    truncrank(howmany::Integer; by=abs, rev::Bool=true)
 
 Truncation strategy to keep the first `howmany` values when sorted according to `by` or the last `howmany` if `rev` is true.
 """
-truncrank(howmany::Int; by=abs, rev=true) = TruncationKeepSorted(howmany, by, rev)
+truncrank(howmany::Integer; by=abs, rev::Bool=true) = TruncationByOrder(howmany, by, rev)
 
 """
-    TruncationKeepFiltered(filter::Function)
+    TruncationByFilter(filter::Function)
 
 Truncation strategy to keep the values for which `filter` returns true.
+
+See also [`truncfilter`](@ref).
 """
-struct TruncationKeepFiltered{F} <: TruncationStrategy
+struct TruncationByFilter{F} <: TruncationStrategy
     filter::F
 end
 
 """
-    truncabove(val::Real; by=abs)
+    truncfilter(filter)
+
+Truncation strategy to keep the values for which `filter` returns true.
+"""
+truncfilter(f) = TruncationByFilter(f)
 
-Truncation strategy to discard the values that are larger than `val` according to `by`.
 """
-truncabove(val::Real; by=abs) = TruncationKeepFiltered(≤(val) ∘ by)
+    TruncationByValue(atol::Real, rtol::Real, p::Real, by, rev::Bool=true)
 
-struct TruncationKeepAbove{T<:Real,P<:Real,F} <: TruncationStrategy
+Truncation strategy to keep the values that satisfy `by(val) < max(atol, rtol * norm(values, p)`
+if `rev = true`, or discard them when `rev = false`.
+See also [`trunctol`](@ref)
+"""
+struct TruncationByValue{T<:Real,P<:Real,F} <: TruncationStrategy
     atol::T
     rtol::T
     p::P
     by::F
+    rev::Bool
 end
-function TruncationKeepAbove(; atol::Real, rtol::Real, p::Real=2, by=abs)
-    return TruncationKeepAbove(atol, rtol, p, by)
+function TruncationByValue(atol::Real, rtol::Real, p::Real=2, by=abs, rev::Bool=true)
+    return TruncationByValue(promote(atol, rtol)..., p, by, rev)
 end
-function TruncationKeepAbove(atol::Real, rtol::Real, p::Real=2, by=abs)
-    return TruncationKeepAbove(promote(atol, rtol)..., p, by)
+
+"""
+    trunctol(; atol::Real=0, rtol::Real=0, p::Real=2, by=abs, )
+
+Truncation strategy to keep the values that satisfy `by(val) < max(atol, rtol * norm(values, p)`
+if `rev = true`, or discard them when `rev = false`.
+"""
+function trunctol(; atol::Real=0, rtol::Real=0, p::Real=2, by=abs, rev::Bool=true)
+    return TruncationByValue(atol, rtol, p, by, rev)
 end
 
 """
-    TruncationKeepBelow(; atol::Real, rtol::Real, p=2, by=abs)
+    TruncationByError(; atol::Real, rtol::Real, p::Real)
 
-Truncation strategy to discard the values that are smaller than the norm of the values.
+Truncation strategy to discard values until the error caused by the discarded values exceeds some tolerances.
+See also [`truncerror`](@ref).
 """
-struct TruncationKeepBelow{T<:Real,P<:Real,F} <: TruncationStrategy
+struct TruncationByError{T<:Real,P<:Real} <: TruncationStrategy
     atol::T
     rtol::T
     p::P
-    by::F
-end
-function TruncationKeepBelow(; atol::Real, rtol::Real, p::Real=2, by=abs)
-    return TruncationKeepBelow(atol, rtol, p, by)
 end
-function TruncationKeepBelow(atol::Real, rtol::Real, p::Real=2, by=abs)
-    return TruncationKeepBelow(promote(atol, rtol)..., p, by)
+function TruncationError(atol::Real, rtol::Real, p::Real=2)
+    return TruncationError(promote(atol, rtol)..., p)
 end
 
 """
-    trunctol(; atol::Real, rtol::Real, p::Real=2, by=abs)
+    truncerror(; atol::Real=0, rtol::Real=0, p::Real=2)
 
-Truncation strategy to discard all values that satisfy `by(val) < max(atol, rtol * norm(values))`.
+Create a truncation strategy for truncating such that the error in the factorization
+is smaller than `max(atol, rtol * norm)`, where the error is determined using the `p`-norm.
 """
-function trunctol(; atol::Real=0, rtol::Real=0, p::Real=2, by=abs)
-    return TruncationKeepBelow(; atol, rtol, p, by)
+function truncerror(; atol::Real=0, rtol::Real=0, p::Real=2)
+    return TruncationByError(promote(atol, rtol)..., p)
 end
 
 """
     TruncationIntersection(trunc::TruncationStrategy, truncs::TruncationStrategy...)
 
 Composition of multiple truncation strategies, keeping values common between them.
 """
-struct TruncationIntersection{T<:Tuple{Vararg{TruncationStrategy}}} <:
-       TruncationStrategy
+struct TruncationIntersection{T<:Tuple{Vararg{TruncationStrategy}}} <: TruncationStrategy
     components::T
 end
 function TruncationIntersection(trunc::TruncationStrategy, truncs::TruncationStrategy...)
@@ -141,31 +156,3 @@ end
 function Base.:&(trunc1::TruncationStrategy, trunc2::TruncationIntersection)
     return TruncationIntersection((trunc1, trunc2.components...))
 end
-
-"""
-    TruncationError(; atol::Real, rtol::Real, p::Real)
-
-Truncation strategy to discard values until the error caused by the discarded values exceeds some tolerances.
-See also [`truncerror`](@ref).
-"""
-struct TruncationError{T<:Real,P<:Real} <: TruncationStrategy
-    atol::T
-    rtol::T
-    p::P
-end
-function TruncationError(; atol::Real, rtol::Real, p::Real=2)
-    return TruncationError(atol, rtol, p)
-end
-function TruncationError(atol::Real, rtol::Real, p::Real=2)
-    return TruncationError(promote(atol, rtol)..., p)
-end
-
-"""
-    truncerror(; atol::Real=0, rtol::Real=0, p::Real=2)
-
-Create a truncation strategy for truncating such that the error in the factorization
-is smaller than `max(atol, rtol * norm)`, where the error is determined using the `p`-norm.
-"""
-function truncerror(; atol::Real=0, rtol::Real=0, p::Real=2)
-    return TruncationError(promote(atol, rtol)..., p)
-end