docs improvements

Author: lkdvos

ext/MatrixAlgebraKitCUDAExt/yacusolver.jl

@@ -164,9 +164,7 @@ function gesvdp!(
         )
     end
     err = h_err_sigma[]
-    if err > tol
-        warn("gesvdp! did not attained requested tolerance: error = $err > tolerance = $tol")
-    end
+    err > tol && @warn "gesvdp! did not attain the requested tolerance: error = $err > tolerance = $tol"
 
     flag = @allowscalar dh.info[1]
     CUSOLVER.chklapackerror(BlasInt(flag))

src/common/defaults.jl

@@ -59,3 +59,5 @@ function default_fixgauge(new_value::Bool)
     DEFAULT_FIXGAUGE[] = new_value
     return previous_value
 end
+
+const _fixgauge_docs = "The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the output, see also [`default_fixgauge`](@ref) for a global toggle and [`gaugefix!`](@ref) for implementation details."

src/interface/decompositions.jl

@@ -60,7 +60,6 @@ of `R` are non-negative.
 """
 @algdef GLA_HouseholderQR
 
-# TODO:
 @algdef LAPACK_HouseholderQL
 @algdef LAPACK_HouseholderRQ
 
@@ -86,38 +85,26 @@ function Householder(;
     return Householder((; blocksize, driver, pivoted, positive))
 end
 
-default_householder_driver(A) = default_householder_driver(typeof(A))
-default_householder_driver(::Type) = Native()
-
-default_householder_driver(::Type{A}) where {A <: YALAPACK.MaybeBlasMat} = LAPACK()
-
-# note: StridedVector fallback is needed for handling reshaped parent types
-default_householder_driver(::Type{A}) where {A <: StridedVector{<:BlasFloat}} = LAPACK()
-default_householder_driver(::Type{<:SubArray{T, N, A}}) where {T, N, A} =
-    default_householder_driver(A)
-default_householder_driver(::Type{<:Base.ReshapedArray{T, N, A}}) where {T, N, A} =
-    default_householder_driver(A)
-
 """
