check kwarg for factorizations (#27336)

* check = (true|false) for LinearAlgebra.cholesky[!]

* check = (true|false) for LinearAlgebra.lu[!]

* check = (true|false) for LinearAlgebra.bunchkaufman[!]

* check = (true|false) for CHOLMOD.cholesky[!] and CHOLMOD.ldlt[!]

* check = (true|false) for UMFPACK.lu

Author: fredrikekre

stdlib/LinearAlgebra/src/bunchkaufman.jl

@@ -24,31 +24,35 @@ Base.iterate(S::BunchKaufman, ::Val{:done}) = nothing
 
 
 """
-    bunchkaufman!(A, rook::Bool=false) -> BunchKaufman
+    bunchkaufman!(A, rook::Bool=false; check = true) -> BunchKaufman
 
 `bunchkaufman!` is the same as [`bunchkaufman`](@ref), but saves space by overwriting the
 input `A`, instead of creating a copy.
 """
-function bunchkaufman!(A::RealHermSymComplexSym{T,S} where {T<:BlasReal,S<:StridedMatrix}, rook::Bool = false)
+function bunchkaufman!(A::RealHermSymComplexSym{T,S} where {T<:BlasReal,S<:StridedMatrix},
+                       rook::Bool = false; check::Bool = true)
     LD, ipiv, info = rook ? LAPACK.sytrf_rook!(A.uplo, A.data) : LAPACK.sytrf!(A.uplo, A.data)
+    check && checknonsingular(info)
     BunchKaufman(LD, ipiv, A.uplo, true, rook, info)
 end
-function bunchkaufman!(A::Hermitian{T,S} where {T<:BlasComplex,S<:StridedMatrix{T}}, rook::Bool = false)
+function bunchkaufman!(A::Hermitian{T,S} where {T<:BlasComplex,S<:StridedMatrix{T}},
+                       rook::Bool = false; check::Bool = true)
     LD, ipiv, info = rook ? LAPACK.hetrf_rook!(A.uplo, A.data) : LAPACK.hetrf!(A.uplo, A.data)
+    check && checknonsingular(info)
     BunchKaufman(LD, ipiv, A.uplo, false, rook, info)
 end
-function bunchkaufman!(A::StridedMatrix{<:BlasFloat}, rook::Bool = false)
+function bunchkaufman!(A::StridedMatrix{<:BlasFloat}, rook::Bool = false; check::Bool = true)
     if ishermitian(A)
-        return bunchkaufman!(Hermitian(A), rook)
+        return bunchkaufman!(Hermitian(A), rook; check = check)
     elseif issymmetric(A)
-        return bunchkaufman!(Symmetric(A), rook)
+        return bunchkaufman!(Symmetric(A), rook; check = check)
     else
         throw(ArgumentError("Bunch-Kaufman decomposition is only valid for symmetric or Hermitian matrices"))
     end
 end
 
 """
-    bunchkaufman(A, rook::Bool=false) -> S::BunchKaufman
+    bunchkaufman(A, rook::Bool=false; check = true) -> S::BunchKaufman
 
 Compute the Bunch-Kaufman [^Bunch1977] factorization of a `Symmetric` or
 `Hermitian` matrix `A` as ``P'*U*D*U'*P`` or ``P'*L*D*L'*P``, depending on
@@ -62,6 +66,10 @@ as appropriate given `S.uplo`, and `S.p`.
 If `rook` is `true`, rook pivoting is used. If `rook` is false,
 rook pivoting is not used.
 
+When `check = true`, an error is thrown if the decomposition fails.
+When `check = false`, responsibility for checking the decomposition's
+validity (via [`issuccess`](@ref)) lies with the user.
+
 The following functions are available for `BunchKaufman` objects:
 [`size`](@ref), `\\`, [`inv`](@ref), [`issymmetric`](@ref),
 [`ishermitian`](@ref), [`getindex`](@ref).
@@ -98,8 +106,8 @@ julia> d == S.D && u == S.U && p == S.p
 true
 ```
 """
-bunchkaufman(A::AbstractMatrix{T}, rook::Bool=false) where {T} =
-    bunchkaufman!(copy_oftype(A, typeof(sqrt(one(T)))), rook)
+bunchkaufman(A::AbstractMatrix{T}, rook::Bool=false; check::Bool = true) where {T} =
+    bunchkaufman!(copy_oftype(A, typeof(sqrt(one(T)))), rook; check = check)
 
 convert(::Type{BunchKaufman{T}}, B::BunchKaufman{T}) where {T} = B
 convert(::Type{BunchKaufman{T}}, B::BunchKaufman) where {T} =
@@ -249,10 +257,6 @@ function Base.show(io::IO, mime::MIME{Symbol("text/plain")}, B::BunchKaufman)
 end
 
 function inv(B::BunchKaufman{<:BlasReal})
-    if !issuccess(B)
-        throw(SingularException(B.info))
-    end
-
     if B.rook
         copytri!(LAPACK.sytri_rook!(B.uplo, copy(B.LD), B.ipiv), B.uplo, true)
     else
@@ -261,10 +265,6 @@ function inv(B::BunchKaufman{<:BlasReal})
 end
 
 function inv(B::BunchKaufman{<:BlasComplex})
-    if !issuccess(B)
-        throw(SingularException(B.info))
-    end
-
     if issymmetric(B)
         if B.rook
             copytri!(LAPACK.sytri_rook!(B.uplo, copy(B.LD), B.ipiv), B.uplo)
@@ -281,21 +281,13 @@ function inv(B::BunchKaufman{<:BlasComplex})
 end
 
 function ldiv!(B::BunchKaufman{T}, R::StridedVecOrMat{T}) where T<:BlasReal
-    if !issuccess(B)
-        throw(SingularException(B.info))
-    end
-
     if B.rook
         LAPACK.sytrs_rook!(B.uplo, B.LD, B.ipiv, R)
     else
         LAPACK.sytrs!(B.uplo, B.LD, B.ipiv, R)
     end
 end
 function ldiv!(B::BunchKaufman{T}, R::StridedVecOrMat{T}) where T<:BlasComplex
-    if !issuccess(B)
-        throw(SingularException(B.info))
-    end
-
     if B.rook
         if issymmetric(B)
             LAPACK.sytrs_rook!(B.uplo, B.LD, B.ipiv, R)

stdlib/LinearAlgebra/src/cholesky.jl

@@ -136,19 +136,15 @@ end
 # cholesky!. Destructive methods for computing Cholesky factorization of real symmetric
 # or Hermitian matrix
 ## No pivoting (default)
-function cholesky!(A::RealHermSymComplexHerm, ::Val{false}=Val(false))
-    if A.uplo == 'U'
-        CU, info = _chol!(A.data, UpperTriangular)
-        Cholesky(CU.data, 'U', info)
-    else
-        CL, info = _chol!(A.data, LowerTriangular)
-        Cholesky(CL.data, 'L', info)
-    end
+function cholesky!(A::RealHermSymComplexHerm, ::Val{false}=Val(false); check::Bool = true)
+    C, info = _chol!(A.data, A.uplo == 'U' ? UpperTriangular : LowerTriangular)
+    check && checkpositivedefinite(info)
+    return Cholesky(C.data, A.uplo, info)
 end
 
 ### for StridedMatrices, check that matrix is symmetric/Hermitian
 """
-    cholesky!(A, Val(false)) -> Cholesky
+    cholesky!(A, Val(false); check = true) -> Cholesky
 
 The same as [`cholesky`](@ref), but saves space by overwriting the input `A`,
 instead of creating a copy. An [`InexactError`](@ref) exception is thrown if
@@ -168,53 +164,58 @@ Stacktrace:
 [...]
 ```
 """
-function cholesky!(A::StridedMatrix, ::Val{false}=Val(false))
+function cholesky!(A::StridedMatrix, ::Val{false}=Val(false); check::Bool = true)
     checksquare(A)
     if !ishermitian(A) # return with info = -1 if not Hermitian
+        check && checkpositivedefinite(-1)
         return Cholesky(A, 'U', convert(BlasInt, -1))
     else
-        return cholesky!(Hermitian(A), Val(false))
+        return cholesky!(Hermitian(A), Val(false); check = check)
     end
 end
 
 
 ## With pivoting
 ### BLAS/LAPACK element types
 function cholesky!(A::RealHermSymComplexHerm{<:BlasReal,<:StridedMatrix},
-                   ::Val{true}; tol = 0.0)
+                   ::Val{true}; tol = 0.0, check::Bool = true)
     AA, piv, rank, info = LAPACK.pstrf!(A.uplo, A.data, tol)
