LightKrylov_Utils – LightKrylov

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

- Descendants:
- utility_functions

Interfaces

public interface apply_givens_rotation

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

Arguments

Type	Intent	Attributes		Name
complex(kind=dp),	intent(inout),	target, contiguous	::	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	Intent	Attributes		Name
complex(kind=sp),	intent(inout),	target, contiguous	::	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	Intent	Attributes		Name
real(kind=dp),	intent(inout),	target, contiguous	::	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	Intent	Attributes		Name
real(kind=sp),	intent(inout),	target, contiguous	::	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	Intent		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	Intent		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	Intent		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	Intent		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	Intent		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	Intent		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	Intent		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	Intent		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 $\mathbf{Ax} = \lambda \mathbf{x}$ , where $\mathbf{A}$ is a square real or complex matrix.

Result array lambda returns the eigenvalues of $\mathbf{A}$ , while vecs returns the corresponding eigenvectors. Note that it follows the LAPACK convention when $\mathbf{A}$ 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	Intent		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	Intent		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	Intent		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	Intent		Name
real(kind=sp),	intent(in)	::	A(:,:)
real(kind=sp),	intent(out)	::	vecs(:,:)
complex(kind=sp),	intent(out)	::	vals(:)

public interface givens_rotation

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

Arguments

Type	Intent	Optional	Attributes		Name
complex(kind=dp),	intent(in)			::	x(2)	Vector whose second entry 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	Intent	Optional	Attributes		Name
complex(kind=sp),	intent(in)			::	x(2)	Vector whose second entry 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	Intent	Optional	Attributes		Name
real(kind=dp),	intent(in)			::	x(2)	Vector whose second entry 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	Intent	Optional	Attributes		Name
real(kind=sp),	intent(in)			::	x(2)	Vector whose second entry 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	Intent	Optional	Attributes		Name
real(kind=dp),	intent(in)			::	x

Return Value real(kind=dp)

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

Arguments

Type	Intent	Optional	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 $\mathbf{A}$ 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	Intent		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	Intent		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	Intent		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	Intent		Name
real(kind=sp),	intent(inout)	::	T(:,:)
real(kind=sp),	intent(inout)	::	Q(:,:)
logical,	intent(in)	::	selected(:)

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 $\mathbf{A}$ .

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	Intent		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	Intent		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	Intent		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	Intent		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.

LightKrylov_Utils Module

Contents

Interfaces

Derived Types

Uses

Used by

Descendants:

Interfaces

public interface apply_givens_rotation

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

Arguments

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

Arguments

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

Arguments

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

Arguments

public interface assert_shape

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

Arguments

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

Arguments

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

Arguments

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

Arguments

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

Arguments

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

Arguments

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

Arguments

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

Arguments

public interface eig

Description

Syntax

Arguments

private module subroutine eig_cdp(A, vecs, vals)

Arguments

private module subroutine eig_csp(A, vecs, vals)

Arguments

private module subroutine eig_rdp(A, vecs, vals)

Arguments

private module subroutine eig_rsp(A, vecs, vals)

Arguments

public interface givens_rotation

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

Arguments

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

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

Arguments

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

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

Arguments

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

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

Arguments

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

public interface log2

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

Arguments

Return Value real(kind=dp)

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

Arguments

Return Value real(kind=sp)

public interface ordschur

Description

Syntax

Arguments

private module subroutine ordschur_cdp(T, Q, selected)

Arguments

private module subroutine ordschur_csp(T, Q, selected)

Arguments

private module subroutine ordschur_rdp(T, Q, selected)

Arguments

private module subroutine ordschur_rsp(T, Q, selected)

Arguments

public interface sqrtm

Description