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.
  • sqrtm_eig: Compute the non-negative square root of a symmetric positive definite matrix using its eigenvalue decomposition.
  • schur: Compute the Schur factorization of a general square matrix.
  • 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


Interfaces

public interface assert_shape

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

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

    Utility function to assert the shape of a vector.

    Arguments

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

    Vector whose dimension need to be asserted.
    integer, intent(in) :: size(:)

    Expected dimensions of v.
    character(len=*), intent(in) :: vecname

    Name of the asserted vector.
    character(len=*), intent(in) :: module

    Name of the module where assertion is done.
    character(len=*), intent(in) :: procedure

    Name of the routine where assertion is done.

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

    Utility function to assert the shape of a matrix.

    Arguments

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

    Matrix whose dimension need to be asserted.
    integer, intent(in) :: size(:)

    Expected dimensions of A.
    character(len=*), intent(in) :: matname

    Name of the asserted matrix.
    character(len=*), intent(in) :: module

    Name of the module where assertion is done.
    character(len=*), intent(in) :: procedure

    Name of the routine where assertion is done.

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

    Utility function to assert the shape of a vector.

    Arguments

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

    Vector whose dimension need to be asserted.
    integer, intent(in) :: size(:)

    Expected dimensions of v.
    character(len=*), intent(in) :: vecname

    Name of the asserted vector.
    character(len=*), intent(in) :: module

    Name of the module where assertion is done.
    character(len=*), intent(in) :: procedure

    Name of the routine where assertion is done.

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

    Utility function to assert the shape of a matrix.

    Arguments

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

    Matrix whose dimension need to be asserted.
    integer, intent(in) :: size(:)

    Expected dimensions of A.
    character(len=*), intent(in) :: matname

    Name of the asserted matrix.
    character(len=*), intent(in) :: module

    Name of the module where assertion is done.
    character(len=*), intent(in) :: procedure

    Name of the routine where assertion is done.

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

    Utility function to assert the shape of a vector.

    Arguments

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

    Vector whose dimension need to be asserted.
    integer, intent(in) :: size(:)

    Expected dimensions of v.
    character(len=*), intent(in) :: vecname

    Name of the asserted vector.
    character(len=*), intent(in) :: module

    Name of the module where assertion is done.
    character(len=*), intent(in) :: procedure

    Name of the routine where assertion is done.

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

    Utility function to assert the shape of a matrix.

    Arguments

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

    Matrix whose dimension need to be asserted.
    integer, intent(in) :: size(:)

    Expected dimensions of A.
    character(len=*), intent(in) :: matname

    Name of the asserted matrix.
    character(len=*), intent(in) :: module

    Name of the module where assertion is done.
    character(len=*), intent(in) :: procedure

    Name of the routine where assertion is done.

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

    Utility function to assert the shape of a vector.

    Arguments

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

    Vector whose dimension need to be asserted.
    integer, intent(in) :: size(:)

    Expected dimensions of v.
    character(len=*), intent(in) :: vecname

    Name of the asserted vector.
    character(len=*), intent(in) :: module

    Name of the module where assertion is done.
    character(len=*), intent(in) :: procedure

    Name of the routine where assertion is done.

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

    Utility function to assert the shape of a matrix.

    Arguments

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

    Matrix whose dimension need to be asserted.
    integer, intent(in) :: size(:)

    Expected dimensions of A.
    character(len=*), intent(in) :: matname

    Name of the asserted matrix.
    character(len=*), intent(in) :: module

    Name of the module where assertion is done.
    character(len=*), intent(in) :: procedure

    Name of the routine where assertion is done.

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 subroutine eig_rsp(A, vecs, vals)

    Eigenvalue decomposition of a dense matrix using LAPACK.

    Arguments

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

    Matrix to be factorized.
    real(kind=sp), intent(out) :: vecs(:,:)

    Eigenvectors.
    complex(kind=sp), intent(out) :: vals(:)

  • private subroutine eig_rdp(A, vecs, vals)

    Eigenvalue decomposition of a dense matrix using LAPACK.

    Arguments

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

    Matrix to be factorized.
    real(kind=dp), intent(out) :: vecs(:,:)

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

  • private subroutine eig_csp(A, vecs, vals)

    Eigenvalue decomposition of a dense matrix using LAPACK.

    Arguments

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

    Matrix to be factorized.
    complex(kind=sp), intent(out) :: vecs(:,:)

    Eigenvectors.
    complex(kind=sp), intent(out) :: vals(:)

  • private subroutine eig_cdp(A, vecs, vals)

    Eigenvalue decomposition of a dense matrix using LAPACK.

    Arguments

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

    Matrix to be factorized.
    complex(kind=dp), intent(out) :: vecs(:,:)

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