-    return CholeskyPivoted{eltype(AA),typeof(AA)}(AA, A.uplo, piv, rank, tol, info)
+    C = CholeskyPivoted{eltype(AA),typeof(AA)}(AA, A.uplo, piv, rank, tol, info)
+    check && chkfullrank(C)
+    return C
 end
 
 ### Non BLAS/LAPACK element types (generic). Since generic fallback for pivoted Cholesky
 ### is not implemented yet we throw an error
-cholesky!(A::RealHermSymComplexHerm{<:Real}, ::Val{true}; tol = 0.0) =
+cholesky!(A::RealHermSymComplexHerm{<:Real}, ::Val{true}; tol = 0.0, check::Bool = true) =
     throw(ArgumentError("generic pivoted Cholesky factorization is not implemented yet"))
 
 ### for StridedMatrices, check that matrix is symmetric/Hermitian
 """
-    cholesky!(A, Val(true); tol = 0.0) -> CholeskyPivoted
+    cholesky!(A, Val(true); tol = 0.0, check = true) -> CholeskyPivoted
 
 The same as [`cholesky`](@ref), but saves space by overwriting the input `A`,
 instead of creating a copy. An [`InexactError`](@ref) exception is thrown if the
 factorization produces a number not representable by the element type of `A`,
 e.g. for integer types.
 """
