From 42f5758a53f883b146ad69de688ba16449ffb89f Mon Sep 17 00:00:00 2001 From: Fredrik Ekre Date: Sat, 24 Jun 2017 07:44:08 +0200 Subject: [PATCH] document Upper/LowerTriangular and clarify that Symmetric/Hermitian are views as well add references to Upper/LowerTriangular in the manual Ref #22504 (cherry picked from commit c964958260f6c0dd1baa51bc4bf66ffcfe93c135) --- base/linalg/cholesky.jl | 2 +- base/linalg/symmetric.jl | 6 ++-- base/linalg/triangular.jl | 45 +++++++++++++++++++++++++ doc/src/manual/linear-algebra.md | 58 ++++++++++++++++---------------- doc/src/stdlib/linalg.md | 2 ++ 5 files changed, 81 insertions(+), 32 deletions(-) diff --git a/base/linalg/cholesky.jl b/base/linalg/cholesky.jl index 5ba08622ded9c4..4629fb9341aecb 100644 --- a/base/linalg/cholesky.jl +++ b/base/linalg/cholesky.jl @@ -160,7 +160,7 @@ end chol(A) -> U Compute the Cholesky factorization of a positive definite matrix `A` -and return the UpperTriangular matrix `U` such that `A = U'U`. +and return the [`UpperTriangular`](@ref) matrix `U` such that `A = U'U`. # Example diff --git a/base/linalg/symmetric.jl b/base/linalg/symmetric.jl index 7db6d98be6610e..c101d6ae65763d 100644 --- a/base/linalg/symmetric.jl +++ b/base/linalg/symmetric.jl @@ -8,7 +8,8 @@ end """ Symmetric(A, uplo=:U) -Construct a `Symmetric` matrix from the upper (if `uplo = :U`) or lower (if `uplo = :L`) triangle of `A`. +Construct a `Symmetric` view of the upper (if `uplo = :U`) or lower (if `uplo = :L`) +triangle of the matrix `A`. # Example @@ -57,7 +58,8 @@ end """ Hermitian(A, uplo=:U) -Construct a `Hermitian` matrix from the upper (if `uplo = :U`) or lower (if `uplo = :L`) triangle of `A`. +Construct a `Hermitian` view of the upper (if `uplo = :U`) or lower (if `uplo = :L`) +triangle of the matrix `A`. # Example diff --git a/base/linalg/triangular.jl b/base/linalg/triangular.jl index a9935851177cc0..8c95da6f198392 100644 --- a/base/linalg/triangular.jl +++ b/base/linalg/triangular.jl @@ -50,6 +50,51 @@ LowerTriangular(U::UpperTriangular) = throw(ArgumentError( UpperTriangular(U::LowerTriangular) = throw(ArgumentError( "cannot create an UpperTriangular matrix from a LowerTriangular input")) +""" + LowerTriangular(A::AbstractMatrix) + +Construct a `LowerTriangular` view of the the matrix `A`. + +# Example + +```jldoctest +julia> A = [1.0 2.0 3.0; 4.0 5.0 6.0; 7.0 8.0 9.0] +3×3 Array{Float64,2}: + 1.0 2.0 3.0 + 4.0 5.0 6.0 + 7.0 8.0 9.0 + +julia> LowerTriangular(A) +3×3 LowerTriangular{Float64,Array{Float64,2}}: + 1.0 ⋅ ⋅ + 4.0 5.0 ⋅ + 7.0 8.0 9.0 +``` +""" +LowerTriangular +""" + UpperTriangular(A::AbstractMatrix) + +Construct an `UpperTriangular` view of the the matrix `A`. + +# Example + +```jldoctest +julia> A = [1.0 2.0 3.0; 4.0 5.0 6.0; 7.0 8.0 9.0] +3×3 Array{Float64,2}: + 1.0 2.0 3.0 + 4.0 5.0 6.0 + 7.0 8.0 9.0 + +julia> UpperTriangular(A) +3×3 UpperTriangular{Float64,Array{Float64,2}}: + 1.0 2.0 3.0 + ⋅ 5.0 6.0 + ⋅ ⋅ 9.0 +``` +""" +UpperTriangular + imag(A::UpperTriangular) = UpperTriangular(imag(A.data)) imag(A::LowerTriangular) = LowerTriangular(imag(A.data)) imag(A::UnitLowerTriangular) = LowerTriangular(tril!(imag(A.data),-1)) diff --git a/doc/src/manual/linear-algebra.md b/doc/src/manual/linear-algebra.md index af5ff9a2766f4e..16ba1b10fb70c8 100644 --- a/doc/src/manual/linear-algebra.md +++ b/doc/src/manual/linear-algebra.md @@ -144,29 +144,29 @@ specialized routines that are specially developed for particular matrix types. The following tables summarize the types of special matrices that have been implemented in Julia, as well as whether hooks to various optimized methods for them in LAPACK are available. -| Type | Description | -|:------------------------ |:-------------------------------------------------------------------------------- | -| [`Hermitian`](@ref) | [Hermitian matrix](https://en.wikipedia.org/wiki/Hermitian_matrix) | -| `UpperTriangular` | Upper [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) | -| `LowerTriangular` | Lower [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) | -| [`Tridiagonal`](@ref) | [Tridiagonal matrix](https://en.wikipedia.org/wiki/Tridiagonal_matrix) | -| [`SymTridiagonal`](@ref) | Symmetric tridiagonal matrix | -| [`Bidiagonal`](@ref) | Upper/lower [bidiagonal matrix](https://en.wikipedia.org/wiki/Bidiagonal_matrix) | -| [`Diagonal`](@ref) | [Diagonal matrix](https://en.wikipedia.org/wiki/Diagonal_matrix) | -| `UniformScaling` | [Uniform scaling operator](https://en.wikipedia.org/wiki/Uniform_scaling) | +| Type | Description | +|:------------------------- |:-------------------------------------------------------------------------------- | +| [`Hermitian`](@ref) | [Hermitian matrix](https://en.wikipedia.org/wiki/Hermitian_matrix) | +| [`UpperTriangular`](@ref) | Upper [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) | +| [`LowerTriangular`](@ref) | Lower [triangular matrix](https://en.wikipedia.org/wiki/Triangular_matrix) | +| [`Tridiagonal`](@ref) | [Tridiagonal matrix](https://en.wikipedia.org/wiki/Tridiagonal_matrix) | +| [`SymTridiagonal`](@ref) | Symmetric tridiagonal matrix | +| [`Bidiagonal`](@ref) | Upper/lower [bidiagonal matrix](https://en.wikipedia.org/wiki/Bidiagonal_matrix) | +| [`Diagonal`](@ref) | [Diagonal matrix](https://en.wikipedia.org/wiki/Diagonal_matrix) | +| `UniformScaling` | [Uniform scaling operator](https://en.wikipedia.org/wiki/Uniform_scaling) | ### Elementary operations -| Matrix type | `+` | `-` | `*` | `\` | Other functions with optimized methods | -|:------------------------ |:--- |:--- |:--- |:--- |:------------------------------------------------------------------- | -| [`Hermitian`](@ref) |   |   |   | MV | [`inv()`](@ref), [`sqrtm()`](@ref), [`expm()`](@ref) | -| `UpperTriangular` |   |   | MV | MV | [`inv()`](@ref), [`det()`](@ref) | -| `LowerTriangular` |   |   | MV | MV | [`inv()`](@ref), [`det()`](@ref) | -| [`SymTridiagonal`](@ref) | M | M | MS | MV | [`eigmax()`](@ref), [`eigmin()`](@ref) | -| [`Tridiagonal`](@ref) | M | M | MS | MV |   | -| [`Bidiagonal`](@ref) | M | M | MS | MV |   | -| [`Diagonal`](@ref) | M | M | MV | MV | [`inv()`](@ref), [`det()`](@ref), [`logdet()`](@ref), [`/()`](@ref) | -| `UniformScaling` | M | M | MVS | MVS | [`/()`](@ref) | +| Matrix type | `+` | `-` | `*` | `\` | Other functions with optimized methods | +|:------------------------- |:--- |:--- |:--- |:--- |:------------------------------------------------------------------- | +| [`Hermitian`](@ref) |   |   |   | MV | [`inv()`](@ref), [`sqrtm()`](@ref), [`expm()`](@ref) | +| [`UpperTriangular`](@ref) |   |   | MV | MV | [`inv()`](@ref), [`det()`](@ref) | +| [`LowerTriangular`](@ref) |   |   | MV | MV | [`inv()`](@ref), [`det()`](@ref) | +| [`SymTridiagonal`](@ref) | M | M | MS | MV | [`eigmax()`](@ref), [`eigmin()`](@ref) | +| [`Tridiagonal`](@ref) | M | M | MS | MV |   | +| [`Bidiagonal`](@ref) | M | M | MS | MV |   | +| [`Diagonal`](@ref) | M | M | MV | MV | [`inv()`](@ref), [`det()`](@ref), [`logdet()`](@ref), [`/()`](@ref) | +| `UniformScaling` | M | M | MVS | MVS | [`/()`](@ref) | Legend: @@ -178,15 +178,15 @@ Legend: ### Matrix factorizations -| Matrix type | LAPACK | [`eig()`](@ref) | [`eigvals()`](@ref) | [`eigvecs()`](@ref) | [`svd()`](@ref) | [`svdvals()`](@ref) | -|:------------------------ |:------ |:--------------- |:------------------- |:------------------- |:--------------- |:------------------- | -| [`Hermitian`](@ref) | HE |   | ARI |   |   |   | -| `UpperTriangular` | TR | A | A | A |   |   | -| `LowerTriangular` | TR | A | A | A |   |   | -| [`SymTridiagonal`](@ref) | ST | A | ARI | AV |   |   | -| [`Tridiagonal`](@ref) | GT |   |   |   |   |   | -| [`Bidiagonal`](@ref) | BD |   |   |   | A | A | -| [`Diagonal`](@ref) | DI |   | A |   |   |   | +| Matrix type | LAPACK | [`eig()`](@ref) | [`eigvals()`](@ref) | [`eigvecs()`](@ref) | [`svd()`](@ref) | [`svdvals()`](@ref) | +|:------------------------- |:------ |:--------------- |:------------------- |:------------------- |:--------------- |:------------------- | +| [`Hermitian`](@ref) | HE |   | ARI |   |   |   | +| [`UpperTriangular`](@ref) | TR | A | A | A |   |   | +| [`LowerTriangular`](@ref) | TR | A | A | A |   |   | +| [`SymTridiagonal`](@ref) | ST | A | ARI | AV |   |   | +| [`Tridiagonal`](@ref) | GT |   |   |   |   |   | +| [`Bidiagonal`](@ref) | BD |   |   |   | A | A | +| [`Diagonal`](@ref) | DI |   | A |   |   |   | Legend: diff --git a/doc/src/stdlib/linalg.md b/doc/src/stdlib/linalg.md index 66dde6330d3e8a..3e90cb5b2cafeb 100644 --- a/doc/src/stdlib/linalg.md +++ b/doc/src/stdlib/linalg.md @@ -18,6 +18,8 @@ Base.LinAlg.SymTridiagonal Base.LinAlg.Tridiagonal Base.LinAlg.Symmetric Base.LinAlg.Hermitian +Base.LinAlg.LowerTriangular +Base.LinAlg.UpperTriangular Base.LinAlg.lu Base.LinAlg.lufact Base.LinAlg.lufact!