StarNEig Library  version v0.1-beta.5
A task-based library for solving nonsymmetric eigenvalue problems
Distributed Memory / Generalized EVP

Functions for solving non-symmetric generalized eigenvalue problems on distributed memory systems. More...

Computational functions

starneig_error_t starneig_GEP_DM_HessenbergTriangular (starneig_distr_matrix_t A, starneig_distr_matrix_t B, starneig_distr_matrix_t Q, starneig_distr_matrix_t Z)
 Computes a Hessenberg-triangular decomposition of a general matrix pencil. More...
 
starneig_error_t starneig_GEP_DM_Schur (starneig_distr_matrix_t H, starneig_distr_matrix_t T, starneig_distr_matrix_t Q, starneig_distr_matrix_t Z, double real[], double imag[], double beta[])
 Computes a generalized Schur decomposition given a Hessenberg-triangular decomposition. More...
 
starneig_error_t starneig_GEP_DM_ReorderSchur (int selected[], starneig_distr_matrix_t S, starneig_distr_matrix_t T, starneig_distr_matrix_t Q, starneig_distr_matrix_t Z, double real[], double imag[], double beta[])
 Reorders selected generalized eigenvalues to the top left corner of a generalized Schur decomposition. More...
 
starneig_error_t starneig_GEP_DM_Reduce (starneig_distr_matrix_t A, starneig_distr_matrix_t B, starneig_distr_matrix_t Q, starneig_distr_matrix_t Z, double real[], double imag[], double beta[], int(*predicate)(double real, double imag, double beta, void *arg), void *arg, int selected[], int *num_selected)
 Computes a (reordered) generalized Schur decomposition given a general matrix pencil. More...
 
starneig_error_t starneig_GEP_DM_Eigenvectors (int selected[], starneig_distr_matrix_t S, starneig_distr_matrix_t T, starneig_distr_matrix_t Z, starneig_distr_matrix_t X)
 Computes a generalized eigenvector for each selected generalized eigenvalue. More...
 

Helper functions

starneig_error_t starneig_GEP_DM_Select (starneig_distr_matrix_t S, starneig_distr_matrix_t T, int(*predicate)(double real, double imag, double beta, void *arg), void *arg, int selected[], int *num_selected)
 Generates a selection array for a Schur-triangular matrix pencil using a user-supplied predicate function. More...
 

Expert computational functions

starneig_error_t starneig_GEP_DM_Schur_expert (struct starneig_schur_conf *conf, starneig_distr_matrix_t H, starneig_distr_matrix_t T, starneig_distr_matrix_t Q, starneig_distr_matrix_t Z, double real[], double imag[], double beta[])
 Computes a generalized Schur decomposition given a Hessenberg-triangular decomposition. More...
 
starneig_error_t starneig_GEP_DM_ReorderSchur_expert (struct starneig_reorder_conf *conf, int selected[], starneig_distr_matrix_t S, starneig_distr_matrix_t T, starneig_distr_matrix_t Q, starneig_distr_matrix_t Z, double real[], double imag[], double beta[])
 Reorders selected generalized eigenvalues to the top left corner of a generalized Schur decomposition. More...
 
starneig_error_t starneig_GEP_DM_Eigenvectors_expert (struct starneig_eigenvectors_conf *conf, int selected[], starneig_distr_matrix_t S, starneig_distr_matrix_t T, starneig_distr_matrix_t Z, starneig_distr_matrix_t X)
 Computes a generalized eigenvector for each selected generalized eigenvalue. More...
 

Detailed Description

Functions for solving non-symmetric generalized eigenvalue problems on distributed memory systems.

Function Documentation

◆ starneig_GEP_DM_HessenbergTriangular()

starneig_error_t starneig_GEP_DM_HessenbergTriangular ( starneig_distr_matrix_t  A,
starneig_distr_matrix_t  B,
starneig_distr_matrix_t  Q,
starneig_distr_matrix_t  Z 
)

Computes a Hessenberg-triangular decomposition of a general matrix pencil.

Attention
This function is a wrapper for several ScaLAPACK subroutines. The function exists if STARNEIG_GEP_DM_HESSENBERGTRIANGULAR is defined.
Parameters
[in,out]AOn entry, the general matrix $A$. On exit, the upper Hessenberg matrix $H$.
[in,out]BOn entry, the general matrix $B$. On exit, the upper triangular matrix $T$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U_1$.
[in,out]ZOn entry, the orthogonal matrix $Z$. On exit, the product matrix $Z * U_2$.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
Examples:
gep_dm_full_chain.c.

◆ starneig_GEP_DM_Schur()

starneig_error_t starneig_GEP_DM_Schur ( starneig_distr_matrix_t  H,
starneig_distr_matrix_t  T,
starneig_distr_matrix_t  Q,
starneig_distr_matrix_t  Z,
double  real[],
double  imag[],
double  beta[] 
)

