eigs Interface

public interface eigs

Description

Computes the leading eigenpairs of a square linear operator using the Arnoldi iterative process. Given a square linear operator , it finds the leading eigenvalues and eigenvectors such that:

or

The subspace is constructed via Arnoldi factorization, resulting in an upper Hessenberg matrix . The eigenvalues of are approximated by those of and the eigenvectors are computed accordingly.

References

  • Arnoldi, W. E. (1951). "The Principle of Minimized Iterations in the Solution of the Matrix Eigenvalue Problem." Quarterly of Applied Mathematics, 9(1), 17–29.

Syntax

    call eigs(A, X, eigvals, residuals, info [, kdim] [, select] [,tolerance] [, transpose])

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

  • select (optional) : Function to select which eigenvalues to compute.

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

  • transpose (optional) : logical flag determining whether the eigenvalues of or need to be computed. It is an optional intent(in) argument.


Module Procedures

private subroutine eigs_rsp(A, X, eigvals, residuals, info, x0, kdim, tolerance, transpose, write_intermediate)

Arguments

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

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

Leading eigenvectors of .
complex(kind=sp), intent(out), allocatable :: eigvals(:)

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

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

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

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

Maximum dimension of the Krylov subspace (optional).
real(kind=sp), intent(in), optional :: tolerance

Tolerance.
logical, intent(in), optional :: transpose

Determine whether or is being used.
logical, intent(in), optional :: write_intermediate

Write intermediate eigenvalues to file during iteration?

private subroutine eigs_rdp(A, X, eigvals, residuals, info, x0, kdim, tolerance, transpose, write_intermediate)

Arguments

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

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

Leading eigenvectors of .
complex(kind=dp), intent(out), allocatable :: eigvals(:)

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

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

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

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

Maximum dimension of the Krylov subspace (optional).
real(kind=dp), intent(in), optional :: tolerance

Tolerance.
logical, intent(in), optional :: transpose

Determine whether or is being used.
logical, intent(in), optional :: write_intermediate

Write intermediate eigenvalues to file during iteration?

private subroutine eigs_csp(A, X, eigvals, residuals, info, x0, kdim, tolerance, transpose, write_intermediate)

Arguments

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

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

Leading eigenvectors of .
complex(kind=sp), intent(out), allocatable :: eigvals(:)

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

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

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

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

Maximum dimension of the Krylov subspace (optional).
real(kind=sp), intent(in), optional :: tolerance

Tolerance.
logical, intent(in), optional :: transpose

Determine whether or is being used.
logical, intent(in), optional :: write_intermediate

Write intermediate eigenvalues to file during iteration?

private subroutine eigs_cdp(A, X, eigvals, residuals, info, x0, kdim, tolerance, transpose, write_intermediate)

Arguments

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

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

Leading eigenvectors of .
complex(kind=dp), intent(out), allocatable :: eigvals(:)

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

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

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

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

Maximum dimension of the Krylov subspace (optional).
real(kind=dp), intent(in), optional :: tolerance

Tolerance.
logical, intent(in), optional :: transpose

Determine whether or is being used.
logical, intent(in), optional :: write_intermediate

Write intermediate eigenvalues to file during iteration?