specialmatrices_toeplitz Module


Uses

Used by


Interfaces

public interface Circulant

Utility function to embed an m x n Toeplitz matrix into an (m+n) x (m+n) Circulant matrix.

  • private pure module function Toeplitz2Circulant(T) result(C)

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: T

    Return Value type(Circulant)

public interface Toeplitz

This interface provides methods to construct Toeplitz matrices. Given a vector vc specifying the first column of the matrix and a vector vr specifying its first row, the associated Toeplitz matrix is the following matrix

Syntax

   integer, parameter :: m = 100, n = 200
   real(dp) :: vc(n), vr(n)
   type(Toeplitz) :: A

   call random_number(vc) ; call random_number(vr)
   A = Toeplitz(vc, vr)

Warning

The element is read from the first entry of the vector vc. The first entry of vr is not referenced.

Note

Only double precision is currently supported for this matrix type.

  • private pure module function construct(vc, vr) result(A)

    Construct a Toeplitz matrix from the rank-1 arrays vc and vr.

    Arguments

    Type IntentOptional Attributes Name
    real(kind=dp), intent(in) :: vc(:)

    First column of the matrix.
    real(kind=dp), intent(in) :: vr(:)

    First row of the matrix.

    Return Value type(Toeplitz)

    Corresponding Toeplitz matrix.

public interface dense

Convert a Toeplitz matrix to a standard rank-2 array.

Syntax

   B = dense(A)

Arguments

  • A : Matrix of Toeplitz type. It is an intent(in) argument.

  • B : Rank-2 array representation of the matrix .

  • private pure module function dense_rdp(A) result(B)

    Utility function to convert a Toeplitz matrix to a rank-2 array.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input diagonal matrix.

    Return Value real(kind=dp), allocatable, (:,:)

    Output dense rank-2 array.

public interface eig

This interface overloads the eig interface from stdlib_linalg to compute the eigenvalues and eigenvectors of a real-valued matrix whose type is Toeplitz.

Syntax

   call eig(A, lambda [, left] [, right])

Arguments

  • A : real-valued matrix of Toeplitz. It is an intent(in) argument.

  • lambda : Rank-1 real array returning the eigenvalues of A in increasing order. It is an intent(out) argument.

  • left (optional) : complex rank-2 array of the same kind as A returning the left eigenvectors of A. It is an intent(out) argument.

  • right (optional) : complex rank-2 array of the same kind as A returning the right eigenvectors of A. It is an intent(out) argument.

Note

No analytic expression exist for the eigendecomposition of a general Toeplitz matrix. Under the hood, the matrix A is converted to its dense representation and the function eig from stdlib_linalg is used.

  • private module subroutine eig_rdp(A, lambda, left, right)

    Utility function to compute the eigenvalues and eigenvectors of a Toeplitz matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.
    complex(kind=dp), intent(out) :: lambda(:)

    Eigenvalues.
    complex(kind=dp), intent(out), optional :: left(:,:)

    Eigenvectors.
    complex(kind=dp), intent(out), optional :: right(:,:)

    Eigenvectors.

public interface eigvals

This interface overloads the eigvals interface from stdlib_linalg to compute the eigenvalues of a real-valued matrix whose type is Toeplitz.

Syntax

   lambda = eigvals(A)

Arguments

  • A : real-valued matrix of Toeplitz type. It is an intent(in) argument.

  • lambda : Vector of eigenvalues in increasing order.

Note

No analytic expression exist for the eigenvalues of a general Toeplitz matrix. Under the hood, the matrix A is converted to its dense representation and the function eigvals from stdlib_linalg is used.

  • private module function eigvals_rdp(A) result(lambda)

    Utility function to compute the eigenvalues of a real Toeplitz matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.

    Return Value complex(kind=dp), allocatable, (:)

    Eigenvalues.

public interface matmul

This interface overloads the Fortran intrinsic matmul for a Toeplitz matrix, both for matrix-vector and matrix-matrix products. For a matrix-matrix product , only the matrix has to be a Toeplitz matrix. Both and need to be standard Fortran rank-2 arrays. All the underlying functions are defined as pure.

Syntax

   y = matmul(A, x)

Note

Matrix-vector products for Toeplitz matrices can be efficiently computed by embedding the Toeplitz matrix into a Circulant matrix of size [m+n x m+n] and using the Fast Fourier Transform provided by fftpack.

  • private pure module function spmv(A, x) result(y)

    Compute the matrix-vector product for a Toeplitz matrix . Both x and y are rank-1 arrays with the same kind as A.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.
    real(kind=dp), intent(in) :: x(:)

    Input vector.

    Return Value real(kind=dp), allocatable, (:)

    Output vector.

  • private pure module function spmvs(A, x) result(y)

    Compute the matrix-matrix product for a Toeplitz matrix A. Both X and Y are rank-2 arrays with the same kind as A.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.
    real(kind=dp), intent(in) :: x(:,:)

    Input matrix.

    Return Value real(kind=dp), allocatable, (:,:)

    Output matrix.

