Deprecate bkfact to bk.

NEWS.md

@@ -690,8 +690,9 @@ Deprecated or removed
   * The keyword `immutable` is fully deprecated to `struct`, and
     `type` is fully deprecated to `mutable struct` ([#19157], [#20418]).
 
-  * `lufact`, `eigfact`, `schurfact`, `lqfact`, and `qrfact` have respectively
-    been deprecated to `lu`, `eig`, `schur`, `lq`, and `qr` ([#27159]).
+  * `lufact`, `eigfact`, `schurfact`, `lqfact`, `qrfact`, and `bkfact` have
+    respectively been deprecated to `lu`, `eig`, `schur`, `lq`, `qr`, and `bk`
+    ([#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.

stdlib/LinearAlgebra/docs/src/index.md

@@ -329,7 +329,7 @@ LinearAlgebra.QRCompactWY
 LinearAlgebra.QRPivoted
 LinearAlgebra.lqfact!
 LinearAlgebra.lq
-LinearAlgebra.bkfact
+LinearAlgebra.bk
 LinearAlgebra.bkfact!
 LinearAlgebra.eig
 LinearAlgebra.eigvals

stdlib/LinearAlgebra/src/LinearAlgebra.jl

@@ -63,6 +63,7 @@ export
 # Functions
     axpy!,
     axpby!,
+    bk,
     bkfact,
     bkfact!,
     chol,

stdlib/LinearAlgebra/src/bunchkaufman.jl

@@ -16,10 +16,17 @@ BunchKaufman(A::AbstractMatrix{T}, ipiv::Vector{BlasInt}, uplo::AbstractChar, sy
              rook::Bool, info::BlasInt) where {T} =
         BunchKaufman{T,typeof(A)}(A, ipiv, uplo, symmetric, rook, info)
 
+# iteration for destructuring into components
+Base.iterate(S::BunchKaufman) = (S.D, Val(:UL))
+Base.iterate(S::BunchKaufman, ::Val{:UL}) = (S.uplo == 'L' ? S.L : S.U, Val(:p))
+Base.iterate(S::BunchKaufman, ::Val{:p}) = (S.p, Val(:done))
+Base.iterate(S::BunchKaufman, ::Val{:done}) = nothing
+
+
 """
     bkfact!(A, rook::Bool=false) -> BunchKaufman
 
-`bkfact!` is the same as [`bkfact`](@ref), but saves space by overwriting the
+`bkfact!` is the same as [`bk`](@ref), but saves space by overwriting the
 input `A`, instead of creating a copy.
 """
 function bkfact!(A::RealHermSymComplexSym{T,S} where {T<:BlasReal,S<:StridedMatrix}, rook::Bool = false)
@@ -41,15 +48,27 @@ function bkfact!(A::StridedMatrix{<:BlasFloat}, rook::Bool = false)
 end
 
 """
-    bkfact(A, rook::Bool=false) -> BunchKaufman
+    bk(A, rook::Bool=false) -> 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
+which triangle is stored in `A`, and return a `BunchKaufman` object.
+Note that if `A` is complex symmetric then `U'` and `L'` denote
+the unconjugated transposes, i.e. `transpose(U)` and `transpose(L)`.
 
-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 which triangle is stored in `A`, and return a `BunchKaufman` object. Note that if `A` is complex symmetric then `U'` and `L'` denote the unconjugated transposes, i.e. `transpose(U)` and `transpose(L)`.
+Iterating the decomposition produces the components `S.D`, `S.U` or `S.L`
+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.
+If `rook` is `true`, rook pivoting is used. If `rook` is false,
+rook pivoting is not used.
 
-The following functions are available for `BunchKaufman` objects: [`size`](@ref), `\\`, [`inv`](@ref), [`issymmetric`](@ref), [`ishermitian`](@ref), [`getindex`](@ref).
+The following functions are available for `BunchKaufman` objects:
+[`size`](@ref), `\\`, [`inv`](@ref), [`issymmetric`](@ref),
+[`ishermitian`](@ref), [`getindex`](@ref).
 
-[^Bunch1977]: J R Bunch and L Kaufman, Some stable methods for calculating inertia and solving symmetric linear systems, Mathematics of Computation 31:137 (1977), 163-179. [url](http://www.ams.org/journals/mcom/1977-31-137/S0025-5718-1977-0428694-0/).
+[^Bunch1977]: J R Bunch and L Kaufman, Some stable methods for calculating inertia
+and solving symmetric linear systems, Mathematics of Computation 31:137 (1977), 163-179.
+[url](http://www.ams.org/journals/mcom/1977-31-137/S0025-5718-1977-0428694-0/).
 
 # Examples
 ```jldoctest
@@ -58,7 +77,7 @@ julia> A = [1 2; 2 3]
  1  2
  2  3
 
-julia> bkfact(A)
+julia> S = bk(A)
 BunchKaufman{Float64,Array{Float64,2}}
 D factor:
 2×2 Tridiagonal{Float64,Array{Float64,1}}:
@@ -72,9 +91,14 @@ permutation:
 2-element Array{Int64,1}:
  1
  2
+
+julia> d, u, p = S; # destructuring via iteration
+
+julia> d == S.D && u == S.U && p == S.p
+true
 ```
 """
-bkfact(A::AbstractMatrix{T}, rook::Bool=false) where {T} =
+bk(A::AbstractMatrix{T}, rook::Bool=false) where {T} =
     bkfact!(copy_oftype(A, typeof(sqrt(one(T)))), rook)
 
 convert(::Type{BunchKaufman{T}}, B::BunchKaufman{T}) where {T} = B
@@ -134,7 +158,7 @@ julia> A = [1 2 3; 2 1 2; 3 2 1]
  2  1  2
  3  2  1
 
-julia> F = bkfact(Symmetric(A, :L))
+julia> F = bk(Symmetric(A, :L))
 BunchKaufman{Float64,Array{Float64,2}}
 D factor:
 3×3 Tridiagonal{Float64,Array{Float64,1}}:
@@ -158,7 +182,7 @@ julia> F.L*F.D*F.L' - A[F.p, F.p]
  0.0  0.0  0.0
  0.0  0.0  0.0
 
-julia> F = bkfact(Symmetric(A));
+julia> F = bk(Symmetric(A));
 
 julia> F.U*F.D*F.U' - F.P*A*F.P'
 3×3 Array{Float64,2}:

stdlib/LinearAlgebra/src/dense.jl

@@ -1113,7 +1113,7 @@ systems. For example: `A=factorize(A); x=A\\b; y=A\\C`.
 | Properties of `A`          | type of factorization                          |
 |:---------------------------|:-----------------------------------------------|
 | Positive-definite          | Cholesky (see [`cholfact`](@ref))  |
-| Dense Symmetric/Hermitian  | Bunch-Kaufman (see [`bkfact`](@ref)) |
+| Dense Symmetric/Hermitian  | Bunch-Kaufman (see [`bk`](@ref)) |
 | Sparse Symmetric/Hermitian | LDLt (see [`ldltfact`](@ref))      |
 | Triangular                 | Triangular                                     |
 | Diagonal                   | Diagonal                                       |

stdlib/LinearAlgebra/src/deprecated.jl

@@ -19,7 +19,8 @@ using Base: @deprecate, depwarn
 @deprecate isposdef!(A::StridedMatrix, UL::Symbol) isposdef!(Hermitian(A, UL))
 
 # bkfact
-import .LinearAlgebra: bkfact, bkfact!
+export bkfact
+import .LinearAlgebra: bkfact!
 function bkfact(A::StridedMatrix, uplo::Symbol, symmetric::Bool = issymmetric(A), rook::Bool = false)
     depwarn(string("`bkfact` with uplo and symmetric arguments is deprecated, ",
         "use `bkfact($(symmetric ? "Symmetric(" : "Hermitian(")A, :$uplo))` instead."),
@@ -1307,3 +1308,7 @@ export qrfact
 @deprecate(qrfact(v::AbstractVector), qr(v))
 @deprecate(qrfact(A::AbstractMatrix{T}) where T, qr(A))
 @deprecate(qrfact(A::AbstractMatrix{T}, arg) where T, qr(A, arg))
+
+# deprecate bkfact to bk
+# bkfact exported in a deprecation above
+@deprecate(bkfact(A::AbstractMatrix{T}, rook::Bool=false) where {T}, bk(A, rook))

stdlib/LinearAlgebra/src/symmetric.jl

@@ -440,7 +440,7 @@ end
 function factorize(A::HermOrSym{T}) where T
     TT = typeof(sqrt(one(T)))
     if TT <: BlasFloat
-        return bkfact(A)
+        return bk(A)
     else # fallback
         return lu(A)
     end

stdlib/LinearAlgebra/test/bunchkaufman.jl

@@ -38,7 +38,7 @@ bimg  = randn(n,2)/2
         @test isa(factorize(asym), LinearAlgebra.BunchKaufman)
         @test isa(factorize(aher), LinearAlgebra.BunchKaufman)
         @testset "$uplo Bunch-Kaufman factor of indefinite matrix" for uplo in (:L, :U)
-            bc1 = bkfact(Hermitian(aher, uplo))
+            bc1 = bk(Hermitian(aher, uplo))
             @test LinearAlgebra.issuccess(bc1)
             @test logabsdet(bc1)[1] ≈ log(abs(det(bc1)))
             if eltya <: Real
@@ -48,7 +48,7 @@ bimg  = randn(n,2)/2
             end
             @test inv(bc1)*aher ≈ Matrix(I, n, n)
             @testset for rook in (false, true)
-                @test inv(bkfact(Symmetric(transpose(a) + a, uplo), rook))*(transpose(a) + a) ≈ Matrix(I, n, n)
+                @test inv(bk(Symmetric(transpose(a) + a, uplo), rook))*(transpose(a) + a) ≈ Matrix(I, n, n)
                 if eltya <: BlasFloat
                     # test also bkfact! without explicit type tag
                     # no bkfact! method for Int ... yet
@@ -58,15 +58,15 @@ bimg  = randn(n,2)/2
                 @test size(bc1, 1) == size(bc1.LD, 1)
                 @test size(bc1, 2) == size(bc1.LD, 2)
                 if eltya <: BlasReal
-                    @test_throws ArgumentError bkfact(a)
+                    @test_throws ArgumentError bk(a)
                 end
                 # Test extraction of factors
                 if eltya <: Real
                     @test getproperty(bc1, uplo)*bc1.D*getproperty(bc1, uplo)' ≈ aher[bc1.p, bc1.p]
                     @test getproperty(bc1, uplo)*bc1.D*getproperty(bc1, uplo)' ≈ bc1.P*aher*bc1.P'
                 end
 
-                bc1 = bkfact(Symmetric(asym, uplo))
+                bc1 = bk(Symmetric(asym, uplo))
                 @test getproperty(bc1, uplo)*bc1.D*transpose(getproperty(bc1, uplo)) ≈ asym[bc1.p, bc1.p]
                 @test getproperty(bc1, uplo)*bc1.D*transpose(getproperty(bc1, uplo)) ≈ bc1.P*asym*transpose(bc1.P)
                 @test_throws ErrorException bc1.Z
@@ -81,13 +81,13 @@ bimg  = randn(n,2)/2
                 ε = max(εa,εb)
 
                 @testset "$uplo Bunch-Kaufman factor of indefinite matrix" for uplo in (:L, :U)
-                    bc1 = bkfact(Hermitian(aher, uplo))
+                    bc1 = bk(Hermitian(aher, uplo))
                     @test aher*(bc1\b) ≈ b atol=1000ε
                 end
 
                 @testset "$uplo Bunch-Kaufman factors of a pos-def matrix" for uplo in (:U, :L)
                     @testset "rook pivoting: $rook" for rook in (false, true)
-                        bc2 = bkfact(Hermitian(apd, uplo), rook)
+                        bc2 = bk(Hermitian(apd, uplo), rook)
                         @test LinearAlgebra.issuccess(bc2)
                         bks = split(sprint(show, "text/plain", bc2), "\n")
                         @test bks[1] == summary(bc2)
@@ -114,7 +114,7 @@ bimg  = randn(n,2)/2
                 for As in (As, view(As, 1:n, 1:n))
                     @testset "$uplo Bunch-Kaufman factors of a singular matrix" for uplo in (:L, :U)
                         @testset for rook in (false, true)
-                            F = bkfact(issymmetric(As) ? Symmetric(As, uplo) : Hermitian(As, uplo), rook)
+                            F = bk(issymmetric(As) ? Symmetric(As, uplo) : Hermitian(As, uplo), rook)
                             @test !LinearAlgebra.issuccess(F)
                             # test printing of this as well!
                             bks = sprint(show, "text/plain", F)
@@ -138,8 +138,8 @@ end
     @test F\v5 == F\v6[1:5]
 end
 
-@test_throws DomainError logdet(bkfact([-1 -1; -1 1]))
-@test logabsdet(bkfact([8 4; 4 2]))[1] == -Inf
-@test isa(bkfact(Symmetric(ones(0,0))), BunchKaufman) # 0x0 matrix
+@test_throws DomainError logdet(bk([-1 -1; -1 1]))
+@test logabsdet(bk([8 4; 4 2]))[1] == -Inf
+@test isa(bk(Symmetric(ones(0,0))), BunchKaufman) # 0x0 matrix
 
 end # module TestBunchKaufman