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

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

Computational functions

starneig_error_t starneig_SEP_DM_Hessenberg (starneig_distr_matrix_t A, starneig_distr_matrix_t Q)
 Computes a Hessenberg decomposition of a general matrix. More...
 
starneig_error_t starneig_SEP_DM_Schur (starneig_distr_matrix_t H, starneig_distr_matrix_t Q, double real[], double imag[])
 Computes a Schur decomposition given a Hessenberg decomposition. More...
 
starneig_error_t starneig_SEP_DM_ReorderSchur (int selected[], starneig_distr_matrix_t S, starneig_distr_matrix_t Q, double real[], double imag[])
 Reorders selected eigenvalues to the top left corner of a Schur decomposition. More...
 
starneig_error_t starneig_SEP_DM_Reduce (starneig_distr_matrix_t A, starneig_distr_matrix_t Q, double real[], double imag[], int(*predicate)(double real, double imag, void *arg), void *arg, int selected[], int *num_selected)
 Computes a (reordered) Schur decomposition of a general matrix. More...
 
starneig_error_t starneig_SEP_DM_Eigenvectors (int selected[], starneig_distr_matrix_t S, starneig_distr_matrix_t Q, starneig_distr_matrix_t X)
 Computes an eigenvector for each selected eigenvalue. More...
 

Helper functions

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

Expert computational functions

starneig_error_t starneig_SEP_DM_Schur_expert (struct starneig_schur_conf *conf, starneig_distr_matrix_t H, starneig_distr_matrix_t Q, double real[], double imag[])
 Computes a Schur decomposition given a Hessenberg decomposition. More...
 
starneig_error_t starneig_SEP_DM_ReorderSchur_expert (struct starneig_reorder_conf *conf, int selected[], starneig_distr_matrix_t S, starneig_distr_matrix_t Q, double real[], double imag[])
 Reorders selected eigenvalues to the top left corner of a Schur decomposition. More...
 
starneig_error_t starneig_SEP_DM_Eigenvectors_expert (struct starneig_eigenvectors_conf *conf, int selected[], starneig_distr_matrix_t S, starneig_distr_matrix_t Q, starneig_distr_matrix_t X)
 Computes an eigenvector for each selected eigenvalue. More...
 

Detailed Description

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

Function Documentation

◆ starneig_SEP_DM_Hessenberg()

starneig_error_t starneig_SEP_DM_Hessenberg ( starneig_distr_matrix_t  A,
starneig_distr_matrix_t  Q 
)

Computes a Hessenberg decomposition of a general matrix.

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

◆ starneig_SEP_DM_Schur()

starneig_error_t starneig_SEP_DM_Schur ( starneig_distr_matrix_t  H,
starneig_distr_matrix_t  Q,
double  real[],
double  imag[] 
)

Computes a Schur decomposition given a Hessenberg decomposition.

Parameters
[in,out]HOn entry, the upper Hessenberg matrix $H$. On exit, the Schur matrix $S$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[out]realAn array of the same size as $H$ containing the real parts of the computed eigenvalues.
[out]imagAn array of the same size as $H$ containing the imaginary parts of the computed 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 QR algorithm failed to converge.
Examples:
sep_dm_full_chain.c.

◆ starneig_SEP_DM_ReorderSchur()

starneig_error_t starneig_SEP_DM_ReorderSchur ( int  selected[],
starneig_distr_matrix_t  S,
starneig_distr_matrix_t  Q,
double  real[],
double  imag[] 
)

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

Parameters
[in,out]selectedThe selection array. On entry, the initial positions of the selected eigenvalues. On exit, the final positions of all correctly placed selected 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]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[out]realAn array of the same size as $S$ containing the real parts of the computed eigenvalues.
[out]imagAn array of the same size as $S$ containing the imaginary parts of the computed 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 Schur form is not fully reordered.
See also
starneig_SEP_DM_Select
Examples:
sep_dm_full_chain.c.

◆ starneig_SEP_DM_Reduce()

starneig_error_t starneig_SEP_DM_Reduce ( starneig_distr_matrix_t  A,
starneig_distr_matrix_t  Q,
double  real[],
double  imag[],
int(*)(double real, double imag, void *arg)  predicate,
void *  arg,
int  selected[],
int *  num_selected 
)

