ELPA_GENERALIZED_EIGENVECTORS(3)

💅 NAME

Okay so bestie, this is the elpa_gener...igenvectors(3) page from the Library Functions Manual, and the main character is elpa_generalized_eigenvectors — it computes all eigenvalues and (part of) eigenvectors of a generalized eigenvalue problem, A*Q = λ*B*Q, for real symmetric or complex hermitian matrices A, B. No cap. 💖

There are also variations of this routine that can accept not only host but also device pointers as input/output. Names of these routines explicitly contain the corresponding datatypes, so it's giving very “say my type out loud” energy: elpa_generalized_eigenvectors_double, elpa_generalized_eigenvectors_float, elpa_generalized_eigenvectors_double_complex, elpa_generalized_eigenvectors_float_complex. ✨

🎀 SYNOPSIS 🎀

FORTRAN INTERFACE

use elpa
class(elpa_t), pointer :: elpa_handle

call elpa_handle%generalized_eigenvectors (a, b, ev, q,
is_already_decomposed, error)

With the definitions of the input and output variables:

• class(elpa_t) :: elpa_handle — An instance of the ELPA object.
• datatype :: a — The local matrix a for which the eigenvalues and eigenvalues should be computed. The dimensions of matrix a must be set BEFORE with the methods elpa_set(3) and elpa_setup(3). The datatype of the matrix can be one of "real(kind=c_double)", "real(kind=c_float)", "complex(kind=c_double)", or "complex(kind=c_float)".
• datatype :: b — The local matrix b defining the generalized eigenvalue problem. The dimensions and datatype of the matrix b has to be the same as for matrix a.
• datatype :: ev — The array where the eigenvalues λ will be stored in ascending order. The datatype_real of ev can be either "real(kind=c_double)" or "real(kind=c_float)", depending of the datatype of the matrix. Note that complex hermitian matrices also have real eigenvalues.
• datatype :: q — The storage space for the computed eigenvectors Q. The number of requested eigenvectors, nev, must be set BEFORE with the methods elpa_set(3) and elpa_setup(3). The datatype of the matrix can be one of "real(kind=c_double)", "real(kind=c_float)", "complex(kind=c_double)", or "complex(kind=c_float)".
• logical :: is_already_decomposed — Has to be set to .false. for the first call with a given b and to .true. for each subsequent call with the same b, since b then already contains decomposition and thus the decomposing step is skipped.
• integer, optional :: error — The return error code of the function. Should be "ELPA_OK". The error code can be queried with the function elpa_strerr(3).

C/C++ INTERFACE

#include <elpa/elpa.h>
elpa_t elpa_handle;

void elpa_generalized_eigenvectors(elpa_t elpa_handle, datatype *a,
datatype *b, datatype *ev, datatype *q,  int is_already_decomposed, int
*error);

With the definitions of the input and output variables:

• elpa_t elpa_handle; — The handle to the ELPA object.
• datatype *a; — The local matrix a for which all eigenvalues and (part of) eigenvectors should be computed. The dimensions of the matrix must be set BEFORE with the methods elpa_set(3) and elpa_setup(3). The global matrix has to be symmetric or hermitian, this is not checked by the routine. The datatype can be one of "double", "float", "double complex"/"std::complex<double>", "float complex"/"std::complex<float>" for C/C++.
• datatype *b; — The local matrix b defining the generalized eigenvalue problem. The dimensions and the datatype of the matrix b must be the same as matrix a. The global matrix has to be symmetric or hermitian, this is not checked by the routine. The datatype can be one of "double", "float", "double complex"/"std::complex<double>", "float complex"/"std::complex<float>" for C/C++.
• datatype_real *ev; — The array where the eigenvalues λ will be stored in ascending order. Eigenvalues will be stored in ascending order. The datatype_real can be either "double" or "float". Note that the eigenvalues of complex hermitian matrices are also real.
• datatype *q; — The storage space for the computed eigenvectors Q. The number of requested eigenvectors must be set BEFORE with the methods elpa_set(3) and elpa_setup(3). The datatype can be one of "double", "float", "double complex"/"std::complex<double>", "float complex"/"std::complex<float>" for C/C++.
• int is_already_decomposed; — Has to be set to 0 for the first call with a given b and 1 for each subsequent call with the same b, since b then already contains decomposition and thus the decomposing step is skipped.
• int *error; — The error code of the function. Should be "ELPA_OK". The error codes can be queried with elpa_strerr(3).

💖 DESCRIPTION

Computes the generalized eigenvalues and (part of) the generalized eigenvectors for a real symmetric or complex hermitian generalized eigenproblem. The functions elpa_init(3), elpa_allocate(3), elpa_set(3), and elpa_setup(3) must be called BEFORE elpa_generalized_eigenvalues can be called. In particular, the number of eigenvectors to be computed, nev, can be set with elpa_set(3).

Unlike in the case of ordinary eigenvalue problem, the generalized problem calls some external ScaLAPACK routines. The user is responsible for initialization of the BLACS context, which then has to be passed to ELPA by elpa_set(3) BEFORE elpa_generalized_eigenvalues can be called. That part is very “you handle the setup, bestie, I handle the math” energy. 🫶

👑 SEE ALSO

• elpa_init(3)
• elpa_allocate(3)
• elpa_set(3)
• elpa_setup(3)
• elpa_strerr(3)
• elpa_eigenvalues(3)
• elpa_eigenvectors(3)
• elpa_cholesky(3)
• elpa_invert_triangular(3)
• elpa_solve_tridiagonal(3)
• elpa_hermitian_multiply(3)
• elpa_uninit(3)
• elpa_deallocate(3)

Okay that's the whole page, bestie 🫶 — source/version ELPA, date Thu Nov 28 2024, and the footer name elpa_gener...igenvectors(3). Periodt. 💅✨