specialmatrices_circulant Module


Uses

    • stdlib_linalg_constants
    • fftpack

Used by


Interfaces

public interface Circulant

This interface provides methods to construct Circulant matrices. Given a vector , the associated Circulant matrix is the following [n x n] matrix

Syntax

   integer, parameter :: n = 100
   real(dp) :: c(n)
   type(Circulant) :: A

   call random_number(c)
   A = Circulant(c)

Note

Only double precision is currently supported for this matrix type.

  • private pure module function construct(c) result(A)

    Construct a Circulant matrix from the rank-1 array c.

    Arguments

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

    Generating vector.

    Return Value type(Circulant)

    Corresponding Circulant matrix.

public interface dense

Convert a Circulant matrix to its dense representation.

Syntax

   B = dense(A)

Arguments

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

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

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

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

    Arguments

    Type IntentOptional Attributes Name
    type(Circulant), 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 Circulant.

Syntax

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

Arguments

  • A : real-valued matrix of Circulant. 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

Eigenvalues of a circulant matrix can be efficiently computed using the Fast Fourier Transform of the generating vector c. Likewise, its eigenvectors are simply the corresponding Fourier modes.

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

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

    Arguments

    Type IntentOptional Attributes Name
    type(Circulant), 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 Circulant.

Syntax

   lambda = eigvals(A)

Arguments

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

  • lambda : Vector of eigenvalues in increasing order.

Note

Eigenvalues of a circulant matrix can be efficiently computed using the Fast Fourier Transform of the generating vector c.

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

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

    Arguments

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

    Input matrix.

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

    Eigenvalues.

public interface inv

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

    Utility function to compute the inverse of a Circulant matrix. If A is circulant, its inverse also is circulant.

    Arguments

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

    Input matrix.

    Return Value type(Circulant)

    Inverse of A.

public interface matmul

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

Syntax

   y = matmul(A, x)

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

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

    Arguments

    Type IntentOptional Attributes Name
    type(Circulant), 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 Circulant matrix A. Both X and Y are rank-2 arrays with the same kind as A.

    Arguments

    Type IntentOptional Attributes Name
    type(Circulant), 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 Circulant matrix.

    Arguments

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

    Return Value type(Circulant)

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

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

    Arguments

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

    Return Value type(Circulant)

public interface shape

Utility function to return the shape of a Circulant matrix.

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

    Utility function to get the shape of a Circulant matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Circulant), 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 a Circulant matrix along a given dimension.

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

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

    Arguments

    Type IntentOptional Attributes Name
    type(Circulant), 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 Circulant matrix. It also enables to solve a linear system with multiple right-hand sides.

Syntax

   x = solve(A, b)

Arguments

  • A : Matrix of Circulant 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

Linear systems characterized by a circulant matrix can be solved efficiently in operations using the Fast Fourier Transform algorithm available via fftpack.

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

    Solve the linear system , where A is Circulant 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(Circulant), 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 Circulant 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(Circulant), 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 Circulant matrix .

Syntax

   call svd(A, s, u, vt)

Arguments

  • A : Matrix of Circulant 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

Singular values and singular vectors of a Circulant matrix can be efficiently computed based on the Fast Fourier transform.

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

    Compute the singular value decomposition of a Circulant matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Circulant), 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 Circulant matrix .

Syntax

   s = svdvals(A)

Arguments

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

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

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

    Compute the singular values of a Circulant matrix.

    Arguments

    Type IntentOptional Attributes Name
    type(Circulant), 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 Circulant matrix.

Syntax

   B = transpose(A)

Arguments

  • A : Matrix of Circulant. 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 Circulant matrix.

    Arguments

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

    Input matrix.

    Return Value type(Circulant)

    Transpose of the matrix.


Derived Types

type, public ::  Circulant

Base type to define a Circulant matrix of size [n x n] with elements given by the vector

Constructor

This interface provides methods to construct Circulant matrices. Given a vector , the associated Circulant matrix is the following [n x n] matrix

Read more…
private pure, module function construct (c)

Construct a Circulant matrix from the rank-1 array c.