Split up eigenfactorization docs

Make the docstrings accurately reflect the function signatures.
Add doctests for the symmetric cases.

Author: kshyatt

base/linalg/eigen.jl

@@ -56,20 +56,14 @@ function eigfact!{T<:BlasComplex}(A::StridedMatrix{T}; permute::Bool=true, scale
 end
 
 """
-    eigfact(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> Eigen
+    eigfact(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]`.)
 
 The following functions are available for `Eigen` objects: [`inv`](@ref), [`det`](@ref), and [`isposdef`](@ref).
 
-If `A` is [`Symmetric`](@ref), [`Hermitian`](@ref) or
-[`SymTridiagonal`](@ref), it is possible to calculate only a subset of
-the eigenvalues by specifying either a `UnitRange` `irange` covering
-indices of the sorted eigenvalues or a pair `vl` and `vu` for the lower and upper boundaries
-of the eigenvalues.
-
 For general nonsymmetric matrices it is possible to specify how the matrix is balanced
 before the eigenvector calculation. The option `permute=true` permutes the matrix to become
 closer to upper triangular, and `scale=true` scales the matrix by its diagonal elements to
@@ -106,11 +100,15 @@ function eig(A::Union{Number, StridedMatrix}; permute::Bool=true, scale::Bool=tr
 end
 
 """
-    eig(A,[irange,][vl,][vu,][permute=true,][scale=true]) -> D, V
+    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`, and
+`Symmetric` matrices)
 and the `permute` and `scale` keyword arguments.
 The eigenvectors are returned columnwise.
 
@@ -131,15 +129,12 @@ function eig(A::AbstractMatrix, args...)
 end
 
 """
-    eigvecs(A, [eigvals,][permute=true,][scale=true]) -> Matrix
+    eigvecs(A; permute::Bool=true, scale::Bool=true) -> Matrix
 
 Returns 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 [`SymTridiagonal`](@ref) matrices, if the optional vector of
-eigenvalues `eigvals` is specified, returns the specific corresponding eigenvectors.
-
 # Example
 
 ```jldoctest
@@ -157,9 +152,12 @@ eigvecs{T,V,S,U}(F::Union{Eigen{T,V,S,U}, GeneralizedEigen{T,V,S,U}}) = F[:vecto
 eigvals{T,V,S,U}(F::Union{Eigen{T,V,S,U}, GeneralizedEigen{T,V,S,U}}) = F[:values]::U
 
 """
-    eigvals!(A,[irange,][vl,][vu]) -> values
+    eigvals!(A; permute::Bool=true, scale::Bool=true) -> values
 
 Same as [`eigvals`](@ref), but saves space by overwriting the input `A`, instead of creating a copy.
+The option `permute=true` permutes the matrix to become
+closer to upper triangular, and `scale=true` scales the matrix by its diagonal elements to
+make rows and columns more equal in norm.
 """
 function eigvals!{T<:BlasReal}(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true)
     issymmetric(A) && return eigvals!(Symmetric(A))
@@ -172,15 +170,12 @@ function eigvals!{T<:BlasComplex}(A::StridedMatrix{T}; permute::Bool=true, scale
 end
 
 """
-    eigvals(A,[irange,][vl,][vu]) -> values
+    eigvals(A; permute::Bool=true, scale::Bool=true) -> values
 
-Returns the eigenvalues of `A`. If `A` is [`Symmetric`](@ref), [`Hermitian`](@ref) or [`SymTridiagonal`](@ref),
-it is possible to calculate only a subset of the eigenvalues by specifying either a
-`UnitRange` `irange` covering indices of the sorted eigenvalues, or a pair `vl` and `vu`
-for the lower and upper boundaries of the eigenvalues.
+Returns the eigenvalues of `A`.
 
 For general non-symmetric matrices it is possible to specify how the matrix is balanced
-before the eigenvector calculation. The option `permute=true` permutes the matrix to
+before the eigenvalue calculation. The option `permute=true` permutes the matrix to
 become closer to upper triangular, and `scale=true` scales the matrix by its diagonal
 elements to make rows and columns more equal in norm. The default is `true` for both
 options.

base/linalg/symmetric.jl

@@ -41,7 +41,7 @@ julia> eigfact(Supper)
 Base.LinAlg.Eigen{Float64,Float64,Array{Float64,2},Array{Float64,1}}([-2.96684,-2.72015,0.440875,7.72015,14.526],[-0.302016 -2.22045e-16 … 1.11022e-16 0.248524; -6.67755e-16 0.596931 … -0.802293 1.93069e-17; … ; 8.88178e-16 -0.802293 … -0.596931 0.0; 0.772108 8.93933e-16 … 0.0 0.630015])
 ```
 
-`eigfact` will use a method specialized for matrices known to be symmetric.
+[`eigfact`](@ref) will use a method specialized for matrices known to be symmetric.
 Note that `Supper` will not be equal to `Slower` unless `A` is itself symmetric (e.g. if `A == A.'`).
 """
 Symmetric(A::AbstractMatrix, uplo::Symbol=:U) = (checksquare(A);Symmetric{eltype(A),typeof(A)}(A, char_uplo(uplo)))
@@ -79,7 +79,7 @@ julia> eigfact(Hupper)
 Base.LinAlg.Eigen{Complex{Float64},Float64,Array{Complex{Float64},2},Array{Float64,1}}([-8.32069,-2.72015,3.1496,7.72015,17.1711],Complex{Float64}[-0.231509+0.392692im -2.77556e-17+1.11022e-16im … -4.16334e-17-4.16334e-17im -0.129023-0.00628656im; 0.0+0.0im -0.523844+0.286205im … -0.521629+0.609571im 0.0+0.0im; … ; 0.0-6.93889e-18im 0.704063-0.384669im … -0.388108+0.45354im 0.0-1.38778e-17im; 0.67898+0.0im 0.0+0.0im … 0.0+0.0im -0.661651-0.0im])
 ```
 
-`eigfact` will use a method specialized for matrices known to be Hermitian.
+[`eigfact`](@ref) will use a method specialized for matrices known to be Hermitian.
 Note that `Hupper` will not be equal to `Hlower` unless `A` is itself Hermitian (e.g. if `A == A'`).
 """
 function Hermitian(A::AbstractMatrix, uplo::Symbol=:U)
@@ -278,22 +278,114 @@ eigfact{T1<:Real,T2}(A::RealHermSymComplexHerm{T1,T2}) = (T = eltype(A); S = pro
 
 eigfact!{T<:BlasReal,S<:StridedMatrix}(A::RealHermSymComplexHerm{T,S}, irange::UnitRange) = Eigen(LAPACK.syevr!('V', 'I', A.uplo, A.data, 0.0, 0.0, irange.start, irange.stop, -1.0)...)
 # Because of #6721 it is necessary to specify the parameters explicitly here.
+
+"""
+    eigfact(A::Union{SymTridiagonal, Hermitian, Symmetric}, irange::UnitRange) -> 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]`.)
+
+The following functions are available for `Eigen` objects: [`inv`](@ref), [`det`](@ref), and [`isposdef`](@ref).
+
+The `UnitRange` `irange` specifies indices of the sorted eigenvalues to search for.
+
+!!! note
+    If `irange` is not `1:n`, where `n` is the dimension of `A`, then the returned factorization
+    will be a *truncated* factorization.
+"""
 eigfact{T1<:Real,T2}(A::RealHermSymComplexHerm{T1,T2}, irange::UnitRange) = (T = eltype(A); S = promote_type(Float32, typeof(zero(T)/norm(one(T)))); eigfact!(S != T ? convert(AbstractMatrix{S}, A) : copy(A), irange))
 
 eigfact!{T<:BlasReal,S<:StridedMatrix}(A::RealHermSymComplexHerm{T,S}, vl::Real, vh::Real) = Eigen(LAPACK.syevr!('V', 'V', A.uplo, A.data, convert(T, vl), convert(T, vh), 0, 0, -1.0)...)
 # Because of #6721 it is necessary to specify the parameters explicitly here.
+"""
+    eigfact(A::Union{SymTridiagonal, Hermitian, Symmetric}, vl::Real, vu::Real) -> 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]`.)
+
+The following functions are available for `Eigen` objects: [`inv`](@ref), [`det`](@ref), and [`isposdef`](@ref).
+
+`vl` is the lower bound of the window of eigenvalues to search for, and `vu` is the upper bound.
+
+!!! note
+    If [`vl`, `vu`] does not contain all eigenvalues of `A`, then the returned factorization
+    will be a *truncated* factorization.
+"""
 eigfact{T1<:Real,T2}(A::RealHermSymComplexHerm{T1,T2}, vl::Real, vh::Real) = (T = eltype(A); S = promote_type(Float32, typeof(zero(T)/norm(one(T)))); eigfact!(S != T ? convert(AbstractMatrix{S}, A) : copy(A), vl, vh))
 
 eigvals!{T<:BlasReal,S<:StridedMatrix}(A::RealHermSymComplexHerm{T,S}) = LAPACK.syevr!('N', 'A', A.uplo, A.data, 0.0, 0.0, 0, 0, -1.0)[1]
 # Because of #6721 it is necessary to specify the parameters explicitly here.
 eigvals{T1<:Real,T2}(A::RealHermSymComplexHerm{T1,T2}) = (T = eltype(A); S = promote_type(Float32, typeof(zero(T)/norm(one(T)))); eigvals!(S != T ? convert(AbstractMatrix{S}, A) : copy(A)))
 
+"""
+    eigvals!(A::Union{SymTridiagonal, Hermitian, Symmetric}, irange::UnitRange) -> values
+
+Same as [`eigvals`](@ref), but saves space by overwriting the input `A`, instead of creating a copy.
+`irange` is a range of eigenvalue *indices* to search for - for instance, the 2nd to 8th eigenvalues.
+"""
 eigvals!{T<:BlasReal,S<:StridedMatrix}(A::RealHermSymComplexHerm{T,S}, irange::UnitRange) = LAPACK.syevr!('N', 'I', A.uplo, A.data, 0.0, 0.0, irange.start, irange.stop, -1.0)[1]
 # Because of #6721 it is necessary to specify the parameters explicitly here.
+"""
+    eigvals(A::Union{SymTridiagonal, Hermitian, Symmetric}, irange::UnitRange) -> values
+
+Returns the eigenvalues of `A`. It is possible to calculate only a subset of the
+eigenvalues by specifying a `UnitRange` `irange` covering indices of the sorted eigenvalues,
+e.g. the 2nd to 8th eigenvalues.
+
+```jldoctest
+julia> A = SymTridiagonal([1.; 2.; 1.], [2.; 3.])
+3×3 SymTridiagonal{Float64}:
+ 1.0  2.0   ⋅
+ 2.0  2.0  3.0
+  ⋅   3.0  1.0
+
+julia> eigvals(A, 2:2)
+1-element Array{Float64,1}:
+ 1.0
+
+julia> eigvals(A)
+3-element Array{Float64,1}:
+ -2.14005
+  1.0
+  5.14005
+```
+"""
 eigvals{T1<:Real,T2}(A::RealHermSymComplexHerm{T1,T2}, irange::UnitRange) = (T = eltype(A); S = promote_type(Float32, typeof(zero(T)/norm(one(T)))); eigvals!(S != T ? convert(AbstractMatrix{S}, A) : copy(A), irange))
 
+"""
+    eigvals!(A::Union{SymTridiagonal, Hermitian, Symmetric}, vl::Real, vu::Real) -> values
+
+Same as [`eigvals`](@ref), but saves space by overwriting the input `A`, instead of creating a copy.
+`vl` is the lower bound of the interval to search for eigenvalues, and `vu` is the upper bound.
+"""
 eigvals!{T<:BlasReal,S<:StridedMatrix}(A::RealHermSymComplexHerm{T,S}, vl::Real, vh::Real) = LAPACK.syevr!('N', 'V', A.uplo, A.data, convert(T, vl), convert(T, vh), 0, 0, -1.0)[1]
 # Because of #6721 it is necessary to specify the parameters explicitly here.
+"""
+    eigvals(A::Union{SymTridiagonal, Hermitian, Symmetric}, vl::Real, vu::Real) -> values
+
+Returns the eigenvalues of `A`. It is possible to calculate only a subset of the eigenvalues
+by specifying a pair `vl` and `vu` for the lower and upper boundaries of the eigenvalues.
+
+```jldoctest
+julia> A = SymTridiagonal([1.; 2.; 1.], [2.; 3.])
+3×3 SymTridiagonal{Float64}:
+ 1.0  2.0   ⋅
+ 2.0  2.0  3.0
+  ⋅   3.0  1.0
+
+julia> eigvals(A, -1, 2)
+1-element Array{Float64,1}:
+ 1.0
+
+julia> eigvals(A)
+3-element Array{Float64,1}:
+ -2.14005
+  1.0
+  5.14005
+```
+"""
 eigvals{T1<:Real,T2}(A::RealHermSymComplexHerm{T1,T2}, vl::Real, vh::Real) = (T = eltype(A); S = promote_type(Float32, typeof(zero(T)/norm(one(T)))); eigvals!(S != T ? convert(AbstractMatrix{S}, A) : copy(A), vl, vh))
 
 eigmax{T<:Real,S<:StridedMatrix}(A::RealHermSymComplexHerm{T,S}) = eigvals(A, size(A, 1):size(A, 1))[1]

base/linalg/tridiag.jl

@@ -202,6 +202,44 @@ eigmin(A::SymTridiagonal) = eigvals(A, 1:1)[1]
 
 #Compute selected eigenvectors only corresponding to particular eigenvalues
 eigvecs(A::SymTridiagonal) = eigfact(A)[:vectors]
+
+"""
+    eigvecs(A::SymTridiagonal[, eigvals]) -> Matrix
+
+Returns a matrix `M` whose columns are the eigenvectors of `A`. (The `k`th eigenvector can
+be obtained from the slice `M[:, k]`.)
+
+If the optional vector of eigenvalues `eigvals` is specified, `eigvecs`
+returns the specific corresponding eigenvectors.
+
+# Example
+
+```jldoctest
+julia> A = SymTridiagonal([1.; 2.; 1.], [2.; 3.])
+3×3 SymTridiagonal{Float64}:
+ 1.0  2.0   ⋅
+ 2.0  2.0  3.0
+  ⋅   3.0  1.0
+
+julia> eigvals(A)
+3-element Array{Float64,1}:
+ -2.14005
+  1.0
+  5.14005
+
+julia> eigvecs(A)
+3×3 Array{Float64,2}:
+  0.418304  -0.83205      0.364299
+ -0.656749  -7.39009e-16  0.754109
+  0.627457   0.5547       0.546448
+
+julia> eigvecs(A, [1.])
+3×1 Array{Float64,2}:
+  0.83205
+  4.26351e-17
+ -0.5547
+```
+"""
 eigvecs{T<:BlasFloat,Eigenvalue<:Real}(A::SymTridiagonal{T}, eigvals::Vector{Eigenvalue}) = LAPACK.stein!(A.dv, A.ev, eigvals)
 
 #tril and triu