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]	A	On entry, the general matrix \(A\). On exit, the upper Hessenberg matrix \(H\).
[in,out]	Q	On 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]	H	On entry, the upper Hessenberg matrix \(H\). On exit, the Schur matrix \(S\).
[in,out]	Q	On entry, the orthogonal matrix \(Q\). On exit, the product matrix \(Q * U\).
[out]	real	An array of the same size as \(H\) containing the real parts of the computed eigenvalues.
[out]	imag	An 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]	selected	The 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]	S	On entry, the Schur matrix \(S\). On exit, the updated Schur matrix \(\hat{S}\).
[in,out]	Q	On entry, the orthogonal matrix \(Q\). On exit, the product matrix \(Q * U\).
[out]	real	An array of the same size as \(S\) containing the real parts of the computed eigenvalues.
[out]	imag	An 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]	A	On entry, the general matrix \(A\). On exit, the Schur matrix \(S\).
[in,out]	Q	On entry, the orthogonal matrix \(Q\). On exit, the product matrix \(Q * U\).
[out]	real	An array of the same size as \(A\) containing the real parts of the computed eigenvalues.
[out]	imag	An array of the same size as \(A\) containing the imaginary parts of the computed eigenvalues.
[in]	predicate	A 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]	arg	An optional argument for the predicate function.
[out]	selected	The final positions of all correctly placed selected eigenvalues.
[out]	num_selected	The 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]	selected	The 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]	S	The Schur matrix \(S\).
[in]	Q	The orthogonal matrix \(Q\).
[out]	X	A 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]	S	The Schur matrix \(S\).
[in]	predicate	A 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]	arg	An optional argument for the predicate function.
[out]	selected	The selection array. Both elements of a selected complex conjugate pair are set to 1.
[out]	num_selected	The (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]	conf	Configuration structure.
[in,out]	H	On entry, the upper Hessenberg matrix \(H\). On exit, the Schur matrix \(S\).
[in,out]	Q	On entry, the orthogonal matrix \(Q\). On exit, the product matrix \(Q * U\).
[out]	real	An array of the same size as \(H\) containing the real parts of the computed eigenvalues.
[out]	imag	An 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]	conf	Configuration structure.
[in,out]	selected	The selection array.
[in,out]	S	On entry, the Schur matrix \(S\). On exit, the updated Schur matrix \(\hat{S}\).
[in,out]	Q	On entry, the orthogonal matrix \(Q\). On exit, the product matrix \(Q * U\).
[out]	real	An array of the same size as \(S\) containing the real parts of the computed eigenvalues.
[out]	imag	An 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]	conf	Configuration structure.
[in]	selected	The 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]	S	The Schur matrix \(S\).
[in]	Q	The orthogonal matrix \(Q\).
[out]	X	A 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.