Deprecate lufact to lu.

NEWS.md

@@ -227,6 +227,9 @@ This section lists changes that do not have deprecation warnings.
   * `readuntil` now does *not* include the delimiter in its result, matching the
     behavior of `readline`. Pass `keep=true` to get the old behavior ([#25633]).
 
+  * `lu` methods now return decomposition objects such as `LU` rather than
+    tuples of arrays or tuples of numbers ([#27159]).
+
   * `countlines` now always counts the last non-empty line even if it does not
     end with EOL, matching the behavior of `eachline` and `readlines` ([#25845]).
 
@@ -675,6 +678,8 @@ Deprecated or removed
   * The keyword `immutable` is fully deprecated to `struct`, and
     `type` is fully deprecated to `mutable struct` ([#19157], [#20418]).
 
+  * `lufact` has been deprecated to `lu` ([#27159]).
+
   * Indexing into multidimensional arrays with more than one index but fewer indices than there are
     dimensions is no longer permitted when those trailing dimensions have lengths greater than 1.
     Instead, reshape the array or add trailing indices so the dimensionality and number of indices

stdlib/LinearAlgebra/docs/src/index.md

@@ -312,7 +312,6 @@ LinearAlgebra.LowerTriangular
 LinearAlgebra.UpperTriangular
 LinearAlgebra.UniformScaling
 LinearAlgebra.lu
-LinearAlgebra.lufact
 LinearAlgebra.lufact!
 LinearAlgebra.chol
 LinearAlgebra.cholfact

stdlib/LinearAlgebra/src/LinearAlgebra.jl

@@ -112,7 +112,6 @@ export
     lowrankupdate,
     lowrankupdate!,
     lu,
-    lufact,
     lufact!,
     lyap,
     mul!,

stdlib/LinearAlgebra/src/dense.jl

@@ -721,7 +721,7 @@ function inv(A::StridedMatrix{T}) where T
     elseif istril(AA)
         Ai = tril!(parent(inv(LowerTriangular(AA))))
     else
-        Ai = inv!(lufact(AA))
+        Ai = inv!(lu(AA))
         Ai = convert(typeof(parent(Ai)), Ai)
     end
     return Ai
@@ -1118,9 +1118,9 @@ systems. For example: `A=factorize(A); x=A\\b; y=A\\C`.
 | Triangular                 | Triangular                                     |
 | Diagonal                   | Diagonal                                       |
 | Bidiagonal                 | Bidiagonal                                     |
-| Tridiagonal                | LU (see [`lufact`](@ref))            |
+| Tridiagonal                | LU (see [`lu`](@ref))            |
 | Symmetric real tridiagonal | LDLt (see [`ldltfact`](@ref))      |
-| General square             | LU (see [`lufact`](@ref))            |
+| General square             | LU (see [`lu`](@ref))            |
 | General non-square         | QR (see [`qrfact`](@ref))            |
 
 If `factorize` is called on a Hermitian positive-definite matrix, for instance, then `factorize`
@@ -1201,7 +1201,7 @@ function factorize(A::StridedMatrix{T}) where T
                         return ldltfact!(SymTridiagonal(diag(A), diag(A, -1)))
                     end
                 end
-                return lufact(Tridiagonal(diag(A, -1), diag(A), diag(A, 1)))
+                return lu(Tridiagonal(diag(A, -1), diag(A), diag(A, 1)))
             end
         end
         if utri
@@ -1218,7 +1218,7 @@ function factorize(A::StridedMatrix{T}) where T
         if sym
             return factorize(Symmetric(A))
         end
-        return lufact(A)
+        return lu(A)
     end
     qrfact(A, Val(true))
 end
@@ -1367,7 +1367,7 @@ function cond(A::AbstractMatrix, p::Real=2)
     end
     throw(ArgumentError("p-norm must be 1, 2 or Inf, got $p"))
 end
-_cond1Inf(A::StridedMatrix{<:BlasFloat}, p::Real) = _cond1Inf(lufact(A), p, norm(A, p))
+_cond1Inf(A::StridedMatrix{<:BlasFloat}, p::Real) = _cond1Inf(lu(A), p, norm(A, p))
 _cond1Inf(A::AbstractMatrix, p::Real)             = norm(A, p)*norm(inv(A), p)
 
 ## Lyapunov and Sylvester equation

stdlib/LinearAlgebra/src/deprecated.jl

@@ -1260,3 +1260,10 @@ end
 @deprecate scale!(C::AbstractMatrix, a::AbstractVector, B::AbstractMatrix) mul!(C, Diagonal(a), B)
 
 Base.@deprecate_binding trace tr
+
+# deprecate lufact to lu
+@deprecate(lufact(S::LU), lu(S))
+@deprecate(lufact(x::Number), lu(x))
+@deprecate(lufact(A::AbstractMatrix{T}) where T, lu(A))
+@deprecate(lufact(A::AbstractMatrix{T}, pivot::Union{Val{false}, Val{true}}) where T, lu(A, pivot))
+@deprecate(lufact(A::Union{AbstractMatrix{T}, AbstractMatrix{Complex{T}}}, pivot::Union{Val{false}, Val{true}} = Val(true)) where {T<:AbstractFloat}, lu(A, pivot))

stdlib/LinearAlgebra/src/factorization.jl

@@ -27,7 +27,7 @@ julia> F = cholfact([1 0; 0 1]);
 julia> LinearAlgebra.issuccess(F)
 true
 
-julia> F = lufact([1 0; 0 0]);
+julia> F = lu([1 0; 0 0]);
 
 julia> LinearAlgebra.issuccess(F)
 false

stdlib/LinearAlgebra/src/generic.jl

@@ -862,7 +862,7 @@ function (\)(A::AbstractMatrix, B::AbstractVecOrMat)
         if istriu(A)
             return UpperTriangular(A) \ B
         end
-        return lufact(A) \ B
+        return lu(A) \ B
     end
     return qrfact(A,Val(true)) \ B
 end
@@ -1270,7 +1270,7 @@ function det(A::AbstractMatrix{T}) where T
         S = typeof((one(T)*zero(T) + zero(T))/one(T))
         return convert(S, det(UpperTriangular(A)))
     end
-    return det(lufact(A))
+    return det(lu(A))
 end
 det(x::Number) = x
 
@@ -1305,7 +1305,7 @@ julia> logabsdet(B)
 (0.6931471805599453, 1.0)
 ```
 """
-logabsdet(A::AbstractMatrix) = logabsdet(lufact(A))
+logabsdet(A::AbstractMatrix) = logabsdet(lu(A))
 
 """
     logdet(M)

stdlib/LinearAlgebra/src/lu.jl

@@ -11,6 +11,20 @@ struct LU{T,S<:AbstractMatrix} <: Factorization{T}
 end
 LU(factors::AbstractMatrix{T}, ipiv::Vector{BlasInt}, info::BlasInt) where {T} = LU{T,typeof(factors)}(factors, ipiv, info)
 
+# iteration for destructuring into components
+Base.iterate(S::LU) = (S.L, Val(:U))
+Base.iterate(S::LU, ::Val{:U}) = (S.U, Val(:p))
+Base.iterate(S::LU, ::Val{:p}) = (S.p, Val(:done))
+Base.iterate(S::LU, ::Val{:done}) = nothing
+
+# indexing for destructuring into components
+@inline function Base.getindex(S::LU, i::Integer)
+    i == 1 ? (return S.L) :
+    i == 2 ? (return S.U) :
+    i == 3 ? (return S.p) :
+        throw(BoundsError)
+end
+
 adjoint(F::LU) = Adjoint(F)
 transpose(F::LU) = Transpose(F)
 
@@ -30,7 +44,7 @@ end
 """
     lufact!(A, pivot=Val(true)) -> LU
 
-`lufact!` is the same as [`lufact`](@ref), but saves space by overwriting the
+`lufact!` is the same as [`lu`](@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.
@@ -114,13 +128,14 @@ function generic_lufact!(A::StridedMatrix{T}, ::Val{Pivot} = Val(true)) where {T
 end
 
 # floating point types doesn't have to be promoted for LU, but should default to pivoting
-lufact(A::Union{AbstractMatrix{T}, AbstractMatrix{Complex{T}}},
-    pivot::Union{Val{false}, Val{true}} = Val(true)) where {T<:AbstractFloat} =
-        lufact!(copy(A), pivot)
+function lu(A::Union{AbstractMatrix{T}, AbstractMatrix{Complex{T}}},
+            pivot::Union{Val{false}, Val{true}} = Val(true)) where {T<:AbstractFloat}
+    lufact!(copy(A), pivot)
+end
 
 # for all other types we must promote to a type which is stable under division
 """
-    lufact(A, pivot=Val(true)) -> F::LU
+    lu(A, pivot=Val(true)) -> F::LU
 
 Compute the LU factorization of `A`.
 
@@ -129,7 +144,7 @@ type `T` supporting `+`, `-`, `*` and `/`, the return type is `LU{T,S{T}}`. If
 pivoting is chosen (default) the element type should also support `abs` and
 `<`.
 
-The individual components of the factorization `F` can be accessed by indexing:
+The individual components of the factorization `F` can be accessed via `getproperty`:
 
 | Component | Description                         |
 |:----------|:------------------------------------|
@@ -138,6 +153,8 @@ The individual components of the factorization `F` can be accessed by indexing:
 | `F.p`     | (right) permutation `Vector`        |
 | `F.P`     | (right) permutation `Matrix`        |
 
+Iterating the factorization produces the components `F.L`, `F.U`, and `F.p`.
+
 The relationship between `F` and `A` is
 
 `F.L*F.U == A[F.p, :]`
@@ -161,7 +178,7 @@ julia> A = [4 3; 6 3]
  4  3
  6  3
 
-julia> F = lufact(A)
+julia> F = lu(A)
 LU{Float64,Array{Float64,2}}
 L factor:
 2×2 Array{Float64,2}:
@@ -174,16 +191,21 @@ U factor:
 
 julia> F.L * F.U == A[F.p, :]
 true
+
+julia> l, u, p = lu(A); # destructuring via iteration
+
+julia> l == F.L && u == F.U && p == F.p
+true
 ```
 """
-function lufact(A::AbstractMatrix{T}, pivot::Union{Val{false}, Val{true}}) where T
+function lu(A::AbstractMatrix{T}, pivot::Union{Val{false}, Val{true}}) where T
     S = typeof(zero(T)/one(T))
     AA = similar(A, S)
     copyto!(AA, A)
     lufact!(AA, pivot)
 end
 # We can't assume an ordered field so we first try without pivoting
-function lufact(A::AbstractMatrix{T}) where T
+function lu(A::AbstractMatrix{T}) where T
     S = typeof(zero(T)/one(T))
     AA = similar(A, S)
     copyto!(AA, A)
@@ -197,38 +219,8 @@ function lufact(A::AbstractMatrix{T}) where T
     end
 end
 
-lufact(x::Number) = LU(fill(x, 1, 1), BlasInt[1], x == 0 ? one(BlasInt) : zero(BlasInt))
-lufact(F::LU) = F
-
-lu(x::Number) = (one(x), x, 1)
-
-"""
-    lu(A, pivot=Val(true)) -> L, U, p
-
-Compute the LU factorization of `A`, such that `A[p,:] = L*U`.
-By default, pivoting is used. This can be overridden by passing
-`Val(false)` for the second argument.
-
-See also [`lufact`](@ref).
-
-# Examples
-```jldoctest
-julia> A = [4. 3.; 6. 3.]
-2×2 Array{Float64,2}:
- 4.0  3.0
- 6.0  3.0
-
-julia> L, U, p = lu(A)
-([1.0 0.0; 0.666667 1.0], [6.0 3.0; 0.0 1.0], [2, 1])
-
-julia> A[p, :] == L * U
-true
-```
-"""
-function lu(A::AbstractMatrix, pivot::Union{Val{false}, Val{true}} = Val(true))
-    F = lufact(A, pivot)
-    F.L, F.U, F.p
-end
+lu(S::LU) = S
+lu(x::Number) = LU(fill(x, 1, 1), BlasInt[1], x == 0 ? one(BlasInt) : zero(BlasInt))
 
 function LU{T}(F::LU) where T
     M = convert(AbstractMatrix{T}, F.factors)
@@ -459,7 +451,7 @@ function lufact!(A::Tridiagonal{T,V}, pivot::Union{Val{false}, Val{true}} = Val(
     LU{T,Tridiagonal{T,V}}(B, ipiv, convert(BlasInt, info))
 end
 
-factorize(A::Tridiagonal) = lufact(A)
+factorize(A::Tridiagonal) = lu(A)
 
 function getproperty(F::LU{T,Tridiagonal{T,V}}, d::Symbol) where {T,V}
     m, n = size(F)

stdlib/LinearAlgebra/src/symmetric.jl

@@ -442,7 +442,7 @@ function factorize(A::HermOrSym{T}) where T
     if TT <: BlasFloat
         return bkfact(A)
     else # fallback
-        return lufact(A)
+        return lu(A)
     end
 end
 
@@ -453,11 +453,11 @@ det(A::Symmetric) = det(factorize(A))
 \(A::HermOrSym{<:Any,<:StridedMatrix}, B::AbstractVector) = \(factorize(A), B)
 # Bunch-Kaufman solves can not utilize BLAS-3 for multiple right hand sides
 # so using LU is faster for AbstractMatrix right hand side
-\(A::HermOrSym{<:Any,<:StridedMatrix}, B::AbstractMatrix) = \(lufact(A), B)
+\(A::HermOrSym{<:Any,<:StridedMatrix}, B::AbstractMatrix) = \(lu(A), B)
 
 function _inv(A::HermOrSym)
     n = checksquare(A)
-    B = inv!(lufact(A))
+    B = inv!(lu(A))
     conjugate = isa(A, Hermitian)
     # symmetrize
     if A.uplo == 'U' # add to upper triangle

stdlib/LinearAlgebra/test/generic.jl

@@ -348,13 +348,13 @@ LinearAlgebra.Transpose(a::ModInt{n}) where {n} = transpose(a)
     A = [ModInt{2}(1) ModInt{2}(0); ModInt{2}(1) ModInt{2}(1)]
     b = [ModInt{2}(1), ModInt{2}(0)]
 
-    @test A*(lufact(A, Val(false))\b) == b
+    @test A*(lu(A, Val(false))\b) == b
 
     # Needed for pivoting:
     Base.abs(a::ModInt{n}) where {n} = a
     Base.:<(a::ModInt{n}, b::ModInt{n}) where {n} = a.k < b.k
 
-    @test A*(lufact(A, Val(true))\b) == b
+    @test A*(lu(A, Val(true))\b) == b
 end
 
 @testset "fallback throws properly for AbstractArrays with dimension > 2" begin

stdlib/LinearAlgebra/test/lapack.jl

@@ -266,7 +266,7 @@ end
         @test_throws DimensionMismatch LAPACK.gttrs!('N', x11, d, du, x9, y10, b)
         @test_throws DimensionMismatch LAPACK.gttrs!('N', dl, d, x11, x9, y10, b)
         @test_throws DimensionMismatch LAPACK.gttrs!('N', dl, d, du, x9, y10, x11)
-        A = lufact(Tridiagonal(dl,d,du))
+        A = lu(Tridiagonal(dl,d,du))
         b  = rand(elty,10,5)
         c = copy(b)
         dl,d,du,du2,ipiv = LAPACK.gttrf!(dl,d,du)