Merge pull request JuliaLang#19507 from xorJane/LinAlgDoctests

Add more doctests for linear algebra standard library

Author: kshyatt

base/arraymath.jl

@@ -473,6 +473,22 @@ end
     transpose(A)
 
 The transposition operator (`.'`).
+
+# Example
+
+```jldoctest
+julia> A = [1 2 3; 4 5 6; 7 8 9]
+3×3 Array{Int64,2}:
+ 1  2  3
+ 4  5  6
+ 7  8  9
+
+julia> transpose(A)
+3×3 Array{Int64,2}:
+ 1  4  7
+ 2  5  8
+ 3  6  9
+```
 """
 function transpose(A::AbstractMatrix)
     ind1, ind2 = indices(A)

base/docs/helpdb/Base.jl

@@ -2081,23 +2081,6 @@ Raise an `ErrorException` with the given message.
 """
 error
 
-"""
-    sqrtm(A)
-
-If `A` has no negative real eigenvalues, compute the principal matrix square root of `A`,
-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`](:func:`eigfact`)) is
-used to compute the square root. Otherwise, the square root is determined by means of the
-Björck-Hammarling method, which computes the complex Schur form ([`schur`](:func:`schur`))
-and then the complex square root of the triangular factor.
-
-[^BH83]: Åke Björck and Sven Hammarling, "A Schur method for the square root of a matrix", Linear Algebra and its Applications, 52-53, 1983, 127-140. [doi:10.1016/0024-3795(83)80010-X](http://dx.doi.org/10.1016/0024-3795(83)80010-X)
-
-"""
-sqrtm
-
 """
     readcsv(source, [T::Type]; options...)
 

base/linalg/dense.jl

@@ -469,6 +469,19 @@ triangular factor.
 
 [^AHR13]: Awad H. Al-Mohy, Nicholas J. Higham and Samuel D. Relton, "Computing the Fréchet derivative of the matrix logarithm and estimating the condition number", SIAM Journal on Scientific Computing, 35(4), 2013, C394-C410. [doi:10.1137/120885991](http://dx.doi.org/10.1137/120885991)
 
+# Example
+
+```jldoctest
+julia> A = 2.7182818 * eye(2)
+2×2 Array{Float64,2}:
+ 2.71828  0.0
+ 0.0      2.71828
+
+julia> logm(A)
+2×2 Array{Float64,2}:
+ 1.0  0.0
+ 0.0  1.0
+```
 """
 function logm(A::StridedMatrix)
     # If possible, use diagonalization
@@ -508,6 +521,34 @@ function logm(a::Number)
 end
 logm(a::Complex) = log(a)
 
+"""
+    sqrtm(A)
+
+If `A` has no negative real eigenvalues, compute the principal matrix square root of `A`,
+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`](:func:`eigfact`)) is
+used to compute the square root. Otherwise, the square root is determined by means of the
+Björck-Hammarling method, which computes the complex Schur form ([`schur`](:func:`schur`))
+and then the complex square root of the triangular factor.
+
+[^BH83]: Åke Björck and Sven Hammarling, "A Schur method for the square root of a matrix", Linear Algebra and its Applications, 52-53, 1983, 127-140. [doi:10.1016/0024-3795(83)80010-X](http://dx.doi.org/10.1016/0024-3795(83)80010-X)
+
+# Example
+
+```jldoctest
+julia> A = [4 0; 0 4]
+2×2 Array{Int64,2}:
+ 4  0
+ 0  4
+
+julia> sqrtm(A)
+2×2 Array{Float64,2}:
+ 2.0  0.0
+ 0.0  2.0
+```
+"""
 function sqrtm{T<:Real}(A::StridedMatrix{T})
     if issymmetric(A)
         return full(sqrtm(Symmetric(A)))

base/linalg/generic.jl

