LightKrylov_Utils Module

This module provides a set of utility functions used throughout LightKrylov. It includes:

  • assert_shape: Assert that the shape of the argument is the expected shape.
  • eig: Compute the eigenvalue decomposition of a general matrix.
  • sqrtm: Compute the non-negative square root of a symmetric positive definite matrix using its SVD.
  • ordschur: Re-order the Schur factorization to have the selected eigenvalues in the upper left block.

Note that as the development of stdlib progresses, some of these functions will be deprecated in favor of the stdlib implementations.


Uses

Used by


Interfaces

public interface apply_givens_rotation

  • private pure module subroutine apply_givens_rotation_cdp(h, c, s)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(inout) :: h(:)

    k-th column of the Hessenberg matrix.
    complex(kind=dp), intent(inout) :: c(:)

    Cosine components of the Givens rotations.
    complex(kind=dp), intent(inout) :: s(:)

    Sine components of the Givens rotations.

  • private pure module subroutine apply_givens_rotation_csp(h, c, s)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(inout) :: h(:)

    k-th column of the Hessenberg matrix.
    complex(kind=sp), intent(inout) :: c(:)

    Cosine components of the Givens rotations.
    complex(kind=sp), intent(inout) :: s(:)

    Sine components of the Givens rotations.

  • private pure module subroutine apply_givens_rotation_rdp(h, c, s)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=dp), intent(inout) :: h(:)

    k-th column of the Hessenberg matrix.
    real(kind=dp), intent(inout) :: c(:)

    Cosine components of the Givens rotations.
    real(kind=dp), intent(inout) :: s(:)

    Sine components of the Givens rotations.

  • private pure module subroutine apply_givens_rotation_rsp(h, c, s)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(inout) :: h(:)

    k-th column of the Hessenberg matrix.
    real(kind=sp), intent(inout) :: c(:)

    Cosine components of the Givens rotations.
    real(kind=sp), intent(inout) :: s(:)

    Sine components of the Givens rotations.

public interface assert_shape

This interface provides methods to assert tha thte shape of its input vector or matrix is as expected. It throws an error if not.

  • private module subroutine assert_shape_matrix_cdp(A, size, matname, module, procedure)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(in) :: A(:,:)
    integer, intent(in) :: size(:)
    character(len=*), intent(in) :: matname
    character(len=*), intent(in) :: module
    character(len=*), intent(in) :: procedure

  • private module subroutine assert_shape_matrix_csp(A, size, matname, module, procedure)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(in) :: A(:,:)
    integer, intent(in) :: size(:)
    character(len=*), intent(in) :: matname
    character(len=*), intent(in) :: module
    character(len=*), intent(in) :: procedure

  • private module subroutine assert_shape_matrix_rdp(A, size, matname, module, procedure)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=dp), intent(in) :: A(:,:)
    integer, intent(in) :: size(:)
    character(len=*), intent(in) :: matname
    character(len=*), intent(in) :: module
    character(len=*), intent(in) :: procedure

  • private module subroutine assert_shape_matrix_rsp(A, size, matname, module, procedure)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(in) :: A(:,:)
    integer, intent(in) :: size(:)
    character(len=*), intent(in) :: matname
    character(len=*), intent(in) :: module
    character(len=*), intent(in) :: procedure

  • private module subroutine assert_shape_vector_cdp(v, size, vecname, module, procedure)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(in) :: v(:)
    integer, intent(in) :: size(:)
    character(len=*), intent(in) :: vecname
    character(len=*), intent(in) :: module
    character(len=*), intent(in) :: procedure

  • private module subroutine assert_shape_vector_csp(v, size, vecname, module, procedure)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(in) :: v(:)
    integer, intent(in) :: size(:)
    character(len=*), intent(in) :: vecname
    character(len=*), intent(in) :: module
    character(len=*), intent(in) :: procedure

  • private module subroutine assert_shape_vector_rdp(v, size, vecname, module, procedure)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=dp), intent(in) :: v(:)
    integer, intent(in) :: size(:)
    character(len=*), intent(in) :: vecname
    character(len=*), intent(in) :: module
    character(len=*), intent(in) :: procedure

  • private module subroutine assert_shape_vector_rsp(v, size, vecname, module, procedure)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(in) :: v(:)
    integer, intent(in) :: size(:)
    character(len=*), intent(in) :: vecname
    character(len=*), intent(in) :: module
    character(len=*), intent(in) :: procedure

