naginterfaces.library.lapackeig.zhsein

naginterfaces.library.lapackeig.zhsein(job, eigsrc, initv, select, h, w, vl=None, vr=None)

zhsein computes selected left and/or right eigenvectors of a complex upper Hessenberg matrix corresponding to specified eigenvalues, by inverse iteration.

For full information please refer to the NAG Library document for f08px

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f08/f08pxf.html

Parameters

jobstr, length 1

Indicates whether left and/or right eigenvectors are to be computed.

$job=\text{'R'}$

Only right eigenvectors are computed.

$job=\text{'L'}$

Only left eigenvectors are computed.

$job=\text{'B'}$

Both left and right eigenvectors are computed.

eigsrcstr, length 1

Indicates whether the eigenvalues of $H$ (stored in $w$) were found using zhseqr().

$eigsrc=\text{'Q'}$

The eigenvalues of $H$ were found using zhseqr(); thus if $H$ has any zero subdiagonal elements (and so is block triangular), then the $j$th eigenvalue can be assumed to be an eigenvalue of the block containing the $j$th row/column. This property allows the function to perform inverse iteration on just one diagonal block.

$eigsrc=\text{'N'}$

No such assumption is made and the function performs inverse iteration using the whole matrix.

initvstr, length 1

Indicates whether you are supplying initial estimates for the selected eigenvectors.

$initv=\text{'N'}$

No initial estimates are supplied.

$initv=\text{'U'}$

Initial estimates are supplied in $vl$ and/or $vr$.

selectbool, array-like, shape $\left(n\right)$

Specifies which eigenvectors are to be computed. To select the eigenvector corresponding to the eigenvalue $w[j-1]$, $select[j-1]$ must be set to $True$.

hcomplex, array-like, shape $(n,n)$

The $n\times n$ upper Hessenberg matrix $H$. If a NaN is detected in $h$, the function will return with $errno$ = -6.

wcomplex, array-like, shape $\left(n\right)$

The eigenvalues of the matrix $H$. If $eigsrc=\text{'Q'}$, the array must be exactly as returned by zhseqr().

vlNone or complex, array-like, shape $(:,:)$, optional

Note: the required extent for this argument in dimension 1 is determined as follows: if $job\text{in}(\text{'L'},\text{'B'})$: $n$; if $job=\text{'R'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $job\text{in}(\text{'L'},\text{'B'})$: $\text{mm}$; if $job=\text{'R'}$: $1$; otherwise: $0$.

If $initv=\text{'U'}$ and $job=\text{'L'}$ or $\text{'B'}$, $vl$ must contain starting vectors for inverse iteration for the left eigenvectors. Each starting vector must be stored in the same column as will be used to store the corresponding eigenvector.

If $initv=\text{'N'}$, $vl$ need not be set.

vrNone or complex, array-like, shape $(:,:)$, optional

Note: the required extent for this argument in dimension 1 is determined as follows: if $job\text{in}(\text{'R'},\text{'B'})$: $n$; if $job=\text{'L'}$: $1$; otherwise: $0$.

Note: the required extent for this argument in dimension 2 is determined as follows: if $job\text{in}(\text{'R'},\text{'B'})$: $\text{mm}$; if $job=\text{'L'}$: $1$; otherwise: $0$.

If $initv=\text{'U'}$ and $job=\text{'R'}$ or $\text{'B'}$, $vr$ must contain starting vectors for inverse iteration for the right eigenvectors. Each starting vector must be stored in the same column as will be used to store the corresponding eigenvector.

If $initv=\text{'N'}$, $vr$ need not be set.

Returns

wcomplex, ndarray, shape $\left(n\right)$

The real parts of some elements of $w$ may be modified, as close eigenvalues are perturbed slightly in searching for independent eigenvectors.

vlNone or complex, ndarray, shape $(:,:)$

If $job=\text{'L'}$ or $\text{'B'}$, $vl$ contains the computed left eigenvectors (as specified by $select$). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues.

If $job=\text{'R'}$, $vl$ is not referenced.

vrNone or complex, ndarray, shape $(:,:)$

If $job=\text{'R'}$ or $\text{'B'}$, $vr$ contains the computed right eigenvectors (as specified by $select$). The eigenvectors are stored consecutively in the columns of the array, in the same order as their eigenvalues.

If $job=\text{'L'}$, $vr$ is not referenced.

mint

$\text{m}$, the number of selected eigenvectors.

ifaillint, ndarray, shape $(:)$

If $job=\text{'L'}$ or $\text{'B'}$, then $ifaill[i-1]=0$ if the selected left eigenvector converged and $ifaill[i-1]=j>0$ if the eigenvector stored in the $i$th row or column of $vl$ (corresponding to the $j$th eigenvalue) failed to converge.

If $job=\text{'R'}$, $ifaill$ is not referenced.

ifailrint, ndarray, shape $(:)$

If $job=\text{'R'}$ or $\text{'B'}$, then $ifailr[i-1]=0$ if the selected right eigenvector converged and $ifailr[i-1]=j>0$ if the eigenvector stored in the $i$th column of $vr$ (corresponding to the $j$th eigenvalue) failed to converge.

If $job=\text{'L'}$, $ifailr$ is not referenced.

Raises

NagValueError

(errno $-1$)

On entry, error in parameter $job$.

Constraint: $job=\text{'R'}$, $\text{'L'}$ or $\text{'B'}$.

(errno $-2$)

On entry, error in parameter $eigsrc$.

Constraint: $eigsrc=\text{'Q'}$ or $\text{'N'}$.

(errno $-3$)

On entry, error in parameter $initv$.

Constraint: $initv=\text{'N'}$ or $\text{'U'}$.

(errno $-5$)

On entry, error in parameter $\text{n}$.

Constraint: $n\ge 0$.

(errno $-6$)

On entry, error in parameter $h$.

Constraint: No element of $h$ is equal to NaN.

(errno $-13$)

On entry, error in parameter $\text{mm}$.

Constraint: $\text{mm}\ge \text{m}$.

(errno $i>0$)

$⟨value⟩$ eigenvectors (as indicated by arguments $ifaill$ and/or $ifailr$) failed to converge. The corresponding columns of $vl$ and/or $vr$ contain no useful information.

Notes

zhsein computes left and/or right eigenvectors of a complex upper Hessenberg matrix $H$, corresponding to selected eigenvalues.

The right eigenvector $x$, and the left eigenvector $y$, corresponding to an eigenvalue $\lambda$, are defined by:

$$Hx=\lambda x\text{and}{y}^{H}H=\lambda y^H(\text{or}{H}^{H}y=\overline{\lambda }y)\text{.}$$

The eigenvectors are computed by inverse iteration. They are scaled so that $max\left(\left|Re\left(x_i\right)\right|+\left|Im\left(x_i\right)\right|\right)=1$.

If $H$ has been formed by reduction of a complex general matrix $A$ to upper Hessenberg form, then the eigenvectors of $H$ may be transformed to eigenvectors of $A$ by a call to zunmhr().

References

Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore