Deprecate eigfact to eig.

Author: Sacha0

NEWS.md

@@ -230,6 +230,9 @@ This section lists changes that do not have deprecation warnings.
   * `lu` methods now return decomposition objects such as `LU` rather than
     tuples of arrays or tuples of numbers ([#27159]).
 
+  * `eig` methods now return decomposition objects such as `Eigen` and
+    `GeneralizedEigen` 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]).
 
@@ -678,7 +681,7 @@ 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]).
+  * `lufact` and `eigfact` have respectively been deprecated to `lu` and `eig` ([#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/IterativeEigensolvers/src/IterativeEigensolvers.jl

@@ -78,7 +78,7 @@ function _eigs(A, B;
     sym = !iscmplx && issymmetric(A) && issymmetric(B)
     nevmax = sym ? n-1 : n-2
     if nevmax <= 0
-        throw(ArgumentError("input matrix A is too small. Use eigfact instead."))
+        throw(ArgumentError("input matrix A is too small. Use eig instead."))
     end
     if nev > nevmax
         @warn "Adjusting nev from $nev to $nevmax"

stdlib/LinearAlgebra/docs/src/index.md

@@ -340,7 +340,6 @@ LinearAlgebra.eigvals!
 LinearAlgebra.eigmax
 LinearAlgebra.eigmin
 LinearAlgebra.eigvecs
-LinearAlgebra.eigfact
 LinearAlgebra.eigfact!
 LinearAlgebra.hessfact
 LinearAlgebra.hessfact!

stdlib/LinearAlgebra/src/LinearAlgebra.jl

@@ -81,7 +81,6 @@ export
     diagm,
     dot,
     eig,
-    eigfact,
     eigfact!,
     eigmax,
     eigmin,

stdlib/LinearAlgebra/src/bidiag.jl

@@ -625,4 +625,4 @@ function eigvecs(M::Bidiagonal{T}) where T
     end
     Q #Actually Triangular
 end
-eigfact(M::Bidiagonal) = Eigen(eigvals(M), eigvecs(M))
+eig(M::Bidiagonal) = Eigen(eigvals(M), eigvecs(M))

stdlib/LinearAlgebra/src/dense.jl

@@ -478,7 +478,7 @@ Compute the matrix exponential of `A`, defined by
 e^A = \\sum_{n=0}^{\\infty} \\frac{A^n}{n!}.
 ```
 
-For symmetric or Hermitian `A`, an eigendecomposition ([`eigfact`](@ref)) is
+For symmetric or Hermitian `A`, an eigendecomposition ([`eig`](@ref)) is
 used, otherwise the scaling and squaring algorithm (see [^H05]) is chosen.
 
 [^H05]: Nicholas J. Higham, "The squaring and scaling method for the matrix exponential revisited", SIAM Journal on Matrix Analysis and Applications, 26(4), 2005, 1179-1193. [doi:10.1137/090768539](https://doi.org/10.1137/090768539)
@@ -602,7 +602,7 @@ the unique matrix ``X`` such that ``e^X = A`` and ``-\\pi < Im(\\lambda) < \\pi`
 the eigenvalues ``\\lambda`` of ``X``. If `A` has nonpositive eigenvalues, a nonprincipal
 matrix function is returned whenever possible.
 
-If `A` is symmetric or Hermitian, its eigendecomposition ([`eigfact`](@ref)) is
+If `A` is symmetric or Hermitian, its eigendecomposition ([`eig`](@ref)) is
 used, if `A` is triangular an improved version of the inverse scaling and squaring method is
 employed (see [^AH12] and [^AHR13]). For general matrices, the complex Schur form
 ([`schur`](@ref)) is computed and the triangular algorithm is used on the
@@ -660,7 +660,7 @@ If `A` has no negative real eigenvalues, compute the principal matrix square roo
 that is the unique matrix ``X`` with eigenvalues having positive real part such that
 ``X^2 = A``. Otherwise, a nonprincipal square root is returned.
 
-If `A` is symmetric or Hermitian, its eigendecomposition ([`eigfact`](@ref)) is
+If `A` is symmetric or Hermitian, its eigendecomposition ([`eig`](@ref)) is
 used to compute the square root. Otherwise, the square root is determined by means of the
 Björck-Hammarling method [^BH83], which computes the complex Schur form ([`schur`](@ref))
 and then the complex square root of the triangular factor.
@@ -732,7 +732,7 @@ end
 
 Compute the matrix cosine of a square matrix `A`.
 
-If `A` is symmetric or Hermitian, its eigendecomposition ([`eigfact`](@ref)) is used to
+If `A` is symmetric or Hermitian, its eigendecomposition ([`eig`](@ref)) is used to
 compute the cosine. Otherwise, the cosine is determined by calling [`exp`](@ref).
 
 # Examples
@@ -765,7 +765,7 @@ end
 
 Compute the matrix sine of a square matrix `A`.
 
-If `A` is symmetric or Hermitian, its eigendecomposition ([`eigfact`](@ref)) is used to
+If `A` is symmetric or Hermitian, its eigendecomposition ([`eig`](@ref)) is used to
 compute the sine. Otherwise, the sine is determined by calling [`exp`](@ref).
 
 # Examples
@@ -851,7 +851,7 @@ end
 
 Compute the matrix tangent of a square matrix `A`.
 
-If `A` is symmetric or Hermitian, its eigendecomposition ([`eigfact`](@ref)) is used to
+If `A` is symmetric or Hermitian, its eigendecomposition ([`eig`](@ref)) is used to
 compute the tangent. Otherwise, the tangent is determined by calling [`exp`](@ref).
 
 # Examples
@@ -924,7 +924,7 @@ end
 
 Compute the inverse matrix cosine of a square matrix `A`.
 
-If `A` is symmetric or Hermitian, its eigendecomposition ([`eigfact`](@ref)) is used to
+If `A` is symmetric or Hermitian, its eigendecomposition ([`eig`](@ref)) is used to
 compute the inverse cosine. Otherwise, the inverse cosine is determined by using
 [`log`](@ref) and [`sqrt`](@ref).  For the theory and logarithmic formulas used to compute
 this function, see [^AH16_1].
@@ -955,7 +955,7 @@ end
 
 Compute the inverse matrix sine of a square matrix `A`.
 
-If `A` is symmetric or Hermitian, its eigendecomposition ([`eigfact`](@ref)) is used to
+If `A` is symmetric or Hermitian, its eigendecomposition ([`eig`](@ref)) is used to
 compute the inverse sine. Otherwise, the inverse sine is determined by using [`log`](@ref)
 and [`sqrt`](@ref).  For the theory and logarithmic formulas used to compute this function,
 see [^AH16_2].
@@ -986,7 +986,7 @@ end
 
 Compute the inverse matrix tangent of a square matrix `A`.
 
-If `A` is symmetric or Hermitian, its eigendecomposition ([`eigfact`](@ref)) is used to
+If `A` is symmetric or Hermitian, its eigendecomposition ([`eig`](@ref)) is used to
 compute the inverse tangent. Otherwise, the inverse tangent is determined by using
 [`log`](@ref).  For the theory and logarithmic formulas used to compute this function, see
 [^AH16_3].

stdlib/LinearAlgebra/src/deprecated.jl

@@ -1267,3 +1267,22 @@ Base.@deprecate_binding trace tr
 @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))
+
+# deprecate eigfact to eig
+@deprecate(eigfact(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) where T, eig(A; permute=permute, scale=scale))
+@deprecate(eigfact(x::Number), eig(x))
+@deprecate(eigfact(A::AbstractMatrix{TA}, B::AbstractMatrix{TB}) where {TA,TB}, eig(A, B))
+@deprecate(eigfact(A::Number, B::Number), eig(A, B))
+
+@deprecate(eigfact(A::SymTridiagonal{T}) where T, eig(A))
+@deprecate(eigfact(A::SymTridiagonal{T}, irange::UnitRange) where T, eig(A, irange))
+@deprecate(eigfact(A::SymTridiagonal{T}, vl::Real, vu::Real) where T, eig(A, vl, vu))
+
+@deprecate(eigfact(M::Bidiagonal), eig(M))
+@deprecate(eigfact(A::RealHermSymComplexHerm), eig(A))
+@deprecate(eigfact(A::RealHermSymComplexHerm, irange::UnitRange), eig(A, irange))
+@deprecate(eigfact(A::RealHermSymComplexHerm, vl::Real, vh::Real), eig(A, vl, vh))
+
+@deprecate(eigfact(A::AbstractTriangular), eig(A))
+
+@deprecate(eigfact(D::Diagonal; permute::Bool=true, scale::Bool=true), eig(D; permute=permute, scale=scale))

stdlib/LinearAlgebra/src/diagonal.jl

@@ -445,7 +445,7 @@ end
 eigvals(D::Diagonal{<:Number}) = D.diag
 eigvals(D::Diagonal) = [eigvals(x) for x in D.diag] #For block matrices, etc.
 eigvecs(D::Diagonal) = Matrix{eltype(D)}(I, size(D))
-function eigfact(D::Diagonal; permute::Bool=true, scale::Bool=true)
+function eig(D::Diagonal; permute::Bool=true, scale::Bool=true)
     if any(!isfinite, D.diag)
         throw(ArgumentError("matrix contains Infs or NaNs"))
     end

stdlib/LinearAlgebra/src/eigen.jl

@@ -20,12 +20,24 @@ end
 GeneralizedEigen(values::AbstractVector{V}, vectors::AbstractMatrix{T}) where {T,V} =
     GeneralizedEigen{T,V,typeof(vectors),typeof(values)}(values, vectors)
 
+# iteration for destructuring into components
+Base.iterate(S::Union{Eigen,GeneralizedEigen}) = (S.values, Val(:vectors))
+Base.iterate(S::Union{Eigen,GeneralizedEigen}, ::Val{:vectors}) = (S.vectors, Val(:done))
+Base.iterate(S::Union{Eigen,GeneralizedEigen}, ::Val{:done}) = nothing
+
+# indexing for destructuring into components
+@inline function Base.getindex(S::Union{Eigen,GeneralizedEigen}, i::Integer)
+    i == 1 ? (return S.values) :
+    i == 2 ? (return S.vectors) :
+        throw(BoundsError(S, i))
+end
+
 isposdef(A::Union{Eigen,GeneralizedEigen}) = isreal(A.values) && all(x -> x > 0, A.values)
 
 """
     eigfact!(A, [B])
 
-Same as [`eigfact`](@ref), but saves space by overwriting the input `A` (and
+Same as [`eig`](@ref), but saves space by overwriting the input `A` (and
 `B`), instead of creating a copy.
 """
 function eigfact!(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) where T<:BlasReal
@@ -59,12 +71,14 @@ function eigfact!(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) whe
 end
 
 """
-    eigfact(A; permute::Bool=true, scale::Bool=true) -> Eigen
+    eig(A; permute::Bool=true, scale::Bool=true) -> Eigen
 
 Computes the eigenvalue decomposition of `A`, returning an `Eigen` factorization object `F`
 which contains the eigenvalues in `F.values` and the eigenvectors in the columns of the
 matrix `F.vectors`. (The `k`th eigenvector can be obtained from the slice `F.vectors[:, k]`.)
 
+Iterating the decomposition produces the components `F.values` and `F.vectors`.
+
 The following functions are available for `Eigen` objects: [`inv`](@ref), [`det`](@ref), and [`isposdef`](@ref).
 
 For general nonsymmetric matrices it is possible to specify how the matrix is balanced
@@ -74,7 +88,7 @@ make rows and columns more equal in norm. The default is `true` for both options
 
 # Examples
 ```jldoctest
-julia> F = eigfact([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0])
+julia> F = eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0])
 Eigen{Float64,Float64,Array{Float64,2},Array{Float64,1}}
 eigenvalues:
 3-element Array{Float64,1}:
@@ -98,53 +112,26 @@ julia> F.vectors
  1.0  0.0  0.0
  0.0  1.0  0.0
  0.0  0.0  1.0
-```
-"""
-function eigfact(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) where T
-    AA = copy_oftype(A, eigtype(T))
-    isdiag(AA) && return eigfact(Diagonal(AA), permute = permute, scale = scale)
-    return eigfact!(AA, permute = permute, scale = scale)
-end
-eigfact(x::Number) = Eigen([x], fill(one(x), 1, 1))
-
-function eig(A::Union{Number, StridedMatrix}; permute::Bool=true, scale::Bool=true)
-    F = eigfact(A, permute=permute, scale=scale)
-    F.values, F.vectors
-end
 
-"""
-    eig(A::Union{SymTridiagonal, Hermitian, Symmetric}, irange::UnitRange) -> D, V
-    eig(A::Union{SymTridiagonal, Hermitian, Symmetric}, vl::Real, vu::Real) -> D, V
-    eig(A, permute::Bool=true, scale::Bool=true) -> D, V
-
-Computes eigenvalues (`D`) and eigenvectors (`V`) of `A`.
-See [`eigfact`](@ref) for details on the
-`irange`, `vl`, and `vu` arguments
-(for [`SymTridiagonal`](@ref), [`Hermitian`](@ref), and
-[`Symmetric`](@ref) matrices)
-and the `permute` and `scale` keyword arguments.
-The eigenvectors are returned columnwise.
+julia> vals, vecs = F; # destructuring via iteration
 
-# Examples
-```jldoctest
-julia> eig([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0])
-([1.0, 3.0, 18.0], [1.0 0.0 0.0; 0.0 1.0 0.0; 0.0 0.0 1.0])
+julia> vals == F.values && vecs == F.vectors
+true
 ```
-
-`eig` is a wrapper around [`eigfact`](@ref), extracting all parts of the
-factorization to a tuple; where possible, using [`eigfact`](@ref) is recommended.
 """
-function eig(A::AbstractMatrix, args...)
-    F = eigfact(A, args...)
-    F.values, F.vectors
+function eig(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) where T
+    AA = copy_oftype(A, eigtype(T))
+    isdiag(AA) && return eig(Diagonal(AA), permute = permute, scale = scale)
+    return eigfact!(AA, permute = permute, scale = scale)
 end
+eig(x::Number) = Eigen([x], fill(one(x), 1, 1))
 
 """
     eigvecs(A; permute::Bool=true, scale::Bool=true) -> Matrix
 
 Return a matrix `M` whose columns are the eigenvectors of `A`. (The `k`th eigenvector can
 be obtained from the slice `M[:, k]`.) The `permute` and `scale` keywords are the same as
-for [`eigfact`](@ref).
+for [`eig`](@ref).
 
 # Examples
 ```jldoctest
@@ -156,7 +143,7 @@ julia> eigvecs([1.0 0.0 0.0; 0.0 3.0 0.0; 0.0 0.0 18.0])
 ```
 """
 eigvecs(A::Union{Number, AbstractMatrix}; permute::Bool=true, scale::Bool=true) =
-    eigvecs(eigfact(A, permute=permute, scale=scale))
+    eigvecs(eig(A, permute=permute, scale=scale))
 eigvecs(F::Union{Eigen, GeneralizedEigen}) = F.vectors
 
 eigvals(F::Union{Eigen, GeneralizedEigen}) = F.values
@@ -351,13 +338,15 @@ function eigfact!(A::StridedMatrix{T}, B::StridedMatrix{T}) where T<:BlasComplex
 end
 
 """
-    eigfact(A, B) -> GeneralizedEigen
+    eig(A, B) -> GeneralizedEigen
 
 Computes the generalized eigenvalue decomposition of `A` and `B`, returning a
 `GeneralizedEigen` factorization object `F` which contains the generalized eigenvalues in
 `F.values` and the generalized eigenvectors in the columns of the matrix `F.vectors`.
 (The `k`th generalized eigenvector can be obtained from the slice `F.vectors[:, k]`.)
 
+Iterating the decomposition produces the components `F.values` and `F.vectors`.
+
 # Examples
 ```jldoctest
 julia> A = [1 0; 0 -1]
@@ -370,7 +359,7 @@ julia> B = [0 1; 1 0]
  0  1
  1  0
 
-julia> F = eigfact(A, B);
+julia> F = eig(A, B);
 
 julia> F.values
 2-element Array{Complex{Float64},1}:
@@ -381,47 +370,19 @@ julia> F.vectors
 2×2 Array{Complex{Float64},2}:
   0.0-1.0im   0.0+1.0im
  -1.0-0.0im  -1.0+0.0im
+
+julia> vals, vecs = F; # destructuring via iteration
+
+julia> vals == F.values && vecs == F.vectors
+true
 ```
 """
-function eigfact(A::AbstractMatrix{TA}, B::AbstractMatrix{TB}) where {TA,TB}
+function eig(A::AbstractMatrix{TA}, B::AbstractMatrix{TB}) where {TA,TB}
     S = promote_type(eigtype(TA),TB)
     return eigfact!(copy_oftype(A, S), copy_oftype(B, S))
 end
 
-eigfact(A::Number, B::Number) = eigfact(fill(A,1,1), fill(B,1,1))
-
-"""
-    eig(A, B) -> D, V
-
-Computes generalized eigenvalues (`D`) and vectors (`V`) of `A` with respect to `B`.
-
-`eig` is a wrapper around [`eigfact`](@ref), extracting all parts of the
-factorization to a tuple; where possible, using [`eigfact`](@ref) is recommended.
-
-# Examples
-```jldoctest
-julia> A = [1 0; 0 -1]
-2×2 Array{Int64,2}:
- 1   0
- 0  -1
-
-julia> B = [0 1; 1 0]
-2×2 Array{Int64,2}:
- 0  1
- 1  0
-
-julia> eig(A, B)
-(Complex{Float64}[0.0+1.0im, 0.0-1.0im], Complex{Float64}[0.0-1.0im 0.0+1.0im; -1.0-0.0im -1.0+0.0im])
-```
-"""
-function eig(A::AbstractMatrix, B::AbstractMatrix)
-    F = eigfact(A,B)
-    F.values, F.vectors
-end
-function eig(A::Number, B::Number)
-    F = eigfact(A,B)
-    F.values, F.vectors
-end
+eig(A::Number, B::Number) = eig(fill(A,1,1), fill(B,1,1))
 
 """
     eigvals!(A, B) -> values
@@ -524,7 +485,7 @@ julia> eigvecs(A, B)
  -1.0-0.0im  -1.0+0.0im
 ```
 """
-eigvecs(A::AbstractMatrix, B::AbstractMatrix) = eigvecs(eigfact(A, B))
+eigvecs(A::AbstractMatrix, B::AbstractMatrix) = eigvecs(eig(A, B))
 
 function show(io::IO, mime::MIME{Symbol("text/plain")}, F::Union{Eigen,GeneralizedEigen})
     println(io, summary(F))