imate.toeplitz

imate.toeplitz(a, b, size=20, gram=False, format='csr', dtype='float64')

Generate a sparse Toeplitz matrix for test purposes.

A bi-diagonal Toeplitz matrix is generated using a and b as

(1)\[ \begin{align}\begin{aligned}\mathbf{A} = \begin{bmatrix} a & b & 0 &\cdots & \cdots & 0 \\\ 0 & a & b & \ddots && \vdots \\\ 0 & 0 & \ddots & \ddots & \ddots & \vdots \\\ \vdots & \ddots & \ddots & \ddots & b & 0 \\\ \vdots & & \ddots & 0 & a & b \\\ 0 & \cdots & \cdots & 0 & 0 & a \end{bmatrix}\end{aligned}\end{align} \]

If gram=True, the Gramian of the above matrix is generated, which is \(\mathbf{B} = \mathbf{A}^{\intercal} \mathbf{A}\), namely

(2)\[ \begin{align}\begin{aligned}\mathbf{B} = \begin{bmatrix} a^2 & ab & 0 &\cdots & \cdots & 0 \\\ ab & a^2+b^2 & ab & \ddots && \vdots \\\ 0 & ab & \ddots & \ddots & \ddots & \vdots \\\ \vdots & \ddots & \ddots & \ddots & b & 0 \\\ \vdots & & \ddots & ab & a^2+b^2 & ab \\\ 0 & \cdots & \cdots & 0 & ab & a^2+b^2 \end{bmatrix}\end{aligned}\end{align} \]

Parameters:

afloat

The diagonal elements of the Toeplitz matrix.

bfloat

The upper off-diagonals element of the Toeplitz matrix.

sizeint, default=20

Size of the square matrix.

grambool, default=False

If False, the bi-diagonal matrix \(\mathbf{A}\) in (1) is returned. If True, the Gramian tri-diagonal matrix \(\mathbf{B}\) in (2) is returned.

format{‘csr’, ‘csc’}, default=’csr’

The format of the sparse matrix. CSR is the compressed sparse row and CSC is the compressed sparse column format.

dtype{‘float32’, ‘float64’, ‘float128’}, default=’float64’

The data type of the matrix.

Returns:

Ascipy.sparse.csr or scipy.sparse.csc, (n, n)

Bi-diagonal or tri-diagonal (if grid=True) Toeplitz matrix

See also

imate.correlation_matrix

imate.sample_matrices.toeplitz_logdet

imate.sample_matrices.toeplitz_trace

imate.sample_matrices.toeplitz_traceinv

Notes

The matrix functions of the Toeplitz matrix (such as log-determinant, trace of its inverse, etc) is known analytically. As such, this matrix can be used to test the accuracy of randomized algorithms for computing matrix functions.

Warning

All eigenvalues of the generated Toeplitz matrix are equal to \(a\). So, in applications where a matrix with distinct eigenvalues is needed, this matrix is not suitable. For such applications, use imate.correlation_matrix() instead.

To generate a symmetric and positive-definite matrix, set gram to True.

Examples

Generate bi-diagonal matrix:

>>> from imate.sample_matrices import toeplitz
>>> a, b = 2, 3

>>> # Bi-diagonal matrix
>>> A = toeplitz(a, b, size=6, format='csr', dtype='float128')

>>> print(A.dtype)
dtype('float128')

>>> print(type(A))
scipy.sparse.csr.csr_matrix

>>> # Convert sparse to dense numpy array to display the matrix
>>> A.toarray()
array([[2., 3., 0., 0., 0., 0.],
       [0., 2., 3., 0., 0., 0.],
       [0., 0., 2., 3., 0., 0.],
       [0., 0., 0., 2., 3., 0.],
       [0., 0., 0., 0., 2., 3.],
       [0., 0., 0., 0., 0., 2.]])

Create a tri-diagonal Matrix:

>>> # Tri-diagonal Gramian matrix
>>> B = toeplitz(a, b, size=6, gram=True)
>>> B.toarray()
array([[ 4.,  6.,  0.,  0.,  0.,  0.],
       [ 6., 13.,  6.,  0.,  0.,  0.],
       [ 0.,  6., 13.,  6.,  0.,  0.],
       [ 0.,  0.,  6., 13.,  6.,  0.],
       [ 0.,  0.,  0.,  6., 13.,  6.],
       [ 0.,  0.,  0.,  0.,  6., 13.]])