The library provides 12 interface functions for the generalized case:

Hessenberg-triangular reduction

Given a general matrix $(A,B)$ , the starneig_GEP_SM_HessenbergTriangular() and starneig_GEP_DM_HessenbergTriangular() interface functions compute a Hessenberg-triangular decomposition

$(A,B) = U_1 * (H,T) * U_2^T,$

where $H$ is upper Hessenberg, $T$ is upper triangular, and $U_1$ and $U_2$ are orthogonal. On exit, $A$ is overwritten by $H$ , $B$ is overwritten by $T$ , and $Q$ and $Z$ (which are orthogonal matrices on entry) are overwritten by

$Q \gets Q * U_1 \text{ and } Z \gets Z * U_2.$

Generalized Schur reduction

Given a Hessenberg-triangular decomposition

$(A,B) = Q * (H,T) * Z^T$

of a general matrix pencil $(A,B)$ , the starneig_GEP_SM_Schur() and starneig_GEP_DM_Schur() interface functions function compute a generalized Schur decomposition

$(A,B) = Q * ( U_1 * (S,\hat{T}) * U_2^T ) * Z^T,$

where $S$ is upper quasi-triangular with $1 \times 1$ and $2 \times 2$ blocks on the diagonal, $\hat{T}$ is a upper triangular matrix, and $U_1$ and $U_2$ are orthogonal.

On exit, $H$ is overwritten by $S$ , $T$ is overwritten by $\hat{T}$ , and $Q$ and $Z$ are overwritten by

$Q \gets Q * U_1 \text{ and } Z \gets Z * U_2.$

The computed generalized eigenvalues are returned as a pair of values $(\alpha,\beta)$ such that $\alpha/\beta$ gives the actual generalized eigenvalue. The quantity $\alpha/\beta$ may overflow.

Generalized eigenvalue reordering

Given a generalized Schur decomposition

$(A,B) = Q * (S,T) * Z^T$

of a general matrix pencil $(A,B)$ and a selection of generalized eigenvalues, the starneig_GEP_SM_ReorderSchur() and starneig_GEP_DM_ReorderSchur() interface functions attempt to reorder the selected generalized eigenvalues to the top left corner of an updated generalized Schur decomposition by an orthogonal similarity transformation

$(A,B) = Q * ( U_1 * (\hat{S},\hat{T}) * U_2^T ) * Z^T.$

On exit, $S$ is overwritten by $\hat{S}$ , $T$ is overwritten by $\hat{T}$ , and $Q$ and $Z$ are overwritten by

$Q \gets Q * U_1 \text{ and } Z \gets Z * U_2.$

Reordering may in rare cases fail. In such cases the output is guaranteed to be a Schur decomposition and all (if any) selected generalized eigenvalues that are correctly placed are marked in the selection array on exit.

Reordering may perturb the generalized eigenvalues and the generalized eigenvalues after reordering are returned. The computed generalized eigenvalues are returned as a pair of values $(\alpha,\beta)$ such that $\alpha/\beta$ gives the actual generalized eigenvalue. The quantity $\alpha/\beta$ may overflow.

Combined reduction to generalized Schur form and eigenvalue reordering

Given a general matrix pencil $(A,B)$ , the starneig_GEP_SM_Reduce() and starneig_GEP_DM_Reduce() interface functions compute a (reordered) generalized Schur decomposition

$(A,B) = U_1 * (S,T) * U_2^T,$

where $S$ is upper quasi-triangular with $1 \times 1$ and $2 \times 2$ blocks on the diagonal, $T$ is a upper triangular matrix, and $U_1$ and $U_2$ are orthogonal. Optionally, the interface functions attempt to reorder selected generalized eigenvalues to the top left corner of the generalized Schur decomposition.

On exit, $A$ is overwritten by $S$ , $B$ is overwritten by $T$ , and $Q$ and $Z$ (which are orthogonal matrices on entry) are overwritten by

$Q \gets Q * U_1 \text{ and } Z \gets Z * U_2.$

The computed generalized eigenvalues are returned as a pair of values $(\alpha,\beta)$ such that $\alpha/\beta$ gives the actual generalized eigenvalue. The quantity $\alpha/\beta$ may overflow.

Reordering may in rare cases fail. In such cases the output is guaranteed to be a Schur-triangular decomposition and all (if any) selected generalized eigenvalues that are correctly placed are marked in the selection array on exit.

Generalized eigenvectors

Given a generalized Schur decomposition

$(A,B) = Q * (S,T) * Z^T$

of a general matrix pencil $(A,B)$ and a selection of generalized eigenvalues, the starneig_GEP_SM_Eigenvectors() and starneig_GEP_DM_Eigenvectors() interface functions compute and return a generalized eigenvector for each of the selected generalized eigenvalues.

The generalized eigenvectors are stored as columns in the output matrix $X$ in the same order as their corresponding generalized eigenvalues appear in the selection array. A real generalized eigenvector is stored as a single column. The real and imaginary parts of a complex generalized eigenvector are stored as consecutive columns.

For a selected pair of complex conjugate generalized eigenvalues, a generalized eigenvector is computed only for the generalized eigenvalue with positive imaginary part. Thus, every selected generalized eigenvalue contributes one column to the output matrix and thus the number of selected generalized eigenvalues is equal to the number of columns of $X$ .

Eigenvalue selection helper

Given a Schur-triangular matrix pencil $(S,T)$ and a predicate function, the starneig_GEP_SM_Select() and starneig_GEP_DM_Select() interface functions conveniently generate a correct selection array and count the number of selected generalized eigenvalues. The count is useful when allocating storage for the generalized eigenvector matrix computed by starneig_GEP_DM_Eigenvectors().

// a predicate function that selects all finite generalized eigenvalues that
// have a real part that is larger than a given value
static int predicate(double real, double imag, double beta, void *arg)
{
    double value = * (double *) arg;
    if (beta != 0.0 && value < real/beta)
        return 1;
    return 0;
}
void func(...)
{
    ...
    double value = 0.5;
    int num_selected, *selected = malloc(n*sizeof(int));
    starneig_GEP_SM_Select(
        n, S, ldS, T, ldT, &predicate, &value, selected, &num_selected);
    ...
}

See modules Shared Memory / Generalized EVP and Distributed Memory / Generalized EVP for further information. See also examples gep_sm_full_chain.c, gep_dm_full_chain.c and gep_sm_eigenvectors.c.