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 TypedMatricesSetup
The first step is, as usual, to load the package:
julia> using TypedMatricesThe list of available matrices can be obtained with list_matrices:
julia> matrix_list = list_matrices()62-element Vector{Type{<:AbstractMatrix}}: Involutory Randcorr Neumann Lehmer Lesp GCDMat ChebSpec Lauchli Kahan Rosser ⋮ Cauchy Fiedler Wilkinson Ipjfact Orthog Clement InverseHilbert Prolate Sampling
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 Involutory{Rational{Int64}}: -4 1//2 1//3 1//4 -120 20 15 12 240 -45 -36 -30 -140 28 70//3 20
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(:integer) Property(:rectangular) Property(:eigen) Property(:hankel) Property(:totpos) Property(:random) Property(:rankdef) Property(:triangular) Property(:bidiagonal) Property(:circulant) ⋮ Property(:totnonneg) Property(:defective) Property(:graph) Property(:hessenberg) Property(:tridiagonal) Property(:correlation) Property(:nilpotent) Property(:unitary) Property(:orthogonal)
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))ERROR: UndefVarError: `issymmetric` not defined in `Main.var"Main"` Suggestion: check for spelling errors or missing imports. Hint: a global variable of this name may be made accessible by importing LinearAlgebra in the current active module Mainjulia> issymmetric(Clement(5, 1))ERROR: UndefVarError: `issymmetric` not defined in `Main.var"Main"` Suggestion: check for spelling errors or missing imports. Hint: a global variable of this name may be made accessible by importing LinearAlgebra in the current active module Mainjulia> 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))ERROR: UndefVarError: `issymmetric` not defined in `Main.var"Main"` Suggestion: check for spelling errors or missing imports. Hint: a global variable of this name may be made accessible by importing LinearAlgebra in the current active module Main
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.00155784julia> 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.0julia> 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:
- from a specific group, with
remove_from_group, or - from all groups, with
remove_from_all_groups.
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))62-element Vector{Type{<:AbstractMatrix}}: Involutory Randcorr Neumann Lehmer Lesp GCDMat ChebSpec Lauchli Kahan Rosser ⋮ Cauchy Fiedler Wilkinson Ipjfact Orthog Clement InverseHilbert Prolate Samplingjulia> list_matrices(Property(:symmetric))22-element Vector{Type{<:AbstractMatrix}}: Randcorr Lehmer GCDMat Rosser Moler Pascal KMS Poisson Hankel Minij ⋮ Wathen RIS Cauchy Fiedler Wilkinson Ipjfact Clement InverseHilbert Prolate
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}}: Involutory Pascal Forsythe Lotkin
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)4-element Vector{Type{<:AbstractMatrix}}: Pascal Poisson Minij 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.