public interface eig

Computes the eigenvalue decomposition of a general square matrix.

Description

This interface provides methods to compute the solution to the eigenproblem , where $\mathbf{A}$ is a square real or complex matrix.

Result array lambda returns the eigenvalues of , while vecs returns the corresponding eigenvectors. Note that it follows the LAPACK convention when is real. The solver is based on LAPACK's *GEEV backends.

Syntax

call eig(A, vecs, lambda)

Arguments

A: real or complex square array containing the coefficient matrix. It is an intent(in) argument.

vecs: Square array of the same size, type, and kind as A containing the eigenvectors (following LAPACK's convention for real matrices). It is an intent(out) argument.

lambda: complex rank-1 array of the same kind as A containing the eigenvalues. It is an intent(out) argument.

Note

Due to the abstrct nature of the vector types defined in LightKrylov, it is unlikely that this implementation will be superseeded in favor of the stdlib one as the latter does not follow the LAPACK's convention.

  • private module subroutine eig_cdp(A, vecs, vals)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(in) :: A(:,:)
    complex(kind=dp), intent(out) :: vecs(:,:)
    complex(kind=dp), intent(out) :: vals(:)

  • private module subroutine eig_csp(A, vecs, vals)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(in) :: A(:,:)
    complex(kind=sp), intent(out) :: vecs(:,:)
    complex(kind=sp), intent(out) :: vals(:)

  • private module subroutine eig_rdp(A, vecs, vals)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=dp), intent(in) :: A(:,:)
    real(kind=dp), intent(out) :: vecs(:,:)
    complex(kind=dp), intent(out) :: vals(:)

  • private module subroutine eig_rsp(A, vecs, vals)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(in) :: A(:,:)
    real(kind=sp), intent(out) :: vecs(:,:)
    complex(kind=sp), intent(out) :: vals(:)

public interface expm

Description

Evaluate the exponential of a dense matrix using Pade approximations.

Syntax

    E = expm(A, order)

Arguments

E : real or complex rank-2 array with .

A : real or complex matrix that needs to be exponentiated.

order (optional) : Order of the Pade approximation. By default order = 10.

  • private module function expm_cdp(A, order) result(E)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(in) :: A(:,:)

    Matrix to be exponentiated.
    integer, intent(in), optional :: order

    Order of the Pade approximation.

    Return Value complex(kind=dp), (size(A,1),size(A,1))

    Output matrix E = exp(tA).

  • private module function expm_csp(A, order) result(E)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(in) :: A(:,:)

    Matrix to be exponentiated.
    integer, intent(in), optional :: order

    Order of the Pade approximation.

    Return Value complex(kind=sp), (size(A,1),size(A,1))

    Output matrix E = exp(tA).

  • private module function expm_rdp(A, order) result(E)

    Arguments

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

    Matrix to be exponentiated.
    integer, intent(in), optional :: order

    Order of the Pade approximation.

    Return Value real(kind=dp), (size(A,1),size(A,1))

    Output matrix E = exp(tA).

  • private module function expm_rsp(A, order) result(E)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(in) :: A(:,:)

    Matrix to be exponentiated.
    integer, intent(in), optional :: order

    Order of the Pade approximation.

    Return Value real(kind=sp), (size(A,1),size(A,1))

    Output matrix E = exp(tA).

public interface givens_rotation

  • private pure module function givens_rotation_cdp(x) result(g)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(in) :: x(2)

    Vector whose second needs to be eliminated.

    Return Value complex(kind=dp), (2)

    Entries of the Givens rotation matrix.

  • private pure module function givens_rotation_csp(x) result(g)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(in) :: x(2)

    Vector whose second needs to be eliminated.

    Return Value complex(kind=sp), (2)

    Entries of the Givens rotation matrix.

  • private pure module function givens_rotation_rdp(x) result(g)

    Arguments

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

    Vector whose second needs to be eliminated.

    Return Value real(kind=dp), (2)

    Entries of the Givens rotation matrix.

  • private pure module function givens_rotation_rsp(x) result(g)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(in) :: x(2)

    Vector whose second needs to be eliminated.

    Return Value real(kind=sp), (2)

    Entries of the Givens rotation matrix.

public interface log2