Computes a (reordered) Schur decomposition of a general matrix.

Attention
This function uses several ScaLAPACK subroutines. The function exists if STARNEIG_SEP_DM_REDUCE is defined.
Parameters
[in,out]AOn entry, the general matrix $A$. On exit, the Schur matrix $S$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[out]realAn array of the same size as $A$ containing the real parts of the computed eigenvalues.
[out]imagAn array of the same size as $A$ containing the imaginary parts of the computed eigenvalues.
[in]predicateA function that takes a (complex) eigenvalue as input and returns non-zero if it should be selected. For complex conjugate pairs of eigenvalues, the predicate is called only for the 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 eigenvalues.
[out]num_selectedThe number of selected eigenvalues (a complex conjugate pair is counted as two selected 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 QR algorithm failed to converge. STARNEIG_PARTIAL_REORDERING if the Schur form is not fully reordered.

◆ starneig_SEP_DM_Eigenvectors()

starneig_error_t starneig_SEP_DM_Eigenvectors ( int  selected[],
starneig_distr_matrix_t  S,
starneig_distr_matrix_t  Q,
starneig_distr_matrix_t  X 
)

Computes an eigenvector for each selected eigenvalue.

Parameters
[in]selectedThe selection array specifying the locations of the selected 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]QThe orthogonal matrix $Q$.
[out]XA matrix with $n$ rows and one column for each selected eigenvalue. The columns represent the computed 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_SEP_DM_Select
Todo:
This interface function is not implemented.

◆ starneig_SEP_DM_Select()

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

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

Parameters
[in]SThe Schur matrix $S$.
[in]predicateA function that takes a (complex) eigenvalue as input and returns non-zero if it should be selected. For complex conjugate pairs of eigenvalues, the predicate is called only for the 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 (global) number of selected eigenvalues (a complex conjugate pair is counted as two selected eigenvalues).
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
Examples:
sep_dm_full_chain.c.

◆ starneig_SEP_DM_Schur_expert()

starneig_error_t starneig_SEP_DM_Schur_expert ( struct starneig_schur_conf *  conf,
starneig_distr_matrix_t  H,
starneig_distr_matrix_t  Q,
double  real[],
double  imag[] 
)

Computes a Schur decomposition given a Hessenberg decomposition.

Parameters
[in]confConfiguration structure.
[in,out]HOn entry, the upper Hessenberg matrix $H$. On exit, the Schur matrix $S$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[out]realAn array of the same size as $H$ containing the real parts of the computed eigenvalues.
[out]imagAn array of the same size as $H$ containing the imaginary parts of the computed eigenvalues.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_SEP_DM_Schur
starneig_schur_conf
starneig_schur_init_conf

◆ starneig_SEP_DM_ReorderSchur_expert()

starneig_error_t starneig_SEP_DM_ReorderSchur_expert ( struct starneig_reorder_conf *  conf,
int  selected[],
starneig_distr_matrix_t  S,
starneig_distr_matrix_t  Q,
double  real[],
double  imag[] 
)

Reorders selected eigenvalues to the top left corner of a 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]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[out]realAn array of the same size as $S$ containing the real parts of the computed eigenvalues.
[out]imagAn array of the same size as $S$ containing the imaginary parts of the computed eigenvalues.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_SEP_DM_ReorderSchur
starneig_SEP_DM_Select
starneig_reorder_conf
starneig_reorder_init_conf

◆ starneig_SEP_DM_Eigenvectors_expert()

starneig_error_t starneig_SEP_DM_Eigenvectors_expert ( struct starneig_eigenvectors_conf *  conf,
int  selected[],
starneig_distr_matrix_t  S,
starneig_distr_matrix_t  Q,
starneig_distr_matrix_t  X 
)

Computes an eigenvector for each selected eigenvalue.

Parameters
[in]selectedThe selection array specifying the locations of the selected 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]QThe orthogonal matrix $Q$.
[out]XA matrix with $n$ rows and one column for each selected eigenvalue. The columns represent the computed 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_SEP_DM_Select
Todo:
This interface function is not implemented.