Computes a generalized Schur decomposition given a Hessenberg-triangular decomposition.

Parameters
[in,out]HOn entry, the upper Hessenberg matrix $H$. On exit, the Schur matrix $S$.
[in,out]TOn entry, the upper triangular matrix $T$. On exit, the upper triangular matrix $\hat{T}$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U_1$.
[in,out]ZOn entry, the orthogonal matrix $Z$. On exit, the product matrix $Z * U_2$.
[out]realAn array of the same size as $H$ containing the real parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]imagAn array of the same size as $H$ containing the imaginary parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]betaAn array of the same size as $H$ containing the $\beta$ values of computed generalized eigenvalues.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise. STARNEIG_DID_NOT_CONVERGE if the QZ algorithm failed to converge.
Examples:
gep_dm_full_chain.c.

◆ starneig_GEP_DM_ReorderSchur()

starneig_error_t starneig_GEP_DM_ReorderSchur ( int  selected[],
starneig_distr_matrix_t  S,
starneig_distr_matrix_t  T,
starneig_distr_matrix_t  Q,
starneig_distr_matrix_t  Z,
double  real[],
double  imag[],
double  beta[] 
)

Reorders selected generalized eigenvalues to the top left corner of a generalized Schur decomposition.

Parameters
[in,out]selectedThe selection array. On entry, the initial positions of the selected generalized eigenvalues. On exit, the final positions of all correctly placed selected generalized eigenvalues. In case of failure, the number of 1's in the output may be less than the number of 1's in the input.
[in,out]SOn entry, the Schur matrix $S$. On exit, the updated Schur matrix $\hat{S}$.
[in,out]TOn entry, the upper triangular $T$. On exit, the updates upper triangular matrix $\hat{T}$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U_1$.
[in,out]ZOn entry, the orthogonal matrix $Z$. On exit, the product matrix $Z * U_2$.
[out]realAn array of the same size as $S$ containing the real parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]imagAn array of the same size as $S$ containing the imaginary parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]betaAn array of the same size as $S$ containing the $\beta$ values of computed generalized eigenvalues.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise. STARNEIG_PARTIAL_REORDERING if the generalized Schur form is not fully reordered.
See also
starneig_GEP_DM_Select
Examples:
gep_dm_full_chain.c.

◆ starneig_GEP_DM_Reduce()

starneig_error_t starneig_GEP_DM_Reduce ( starneig_distr_matrix_t  A,
starneig_distr_matrix_t  B,
starneig_distr_matrix_t  Q,
starneig_distr_matrix_t  Z,
double  real[],
double  imag[],
double  beta[],
int(*)(double real, double imag, double beta, void *arg)  predicate,
void *  arg,
int  selected[],
int *  num_selected 
)

Computes a (reordered) generalized Schur decomposition given a general matrix pencil.

Attention
This function uses several ScaLAPACK subroutines. The function exists if STARNEIG_GEP_DM_REDUCE is defined.
Parameters
[in,out]AOn entry, the general matrix $A$. On exit, the Schur matrix $S$.
[in,out]BOn entry, the general matrix $B$. On exit, the upper triangular matrix $T$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U_1$.
[in,out]ZOn entry, the orthogonal matrix $Z$. On exit, the product matrix $Z * U_2$.
[out]realAn array of the same size as $A$ containing the real parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]imagAn array of the same size as $A$ containing the imaginary parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]betaAn array of the same size as $A$ containing the $\beta$ values of computed generalized eigenvalues.
[in]predicateA function that takes a (complex) generalized eigenvalue as input and returns non-zero if it should be selected. For complex conjugate pairs of generalized eigenvalues, the predicate is called only for the generalized eigenvalue with positive imaginary part and the corresponding $2 \times 2$ block is either selected or deselected. The reordering step is skipped if the argument is a NULL pointer.
[in]argAn optional argument for the predicate function.
[out]selectedThe final positions of all correctly placed selected generalized eigenvalues.
[out]num_selectedThe number of selected generalized eigenvalues (a complex conjugate pair is counted as two selected generalized eigenvalues).
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise. STARNEIG_DID_NOT_CONVERGE if the QZ algorithm failed to converge. STARNEIG_PARTIAL_REORDERING if the generalized Schur form is not fully reordered.

◆ starneig_GEP_DM_Eigenvectors()

starneig_error_t starneig_GEP_DM_Eigenvectors ( int  selected[],
starneig_distr_matrix_t  S,
starneig_distr_matrix_t  T,
starneig_distr_matrix_t  Z,
starneig_distr_matrix_t  X 
)

Computes a generalized eigenvector for each selected generalized eigenvalue.

