Deprecate eigfact to eigen.

NEWS.md

@@ -704,9 +704,9 @@ Deprecated or removed
  `type` is fully deprecated to `mutable struct` ([#19157], [#20418]).
 
  * `lufact`, `schurfact`, `lqfact`, `qrfact`, `ldltfact`, `svdfact`,
- `bkfact`, and `hessfact` have respectively been deprecated to
+ `bkfact`, `hessfact`, and `eigfact` have respectively been deprecated to
  `lu`, `schur`, `lq`, `qr`, `ldlt`, `svd`, `bunchkaufman`,
- and `hessenberg` ([#27159]).
+ `hessenberg`, and `eigen` ([#27159]).
 
  * `lufact!`, `schurfact!`, `lqfact!`, `qrfact!`, `ldltfact!`, `svdfact!`,
  `bkfact!`, and `hessfact!` have respectively been deprecated to

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 eigen instead."))
  end
  if nev > nevmax
  @warn "Adjusting nev from $nev to $nevmax"

stdlib/LinearAlgebra/docs/src/index.md

@@ -337,7 +337,7 @@ LinearAlgebra.eigvals!
 LinearAlgebra.eigmax
 LinearAlgebra.eigmin
 LinearAlgebra.eigvecs
-LinearAlgebra.eigfact
+LinearAlgebra.eigen
 LinearAlgebra.eigfact!
 LinearAlgebra.hessenberg
 LinearAlgebra.hessenberg!

stdlib/LinearAlgebra/src/LinearAlgebra.jl

@@ -81,7 +81,7 @@ export
  diagm,
  dot,
  eig,
- eigfact,
+ eigen,
  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))
+eigen(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 ([`eigen`](@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 ([`eigen`](@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 ([`eigen`](@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 ([`eigen`](@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 ([`eigen`](@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 ([`eigen`](@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 ([`eigen`](@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 ([`eigen`](@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 ([`eigen`](@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

@@ -1359,3 +1359,22 @@ export hessfact
 # deprecate hessfact! to hessenberg!
 export hessenberg!
 @deprecate(hessfact!(A::StridedMatrix{<:BlasFloat}), hessenberg!(A))
+
+# deprecate eigfact to eigen
+export eigfact
+@deprecate(eigfact(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) where T, eigen(A; permute=permute, scale=scale))
+@deprecate(eigfact(x::Number), eigen(x))
+@deprecate(eigfact(A::AbstractMatrix{TA}, B::AbstractMatrix{TB}) where {TA,TB}, eigen(A, B))
+@deprecate(eigfact(A::Number, B::Number), eigen(A, B))
+
+@deprecate(eigfact(A::SymTridiagonal{T}) where T, eigen(A))
+@deprecate(eigfact(A::SymTridiagonal{T}, irange::UnitRange) where T, eigen(A))
+@deprecate(eigfact(A::SymTridiagonal{T}, vl::Real, vu::Real) where T, eigen(A))
+
+@deprecate(eigfact(M::Bidiagonal), eigen(M))
+
+@deprecate(eigfact(A::RealHermSymComplexHerm), eigen(A))
+@deprecate(eigfact(A::RealHermSymComplexHerm, irange::UnitRange), eigen(A, irange))
+@deprecate(eigfact(A::RealHermSymComplexHerm, vl::Real, vh::Real), eigen(A, vl, vh))
+@deprecate(eigfact(A::AbstractTriangular), eigen(A))
+@deprecate(eigfact(D::Diagonal; permute::Bool=true, scale::Bool=true), eigen(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 eigen(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 [`eigen`](@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
+ eigen(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 = eigen([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,17 +112,22 @@ julia> F.vectors
  1.0 0.0 0.0
  0.0 1.0 0.0
  0.0 0.0 1.0
+
+julia> vals, vecs = F; # destructuring via iteration
+
+julia> vals == F.values && vecs == F.vectors
+true
 ```
 """
-function eigfact(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) where T
+function eigen(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)
+ isdiag(AA) && return eigen(Diagonal(AA), permute = permute, scale = scale)
  return eigfact!(AA, permute = permute, scale = scale)
 end
-eigfact(x::Number) = Eigen([x], fill(one(x), 1, 1))
+eigen(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 = eigen(A, permute=permute, scale=scale)
  F.values, F.vectors
 end
 
@@ -118,7 +137,7 @@ end
  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
+See [`eigen`](@ref) for details on the
 `irange`, `vl`, and `vu` arguments
 (for [`SymTridiagonal`](@ref), [`Hermitian`](@ref), and
 [`Symmetric`](@ref) matrices)
@@ -131,11 +150,11 @@ 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])
 ```
 
-`eig` is a wrapper around [`eigfact`](@ref), extracting all parts of the
-factorization to a tuple; where possible, using [`eigfact`](@ref) is recommended.
+`eig` is a wrapper around [`eigen`](@ref), extracting all parts of the
+factorization to a tuple; where possible, using [`eigen`](@ref) is recommended.
 """
 function eig(A::AbstractMatrix, args...)
- F = eigfact(A, args...)
+ F = eigen(A, args...)
  F.values, F.vectors
 end
 
@@ -144,7 +163,7 @@ end
 
 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 [`eigen`](@ref).
 
 # Examples
 ```jldoctest
@@ -156,7 +175,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(eigen(A, permute=permute, scale=scale))
 eigvecs(F::Union{Eigen, GeneralizedEigen}) = F.vectors
 
 eigvals(F::Union{Eigen, GeneralizedEigen}) = F.values
@@ -351,13 +370,15 @@ function eigfact!(A::StridedMatrix{T}, B::StridedMatrix{T}) where T<:BlasComplex
 end
 
 """
- eigfact(A, B) -> GeneralizedEigen
+ eigen(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 +391,7 @@ julia> B = [0 1; 1 0]
  0 1
  1 0
 
-julia> F = eigfact(A, B);
+julia> F = eigen(A, B);
 
 julia> F.values
 2-element Array{Complex{Float64},1}:
@@ -381,22 +402,27 @@ 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 eigen(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))
+eigen(A::Number, B::Number) = eigen(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.
+`eig` is a wrapper around [`eigen`](@ref), extracting all parts of the
+factorization to a tuple; where possible, using [`eigen`](@ref) is recommended.
 
 # Examples
 ```jldoctest
@@ -415,11 +441,11 @@ julia> eig(A, B)
 ```
 """
 function eig(A::AbstractMatrix, B::AbstractMatrix)
- F = eigfact(A,B)
+ F = eigen(A,B)
  F.values, F.vectors
 end
 function eig(A::Number, B::Number)
- F = eigfact(A,B)
+ F = eigen(A,B)
  F.values, F.vectors
 end
 
@@ -524,7 +550,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(eigen(A, B))
 
 function show(io::IO, mime::MIME{Symbol("text/plain")}, F::Union{Eigen,GeneralizedEigen})
  println(io, summary(F))