GitHub

Getting Started

Installation

TypedMatrices.jl is registered in the Julia package registry, and Julia's builtin package manager can be used to install it:

pkg> add TypedMatrices

Setup

The first step is, as usual, to load the package:

julia> using LinearAlgebra, TypedMatrices

The list of available matrices can be obtained with list_matrices:

julia> matrix_list = list_matrices()63-element Vector{Type{<:AbstractMatrix}}:
 GCDMat
 Wilkinson
 ChebSpec
 Toeplitz
 Pascal
 Rosser
 Randcolu
 Lauchli
 Parter
 Triw
 ⋮
 DingDong
 Pei
 Companion
 Hankel
 Magic
 Krylov
 Cycol
 Hadamard
 Wathen

The function returns a Vector of matrix types, which are subtypes of AbstractMatrix. The elements of this Vector can be used to generate matrices:

julia> matrix_list[1](4)4×4 GCDMat{Int64}:
 1  1  1  1
 1  2  1  2
 1  1  3  1
 1  2  1  4

Generating Matrices

Each type of special matrices has its own type and constructors. For example, a 5 × 5 Hilbert matrix can be generated with:

julia> h = Hilbert(5)5×5 Hilbert{Rational{Int64}}:
  1    1//2  1//3  1//4  1//5
 1//2  1//3  1//4  1//5  1//6
 1//3  1//4  1//5  1//6  1//7
 1//4  1//5  1//6  1//7  1//8
 1//5  1//6  1//7  1//8  1//9

Most matrices can accept a type parameter to specify the element type. For example, a 5 × 5 Hilbert matrix with Float64 elements can be generated with:

julia> Hilbert{Float64}(5)5×5 Hilbert{Float64}:
 1.0       0.5       0.333333  0.25      0.2
 0.5       0.333333  0.25      0.2       0.166667
 0.333333  0.25      0.2       0.166667  0.142857
 0.25      0.2       0.166667  0.142857  0.125
 0.2       0.166667  0.142857  0.125     0.111111

Please check the list of Builtin Matrices for an overview of all available types.

Properties

Matrices have properties, such as "symmetric", "ill conditioned", or "positive definite".

The function list_properties can be used to show all properties currently defined in TypedMatrices.jl:

julia> list_properties()40-element Vector{Property}:
 Property(:tridiagonal)
 Property(:rectangular)
 Property(:hermitian)
 Property(:singval)
 Property(:diagdom)
 Property(:defective)
 Property(:hessenberg)
 Property(:triangular)
 Property(:rankdef)
 Property(:correlation)
 ⋮
 Property(:nonneg)
 Property(:unitary)
 Property(:circulant)
 Property(:illcond)
 Property(:orthogonal)
 Property(:graph)
 Property(:eigen)
 Property(:infdiv)
 Property(:posdef)

The function properties can used to get the properties of a given matrix type:

julia> properties(Hilbert)11-element Vector{Property}:
 Property(:hankel)
 Property(:illcond)
 Property(:inverse)
 Property(:posdef)
 Property(:totpos)
 Property(:symmetric)
 Property(:possemidef)
 Property(:hermitian)
 Property(:normal)
 Property(:positive)
 Property(:nonneg)

For convenience, the same function can be used to list the properties of a matrix instance, rather than a type:

julia> properties(h)11-element Vector{Property}:
 Property(:hankel)
 Property(:illcond)
 Property(:inverse)
 Property(:posdef)
 Property(:totpos)
 Property(:symmetric)
 Property(:possemidef)
 Property(:hermitian)
 Property(:normal)
 Property(:positive)
 Property(:nonneg)

Some matrix properties depend on the specific constructor or parameters used. For example, the Clement matrix is symmetric if generated with Clement(n, 1), but not if Clement(n, 1) if is used. The function properties returns a list of all the properties that a matrix is known to satisfy for at least some constructors or combination of input parameters.

julia> issymmetric(Clement(5, 0))false
julia> issymmetric(Clement(5, 1))true
julia> Property(:symmetric) in properties(Clement)true

All matrix types provide a special constructor where the user only specifies a list of properties and a size. This constructor guarantees that the generated matrix will have the required properties.

julia> issymmetric(Clement([:symmetric], 5))true

If a matrix of the specified type with all the required properties cannot be generated, then an ArgumentError error is thrown. For example, the Kahan matrix cannot be both ill-conditioned and rectangular simultaneously.