public interface log2

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

  • private pure function log2_rsp(x) result(y)

    Arguments

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

    Return Value real(kind=sp)

  • private pure function log2_rdp(x) result(y)

    Arguments

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

    Return Value real(kind=dp)

public interface norml

This interface provides methods to compute the infinity norm of a matrix. Note that it'll eventually be superseeded by the stdlib implementation.

  • private pure function norml_rsp(A) result(norm)

    Arguments

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

    Return Value real(kind=sp)

  • private pure function norml_rdp(A) result(norm)

    Arguments

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

    Return Value real(kind=dp)

  • private pure function norml_csp(A) result(norm)

    Arguments

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

    Return Value real(kind=sp)

  • private pure function norml_cdp(A) result(norm)

    Arguments

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

    Return Value real(kind=dp)

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 subroutine ordschur_rsp(T, Q, selected)

    Re-order the Schur factorization from schur such that the selected eigenvalues are in the upper-left block.

    Arguments

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

    Schur matrix to be re-ordered.
    real(kind=sp), intent(inout) :: Q(:,:)

    Schur vectors to be re-ordered.
    logical, intent(in) :: selected(:)

    Boolean array defining the selected eigenvalues.

  • private subroutine ordschur_rdp(T, Q, selected)

    Re-order the Schur factorization from schur such that the selected eigenvalues are in the upper-left block.

    Arguments

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

    Schur matrix to be re-ordered.
    real(kind=dp), intent(inout) :: Q(:,:)

    Schur vectors to be re-ordered.
    logical, intent(in) :: selected(:)

    Boolean array defining the selected eigenvalues.

  • private subroutine ordschur_csp(T, Q, selected)

    Re-order the Schur factorization from schur such that the selected eigenvalues are in the upper-left block.

    Arguments

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

    Schur matrix to be re-ordered.
    complex(kind=sp), intent(inout) :: Q(:,:)

    Schur vectors to be re-ordered.
    logical, intent(in) :: selected(:)

    Boolean array defining the selected eigenvalues.

  • private subroutine ordschur_cdp(T, Q, selected)

    Re-order the Schur factorization from schur such that the selected eigenvalues are in the upper-left block.

    Arguments

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

    Schur matrix to be re-ordered.
    complex(kind=dp), intent(inout) :: Q(:,:)

    Schur vectors to be re-ordered.
    logical, intent(in) :: selected(:)

    Boolean array defining the selected eigenvalues.

public interface schur

Computes the Schur factorization of a general square matrix.

Description

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

Result array eigvals returns the eigenvalues of while Z contains the Schur basis.

Syntax

call schur(A, Z, eigvals)

Arguments

A: real or complex square array containing the coefficient matrix. On exit, it is overwritten with its (real) Schur factorization. It is an intent(inout) argument.

Z: Two-dimensional square array of the same size, type and kind as A. It contains the Schur basis. It is an intent(out) argument.

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

  • private subroutine schur_rsp(A, Z, eigvals)

    Compute the Schur form (in-place) and Schur vectors of the matrix A.

    Arguments

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

    Matrix to be factorized.
    real(kind=sp), intent(out) :: Z(:,:)

    Schur basis.
    complex(kind=sp), intent(out) :: eigvals(:)

    Eigenvalues.

  • private subroutine schur_rdp(A, Z, eigvals)

    Compute the Schur form (in-place) and Schur vectors of the matrix A.

    Arguments

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

    Matrix to be factorized.
    real(kind=dp), intent(out) :: Z(:,:)

    Schur basis.
    complex(kind=dp), intent(out) :: eigvals(:)

    Eigenvalues.

  • private subroutine schur_csp(A, Z, eigvals)

    Compute the Schur form (in-place) and Schur vectors of the matrix A.

    Arguments

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

    Matrix to be factorized.
    complex(kind=sp), intent(out) :: Z(:,:)

    Schur basis.
    complex(kind=sp), intent(out) :: eigvals(:)

    Eigenvalues.

  • private subroutine schur_cdp(A, Z, eigvals)

    Compute the Schur form (in-place) and Schur vectors of the matrix A.

    Arguments

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

    Matrix to be factorized.
    complex(kind=dp), intent(out) :: Z(:,:)

    Schur basis.
    complex(kind=dp), intent(out) :: eigvals(:)

    Eigenvalues.

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 subroutine sqrtm_rsp(X, sqrtmX, info)

    Matrix-valued sqrt function for dense symmetric/hermitian positive (semi-)definite matrices

    Arguments

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

    Matrix of which to compute the sqrt
    real(kind=sp), intent(out) :: sqrtmX(size(X,1),size(X,1))

    Return matrix
    integer, intent(out) :: info

    Information flag

  • private subroutine sqrtm_rdp(X, sqrtmX, info)

    Matrix-valued sqrt function for dense symmetric/hermitian positive (semi-)definite matrices

    Arguments

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

    Matrix of which to compute the sqrt
    real(kind=dp), intent(out) :: sqrtmX(size(X,1),size(X,1))

    Return matrix
    integer, intent(out) :: info

    Information flag

  • private subroutine sqrtm_csp(X, sqrtmX, info)

    Matrix-valued sqrt function for dense symmetric/hermitian positive (semi-)definite matrices

    Arguments

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

    Matrix of which to compute the sqrt
    complex(kind=sp), intent(out) :: sqrtmX(size(X,1),size(X,1))

    Return matrix
    integer, intent(out) :: info

    Information flag

  • private subroutine sqrtm_cdp(X, sqrtmX, info)

    Matrix-valued sqrt function for dense symmetric/hermitian positive (semi-)definite matrices

    Arguments

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

    Matrix of which to compute the sqrt
    complex(kind=dp), intent(out) :: sqrtmX(size(X,1),size(X,1))

    Return matrix
    integer, intent(out) :: info

    Information flag

