Deprecate lq(...) in favor of lqfact(...) and factorization destructu…

…ring.

NEWS.md

@@ -1080,6 +1080,15 @@ Deprecated or removed
     either destructured into its components (`U, V, Q, D1, D2, R0 = svdfact(x, y)`)
     or as a `GeneralizedSVD` object (`gsvdf = svdfact(x, y)`) ([#26997]).
 
+  * `lq(A; thin=true)` has been deprecated in favor of `lqfact(A)`.
+     Whereas `lq(A; thin=true)` returns a tuple of arrays, `lqfact` returns
+     an `LQ` object. So for a direct replacement of `lqfact(A; thin=true)`,
+     use `(F = lqfact(A); (F.L, Array(F.Q)))`, and for `lqfact(A; thin=false)`
+     use `(F = lqfact(A); k = size(F.Q.factors, 2); (F.L, lmul!(F.Q, Matrix{eltype(F.Q)}(I, k, k))))`.
+     But going forward, consider using the direct result of `lqfact(A)` instead,
+     either destructured into its components (`L, Q = lqfact(A)`)
+     or as an `LQ` object (`lqf = lqfact(A)`) ([#26997]).
+
   * The timing functions `tic`, `toc`, and `toq` are deprecated in favor of `@time` and `@elapsed`
     ([#17046]).
 

stdlib/LinearAlgebra/docs/src/index.md

@@ -331,7 +331,6 @@ LinearAlgebra.QRCompactWY
 LinearAlgebra.QRPivoted
 LinearAlgebra.lqfact!
 LinearAlgebra.lqfact
-LinearAlgebra.lq
 LinearAlgebra.bkfact
 LinearAlgebra.bkfact!
 LinearAlgebra.eigvals

stdlib/LinearAlgebra/src/LinearAlgebra.jl

@@ -126,7 +126,6 @@ export
     qr,
     qrfact!,
     qrfact,
-    lq,
     lqfact!,
     lqfact,
     rank,

stdlib/LinearAlgebra/src/deprecated.jl

@@ -1418,3 +1418,19 @@ end
 svd(A::BitMatrix) = _simpledepsvd(float(A))
 svd(D::Diagonal{<:Number}) = _simpledepsvd(D)
 svd(A::AbstractTriangular) = _simpledepsvd(copyto!(similar(parent(A)), A))
+
+# deprecate lq(...) in favor of lqfact(...) and factorization destructuring
+export lq
+function lq(A::Union{Number,AbstractMatrix}; full::Bool = false, thin::Union{Bool,Nothing} = nothing)
+    depwarn(string("`lq(A; thin=true)` has been deprecated in favor of `lqfact(A)`. ",
+        "Whereas `lq(A; thin=true)` returns a tuple of arrays, `lqfact` returns ",
+        "an `LQ` object. So for a direct replacement of `lqfact(A; thin=true)`, ",
+        "use `(F = lqfact(A); (F.L, Array(F.Q)))`, and for `lqfact(A; thin=false)` ",
+        "use `(F = lqfact(A); k = size(F.Q.factors, 2); (F.L, lmul!(F.Q, Matrix{eltype(F.Q)}(I, k, k))))`. ",
+        "But going forward, consider using the direct result of `lqfact(A)` instead, ",
+        "either destructured into its components (`L, Q = lqfact(A)`) ",
+        "or as an `LQ` object (`lqf = lqfact(A)`)."), :lq)
+    F = lqfact(A)
+    retQ = !full ? Array(F.Q) : (k = size(F.Q.factors, 2); lmul!(F.Q, Matrix{eltype(F.Q)}(I, k, k)))
+    return F.L, retQ
+end

stdlib/LinearAlgebra/src/lq.jl

@@ -17,6 +17,13 @@ end
 LQ(factors::AbstractMatrix{T}, τ::Vector{T}) where {T} = LQ{T,typeof(factors)}(factors, τ)
 LQPackedQ(factors::AbstractMatrix{T}, τ::Vector{T}) where {T} = LQPackedQ{T,typeof(factors)}(factors, τ)
 
+# iteration for destructuring into factors
+Base.start(::LQ) = Val(:L)
+Base.next(F::LQ, ::Val{:L}) = (F.L, Val(:Q))
+Base.next(F::LQ, ::Val{:Q}) = (F.Q, Val(:done))
+Base.done(F::LQ, ::Val{:done}) = true
+Base.done(F::LQ, ::Any) = false
+
 """
     lqfact!(A) -> LQ
 
@@ -27,39 +34,12 @@ lqfact!(A::StridedMatrix{<:BlasFloat}) = LQ(LAPACK.gelqf!(A)...)
 """
     lqfact(A) -> LQ
 
-Compute the LQ factorization of `A`. See also [`lq`](@ref).
+Perform an LQ factorization of `A` such that `A = L*Q`. The LQ factorization is
+the QR factorization of `transpose(A)`.
 """
 lqfact(A::StridedMatrix{<:BlasFloat})  = lqfact!(copy(A))
 lqfact(x::Number) = lqfact(fill(x,1,1))
 
-"""
-    lq(A; full = false) -> L, Q
-
-Perform an LQ factorization of `A` such that `A = L*Q`. The default (`full = false`)
-computes a factorization with possibly-rectangular `L` and `Q`, commonly the "thin"
-factorization. The LQ factorization is the QR factorization of `transpose(A)`. If the explicit,
-full/square form of `Q` is requested via `full = true`, `L` is not extended with zeros.
-
-!!! note
-    While in QR factorization the "thin" factorization is so named due to yielding
-    either a square or "tall"/"thin" rectangular factor `Q`, in LQ factorization the
-    "thin" factorization somewhat confusingly produces either a square or "short"/"wide"
-    rectangular factor `Q`. "Thin" factorizations more broadly are also
-    referred to as "reduced" factorizatons.
-"""
-function lq(A::Union{Number,AbstractMatrix}; full::Bool = false, thin::Union{Bool,Nothing} = nothing)
-    # DEPRECATION TODO: remove deprecated thin argument and associated logic after 0.7
-    if thin != nothing
-        Base.depwarn(string("the `thin` keyword argument in `lq(A; thin = $(thin))` has ",
-            "been deprecated in favor of `full`, which has the opposite meaning, ",
-            "e.g. `lq(A; full = $(!thin))`."), :lq)
-        full::Bool = !thin
-    end
-    F = lqfact(A)
-    L, Q = F.L, F.Q
-    return L, !full ? Array(Q) : lmul!(Q, Matrix{eltype(Q)}(I, size(Q.factors, 2), size(Q.factors, 2)))
-end
-
 copy(A::LQ) = LQ(copy(A.factors), copy(A.τ))
 
 LQ{T}(A::LQ) where {T} = LQ(convert(AbstractMatrix{T}, A.factors), convert(Vector{T}, A.τ))

stdlib/LinearAlgebra/test/lq.jl

@@ -39,7 +39,7 @@ rectangularQ(Q::LinearAlgebra.LQPackedQ) = convert(Array, Q)
         α = rand(eltya)
         aα = fill(α,1,1)
         @test lqfact(α).L*lqfact(α).Q ≈ lqfact(aα).L*lqfact(aα).Q
-        @test lq(α)[1]*lq(α)[2] ≈ lqfact(aα).L*lqfact(aα).Q
+        @test ((αL, αQ) = lqfact(α); αL*αQ ≈ lqfact(aα).L*lqfact(aα).Q)
         @test abs(lqfact(α).Q[1,1]) ≈ one(eltya)
         tab = promote_type(eltya,eltyb)
 
@@ -105,43 +105,6 @@ rectangularQ(Q::LinearAlgebra.LQPackedQ) = convert(Array, Q)
     end
 end
 
-@testset "correct form of Q from lq(...) (#23729)" begin
-    # where the original matrix (say A) is square or has more rows than columns,
-    # then A's factorization's triangular factor (say L) should have the same shape
-    # as A independent of factorization form ("full", "reduced"/"thin"), and A's factorization's
-    # orthogonal factor (say Q) should be a square matrix of order of A's number of
-    # columns independent of factorization form ("full", "reduced"/"thin"), and L and Q
-    # should have multiplication-compatible shapes.
-    local m, n = 4, 2
-    A = randn(m, n)
-    for full in (false, true)
-        L, Q = lq(A, full = full)
-        @test size(L) == (m, n)
-        @test size(Q) == (n, n)
-        @test isapprox(A, L*Q)
-    end
-    # where the original matrix has strictly fewer rows than columns ...
-    m, n = 2, 4
-    A = randn(m, n)
-    # ... then, for a rectangular/"thin" factorization of A, L should be a square matrix
-    # of order of A's number of rows, Q should have the same shape as A,
-    # and L and Q should have multiplication-compatible shapes
-    Lrect, Qrect = lq(A, full = false)
-    @test size(Lrect) == (m, m)
-    @test size(Qrect) == (m, n)
-    @test isapprox(A, Lrect * Qrect)
-    # ... and, for a full factorization of A, L should have the
-    # same shape as A, Q should be a square matrix of order of A's number of columns,
-    # and L and Q should have multiplication-compatible shape. but instead the L returned
-    # has no zero-padding on the right / is L for the rectangular/"thin" factorization,
-    # so for L and Q to have multiplication-compatible shapes, L must be zero-padded
-    # to have the shape of A.
-    Lfull, Qfull = lq(A, full = true)
-    @test size(Lfull) == (m, m)
-    @test size(Qfull) == (n, n)
-    @test isapprox(A, [Lfull zeros(m, n - m)] * Qfull)
-end
-
 @testset "getindex on LQPackedQ (#23733)" begin
     local m, n
     function getqs(F::LinearAlgebra.LQ)