Add ToeplitzFactorization (#60)

* Add `ToeplitzFactorization`

* Update tests

* Update README

* Fix CI workflow

* Bump version

Co-authored-by: Sheehan Olver <[email protected]>

.github/workflows/CI.yml

@@ -3,7 +3,7 @@ name: CI
 on:
   push:
     branches:
-      - main
+      - master
   pull_request:
 
 jobs:

Project.toml

@@ -1,6 +1,6 @@
 name = "ToeplitzMatrices"
 uuid = "c751599d-da0a-543b-9d20-d0a503d91d24"
-version = "0.6.3"
+version = "0.7.0"
 
 [deps]
 AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"

README.md

@@ -10,7 +10,9 @@ for Toeplitz, Hankel and circulant matrices in Julia
 
 # Note
 
-Some computations such as multiplication of large matrices are performed with FFTs.
+Multiplication of large matrices and `sqrt`, `inv`, `LinearAlgebra.eigvals`,
+`LinearAlgebra.ldiv!`, and `LinearAlgebra.pinv` for circulant matrices
+are computed with FFTs.
 To be able to use these methods, you have to install and load a package that implements
 the [AbstractFFTs.jl](https://github.com/JuliaMath/AbstractFFTs.jl) interface such
 as [FFTW.jl](https://github.com/JuliaMath/FFTW.jl):
@@ -19,15 +21,22 @@ as [FFTW.jl](https://github.com/JuliaMath/FFTW.jl):
 using FFTW
 ```
 
-## ToeplitzMatrix
+If you perform multiple calculations with FFTs, it can be more efficient to
+initialize the required arrays and plan the FFT only once. You can precompute
+the FFT factorization with `LinearAlgebra.factorize` and then use the factorization
+for the FFT-based computations.
 
-A Toeplitz matrix has constant diagonals.  It can be constructed using
+# Supported matrices
+
+## Toeplitz
+
+A Toeplitz matrix has constant diagonals. It can be constructed using
 
 ```julia
 Toeplitz(vc,vr)
 ```
 
-where `vc` are the entries in the first column and `vr` are the entries in the first row, where `vc[1]` must equal `vr[1]`.  For example.
+where `vc` are the entries in the first column and `vr` are the entries in the first row, where `vc[1]` must equal `vr[1]`. For example.
 
 ```julia
 Toeplitz(1:3, [1.,4.,5.])
@@ -41,6 +50,28 @@ is a sparse representation of the matrix
   3.0  2.0  1.0 ]
 ```
 
+## SymmetricToeplitz
+
+A symmetric Toeplitz matrix is a symmetric matrix with constant diagonals. It can be constructed with
+
+```julia
+SymmetricToeplitz(vc)
+```
+
+where `vc` are the entries of the first column. For example,
+
+```julia
+SymmetricToeplitz([1.0, 2.0, 3.0])
+```
+
+is a sparse representation of the matrix
+
+```julia
+[ 1.0  2.0  3.0
+  2.0  1.0  2.0
+  3.0  2.0  1.0 ]
+```
+
 ## TriangularToeplitz
 
 A triangular Toeplitz matrix can be constructed using
@@ -52,57 +83,56 @@ TriangularToeplitz(ve,uplo)
 where uplo is either `:L` or `:U` and `ve` are the rows or columns, respectively.  For example,
 
 ```julia
- TriangularToeplitz([1.,2.,3.],:L)
- ```
+TriangularToeplitz([1.,2.,3.],:L)
+```
+
+is a sparse representation of the matrix
 
- is a sparse representation of the matrix
+```julia
+[ 1.0  0.0  0.0
+  2.0  1.0  0.0
+  3.0  2.0  1.0 ]
+```
 
- ```julia
- [ 1.0  0.0  0.0
-   2.0  1.0  0.0
-   3.0  2.0  1.0 ]
- ```
+## Hankel
 
- # Hankel
+A Hankel matrix has constant anti-diagonals.  It can be constructed using
 
- A Hankel matrix has constant anti-diagonals.  It can be constructed using
+```julia
+Hankel(vc,vr)
+```
 
- ```julia
- Hankel(vc,vr)
- ```
+where `vc` are the entries in the first column and `vr` are the entries in the last row, where `vc[end]` must equal `vr[1]`.  For example.
 
- where `vc` are the entries in the first column and `vr` are the entries in the last row, where `vc[end]` must equal `vr[1]`.  For example.
+```julia
+Hankel([1.,2.,3.], 3:5)
+```
 
- ```julia
- Hankel([1.,2.,3.], 3:5)
- ```
+is a sparse representation of the matrix
 
- is a sparse representation of the matrix
+```julia
+[  1.0  2.0  3.0
+   2.0  3.0  4.0
+   3.0  4.0  5.0 ]
+```
 
- ```julia
- [  1.0  2.0  3.0
-    2.0  3.0  4.0
-    3.0  4.0  5.0 ]
- ```
+## Circulant
 
+A circulant matrix is a special case of a Toeplitz matrix with periodic end conditions.
+It can be constructed using
 
- # Circulant
-
- A circulant matrix is a special case of a Toeplitz matrix with periodic end conditions.
- It can be constructed using
-
- ```julia
- Circulant(vc)
- ```
+```julia
+Circulant(vc)
+```
 where `vc` is a vector with the entries for the first column.
 For example:
 ```julia
- Circulant(1:3)
- ```
- is a sparse representation of the matrix
+Circulant([1.0, 2.0, 3.0])
+```
+is a sparse representation of the matrix
 
- ```julia
- [  1.0  3.0  2.0
-    2.0  1.0  3.0
-    3.0  2.0  1.0 ]
- ```
+```julia
+[  1.0  3.0  2.0
+   2.0  1.0  3.0
+   3.0  2.0  1.0 ]
+```