The LA_ELMHES function reduces a real nonsymmetric or complex non-Hermitian array to upper Hessenberg form *H*. If the array is real then the decomposition is *A* = *Q H Q*^{T}, where *Q* is orthogonal. If the array is complex Hermitian then the decomposition is *A* = *Q H Q*^{H}, where *Q* is unitary. The superscript T represents the transpose while superscript *H* represents the Hermitian, or transpose complex conjugate.

LA_ELMHES is based on the following LAPACK routines:

Output Type |
Balance & Reduce |
Norm |
Optional Q |

Float |
sgebal, sgehrd |
slange |
sorghr |

Double |
dgebal, dgehrd |
dlange |
dorghr |

Complex |
cgebal, cgehrd |
clange |
cunghr |

Double complex |
zgebal, zgehrd |
zlange |
zunghr |

## Examples

See LA_EIGENVEC for an example of using this procedure.

## Syntax

*Result* = LA_ELMHES( *Array* [, Q] [, BALANCE=*value*] [, /DOUBLE] [, NORM_BALANCE=*variable*] [, PERMUTE_RESULT=*variable*] [, SCALE_RESULT=*variable*] )

## Return Value

The result is an array of the same type as *A* containing the upper Hessenberg form. The Hessenberg array is stored in the upper triangle and the first subdiagonal. Elements below the subdiagonal should be ignored but are not automatically set to zero.

## Arguments

### Array

The *n*-by-*n* real or complex array to reduce to upper Hessenberg form.

### Q

Set this optional argument to a named variable in which the array *Q* will be returned. The *Q* argument may then be input into LA_HQR to compute the Schur vectors.

## Keywords

### BALANCE

Set this keyword to one of the following values:

- BALANCE = 0: No balancing is applied to
*Array*. - BALANCE = 1: Both permutation and scale balancing are performed.
- BALANCE = 2: Permutations are performed to make the array more nearly upper triangular.
- BALANCE = 3: Diagonally scale the array to make the columns and rows more equal in norm.

The default is BALANCE = 1, which performs both permutation and scaling balances. Balancing a nonsymmetric array is recommended to reduce the sensitivity of eigenvalues to rounding errors.

### DOUBLE

Set this keyword to use double-precision for computations and to return a double-precision (real or complex) result. Set DOUBLE = 0 to use single-precision for computations and to return a single-precision (real or complex) result. The default is /DOUBLE if *Array* is double precision, otherwise the default is DOUBLE = 0.

### NORM_BALANCE

Set this keyword to a named variable in which the one-norm of the balanced matrix will be returned. The one-norm is defined as the maximum value of the sum of absolute values of the columns.

### PERMUTE_RESULT

Set this keyword to a named variable in which the result for permutation balancing will be returned as a two-element vector [*ilo*, *ihi*]. If permute balancing is not done then the values will be *ilo* = *1* and *ihi* = *n*.

### SCALE_RESULT

Set this keyword to a named variable in which the result for permute and scale balancing will be returned as an *n*-element vector.

## Version History

5.6 |
Introduced |

## Resources and References

For details see Anderson et al., *LAPACK Users' Guide*, 3rd ed., SIAM, 1999.