eighs Interface

public interface eighs

Description

Computes the leading eigenpairs of a symmetric operator using the Lanczos iterative process. Given a square linear operator , it finds the leading eigvalues and eigvectors such that:

The subspace is constructed via Lanczos factorization, resulting in a symmetric tridiagonal matrix . The eigenvalues of are approximated by those of and the eigenvectors are computed accordingly.

References

  • Lanczos, C. (1950). "An Iteration Method for the Solution of the Eigenvalue Problem of Linear Differential and Integral Operators". United States Governm. Press Office.

Syntax

    call eighs(A, X, eigvals, residuals, info [, kdim] [,tolerance])

Arguments

  • A : Linear operator derived from abstract_sym_linop_rsp, abstract_sym_linop_rdp, abstract_hermitian_linop_csp or abstract_hermitian_linop_cdp whose leading eigenpairs need to be computed. It is an intent(inout) argument.

  • X : Array of abstract_vectors with the same type and kind as A. On exit, it contains the leading eigenvectors of A. Note that the dimension of X fixes the number of eigenpairs computed. It is an intent(out) argument.

  • eigvals : Rank-1 array of real numbers. On exit, it contains the leading eigenvalues of A. It is an intent(out) argument.

  • residuals : Rank-1 array of real numbers. On exit, it contains the residuals associated with each eigenpairs. It is an intent(out) argument.

  • info : integer Information flag.

  • kdim (optional) : integer, maximum dimension of the Krylov subspace used to approximate the leading eigenpairs. It is an optional intent(in) argument. By default, kdim = 4*size(X).

  • tolerance (optional) : real tolerance below which an eigenpair is considered as being converged. It is an optional intent(in) argument. By default, tolerance = rtol_sp or tolerance = rtol_dp.

Note

This implementation does not currently include an automatic restarting procedure such as krylov_schur for eigs. This is work in progress.


Subroutines

private module subroutine eighs_cdp(A, X, eigvals, residuals, info, x0, kdim, tolerance, write_intermediate)

Arguments

Type IntentOptional Attributes Name
class(abstract_hermitian_linop_cdp), intent(inout) :: A

Linear operator whose leading eigenpairs need to be computed.
class(abstract_vector_cdp), intent(out) :: X(:)

Leading eigevectors of .
real(kind=dp), intent(out), allocatable :: eigvals(:)

Leading eigenvalues of .
real(kind=dp), intent(out), allocatable :: residuals(:)

Residuals associated to each Ritz eigenpairs.
integer, intent(out) :: info

Information flag.
class(abstract_vector_cdp), intent(in), optional :: x0

Optional starting vector to generate the Krylov subspace.
integer, intent(in), optional :: kdim

Desired number of eigenpairs.
real(kind=dp), intent(in), optional :: tolerance

Tolerance
logical, intent(in), optional :: write_intermediate

Write intermediate eigenvalues to file during iteration?

private module subroutine eighs_csp(A, X, eigvals, residuals, info, x0, kdim, tolerance, write_intermediate)

Arguments

Type IntentOptional Attributes Name
class(abstract_hermitian_linop_csp), intent(inout) :: A

Linear operator whose leading eigenpairs need to be computed.
class(abstract_vector_csp), intent(out) :: X(:)

Leading eigevectors of .
real(kind=sp), intent(out), allocatable :: eigvals(:)

Leading eigenvalues of .
real(kind=sp), intent(out), allocatable :: residuals(:)

Residuals associated to each Ritz eigenpairs.
integer, intent(out) :: info

Information flag.
class(abstract_vector_csp), intent(in), optional :: x0

Optional starting vector to generate the Krylov subspace.
integer, intent(in), optional :: kdim

Desired number of eigenpairs.
real(kind=sp), intent(in), optional :: tolerance

Tolerance
logical, intent(in), optional :: write_intermediate

Write intermediate eigenvalues to file during iteration?

private module subroutine eighs_rdp(A, X, eigvals, residuals, info, x0, kdim, tolerance, write_intermediate)

Arguments

Type IntentOptional Attributes Name
class(abstract_sym_linop_rdp), intent(inout) :: A

Linear operator whose leading eigenpairs need to be computed.
class(abstract_vector_rdp), intent(out) :: X(:)

Leading eigevectors of .
real(kind=dp), intent(out), allocatable :: eigvals(:)

Leading eigenvalues of .
real(kind=dp), intent(out), allocatable :: residuals(:)

Residuals associated to each Ritz eigenpairs.
integer, intent(out) :: info

Information flag.
class(abstract_vector_rdp), intent(in), optional :: x0

Optional starting vector to generate the Krylov subspace.
integer, intent(in), optional :: kdim

Desired number of eigenpairs.
real(kind=dp), intent(in), optional :: tolerance

Tolerance
logical, intent(in), optional :: write_intermediate

Write intermediate eigenvalues to file during iteration?

private module subroutine eighs_rsp(A, X, eigvals, residuals, info, x0, kdim, tolerance, write_intermediate)

Arguments

Type IntentOptional Attributes Name
class(abstract_sym_linop_rsp), intent(inout) :: A

Linear operator whose leading eigenpairs need to be computed.
class(abstract_vector_rsp), intent(out) :: X(:)

Leading eigevectors of .
real(kind=sp), intent(out), allocatable :: eigvals(:)

Leading eigenvalues of .
real(kind=sp), intent(out), allocatable :: residuals(:)

Residuals associated to each Ritz eigenpairs.
integer, intent(out) :: info

Information flag.
class(abstract_vector_rsp), intent(in), optional :: x0

Optional starting vector to generate the Krylov subspace.
integer, intent(in), optional :: kdim

Desired number of eigenpairs.
real(kind=sp), intent(in), optional :: tolerance

Tolerance
logical, intent(in), optional :: write_intermediate

Write intermediate eigenvalues to file during iteration?