-    DivideAndConquer(; [driver], fixgauge=default_fixgauge())
+    DivideAndConquer(; [driver], fixgauge = default_fixgauge())
 
 Algorithm type to denote the algorithm for computing the eigenvalue decomposition of a Hermitian matrix,
 or the singular value decomposition of a general matrix using the divide-and-conquer algorithm.
 
 The optional `driver` symbol can be used to choose between different implementations of this algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or singular vectors, see also [`default_fixgauge`](@ref) and [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef DivideAndConquer
 
 """
-    SafeDivideAndConquer(; [driver], kwargs...)
+    SafeDivideAndConquer(; [driver], fixgauge = default_fixgauge())
 
 Algorithm type to for computing the eigenvalue decomposition of a Hermitian matrix,
 or the singular value decomposition of a general matrix using the divide-and-conquer algorithm,
 with an additional fallback to the standard QR iteration algorithm in case the former fails to converge.
 
 The optional `driver` symbol can be used to choose between different implementations of this algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 
 !!! warning
     This approach requires a copy of the input matrix, and is thus the most memory intensive SVD strategy.
@@ -129,46 +116,47 @@ See also [`DivideAndConquer`](@ref) and [`QRIteration`](@ref).
 @algdef SafeDivideAndConquer
 
 """
-    QRIteration(; [driver], fixgauge = true)
+    QRIteration(; [driver], fixgauge = default_fixgauge())
 
 Algorithm type for computing the eigenvalue decomposition of a Hermitian matrix,
 or the singular value decomposition of a general matrix via QR iteration.
 
 The optional `driver` symbol can be used to choose between different implementations of this algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef QRIteration
 
 """
-    Bisection(; [driver], fixgauge::Bool = true)
+    Bisection(; [driver], fixgauge = default_fixgauge())
 
 Algorithm type for computing the eigenvalue decomposition of a Hermitian matrix,
 or the singular value decomposition of a general matrix via the bisection algorithm.
 
 The optional `driver` symbol can be used to choose between different implementations of this algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef Bisection
 
 """
-    Jacobi(; [driver], fixgauge = true)
+    Jacobi(; [driver], fixgauge = default_fixgauge())
 
 Algorithm type for computing the singular value decomposition of a general matrix using the Jacobi algorithm.
 
 The optional `driver` symbol can be used to choose between different implementations of this algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef Jacobi
 
 """
-    SVDViaPolar(; [driver], kwargs...)
+    SVDViaPolar(; [driver], fixgauge = default_fixgauge(), [tol])
 
 Algorithm type to denote the algorithm for computing the singular value decomposition of a general
 matrix via Halley's iterative algorithm for the polar decomposition followed by the Hermitian
 eigenvalue decomposition of the positive definite factor.
 
 The optional `driver` symbol can be used to choose between different implementations of this algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
+The tolerance `tol` can optionally be used to emit a warning if the decomposition failed to converge beyond that given value.
 """
 @algdef SVDViaPolar
 
@@ -195,22 +183,20 @@ end
 # General Eigenvalue Decomposition
 # -------------------------------
 """
-    LAPACK_Simple(; fixgauge::Bool = true)
+    LAPACK_Simple(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the simple LAPACK driver for computing the Schur or non-Hermitian
 eigenvalue decomposition of a matrix.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigenvectors,
-see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef LAPACK_Simple
 
 """
-    LAPACK_Expert(; fixgauge::Bool = true)
+    LAPACK_Expert(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the expert LAPACK driver for computing the Schur or non-Hermitian
 eigenvalue decomposition of a matrix.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigenvectors,
-see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef LAPACK_Expert
 
@@ -227,45 +213,38 @@ eigenvalue decomposition of a non-Hermitian matrix.
 # Hermitian Eigenvalue Decomposition
 # ----------------------------------
 """
-    LAPACK_QRIteration(; fixgauge::Bool = true)
+    LAPACK_QRIteration(; fixgauge = default_fixgauge())
 
-Algorithm type to denote the LAPACK driver for computing the eigenvalue decomposition of a
-Hermitian matrix, or the singular value decomposition of a general matrix using the
-QR Iteration algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+Algorithm type to denote the LAPACK driver for computing the eigenvalue decomposition of a Hermitian matrix,
+or the singular value decomposition of a general matrix using the QR Iteration algorithm.
+$_fixgauge_docs
 """
 @algdef LAPACK_QRIteration
 
 """
-    LAPACK_Bisection(; fixgauge::Bool = true)
+    LAPACK_Bisection(; fixgauge = default_fixgauge())
 
-Algorithm type to denote the LAPACK driver for computing the eigenvalue decomposition of a
-Hermitian matrix, or the singular value decomposition of a general matrix using the
-Bisection algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+Algorithm type to denote the LAPACK driver for computing the eigenvalue decomposition of a Hermitian matrix,
+or the singular value decomposition of a general matrix using the Bisection algorithm.
+$_fixgauge_docs
 """
 @algdef LAPACK_Bisection
 
 """
-    LAPACK_DivideAndConquer(; fixgauge::Bool = true)
+    LAPACK_DivideAndConquer(; fixgauge = default_fixgauge())
 
-Algorithm type to denote the LAPACK driver for computing the eigenvalue decomposition of a
-Hermitian matrix, or the singular value decomposition of a general matrix using the
-Divide and Conquer algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+Algorithm type to denote the LAPACK driver for computing the eigenvalue decomposition of a Hermitian matrix,
+or the singular value decomposition of a general matrix using the Divide and Conquer algorithm.
+$_fixgauge_docs
 """
 @algdef LAPACK_DivideAndConquer
 
 """
-    LAPACK_MultipleRelativelyRobustRepresentations(; fixgauge::Bool = true)
+    LAPACK_MultipleRelativelyRobustRepresentations(; fixgauge = default_fixgauge())
 
-Algorithm type to denote the LAPACK driver for computing the eigenvalue decomposition of a
-Hermitian matrix using the Multiple Relatively Robust Representations algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigenvectors,
-see also [`gaugefix!`](@ref).
+Algorithm type to denote the LAPACK driver for computing the eigenvalue decomposition of a Hermitian matrix
+using the Multiple Relatively Robust Representations algorithm.
+$_fixgauge_docs
 """
 @algdef LAPACK_MultipleRelativelyRobustRepresentations
 
@@ -277,26 +256,24 @@ const LAPACK_EighAlgorithm = Union{
 }
 
 """
-    GLA_QRIteration(; fixgauge::Bool = true)
+    GLA_QRIteration(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the GenericLinearAlgebra.jl implementation for computing the
 eigenvalue decomposition of a Hermitian matrix, or the singular value decomposition of
 a general matrix.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef GLA_QRIteration
 
 # Singular Value Decomposition
 # ----------------------------
 """
-    LAPACK_SafeDivideAndConquer(; fixgauge::Bool = true)
+    LAPACK_SafeDivideAndConquer(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the LAPACK driver for computing the singular value decomposition of
 a general matrix using the Divide and Conquer algorithm, with an additional fallback to
 the standard QR Iteration algorithm in case the former fails to converge.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the singular vectors,
-see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 
 !!! warning
     This approach requires a copy of the input matrix, and is thus the most memory intensive SVD strategy.
@@ -306,12 +283,11 @@ see also [`gaugefix!`](@ref).
 @algdef LAPACK_SafeDivideAndConquer
 
 """
-    LAPACK_Jacobi(; fixgauge::Bool = true)
+    LAPACK_Jacobi(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the LAPACK driver for computing the singular value decomposition of
 a general matrix using the Jacobi algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the singular vectors,
-see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef LAPACK_Jacobi
 
@@ -384,34 +360,31 @@ the diagonal elements of `R` are non-negative.
 @algdef CUSOLVER_HouseholderQR
 
 """
-    CUSOLVER_QRIteration(; fixgauge::Bool = true)
+    CUSOLVER_QRIteration(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the CUSOLVER driver for computing the eigenvalue decomposition of a
 Hermitian matrix, or the singular value decomposition of a general matrix using the
 QR Iteration algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef CUSOLVER_QRIteration
 
 """
-    CUSOLVER_SVDPolar(; fixgauge::Bool = true)
+    CUSOLVER_SVDPolar(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the CUSOLVER driver for computing the singular value decomposition of
 a general matrix by using Halley's iterative algorithm to compute the polar decompositon,
 followed by the hermitian eigenvalue decomposition of the positive definite factor.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the singular
-vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef CUSOLVER_SVDPolar
 
 """
-    CUSOLVER_Jacobi(; fixgauge::Bool = true)
+    CUSOLVER_Jacobi(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the CUSOLVER driver for computing the singular value decomposition of
 a general matrix using the Jacobi algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the singular
-vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef CUSOLVER_Jacobi
 
@@ -433,25 +406,23 @@ for more information.
 does_truncate(::TruncatedAlgorithm{<:CUSOLVER_Randomized}) = true
 
 """
-    CUSOLVER_Simple(; fixgauge::Bool = true)
+    CUSOLVER_Simple(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the simple CUSOLVER driver for computing the non-Hermitian
 eigenvalue decomposition of a matrix.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigenvectors,
-see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef CUSOLVER_Simple
 
 const CUSOLVER_EigAlgorithm = Union{CUSOLVER_Simple}
 
 """
-    CUSOLVER_DivideAndConquer(; fixgauge::Bool = true)
+    CUSOLVER_DivideAndConquer(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the CUSOLVER driver for computing the eigenvalue decomposition of a
 Hermitian matrix, or the singular value decomposition of a general matrix using the
 Divide and Conquer algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef CUSOLVER_DivideAndConquer
 
@@ -472,45 +443,41 @@ the diagonal elements of `R` are non-negative.
 @algdef ROCSOLVER_HouseholderQR
 
 """
-    ROCSOLVER_QRIteration(; fixgauge::Bool = true)
+    ROCSOLVER_QRIteration(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the ROCSOLVER driver for computing the eigenvalue decomposition of a
 Hermitian matrix, or the singular value decomposition of a general matrix using the
 QR Iteration algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef ROCSOLVER_QRIteration
 
 """
-    ROCSOLVER_Jacobi(; fixgauge::Bool = true)
+    ROCSOLVER_Jacobi(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the ROCSOLVER driver for computing the singular value decomposition of
 a general matrix using the Jacobi algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the singular
-vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef ROCSOLVER_Jacobi
 
 """
-    ROCSOLVER_Bisection(; fixgauge::Bool = true)
+    ROCSOLVER_Bisection(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the ROCSOLVER driver for computing the eigenvalue decomposition of a
 Hermitian matrix, or the singular value decomposition of a general matrix using the
 Bisection algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef ROCSOLVER_Bisection
 
 """
-    ROCSOLVER_DivideAndConquer(; fixgauge::Bool = true)
+    ROCSOLVER_DivideAndConquer(; fixgauge = default_fixgauge())
 
 Algorithm type to denote the ROCSOLVER driver for computing the eigenvalue decomposition of a
 Hermitian matrix, or the singular value decomposition of a general matrix using the
 Divide and Conquer algorithm.
-The `fixgauge` keyword can be used to toggle whether or not to fix the gauge of the eigen or
-singular vectors, see also [`gaugefix!`](@ref).
+$_fixgauge_docs
 """
 @algdef ROCSOLVER_DivideAndConquer