public interface operator(*)

  • private pure module function scalar_multiplication_bis_rdp(A, alpha) result(B)

    Utility function to perform a scalar multiplication with a Toeplitz matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A
    real(kind=dp), intent(in) :: alpha

    Return Value type(Toeplitz)

  • private pure module function scalar_multiplication_rdp(alpha, A) result(B)

    Utility function to perform a scalar multiplication with a Toeplitz matrix.

    Arguments

    Type IntentOptional Attributes Name
    real(kind=dp), intent(in) :: alpha
    type(Toeplitz), intent(in) :: A

    Return Value type(Toeplitz)

public interface shape

Utility function to return the size of a Toeplitz matrix.

  • private pure module function shape_rdp(A) result(arr_shape)

    Utility function to get the shape of a Toeplitz matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.

    Return Value integer(kind=ilp), (2)

    Shape of the matrix.

public interface size

Utility function to return the size of Toeplitz matrix along a given dimension.

  • private pure module function size_rdp(A, dim) result(arr_size)

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.
    integer(kind=ilp), intent(in), optional :: dim

    Queried dimension.

    Return Value integer(kind=ilp)

    Size of the matrix along the dimension dim.

public interface solve

This interface overloads the solve interface from stdlib_linalg for solving a linear system where is a Toeplitz matrix. It also enables to solve a linear system with multiple right-hand sides.

Syntax

To solve a system with being of type Toeplitz:

   x = solve(A, b)

Arguments

  • A : Matrix of Toeplitz type. It is an intent(in) argument.

  • b : Rank-1 or rank-2 array defining the right-hand side(s). It is an intent(in) argument.

  • x : Solution of the linear system. It has the same type and shape as b.

Note

Under the hood, a gmres solver is being used along with a Circulant preconditioner. By design, gmres is run until a relative tolerance of is reached.

  • private pure module function solve_multi_rhs(A, B) result(X)

    Solve the linear system , where A is Toeplitz and B is a rank-2 array. The solution matrix X has the same dimension and kind as the right-hand side matrix B.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Coefficient matrix.
    real(kind=dp), intent(in) :: B(:,:)

    Right-hand side vectors.

    Return Value real(kind=dp), allocatable, (:,:)

    Solution vectors.

  • private pure module function solve_single_rhs(A, b) result(x)

    Solve the linear system where is Toeplitz and b a standard rank-1 array. The solution vector x has the same dimension and kind as the right-hand side vector b.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Coefficient matrix.
    real(kind=dp), intent(in) :: b(:)

    Right-hand side vector.

    Return Value real(kind=dp), allocatable, (:)

    Solution vector.

public interface svd

This interface overloads the svd interface from stdlib_linalg to compute the the singular value decomposition of a Toeplitz matrix .

Syntax

   call svd(A, s, u, vt)

Arguments

  • A : Matrix of Toeplitz type. It is an intent(in) argument.

  • s : Rank-1 array real array returning the singular values of A. It is an intent(out) argument.

  • u (optional) : Rank-2 array of the same kind as A returning the left singular vectors of A as columns. Its size should be [n, n]. It is an intent(out) argument.

  • vt (optional) : Rank-2 array of the same kind as A returning the right singular vectors of A as rows. Its size should be [n, n]. It is an intent(out) argument.

Note

No analytic expression exist for the singular value of a general Toeplitz matrix. Under the hood, the matrix A is converted to its dense representation and the function svdvals from stdlib_linalg is used.

  • private module subroutine svd_rdp(A, s, u, vt)

    Compute the singular value decomposition of a Toeplitz matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.
    real(kind=dp), intent(out) :: s(:)

    Singular values in descending order.
    real(kind=dp), intent(out), optional :: u(:,:)

    Left singular vectors as columns.
    real(kind=dp), intent(out), optional :: vt(:,:)

    Right singular vectors as rows.

public interface svdvals

This interface overloads the svdvals interface from stdlib_linalg to compute the singular values of a Toeplitz matrix .

Syntax

   s = svdvals(A)

Arguments

  • A : Matrix of Toeplitz type. It is an intent(in) argument.

  • s : Vector of singular values sorted in decreasing order.

Note

No analytic expression exist for the singular values of a general Toeplitz matrix. Under the hood, the matrix A is converted to its dense representation and the function svdvals from stdlib_linalg is used.

  • private module function svdvals_rdp(A) result(s)

    Compute the singular values of a Toeplitz matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.

    Return Value real(kind=dp), allocatable, (:)

    Singular values in descending order.

public interface transpose

This interface overloads the Fortran intrinsic procedure to define the transpose operation of a Toeplitz matrix.

Syntax

   B = transpose(A)

Arguments

  • A : Matrix of Toeplitz type. It is an intent(in) argument.

  • B : Resulting transposed matrix. It is of the same type as A.

  • private pure module function transpose_rdp(A) result(B)

    Utility function to compute the transpose of a Toeplitz matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Toeplitz), intent(in) :: A

    Input matrix.

    Return Value type(Toeplitz)

    Transpose of the matrix.


Derived Types

type, public ::  Toeplitz

Base type to define a Toeplitz matrix of size [m x n]. The first column is given by the vector vc while the first row is given by vr.

Constructor

This interface provides methods to construct Toeplitz matrices. Given a vector vc specifying the first column of the matrix and a vector vr specifying its first row, the associated Toeplitz matrix is the following matrix

Read more…
private pure, module function construct (vc, vr)

Construct a Toeplitz matrix from the rank-1 arrays vc and vr.