@@ -418,6 +418,16 @@ element type for which `norm` is defined), compute the `p`-norm (defaulting to `
 `A` were a vector of the corresponding length.
 
 For example, if `A` is a matrix and `p=2`, then this is equivalent to the Frobenius norm.
+
+# Example
+
+```jldoctest
+julia> vecnorm([1 2 3; 4 5 6; 7 8 9])
+16.881943016134134
+
+julia> vecnorm([1 2 3 4 5 6 7 8 9])
+16.881943016134134
+```
 """
 function vecnorm(itr, p::Real=2)
     isempty(itr) && return float(real(zero(eltype(itr))))
@@ -1134,6 +1144,21 @@ logabsdet(A::AbstractMatrix) = logabsdet(lufact(A))
 
 Log of matrix determinant. Equivalent to `log(det(M))`, but may provide increased accuracy
 and/or speed.
+
+# Example
+
+```jldoctest
+julia> M = [1 0; 2 2]
+2×2 Array{Int64,2}:
+ 1  0
+ 2  2
+
+julia> logdet(M)
+0.6931471805599453
+
+julia> logdet(eye(3))
+0.0
+```
 """
 function logdet(A::AbstractMatrix)
     d,s = logabsdet(A)

base/linalg/hessenberg.jl

@@ -28,6 +28,24 @@ factorization object, the unitary matrix can be accessed with `F[:Q]` and the He
 matrix with `F[:H]`. When `Q` is extracted, the resulting type is the `HessenbergQ` object,
 and may be converted to a regular matrix with [`convert(Array, _)`](:func:`convert`)
  (or `Array(_)` for short).
+
+# Example
+
+```jldoctest
+julia> A = [4. 9. 7.; 4. 4. 1.; 4. 3. 2.]
+3×3 Array{Float64,2}:
+ 4.0  9.0  7.0
+ 4.0  4.0  1.0
+ 4.0  3.0  2.0
+
+julia> F = hessfact(A);
+
+julia> F[:Q] * F[:H] * F[:Q]'
+3×3 Array{Float64,2}:
+ 4.0  9.0  7.0
+ 4.0  4.0  1.0
+ 4.0  3.0  2.0
+```
 """
 function hessfact{T}(A::StridedMatrix{T})
     S = promote_type(Float32, typeof(one(T)/norm(one(T))))

base/operators.jl

@@ -531,6 +531,20 @@ fldmod1{T<:Integer}(x::T, y::T) = (fld1(x,y), mod1(x,y))
     ctranspose(A)
 
 The conjugate transposition operator (`'`).
+
+# Example
+
+```jldoctest
+julia> A =  [3+2im 9+2im; 8+7im  4+6im]
+2×2 Array{Complex{Int64},2}:
+ 3+2im  9+2im
+ 8+7im  4+6im
+
+julia> ctranspose(A)
+2×2 Array{Complex{Int64},2}:
+ 3-2im  8-7im
+ 9-2im  4-6im
+```
 """
 ctranspose(x) = conj(transpose(x))
 conj(x) = x

doc/stdlib/linalg.rst

@@ -1110,6 +1110,24 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    Compute the Hessenberg decomposition of ``A`` and return a ``Hessenberg`` object. If ``F`` is the factorization object, the unitary matrix can be accessed with ``F[:Q]`` and the Hessenberg matrix with ``F[:H]``\ . When ``Q`` is extracted, the resulting type is the ``HessenbergQ`` object, and may be converted to a regular matrix with :func:`convert`  (or ``Array(_)`` for short).
 
+   **Example**
+
+   .. doctest::
+
+       julia> A = [4. 9. 7.; 4. 4. 1.; 4. 3. 2.]
+       3×3 Array{Float64,2}:
+        4.0  9.0  7.0
+        4.0  4.0  1.0
+        4.0  3.0  2.0
+
+       julia> F = hessfact(A);
+
+       julia> F[:Q] * F[:H] * F[:Q]'
+       3×3 Array{Float64,2}:
+        4.0  9.0  7.0
+        4.0  4.0  1.0
+        4.0  3.0  2.0
+
 .. function:: hessfact!(A) -> Hessenberg
 
    .. Docstring generated from Julia source
@@ -1808,6 +1826,16 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    For example, if ``A`` is a matrix and ``p=2``\ , then this is equivalent to the Frobenius norm.
 
+   **Example**
+
+   .. doctest::
+
+       julia> vecnorm([1 2 3; 4 5 6; 7 8 9])
+       16.881943016134134
+
+       julia> vecnorm([1 2 3 4 5 6 7 8 9])
+       16.881943016134134
+
 .. function:: normalize!(v, [p::Real=2])
 
    .. Docstring generated from Julia source
@@ -1899,6 +1927,21 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    Log of matrix determinant. Equivalent to ``log(det(M))``\ , but may provide increased accuracy and/or speed.
 
+   **Example**
+
+   .. doctest::
+
+       julia> M = [1 0; 2 2]
+       2×2 Array{Int64,2}:
+        1  0
+        2  2
+
+       julia> logdet(M)
+       0.6931471805599453
+
+       julia> logdet(eye(3))
+       0.0
+
 .. function:: logabsdet(M)
 
    .. Docstring generated from Julia source
@@ -2138,6 +2181,20 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    .. [AHR13] Awad H. Al-Mohy, Nicholas J. Higham and Samuel D. Relton, "Computing the Fréchet derivative of the matrix logarithm and estimating the condition number", SIAM Journal on Scientific Computing, 35(4), 2013, C394-C410. `doi:10.1137/120885991 <http://dx.doi.org/10.1137/120885991>`_
 
+   **Example**
+
+   .. doctest::
+
+       julia> A = 2.7182818 * eye(2)
+       2×2 Array{Float64,2}:
+        2.71828  0.0
+        0.0      2.71828
+
+       julia> logm(A)
+       2×2 Array{Float64,2}:
+        1.0  0.0
+        0.0  1.0
+
 .. function:: sqrtm(A)
 
    .. Docstring generated from Julia source
@@ -2148,6 +2205,20 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    .. [BH83] Åke Björck and Sven Hammarling, "A Schur method for the square root of a matrix", Linear Algebra and its Applications, 52-53, 1983, 127-140. `doi:10.1016/0024-3795(83)80010-X <http://dx.doi.org/10.1016/0024-3795(83)80010-X>`_
 
+   **Example**
+
+   .. doctest::
+
+       julia> A = [4 0; 0 4]
+       2×2 Array{Int64,2}:
+        4  0
+        0  4
+
+       julia> sqrtm(A)
+       2×2 Array{Float64,2}:
+        2.0  0.0
+        0.0  2.0
+
 .. function:: lyap(A, C)
 
    .. Docstring generated from Julia source
@@ -2320,6 +2391,22 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    The transposition operator (``.'``\ ).
 
+   **Example**
+
+   .. doctest::
+
+       julia> A = [1 2 3; 4 5 6; 7 8 9]
+       3×3 Array{Int64,2}:
+        1  2  3
+        4  5  6
+        7  8  9
+
+       julia> transpose(A)
+       3×3 Array{Int64,2}:
+        1  4  7
+        2  5  8
+        3  6  9
+
 .. function:: transpose!(dest,src)
 
    .. Docstring generated from Julia source
@@ -2332,6 +2419,20 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    The conjugate transposition operator (``'``\ ).
 
+   **Example**
+
+   .. doctest::
+
+       julia> A =  [3+2im 9+2im; 8+7im  4+6im]
+       2×2 Array{Complex{Int64},2}:
+        3+2im  9+2im
+        8+7im  4+6im
+
+       julia> ctranspose(A)
+       2×2 Array{Complex{Int64},2}:
+        3-2im  8-7im
+        9-2im  4-6im
+
 .. function:: ctranspose!(dest,src)
 
    .. Docstring generated from Julia source