Docs, tests, style improvements

Author: mtfishman

docs/src/dev_interface.md

@@ -0,0 +1,13 @@
+```@meta
+CurrentModule = MatrixAlgebraKit
+CollapsedDocStrings = true
+```
+
+# Developer Interface
+
+MatrixAlgebraKit.jl provides a developer interface for specifying custom algorithm backends and selecting default algorithms.
+
+```@docs; canonical=false
+MatrixAlgebraKit.default_algorithm
+MatrixAlgebraKit.select_algorithm
+```

src/MatrixAlgebraKit.jl

@@ -30,6 +30,8 @@ export LAPACK_HouseholderQR, LAPACK_HouseholderLQ,
        LAPACK_DivideAndConquer, LAPACK_Jacobi
 export truncrank, trunctol, truncabove, TruncationKeepSorted, TruncationKeepFiltered
 
+public default_truncation, select_algorithm
+
 include("common/defaults.jl")
 include("common/initialization.jl")
 include("common/pullbacks.jl")

src/algorithms.jl

@@ -54,7 +54,7 @@ function _show_alg(io::IO, alg::Algorithm)
 end
 
 @doc """
-    select_algorithm(f, A; kwargs...)
+    MatrixAlgebraKit.select_algorithm(f, A; kwargs...)
 
 Given some keyword arguments and an input `A`, decide on an algorithm to use for
 implementing the function `f` on inputs of type `A`.
@@ -82,7 +82,7 @@ function _select_algorithm(f, A, alg::AbstractAlgorithm; kwargs...)
     return alg
 end
 function _select_algorithm(f, A, alg::Symbol; kwargs...)
-    return _select_algorithm(f, A, Algorithm{alg}; kwargs...)
+    return _select_algorithm(f, A, Algorithm{alg}(; kwargs...))
 end
 function _select_algorithm(f, A, alg::Type; kwargs...)
     return _select_algorithm(f, A, alg(; kwargs...))
@@ -97,7 +97,7 @@ function _select_algorithm(f, A, alg; kwargs...)
 end
 
 @doc """
-    default_algorithm(f, A; kwargs...)
+    MatrixAlgebraKit.default_algorithm(f, A; kwargs...)
 
 Select the default algorithm for a given factorization function `f` and input `A`.
 In general, this is called by [`select_algorithm`](@ref) if no algorithm is specified

src/implementations/truncation.jl

@@ -32,16 +32,16 @@ Trivial truncation strategy that keeps all values, mostly for testing purposes.
 """
 struct NoTruncation <: TruncationStrategy end
 
-function to_truncationstrategy(trunc::TruncationStrategy)
+function select_truncation(trunc::TruncationStrategy)
     return trunc
 end
-function to_truncationstrategy(trunc::NamedTuple)
+function select_truncation(trunc::NamedTuple)
     return TruncationStrategy(; trunc...)
 end
-function to_truncationstrategy(trunc::Nothing)
+function select_truncation(trunc::Nothing)
     return NoTruncation()
 end
-function to_truncationstrategy(trunc)
+function select_truncation(trunc)
     return throw(ArgumentError("Unknown truncation strategy: $trunc"))
 end
 

src/interface/eig.jl

@@ -104,7 +104,7 @@ function select_algorithm(::typeof(eig_trunc), A; kwargs...)
 end
 function select_algorithm(::typeof(eig_trunc!), A; trunc=nothing, kwargs...)
     alg_eig = select_algorithm(eig_full!, A; kwargs...)
-    return TruncatedAlgorithm(alg_eig, to_truncationstrategy(trunc))
+    return TruncatedAlgorithm(alg_eig, select_truncation(trunc))
 end
 
 # Default to LAPACK 

src/interface/eigh.jl

@@ -103,7 +103,7 @@ function select_algorithm(::typeof(eigh_trunc), A; kwargs...)
 end
 function select_algorithm(::typeof(eigh_trunc!), A; trunc=nothing, kwargs...)
     alg_eigh = select_algorithm(eigh_full!, A; kwargs...)
-    return TruncatedAlgorithm(alg_eigh, to_truncationstrategy(trunc))
+    return TruncatedAlgorithm(alg_eigh, select_truncation(trunc))
 end
 
 # Default to LAPACK 

src/interface/svd.jl

@@ -107,7 +107,7 @@ function select_algorithm(::typeof(svd_trunc), A; kwargs...)
 end
 function select_algorithm(::typeof(svd_trunc!), A; trunc=nothing, kwargs...)
     alg_svd = select_algorithm(svd_compact!, A; kwargs...)
-    return TruncatedAlgorithm(alg_svd, to_truncationstrategy(trunc))
+    return TruncatedAlgorithm(alg_svd, select_truncation(trunc))
 end
 
 # Default to LAPACK SDD for `StridedMatrix{<:BlasFloat}`

test/eig.jl

@@ -8,21 +8,35 @@ using MatrixAlgebraKit: diagview
 @testset "eig_full! for T = $T" for T in (Float32, Float64, ComplexF32, ComplexF64)
     rng = StableRNG(123)
     m = 54
-    for alg in (LAPACK_Simple(), LAPACK_Expert())
+    for alg in
+        (LAPACK_Simple(), LAPACK_Expert(), LAPACK_Simple, LAPACK_Expert, :LAPACK_Simple,
+         :LAPACK_Expert)
         A = randn(rng, T, m, m)
         Tc = complex(T)
 
-        D, V = @constinferred eig_full(A; alg)
+        alg′ = if (alg isa Type) || (alg isa Symbol)
+            # These cases aren't inferable right now.
+            MatrixAlgebraKit.select_algorithm(eig_full!, A; alg)
+        else
+            @constinferred MatrixAlgebraKit.select_algorithm(eig_full!, A; alg)
+        end
+
+        D, V = if (alg isa Type) || (alg isa Symbol)
+            # These cases aren't inferable right now.
+            eig_full(A; alg)
+        else
+            @constinferred eig_full(A; alg)
+        end
         @test eltype(D) == eltype(V) == Tc
         @test A * V ≈ V * D
 
         Ac = similar(A)
-        D2, V2 = @constinferred eig_full!(copy!(Ac, A), (D, V), alg)
+        D2, V2 = @constinferred eig_full!(copy!(Ac, A), (D, V), alg′)
         @test D2 === D
         @test V2 === V
         @test A * V ≈ V * D
 
-        Dc = @constinferred eig_vals(A, alg)
+        Dc = @constinferred eig_vals(A, alg′)
         @test eltype(Dc) == Tc
         @test D ≈ Diagonal(Dc)
     end