public interface sqrtm_eig

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

Description

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

Syntax

call sqrtm_eig(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 subroutine sqrtm_eig_rsp(X, sqrtmX, info)

    Matrix-valued sqrt function for dense symmetric/hermitian positive (semi-)definite matrices

    Arguments

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

    Matrix of which to compute the sqrt
    real(kind=sp), intent(out) :: sqrtmX(size(X,1),size(X,1))

    Return matrix
    integer, intent(out) :: info

    Information flag

  • private subroutine sqrtm_eig_rdp(X, sqrtmX, info)

    Matrix-valued sqrt function for dense symmetric/hermitian positive (semi-)definite matrices

    Arguments

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

    Matrix of which to compute the sqrt
    real(kind=dp), intent(out) :: sqrtmX(size(X,1),size(X,1))

    Return matrix
    integer, intent(out) :: info

    Information flag

  • private subroutine sqrtm_eig_csp(X, sqrtmX, info)

    Matrix-valued sqrt function for dense symmetric/hermitian positive (semi-)definite matrices

    Arguments

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

    Matrix of which to compute the sqrt
    complex(kind=sp), intent(out) :: sqrtmX(size(X,1),size(X,1))

    Return matrix
    integer, intent(out) :: info

    Information flag

  • private subroutine sqrtm_eig_cdp(X, sqrtmX, info)

    Matrix-valued sqrt function for dense symmetric/hermitian positive (semi-)definite matrices

    Arguments

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

    Matrix of which to compute the sqrt
    complex(kind=dp), intent(out) :: sqrtmX(size(X,1),size(X,1))

    Return matrix
    integer, intent(out) :: info

    Information flag

Derived Types

type, public, abstract ::  abstract_opts

Abstract type container for options from which all others are being extended.

type, public, extends(abstract_opts) ::  cg_dp_opts

Conjugate gradient options.

Components

Type Visibility Attributes Name Initial
integer, public :: maxiter = 100

Maximum number of cg iterations (default: 100).

type, public, extends(abstract_opts) ::  cg_sp_opts

Conjugate gradient options.

Components

Type Visibility Attributes Name Initial
integer, public :: maxiter = 100

Maximum number of cg iterations (default: 100).

type, public, extends(abstract_opts) ::  gmres_dp_opts

GMRES options.

Components

Type Visibility Attributes Name Initial
integer, public :: kdim = 30

Dimension of the Krylov subspace (default: 30).
integer, public :: maxiter = 10

Maximum number of gmres restarts (default: 10).

type, public, extends(abstract_opts) ::  gmres_sp_opts

GMRES options.

Components

Type Visibility Attributes Name Initial
integer, public :: kdim = 30

Dimension of the Krylov subspace (default: 30).
integer, public :: maxiter = 10

Maximum number of gmres restarts (default: 10).

type, public, extends(abstract_opts) ::  newton_dp_opts

Options for Newton-Krylov fixed-point iteration.

Components

Type Visibility Attributes Name Initial
logical, public :: ifbisect = .false.

Bisection toggle to enforce residual reduction (default = .false.)
integer, public :: maxiter = 100

Maximum number of Newton iterations (default = 100)
integer, public :: maxstep_bisection = 5

Maximum number of bisections (evaluations of F) for step selection (default = 5) Ignored if ifbisect = .false.

type, public, extends(abstract_opts) ::  newton_sp_opts

Options for Newton-Krylov fixed-point iteration.

Components

Type Visibility Attributes Name Initial
logical, public :: ifbisect = .false.

Bisection toggle to enforce residual reduction (default = .false.)
integer, public :: maxiter = 100

Maximum number of Newton iterations (default = 100)
integer, public :: maxstep_bisection = 5

Maximum number of bisections (evaluations of F) for step selection (default = 5) Ignored if ifbisect = .false.