From 6bfc6120c896e095eb12a73d3954e6bf4c00b4fa Mon Sep 17 00:00:00 2001 From: Jake Bolewski Date: Mon, 7 Dec 2015 15:39:59 -0500 Subject: [PATCH] remove unnecessary doc string macros, re-sync documentation --- base/linalg/arnoldi.jl | 4 ++-- base/linalg/cholesky.jl | 4 ++-- base/linalg/dense.jl | 2 +- base/linalg/eigen.jl | 4 +++- base/linalg/givens.jl | 2 +- base/linalg/ldlt.jl | 4 ++-- base/linalg/schur.jl | 28 ++++++++++++++-------------- doc/stdlib/linalg.rst | 17 +++++++++-------- 8 files changed, 34 insertions(+), 31 deletions(-) diff --git a/base/linalg/arnoldi.jl b/base/linalg/arnoldi.jl index 2eaf5bbc76c35..6b41dcacb09d7 100644 --- a/base/linalg/arnoldi.jl +++ b/base/linalg/arnoldi.jl @@ -3,7 +3,7 @@ using .ARPACK ## eigs -doc""" +""" ```rst .. eigs(A; nev=6, ncv=max(20,2*nev+1), which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0,))) -> (d,[v,],nconv,niter,nmult,resid) @@ -62,7 +62,7 @@ function eigs(A::AbstractMatrix, B::AbstractMatrix; kwargs...) Tnew = typeof(zero(T)/sqrt(one(T))) eigs(convert(AbstractMatrix{Tnew}, A), convert(AbstractMatrix{Tnew}, B); kwargs...) end -doc""" +""" ```rst .. eigs(A, B; nev=6, ncv=max(20,2*nev+1), which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0,))) -> (d,[v,],nconv,niter,nmult,resid) diff --git a/base/linalg/cholesky.jl b/base/linalg/cholesky.jl index b75429d8723e9..e8be1a22bd2f1 100644 --- a/base/linalg/cholesky.jl +++ b/base/linalg/cholesky.jl @@ -78,7 +78,7 @@ function chol!{T}(A::AbstractMatrix{T}, ::Type{LowerTriangular}) return LowerTriangular(A) end -doc""" +""" chol(A::AbstractMatrix) -> U Compute the Cholesky factorization of a positive definite matrix `A` and return the UpperTriangular matrix `U` such that `A = U'U`. @@ -95,7 +95,7 @@ function chol!(x::Number, uplo) rxr = sqrt(rx) convert(promote_type(typeof(x), typeof(rxr)), rxr) end -doc""" +""" chol(x::Number) -> y Compute the square root of a non-negative number `x`. diff --git a/base/linalg/dense.jl b/base/linalg/dense.jl index 47bc2bbbd3c2f..cf259f528a098 100644 --- a/base/linalg/dense.jl +++ b/base/linalg/dense.jl @@ -282,7 +282,7 @@ function rcswap!{T<:Number}(i::Integer, j::Integer, X::StridedMatrix{T}) end end -doc""" +""" ```rst .. logm(A::StridedMatrix) diff --git a/base/linalg/eigen.jl b/base/linalg/eigen.jl index 611d8050af737..8364b4f22fb4c 100644 --- a/base/linalg/eigen.jl +++ b/base/linalg/eigen.jl @@ -72,12 +72,14 @@ 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 -doc""" +""" eigvals!(A,[irange,][vl,][vu]) -> values Same as `eigvals`, but saves space by overwriting the input `A` (and `B`), instead of creating a copy. """ +function eigvals! end + function eigvals!{T<:BlasReal}(A::StridedMatrix{T}; permute::Bool=true, scale::Bool=true) issym(A) && return eigvals!(Symmetric(A)) _, valsre, valsim, _ = LAPACK.geevx!(permute ? (scale ? 'B' : 'P') : (scale ? 'S' : 'N'), 'N', 'N', 'N', A) diff --git a/base/linalg/givens.jl b/base/linalg/givens.jl index 4f934f906a3ad..972a677d23fbb 100644 --- a/base/linalg/givens.jl +++ b/base/linalg/givens.jl @@ -220,7 +220,7 @@ function givensAlgorithm{T<:AbstractFloat}(f::Complex{T}, g::Complex{T}) return cs, sn, r end -doc""" +""" givens{T}(::T, ::T, ::Integer, ::Integer) -> {Givens, T} diff --git a/base/linalg/ldlt.jl b/base/linalg/ldlt.jl index 9c47ab1d101c7..985f67d2b046f 100644 --- a/base/linalg/ldlt.jl +++ b/base/linalg/ldlt.jl @@ -15,7 +15,7 @@ convert{T,S,U<:AbstractMatrix}(::Type{LDLt{T}}, F::LDLt{S,U}) = convert(LDLt{T,U convert{T,S,U}(::Type{Factorization{T}}, F::LDLt{S,U}) = convert(LDLt{T,U}, F) # SymTridiagonal -doc""" +""" ldltfact!(::SymTridiagonal) -> LDLt @@ -32,7 +32,7 @@ function ldltfact!{T<:Real}(S::SymTridiagonal{T}) return LDLt{T,SymTridiagonal{T}}(S) end -doc""" +""" ldltfact(::SymTridiagonal) -> LDLt Compute an `LDLt` factorization of a real symmetric tridiagonal matrix such that `A = L*Diagonal(d)*L'` where `L` is a unit lower triangular matrix and `d` is a vector. The main use of an `LDLt` factorization `F = ldltfact(A)` is to solve the linear system of equations `Ax = b` with `F\b`. diff --git a/base/linalg/schur.jl b/base/linalg/schur.jl index 3bfdb31ac17b6..a76d91a5668ff 100644 --- a/base/linalg/schur.jl +++ b/base/linalg/schur.jl @@ -9,14 +9,14 @@ immutable Schur{Ty<:BlasFloat, S<:AbstractMatrix} <: Factorization{Ty} end Schur{Ty}(T::AbstractMatrix{Ty}, Z::AbstractMatrix{Ty}, values::Vector) = Schur{Ty, typeof(T)}(T, Z, values) -doc""" +""" schurfact!(A::StridedMatrix) -> F::Schur Same as `schurfact` but uses the input argument as workspace. """ schurfact!{T<:BlasFloat}(A::StridedMatrix{T}) = Schur(LinAlg.LAPACK.gees!('V', A)...) -doc""" +""" schurfact(A::StridedMatrix) -> F::Schur Computes the Schur factorization of the matrix `A`. The (quasi) triangular Schur factor can be obtained from the `Schur` object `F` with either `F[:Schur]` or `F[:T]` and the orthogonal/unitary Schur vectors can be obtained with `F[:vectors]` or `F[:Z]` such that `A = F[:vectors]*F[:Schur]*F[:vectors]'`. The eigenvalues of `A` can be obtained with `F[:values]`. @@ -39,7 +39,7 @@ function getindex(F::Schur, d::Symbol) end end -doc""" +""" schur(A::StridedMatrix) -> T::Matrix, Z::Matrix, λ::Vector Computes the Schur factorization of the matrix `A`. The methods return the (quasi) triangular Schur factor `T` and the orthogonal/unitary Schur vectors `Z` such that `A = Z*T*Z'`. The eigenvalues of `A` are returned in the vector `λ`. @@ -51,7 +51,7 @@ function schur(A::StridedMatrix) SchurF[:T], SchurF[:Z], SchurF[:values] end -doc""" +""" ordschur!(F::Schur, select::Union{Vector{Bool},BitVector}) -> F::Schur Same as `ordschur` but overwrites the factorization `F`. @@ -62,7 +62,7 @@ function ordschur!{Ty<:BlasFloat}(schur::Schur{Ty}, select::Union{Vector{Bool},B return schur end -doc""" +""" ordschur(F::Schur, select::Union{Vector{Bool},BitVector}) -> F::Schur Reorders the Schur factorization `F` of a matrix `A = Z*T*Z'` according to the logical array `select` returning the reordered factorization `F` object. The selected eigenvalues appear in the leading diagonal of `F[:Schur]` and the the corresponding leading columns of `F[:vectors]` form an orthogonal/unitary basis of the corresponding right invariant subspace. In the real case, a complex conjugate pair of eigenvalues must be either both included or both excluded via `select`. @@ -70,14 +70,14 @@ Reorders the Schur factorization `F` of a matrix `A = Z*T*Z'` according to the l """ ordschur{Ty<:BlasFloat}(schur::Schur{Ty}, select::Union{Vector{Bool},BitVector}) = Schur(ordschur(schur.T, schur.Z, select)...) -doc""" +""" ordschur!(T::StridedMatrix, Z::StridedMatrix, select::Union{Vector{Bool},BitVector}) -> T::StridedMatrix, Z::StridedMatrix, λ::Vector Same as `ordschur` but overwrites the input arguments. """ ordschur!{Ty<:BlasFloat}(T::StridedMatrix{Ty}, Z::StridedMatrix{Ty}, select::Union{Vector{Bool},BitVector}) = LinAlg.LAPACK.trsen!(convert(Vector{BlasInt}, select), T, Z) -doc""" +""" ordschur(T::StridedMatrix, Z::StridedMatrix, select::Union{Vector{Bool},BitVector}) -> T::StridedMatrix, Z::StridedMatrix, λ::Vector Reorders the Schur factorization of a real matrix `A = Z*T*Z'` according to the logical array `select` returning the reordered matrices `T` and `Z` as well as the vector of eigenvalues `λ`. The selected eigenvalues appear in the leading diagonal of `T` and the the corresponding leading columns of `Z` form an orthogonal/unitary basis of the corresponding right invariant subspace. In the real case, a complex conjugate pair of eigenvalues must be either both included or both excluded via `select`. @@ -95,14 +95,14 @@ immutable GeneralizedSchur{Ty<:BlasFloat, M<:AbstractMatrix} <: Factorization{Ty end GeneralizedSchur{Ty}(S::AbstractMatrix{Ty}, T::AbstractMatrix{Ty}, alpha::Vector, beta::Vector{Ty}, Q::AbstractMatrix{Ty}, Z::AbstractMatrix{Ty}) = GeneralizedSchur{Ty, typeof(S)}(S, T, alpha, beta, Q, Z) -doc""" +""" schurfact!(A::StridedMatrix, B::StridedMatrix) -> F::GeneralizedSchur Same as `schurfact` but uses the input matrices `A` and `B` as workspace. """ schurfact!{T<:BlasFloat}(A::StridedMatrix{T}, B::StridedMatrix{T}) = GeneralizedSchur(LinAlg.LAPACK.gges!('V', 'V', A, B)...) -doc""" +""" schurfact(A::StridedMatrix, B::StridedMatrix) -> F::GeneralizedSchur Computes the Generalized Schur (or QZ) factorization of the matrices `A` and `B`. The (quasi) triangular Schur factors can be obtained from the `Schur` object `F` with `F[:S]` and `F[:T]`, the left unitary/orthogonal Schur vectors can be obtained with `F[:left]` or `F[:Q]` and the right unitary/orthogonal Schur vectors can be obtained with `F[:right]` or `F[:Z]` such that `A=F[:left]*F[:S]*F[:right]'` and `B=F[:left]*F[:T]*F[:right]'`. The generalized eigenvalues of `A` and `B` can be obtained with `F[:alpha]./F[:beta]`. @@ -113,7 +113,7 @@ function schurfact{TA,TB}(A::StridedMatrix{TA}, B::StridedMatrix{TB}) return schurfact!(copy_oftype(A, S), copy_oftype(B, S)) end -doc""" +""" ordschur!(F::GeneralizedSchur, select::Union{Vector{Bool},BitVector}) -> F::GeneralizedSchur Same as `ordschur` but overwrites the factorization `F`. @@ -125,21 +125,21 @@ function ordschur!{Ty<:BlasFloat}(gschur::GeneralizedSchur{Ty}, select::Union{Ve return gschur end -doc""" +""" ordschur(F::GeneralizedSchur, select::Union{Vector{Bool},BitVector}) -> F::GeneralizedSchur Reorders the Generalized Schur factorization `F` of a matrix pair `(A, B) = (Q*S*Z', Q*T*Z')` according to the logical array `select` and returns a GeneralizedSchur object `F`. The selected eigenvalues appear in the leading diagonal of both `F[:S]` and `F[:T]`, and the left and right orthogonal/unitary Schur vectors are also reordered such that `(A, B) = F[:Q]*(F[:S], F[:T])*F[:Z]'` still holds and the generalized eigenvalues of `A` and `B` can still be obtained with `F[:alpha]./F[:beta]`. """ ordschur{Ty<:BlasFloat}(gschur::GeneralizedSchur{Ty}, select::Union{Vector{Bool},BitVector}) = GeneralizedSchur(ordschur(gschur.S, gschur.T, gschur.Q, gschur.Z, select)...) -doc""" +""" ordschur!(S::StridedMatrix, T::StridedMatrix, Q::StridedMatrix, Z::StridedMatrix, select) -> S::StridedMatrix, T::StridedMatrix, Q::StridedMatrix, Z::StridedMatrix, α::Vector, β::Vector Same as `ordschur` but overwrites the factorization the input arguments. """ ordschur!{Ty<:BlasFloat}(S::StridedMatrix{Ty}, T::StridedMatrix{Ty}, Q::StridedMatrix{Ty}, Z::StridedMatrix{Ty}, select::Union{Vector{Bool},BitVector}) = LinAlg.LAPACK.tgsen!(convert(Vector{BlasInt}, select), S, T, Q, Z) -doc""" +""" ordschur(S::StridedMatrix, T::StridedMatrix, Q::StridedMatrix, Z::StridedMatrix, select) -> S::StridedMatrix, T::StridedMatrix, Q::StridedMatrix, Z::StridedMatrix, α::Vector, β::Vector Reorders the Generalized Schur factorization of a matrix pair `(A, B) = (Q*S*Z', Q*T*Z')` according to the logical array `select` and returns the matrices `S`, `T`, `Q`, `Z` and vectors `α` and `β`. The selected eigenvalues appear in the leading diagonal of both `S` and `T`, and the left and right unitary/orthogonal Schur vectors are also reordered such that `(A, B) = Q*(S, T)*Z'` still holds and the generalized eigenvalues of `A` and `B` can still be obtained with `α./β`. @@ -167,7 +167,7 @@ function getindex(F::GeneralizedSchur, d::Symbol) end end -doc""" +""" schur(A::StridedMatrix, B::StridedMatrix) -> S::StridedMatrix, T::StridedMatrix, Q::StridedMatrix, Z::StridedMatrix, α::Vector, β::Vector See `schurfact` diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst index 39c9dd9216414..f308f76452337 100644 --- a/doc/stdlib/linalg.rst +++ b/doc/stdlib/linalg.rst @@ -149,7 +149,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. Docstring generated from Julia source - Compute an ``LDLt`` factorization of a real symmetric tridiagonal matrix such that ``A = L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector. The main use of an ``LDLt`` factorization ``F = ldltfact(A)`` is to solve the linear system of equations ``Ax = b`` with ``F\b``\ . + Compute an ``LDLt`` factorization of a real symmetric tridiagonal matrix such that ``A = L*Diagonal(d)*L'`` where ``L`` is a unit lower triangular matrix and ``d`` is a vector. The main use of an ``LDLt`` factorization ``F = ldltfact(A)`` is to solve the linear system of equations ``Ax = b`` with ``F``\ . .. function:: ldltfact(::Union{SparseMatrixCSC,Symmetric{Float64,SparseMatrixCSC{Flaot64,SuiteSparse_long}},Hermitian{Complex{Float64},SparseMatrixCSC{Complex{Float64},SuiteSparse_long}}}; shift=0, perm=Int[]) -> CHOLMOD.Factor @@ -904,7 +904,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f .. Docstring generated from Julia source - If ``A`` has no negative real eigenvalue, compute the principal matrix logarithm of ``A``, i.e. the unique matrix :math:`X` such that :math:`e^X = A` and :math:`-\pi < Im(\lambda) < \pi` for all the eigenvalues :math:`\lambda` of :math:`X`. If ``A`` has nonpositive eigenvalues, a nonprincipal matrix function is returned whenever possible. + If ``A`` has no negative real eigenvalue, compute the principal matrix logarithm of ``A``, i.e. the unique matrix :math:`X` such that :math:`e^X = A` and :math:`-pi < Im(lambda) < pi` for all the eigenvalues :math:`lambda` of :math:`X`. If ``A`` has nonpositive eigenvalues, a nonprincipal matrix function is returned whenever possible. If ``A`` is symmetric or Hermitian, its eigendecomposition (:func:`eigfact`) 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 (:func:`schur`) is computed and the triangular algorithm is used on the triangular factor. @@ -1034,7 +1034,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f ``:BE`` compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric ``A`` only) ========= ====================================================================================================================== - * ``tol``: tolerance (:math:`tol \le 0.0` defaults to ``DLAMCH('EPS')``) + * ``tol``: tolerance (:math:`tol le 0.0` defaults to ``DLAMCH('EPS')``) * ``maxiter``: Maximum number of iterations (default = 300) * ``sigma``: Specifies the level shift used in inverse iteration. If ``nothing`` (default), defaults to ordinary (forward) iterations. Otherwise, find eigenvalues close to ``sigma`` using shift and invert iterations. * ``ritzvec``: Returns the Ritz vectors ``v`` (eigenvectors) if ``true`` @@ -1048,7 +1048,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f ``sigma`` iteration mode ``which`` refers to eigenvalues of =============== ================================== ================================== ``nothing`` ordinary (forward) :math:`A` - real or complex inverse with level shift ``sigma`` :math:`(A - \sigma I )^{-1}` + real or complex inverse with level shift ``sigma`` :math:`(A - sigma I )^{-1}` =============== ================================== ================================== .. function:: eigs(A, B; nev=6, ncv=max(20,2*nev+1), which="LM", tol=0.0, maxiter=300, sigma=nothing, ritzvec=true, v0=zeros((0,))) -> (d,[v,],nconv,niter,nmult,resid) @@ -1077,7 +1077,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f ``:BE`` compute half of the eigenvalues from each end of the spectrum, biased in favor of the high end. (real symmetric ``A`` only) ========= ====================================================================================================================== - * ``tol``: tolerance (:math:`tol \le 0.0` defaults to ``DLAMCH('EPS')``) + * ``tol``: tolerance (:math:`tol le 0.0` defaults to ``DLAMCH('EPS')``) * ``maxiter``: Maximum number of iterations (default = 300) * ``sigma``: Specifies the level shift used in inverse iteration. If ``nothing`` (default), defaults to ordinary (forward) iterations. Otherwise, find eigenvalues close to ``sigma`` using shift and invert iterations. * ``ritzvec``: Returns the Ritz vectors ``v`` (eigenvectors) if ``true`` @@ -1085,13 +1085,14 @@ Linear algebra functions in Julia are largely implemented by calling functions f ``eigs`` returns the ``nev`` requested eigenvalues in ``d``, the corresponding Ritz vectors ``v`` (only if ``ritzvec=true``), the number of converged eigenvalues ``nconv``, the number of iterations ``niter`` and the number of matrix vector multiplications ``nmult``, as well as the final residual vector ``resid``. - .. note:: The ``sigma`` and ``which`` keywords interact: the description of eigenvalues searched for by ``which`` do _not_ necessarily refer to the eigenvalue problem :math:`Av = Bv\lambda`, but rather the linear operator constructed by the specification of the iteration mode implied by ``sigma``. + .. note:: The ``sigma`` and ``which`` keywords interact: the description of eigenvalues searched for by ``which`` do _not_ necessarily refer to the eigenvalue problem :math:`Av = Bvlambda`, but rather the linear operator constructed by the specification of the iteration mode implied by ``sigma``. =============== ================================== ================================== ``sigma`` iteration mode ``which`` refers to the problem =============== ================================== ================================== - ``nothing`` ordinary (forward) :math:`Av = Bv\lambda` - real or complex inverse with level shift ``sigma`` :math:`(A - \sigma B )^{-1}B = v\nu` + ``nothing`` ordinary (forward) :math:`Av = Bvlambda` + real or complex inverse with level shift ``sigma`` :math:`(A - sigma B )^{-1}B = v + u` =============== ================================== ================================== .. function:: svds(A; nsv=6, ritzvec=true, tol=0.0, maxiter=1000) -> (left_sv, s, right_sv, nconv, niter, nmult, resid)