Parameters
[in]selectedThe selection array specifying the locations of the selected generalized eigenvalues. The number of 1's in the array is the same as the number of columns in $X$.
[in]SThe Schur matrix $S$.
[in]TThe upper triangular matrix $T$.
[in]ZThe orthogonal matrix $Z$.
[out]XA matrix with $n$ rows and one column for each selected generalized eigenvalue. The columns represent the computed generalized eigenvectors as previously described.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_GEP_DM_Select
Todo:
This interface function is not implemented.

◆ starneig_GEP_DM_Select()

starneig_error_t starneig_GEP_DM_Select ( starneig_distr_matrix_t  S,
starneig_distr_matrix_t  T,
int(*)(double real, double imag, double beta, void *arg)  predicate,
void *  arg,
int  selected[],
int *  num_selected 
)

Generates a selection array for a Schur-triangular matrix pencil using a user-supplied predicate function.

Parameters
[in]SThe Schur matrix $S$.
[in]TThe upper triangular matrix $T$.
[in]predicateA function that takes a (complex) generalized eigenvalue as input and returns non-zero if it should be selected. For complex conjugate pairs of generalized eigenvalues, the predicate is called only for the generallized eigenvalue with positive imaginary part and the corresponding $2 \times 2$ block is either selected or deselected.
[in]argAn optional argument for the predicate function.
[out]selectedThe selection array. Both elements of a selected complex conjugate pair are set to 1.
[out]num_selectedThe number of selected generalized eigenvalues (a complex conjugate pair is counted as two selected generalized eigenvalues).
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
Examples:
gep_dm_full_chain.c.

◆ starneig_GEP_DM_Schur_expert()

starneig_error_t starneig_GEP_DM_Schur_expert ( struct starneig_schur_conf *  conf,
starneig_distr_matrix_t  H,
starneig_distr_matrix_t  T,
starneig_distr_matrix_t  Q,
starneig_distr_matrix_t  Z,
double  real[],
double  imag[],
double  beta[] 
)

Computes a generalized Schur decomposition given a Hessenberg-triangular decomposition.

Parameters
[in]confConfiguration structure.
[in,out]HOn entry, the upper Hessenberg matrix $H$. On exit, the Schur matrix $S$.
[in,out]TOn entry, the upper triangular matrix $T$. On exit, the upper triangular matrix $\hat{T}$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U_1$.
[in,out]ZOn entry, the orthogonal matrix $Z$. On exit, the product matrix $Z * U_2$.
[out]realAn array of the same size as $H$ containing the real parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]imagAn array of the same size as $H$ containing the imaginary parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]betaAn array of the same size as $H$ containing the $\beta$ values of computed generalized eigenvalues.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_GEP_DM_Schur
starneig_schur_conf
starneig_schur_init_conf

◆ starneig_GEP_DM_ReorderSchur_expert()

starneig_error_t starneig_GEP_DM_ReorderSchur_expert ( struct starneig_reorder_conf *  conf,
int  selected[],
starneig_distr_matrix_t  S,
starneig_distr_matrix_t  T,
starneig_distr_matrix_t  Q,
starneig_distr_matrix_t  Z,
double  real[],
double  imag[],
double  beta[] 
)

Reorders selected generalized eigenvalues to the top left corner of a generalized Schur decomposition.

Parameters
[in]confConfiguration structure.
[in,out]selectedThe selection array.
[in,out]SOn entry, the Schur matrix $S$. On exit, the updated Schur matrix $\hat{S}$.
[in,out]TOn entry, the upper triangular $T$. On exit, the updates upper triangular matrix $\hat{T}$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U_1$.
[in,out]ZOn entry, the orthogonal matrix $Z$. On exit, the product matrix $Z * U_2$.
[out]realAn array of the same size as $S$ containing the real parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]imagAn array of the same size as $S$ containing the imaginary parts of the $\alpha$ values of the computed generalized eigenvalues.
[out]betaAn array of the same size as $S$ containing the $\beta$ values of computed generalized eigenvalues.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_GEP_DM_ReorderSchur
starneig_GEP_DM_Select
starneig_reorder_conf
starneig_reorder_init_conf

◆ starneig_GEP_DM_Eigenvectors_expert()

starneig_error_t starneig_GEP_DM_Eigenvectors_expert ( struct starneig_eigenvectors_conf *  conf,
int  selected[],
starneig_distr_matrix_t  S,
starneig_distr_matrix_t  T,
starneig_distr_matrix_t  Z,
starneig_distr_matrix_t  X 
)

Computes a generalized eigenvector for each selected generalized eigenvalue.

Parameters
[in]confConfiguration structure.
[in]selectedThe selection array specifying the locations of the selected generalized eigenvalues. The number of 1's in the array is the same as the number of columns in $X$.
[in]SThe Schur matrix $S$.
[in]TThe upper triangular matrix $T$.
[in]ZThe orthogonal matrix $Z$.
[out]XA matrix with $n$ rows and one column for each selected generalized eigenvalue. The columns represent the computed generalized eigenvectors as previously described.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_GEP_DM_Select
Todo:
This interface function is not implemented.