Utility function to compute the base-2 logarithm of a real number.

  • private elemental module function log2_rdp(x) result(y)

    Arguments

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

    Return Value real(kind=dp)

  • private elemental module function log2_rsp(x) result(y)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(in) :: x

    Return Value real(kind=sp)

public interface ordschur

Given the Schur factorization and basis of a matrix, reorders it to have the selected eigenvalues in the upper left block.

Description

This interface provides methods to re-order the Schur factorization of a real or complex square matrix. Note that, if is real, it returns the real Schur form.

Syntax

call ordschur(T, Q, selected)

Arguments

T: real or complex square array containing the Schur factorization of a matrix. On exit, it is overwritten with its re-ordered counterpart. It is an intent(inout) argument.

Q: Two-dimensional square array of the same size, type and kind as A. It contains the original Schur basis on entry and the re-ordered one on exit. It is an intent(inout) argument.

selected: logical rank-1 array selecting which eigenvalues need to be moved in the upper left block of the Schur factorization. It is an intent(in) arguement.

  • private module subroutine ordschur_cdp(T, Q, selected)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(inout) :: T(:,:)
    complex(kind=dp), intent(inout) :: Q(:,:)
    logical, intent(in) :: selected(:)

  • private module subroutine ordschur_csp(T, Q, selected)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(inout) :: T(:,:)
    complex(kind=sp), intent(inout) :: Q(:,:)
    logical, intent(in) :: selected(:)

  • private module subroutine ordschur_rdp(T, Q, selected)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=dp), intent(inout) :: T(:,:)
    real(kind=dp), intent(inout) :: Q(:,:)
    logical, intent(in) :: selected(:)

  • private module subroutine ordschur_rsp(T, Q, selected)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(inout) :: T(:,:)
    real(kind=sp), intent(inout) :: Q(:,:)
    logical, intent(in) :: selected(:)

public interface solve_triangular

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

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(in) :: A(:,:)

    Matrix to invert.
    complex(kind=dp), intent(in) :: b(:)

    Right-hand side vector.

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

    Solution vector.

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

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(in) :: A(:,:)

    Matrix to invert.
    complex(kind=sp), intent(in) :: b(:)

    Right-hand side vector.

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

    Solution vector.

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

    Arguments

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

    Matrix to invert.
    real(kind=dp), intent(in) :: b(:)

    Right-hand side vector.

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

    Solution vector.

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

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(in) :: A(:,:)

    Matrix to invert.
    real(kind=sp), intent(in) :: b(:)

    Right-hand side vector.

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

    Solution vector.

public interface sqrtm

Computes the non-negative square root of a symmetric positive definite matrix using its singular value decomposition.

Description

This interface provides methods to compute the non-negative square root of a symmetric (hermitian) positive definite matrix .

Syntax

call sqrtm(A, sqrtmA, info)

Arguments

A: Symmetric (hermitian) positive definite matrix whose non-negative square root needs to be computed. It is an intent(in) argument.

sqrtmA: Non-negative square root of A. It has the same size, kind and type as A. It is an intent(out) argument.

info: Information flag. It is an intent(out) argument.

  • private module subroutine sqrtm_cdp(A, sqrtA, info)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=dp), intent(inout) :: A(:,:)
    complex(kind=dp), intent(out) :: sqrtA(:,:)
    integer, intent(out) :: info

  • private module subroutine sqrtm_csp(A, sqrtA, info)

    Arguments

    Type IntentOptional Attributes Name
    complex(kind=sp), intent(inout) :: A(:,:)
    complex(kind=sp), intent(out) :: sqrtA(:,:)
    integer, intent(out) :: info

  • private module subroutine sqrtm_rdp(A, sqrtA, info)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=dp), intent(inout) :: A(:,:)
    real(kind=dp), intent(out) :: sqrtA(:,:)
    integer, intent(out) :: info

  • private module subroutine sqrtm_rsp(A, sqrtA, info)

    Arguments

    Type IntentOptional Attributes Name
    real(kind=sp), intent(inout) :: A(:,:)
    real(kind=sp), intent(out) :: sqrtA(:,:)
    integer, intent(out) :: info

Derived Types

type, public, abstract ::  abstract_metadata

Abstract type for solver metadata from which all others are extended.

Type-Bound Procedures

procedure(abstract_print_metadata), public, deferred, pass(self) :: print
procedure(abstract_reset_metadata), public, deferred, pass(self) :: reset

type, public, abstract ::  abstract_opts

Abstract type for options from which all others are extended.