-function cholesky!(A::StridedMatrix, ::Val{true}; tol = 0.0)
+function cholesky!(A::StridedMatrix, ::Val{true}; tol = 0.0, check::Bool = true)
     checksquare(A)
-    if !ishermitian(A) # return with info = -1 if not Hermitian
-        return CholeskyPivoted(A, 'U', Vector{BlasInt}(),convert(BlasInt, 1),
-                               tol, convert(BlasInt, -1))
+    if !ishermitian(A)
+        C = CholeskyPivoted(A, 'U', Vector{BlasInt}(),convert(BlasInt, 1),
+                            tol, convert(BlasInt, -1))
+        check && chkfullrank(C)
+        return C
     else
-        return cholesky!(Hermitian(A), Val(true); tol = tol)
+        return cholesky!(Hermitian(A), Val(true); tol = tol, check = check)
     end
 end
 
 # cholesky. Non-destructive methods for computing Cholesky factorization of real symmetric
 # or Hermitian matrix
 ## No pivoting (default)
 """
-    cholesky(A, Val(false)) -> Cholesky
+    cholesky(A, Val(false); check = true) -> Cholesky
 
 Compute the Cholesky factorization of a dense symmetric positive definite matrix `A`
 and return a `Cholesky` factorization. The matrix `A` can either be a [`Symmetric`](@ref) or [`Hermitian`](@ref)
@@ -223,6 +224,10 @@ The triangular Cholesky factor can be obtained from the factorization `F` with:
 The following functions are available for `Cholesky` objects: [`size`](@ref), [`\\`](@ref),
 [`inv`](@ref), [`det`](@ref), [`logdet`](@ref) and [`isposdef`](@ref).
 
+When `check = true`, an error is thrown if the decomposition fails.
+When `check = false`, responsibility for checking the decomposition's
+validity (via [`issuccess`](@ref)) lies with the user.
+
 # Examples
 ```jldoctest
 julia> A = [4. 12. -16.; 12. 37. -43.; -16. -43. 98.]
@@ -256,12 +261,12 @@ true
 ```
 """
 cholesky(A::Union{StridedMatrix,RealHermSymComplexHerm{<:Real,<:StridedMatrix}},
-    ::Val{false}=Val(false)) = cholesky!(cholcopy(A))
+    ::Val{false}=Val(false); check::Bool = true) = cholesky!(cholcopy(A); check = check)
 
 
 ## With pivoting
 """
-    cholesky(A, Val(true); tol = 0.0) -> CholeskyPivoted
+    cholesky(A, Val(true); tol = 0.0, check = true) -> CholeskyPivoted
 
 Compute the pivoted Cholesky factorization of a dense symmetric positive semi-definite matrix `A`
 and return a `CholeskyPivoted` factorization. The matrix `A` can either be a [`Symmetric`](@ref)
@@ -271,9 +276,14 @@ The following functions are available for `PivotedCholesky` objects:
 [`size`](@ref), [`\\`](@ref), [`inv`](@ref), [`det`](@ref), and [`rank`](@ref).
 The argument `tol` determines the tolerance for determining the rank.
 For negative values, the tolerance is the machine precision.
+
+When `check = true`, an error is thrown if the decomposition fails.
+When `check = false`, responsibility for checking the decomposition's
+validity (via [`issuccess`](@ref)) lies with the user.
 """
 cholesky(A::Union{StridedMatrix,RealHermSymComplexHerm{<:Real,<:StridedMatrix}},
-    ::Val{true}; tol = 0.0) = cholesky!(cholcopy(A), Val(true); tol = tol)
+    ::Val{true}; tol = 0.0, check::Bool = true) =
+    cholesky!(cholcopy(A), Val(true); tol = tol, check = check)
 
 ## Number
 function cholesky(x::Number, uplo::Symbol=:U)
