StarNEig User's Guide  v0.1.5
A task-based library for solving dense nonsymmetric eigenvalue problems
Shared Memory / Standard EVP

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

Computational functions

starneig_error_t starneig_SEP_SM_Hessenberg (int n, double A[], int ldA, double Q[], int ldQ)
 Computes a Hessenberg decomposition of a general matrix. More...
 
starneig_error_t starneig_SEP_SM_Schur (int n, double H[], int ldH, double Q[], int ldQ, double real[], double imag[])
 Computes a Schur decomposition given a Hessenberg decomposition. More...
 
starneig_error_t starneig_SEP_SM_ReorderSchur (int n, int selected[], double S[], int ldS, double Q[], int ldQ, double real[], double imag[])
 Reorders selected eigenvalues to the top left corner of a Schur decomposition. More...
 
starneig_error_t starneig_SEP_SM_Reduce (int n, double A[], int ldA, double Q[], int ldQ, 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_SM_Eigenvectors (int n, int selected[], double S[], int ldS, double Q[], int ldQ, double X[], int ldX)
 Computes an eigenvector for each selected eigenvalue. More...
 

Helper functions

starneig_error_t starneig_SEP_SM_Select (int n, double S[], int ldS, 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_SM_Hessenberg_expert (struct starneig_hessenberg_conf *conf, int n, int begin, int end, double A[], int ldA, double Q[], int ldQ)
 Computes a Hessenberg decomposition of a general matrix. More...
 
starneig_error_t starneig_SEP_SM_Schur_expert (struct starneig_schur_conf *conf, int n, double H[], int ldH, double Q[], int ldQ, double real[], double imag[])
 Computes a Schur decomposition given a Hessenberg decomposition. More...
 
starneig_error_t starneig_SEP_SM_ReorderSchur_expert (struct starneig_reorder_conf *conf, int n, int selected[], double S[], int ldS, double Q[], int ldQ, double real[], double imag[])
 Reorders selected eigenvalues to the top left corner of a Schur decomposition. More...
 
starneig_error_t starneig_SEP_SM_Eigenvectors_expert (struct starneig_eigenvectors_conf *conf, int n, int selected[], double S[], int ldS, double Q[], int ldQ, double X[], int ldX)
 Computes an eigenvector for each selected eigenvalue. More...
 

Detailed Description

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

Function Documentation

◆ starneig_SEP_SM_Hessenberg()

starneig_error_t starneig_SEP_SM_Hessenberg ( int  n,
double  A[],
int  ldA,
double  Q[],
int  ldQ 
)

Computes a Hessenberg decomposition of a general matrix.

Parameters
[in]nThe order of $A$ and $Q$.
[in,out]AOn entry, the general matrix $A$. On exit, the upper Hessenberg matrix $H$.
[in]ldAThe leading dimension of $A$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[in]ldQThe leading dimension of $Q$.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
Examples:
sep_sm_full_chain.c.

◆ starneig_SEP_SM_Schur()

starneig_error_t starneig_SEP_SM_Schur ( int  n,
double  H[],
int  ldH,
double  Q[],
int  ldQ,
double  real[],
double  imag[] 
)

Computes a Schur decomposition given a Hessenberg decomposition.

Parameters
[in]nThe order of $H$ and $Q$.
[in,out]HOn entry, the upper Hessenberg matrix $H$. On exit, the Schur matrix $S$.
[in]ldHThe leading dimension of $H$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[in]ldQThe leading dimension of $Q$.
[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_sm_full_chain.c.

◆ starneig_SEP_SM_ReorderSchur()

starneig_error_t starneig_SEP_SM_ReorderSchur ( int  n,
int  selected[],
double  S[],
int  ldS,
double  Q[],
int  ldQ,
double  real[],
double  imag[] 
)

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

Parameters
[in]nThe order of $S$ and $Q$.
[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]ldSThe leading dimension of $S$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[in]ldQThe leading dimension of $Q$.
[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_SM_Select
Examples:
sep_sm_full_chain.c.

◆ starneig_SEP_SM_Reduce()

starneig_error_t starneig_SEP_SM_Reduce ( int  n,
double  A[],
int  ldA,
double  Q[],
int  ldQ,
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.

Parameters
[in]nThe order of $A$ and $Q$.
[in,out]AOn entry, the general matrix $A$. On exit, the Schur matrix $S$.
[in]ldAThe leading dimension of $A$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[in]ldQThe leading dimension of $Q$.
[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.
Examples:
sep_sm_eigenvectors.c.

◆ starneig_SEP_SM_Eigenvectors()

starneig_error_t starneig_SEP_SM_Eigenvectors ( int  n,
int  selected[],
double  S[],
int  ldS,
double  Q[],
int  ldQ,
double  X[],
int  ldX 
)

Computes an eigenvector for each selected eigenvalue.

Parameters
[in]nThe order of $S$ and $Q$ and the number of rows of $X$.
[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]ldSThe leading dimension of $S$.
[in]QThe orthogonal matrix $Q$.
[in]ldQThe The leading dimension of $Q$.
[out]XA matrix with $n$ rows and one column for each selected eigenvalue. The columns represent the computed eigenvectors as previously described.
[in]ldXThe leading dimension of $X$.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_SEP_SM_Select
Examples:
sep_sm_eigenvectors.c.

◆ starneig_SEP_SM_Select()

starneig_error_t starneig_SEP_SM_Select ( int  n,
double  S[],
int  ldS,
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]nThe order of $S$.
[in]SThe Schur matrix $S$.
[in]ldSThe leading dimension of $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 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_sm_eigenvectors.c, and sep_sm_full_chain.c.

◆ starneig_SEP_SM_Hessenberg_expert()

starneig_error_t starneig_SEP_SM_Hessenberg_expert ( struct starneig_hessenberg_conf *  conf,
int  n,
int  begin,
int  end,
double  A[],
int  ldA,
double  Q[],
int  ldQ 
)

Computes a Hessenberg decomposition of a general matrix.

Parameters
[in]confConfiguration structure.
[in]nThe order of $A$ and $Q$.
[in]beginFirst column to be reduced.
[in]endLast column to be reduced + 1.
[in,out]AOn entry, the general matrix $A$. On exit, the upper Hessenberg matrix $H$.
[in]ldAThe leading dimension of $A$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[in]ldQThe leading dimension of $Q$.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_SEP_SM_Hessenberg
starneig_hessenberg_conf
starneig_hessenberg_init_conf

◆ starneig_SEP_SM_Schur_expert()

starneig_error_t starneig_SEP_SM_Schur_expert ( struct starneig_schur_conf *  conf,
int  n,
double  H[],
int  ldH,
double  Q[],
int  ldQ,
double  real[],
double  imag[] 
)

Computes a Schur decomposition given a Hessenberg decomposition.

Parameters
[in]confConfiguration structure.
[in]nThe order of $H$ and $Q$.
[in,out]HOn entry, the upper Hessenberg matrix $H$. On exit, the Schur matrix $S$.
[in]ldHThe leading dimension of $H$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[in]ldQThe leading dimension of $Q$.
[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_SM_Schur
starneig_schur_conf
starneig_schur_init_conf

◆ starneig_SEP_SM_ReorderSchur_expert()

starneig_error_t starneig_SEP_SM_ReorderSchur_expert ( struct starneig_reorder_conf *  conf,
int  n,
int  selected[],
double  S[],
int  ldS,
double  Q[],
int  ldQ,
double  real[],
double  imag[] 
)

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

Parameters
[in]confConfiguration structure.
[in]nThe order of $S$ and $Q$.
[in,out]selectedThe selection array.
[in,out]SOn entry, the Schur matrix $S$. On exit, the updated Schur matrix $\hat{S}$.
[in]ldSThe leading dimension of $S$.
[in,out]QOn entry, the orthogonal matrix $Q$. On exit, the product matrix $Q * U$.
[in]ldQThe leading dimension of $Q$.
[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_SM_ReorderSchur
starneig_SEP_SM_Select
starneig_reorder_conf
starneig_reorder_init_conf

◆ starneig_SEP_SM_Eigenvectors_expert()

starneig_error_t starneig_SEP_SM_Eigenvectors_expert ( struct starneig_eigenvectors_conf *  conf,
int  n,
int  selected[],
double  S[],
int  ldS,
double  Q[],
int  ldQ,
double  X[],
int  ldX 
)

Computes an eigenvector for each selected eigenvalue.

Parameters
[in]confConfiguration structure.
[in]nThe order of $S$ and $Q$ and the number of rows of $X$.
[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]ldSThe leading dimension of $S$.
[in]QThe orthogonal matrix $Q$.
[in]ldQThe The leading dimension of $Q$.
[out]XA matrix with $n$ rows and one column for each selected eigenvalue. The columns represent the computed eigenvectors as previously described.
[in]ldXThe leading dimension of $X$.
Returns
STARNEIG_SUCCESS (0) on success. Negative integer -i when i'th argument is invalid. Positive error code otherwise.
See also
starneig_SEP_SM_Select