julia> Kahan([:illcond], 5)5×5 Kahan{Float64}:
 1.0  -0.980067  -0.980067   -0.980067    -0.980067
 0.0   0.198669  -0.194709   -0.194709    -0.194709
 0.0   0.0        0.0394695  -0.0386827   -0.0386827
 0.0   0.0        0.0         0.00784138  -0.00768507
 0.0   0.0        0.0         0.0          0.00155784
julia> Kahan([:rectangular], 5)10×5 Kahan{Float64}:
 1.0  -0.362358  -0.362358  -0.362358  -0.362358
 0.0   0.932039  -0.337732  -0.337732  -0.337732
 0.0   0.0        0.868697  -0.314779  -0.314779
 0.0   0.0        0.0        0.809659  -0.293386
 0.0   0.0        0.0        0.0        0.754634
 0.0   0.0        0.0        0.0        0.0
 0.0   0.0        0.0        0.0        0.0
 0.0   0.0        0.0        0.0        0.0
 0.0   0.0        0.0        0.0        0.0
 0.0   0.0        0.0        0.0        0.0
julia> Kahan([:illcond, :rectangular], 5)ERROR: ArgumentError: No constructor for the given set of properties: $input_properties

Grouping

Matrices can be organized by creating user-defined groups. All builtin matrices belong to the :builtin group, and the package comes with an empty :user group for user-defined matrices. All available groups can be listed with:

julia> list_groups()2-element Vector{Group}:
 Group(:user)
 Group(:builtin)

The function add_to_groups can be used to add a matrix to a group:

julia> add_to_groups(Matrix, :user, :test)

The function list_matrices can be used to list the matrices that belong to a chosen group:

julia> list_matrices(Group(:user))1-element Vector{Type{<:AbstractMatrix}}:
 Matrix (alias for Array{T, 2} where T)

Builtin matrices can also be added to a group:

julia> add_to_groups(Hilbert, :test)
julia> list_matrices(Group(:test))2-element Vector{Type{<:AbstractMatrix}}:
 Hilbert
 Matrix (alias for Array{T, 2} where T)

A matrix can be removed:

Matrices cannot be removed from the :builtin group, and user-defined groups are automatically removed when they become empty:

julia> remove_from_group(Hilbert, :test)
julia> remove_from_all_groups(Matrix)
julia> list_groups()2-element Vector{Group}:
 Group(:user)
 Group(:builtin)

Finding Matrices

list_matrices is a powerful function to search for matrices, and filter the results by groups or properties. All arguments are "and" relationship, meaning that only matrices that satisfy all conditions will be retained.

For example, one can list all the matrices in the :builtin group, or all those that are satisfy the :symmetric property:

julia> list_matrices(Group(:builtin))63-element Vector{Type{<:AbstractMatrix}}:
 GCDMat
 Wilkinson
 ChebSpec
 Toeplitz
 Pascal
 Rosser
 Randcolu
 Lauchli
 Parter
 Triw
 ⋮
 DingDong
 Pei
 Companion
 Hankel
 Magic
 Krylov
 Cycol
 Hadamard
 Wathen
julia> list_matrices(Property(:symmetric))23-element Vector{Type{<:AbstractMatrix}}:
 GCDMat
 Wilkinson
 Pascal
 Rosser
 Strakos
 Cauchy
 Moler
 RIS
 Fiedler
 Clement
 ⋮
 Prolate
 Randcorr
 Poisson
 Hilbert
 KMS
 DingDong
 Pei
 Hankel
 Wathen

One can also combine the two filters and show all matrices in the :builtin group that satisfy the :inverse, :illcond, and :eigen properties:

julia> list_matrices(
           [
               Group(:builtin),
           ],
           [
               Property(:inverse),
               Property(:illcond),
               Property(:eigen),
           ]
       )4-element Vector{Type{<:AbstractMatrix}}:
 Pascal
 Lotkin
 Forsythe
 Involutory

A simpler syntax can be used to list all matrices that satisfy a list of properties. For example, all matrices with :symmetric, :eigen, and :posdef can be listed with:

julia> list_matrices(:symmetric, :eigen, :posdef)5-element Vector{Type{<:AbstractMatrix}}:
 Pascal
 Strakos
 Minij
 Poisson
 Wathen

The list_matrices functions provides a number of alternative interfaces. Check the full documentation of list_matrices or use the Julia help system for a complete list.