@@ -319,11 +329,11 @@ function getproperty(C::Cholesky, d::Symbol)
     Cuplo    = getfield(C, :uplo)
     info     = getfield(C, :info)
     if d == :U
-        return @assertposdef UpperTriangular(Symbol(Cuplo) == d ? Cfactors : copy(Cfactors')) info
+        return UpperTriangular(Symbol(Cuplo) == d ? Cfactors : copy(Cfactors'))
     elseif d == :L
-        return @assertposdef LowerTriangular(Symbol(Cuplo) == d ? Cfactors : copy(Cfactors')) info
+        return LowerTriangular(Symbol(Cuplo) == d ? Cfactors : copy(Cfactors'))
     elseif d == :UL
-        return @assertposdef (Symbol(Cuplo) == :U ? UpperTriangular(Cfactors) : LowerTriangular(Cfactors)) info
+        return (Symbol(Cuplo) == :U ? UpperTriangular(Cfactors) : LowerTriangular(Cfactors))
     else
         return getfield(C, d)
     end
@@ -335,16 +345,12 @@ function getproperty(C::CholeskyPivoted{T}, d::Symbol) where T<:BlasFloat
     Cfactors = getfield(C, :factors)
     Cuplo    = getfield(C, :uplo)
     if d == :U
-        chkfullrank(C)
         return UpperTriangular(Symbol(Cuplo) == d ? Cfactors : copy(Cfactors'))
     elseif d == :L
-        chkfullrank(C)
         return LowerTriangular(Symbol(Cuplo) == d ? Cfactors : copy(Cfactors'))
     elseif d == :p
-        chkfullrank(C)
         return getfield(C, :piv)
     elseif d == :P
-        chkfullrank(C)
         n = size(C, 1)
         P = zeros(T, n, n)
         for i = 1:n
@@ -379,7 +385,7 @@ function show(io::IO, mime::MIME{Symbol("text/plain")}, C::CholeskyPivoted{<:Any
 end
 
 ldiv!(C::Cholesky{T,<:AbstractMatrix}, B::StridedVecOrMat{T}) where {T<:BlasFloat} =
-    @assertposdef LAPACK.potrs!(C.uplo, C.factors, B) C.info
+    LAPACK.potrs!(C.uplo, C.factors, B)
 
 function ldiv!(C::Cholesky{<:Any,<:AbstractMatrix}, B::StridedVecOrMat)
     if C.uplo == 'L'
@@ -390,11 +396,9 @@ function ldiv!(C::Cholesky{<:Any,<:AbstractMatrix}, B::StridedVecOrMat)
 end
 
 function ldiv!(C::CholeskyPivoted{T}, B::StridedVector{T}) where T<:BlasFloat
-    chkfullrank(C)
     invpermute!(LAPACK.potrs!(C.uplo, C.factors, permute!(B, C.piv)), C.piv)
 end
 function ldiv!(C::CholeskyPivoted{T}, B::StridedMatrix{T}) where T<:BlasFloat
-    chkfullrank(C)
     n = size(C, 1)
     for i=1:size(B, 2)
         permute!(view(B, 1:n, i), C.piv)
@@ -429,7 +433,6 @@ end
 isposdef(C::Union{Cholesky,CholeskyPivoted}) = C.info == 0
 
 function det(C::Cholesky)
-    isposdef(C) || throw(PosDefException(C.info))
     dd = one(real(eltype(C)))
     @inbounds for i in 1:size(C.factors,1)
         dd *= real(C.factors[i,i])^2
@@ -438,8 +441,6 @@ function det(C::Cholesky)
 end
 
 function logdet(C::Cholesky)
-    # need to check first, or log will throw DomainError
-    isposdef(C) || throw(PosDefException(C.info))
     dd = zero(real(eltype(C)))
     @inbounds for i in 1:size(C.factors,1)
         dd += log(real(C.factors[i,i]))
@@ -472,12 +473,11 @@ function logdet(C::CholeskyPivoted)
 end
 
 inv!(C::Cholesky{<:BlasFloat,<:StridedMatrix}) =
-    @assertposdef copytri!(LAPACK.potri!(C.uplo, C.factors), C.uplo, true) C.info
+    copytri!(LAPACK.potri!(C.uplo, C.factors), C.uplo, true)
 
 inv(C::Cholesky{<:BlasFloat,<:StridedMatrix}) = inv!(copy(C))
 
 function inv(C::CholeskyPivoted)
-    chkfullrank(C)
     ipiv = invperm(C.piv)
     copytri!(LAPACK.potri!(C.uplo, copy(C.factors)), C.uplo, true)[ipiv, ipiv]
 end

stdlib/LinearAlgebra/src/dense.jl

@@ -89,7 +89,8 @@ julia> A
  2.0  6.78233
 ```
 """
-isposdef!(A::AbstractMatrix) = ishermitian(A) && isposdef(cholesky!(Hermitian(A)))
+isposdef!(A::AbstractMatrix) =
+    ishermitian(A) && isposdef(cholesky!(Hermitian(A); check = false))
 
 """
     isposdef(A) -> Bool
@@ -109,7 +110,8 @@ julia> isposdef(A)
 true
 ```
 """
-isposdef(A::AbstractMatrix) = ishermitian(A) && isposdef(cholesky(Hermitian(A)))
+isposdef(A::AbstractMatrix) =
+    ishermitian(A) && isposdef(cholesky(Hermitian(A); check = false))
 isposdef(x::Number) = imag(x)==0 && real(x) > 0
 
 # the definition of strides for Array{T,N} is tuple() if N = 0, otherwise it is
@@ -1208,7 +1210,7 @@ function factorize(A::StridedMatrix{T}) where T
             return UpperTriangular(A)
         end
         if herm
-            cf = cholesky(A)
+            cf = cholesky(A; check = false)
             if cf.info == 0
                 return cf
             else

stdlib/LinearAlgebra/src/factorization.jl

@@ -8,13 +8,8 @@ eltype(::Type{<:Factorization{T}}) where {T} = T
 size(F::Adjoint{<:Any,<:Factorization}) = reverse(size(parent(F)))
 size(F::Transpose{<:Any,<:Factorization}) = reverse(size(parent(F)))
 
-macro assertposdef(A, info)
-   :($(esc(info)) == 0 ? $(esc(A)) : throw(PosDefException($(esc(info)))))
-end
-
-macro assertnonsingular(A, info)
-   :($(esc(info)) == 0 ? $(esc(A)) : throw(SingularException($(esc(info)))))
-end
+checkpositivedefinite(info) = info == 0 || throw(PosDefException(info))
+checknonsingular(info) = info == 0 || throw(SingularException(info))
 
 """
     issuccess(F::Factorization)
@@ -27,7 +22,7 @@ julia> F = cholesky([1 0; 0 1]);
 julia> LinearAlgebra.issuccess(F)
 true
 
-julia> F = lu([1 0; 0 0]);
+julia> F = lu([1 0; 0 0]; check = false);
 
 julia> LinearAlgebra.issuccess(F)
 false
@@ -101,4 +96,4 @@ end
 
 # fallback methods for transposed solves
 \(F::Transpose{<:Any,<:Factorization{<:Real}}, B::AbstractVecOrMat) = adjoint(F.parent) \ B
-\(F::Transpose{<:Any,<:Factorization}, B::AbstractVecOrMat) = conj.(adjoint(F.parent) \ conj.(B))
+\(F::Transpose{<:Any,<:Factorization}, B::AbstractVecOrMat) = conj.(adjoint(F.parent) \ conj.(B))