## Stata 15 help for mf_hessenbergd

```
[M-5] hessenbergd() -- Hessenberg decomposition

Syntax

void     hessenbergd(numeric matrix A, H, Q)

void    _hessenbergd(numeric matrix A,    Q)

Description

hessenbergd(A, H, Q) calculates the Hessenberg decomposition of a square,
numeric matrix, A, returning the upper Hessenberg form matrix in H and
the orthogonal (unitary) matrix in Q.  Q is orthogonal if A is real and
unitary if A is complex.

_hessenbergd(A, Q) does the same as hessenbergd() except that it returns
H in A.

_hessenbergd_la() is the interface into the LAPACK routines used to
implement the above function; see [M-1] LAPACK. Its direct use is not
recommended.

Remarks

The Hessenberg decomposition of a matrix, A, can be written as

Q' * A * Q = H

where H is upper Hessenberg; Q is orthogonal if A is real or unitary if A
is complex.

A matrix H is in upper Hessenberg form if all entries below its first
subdiagonal are zero.  For example, a 5 x 5 upper Hessenberg matrix looks
like

1   2   3   4   5
+---------------------+
1 |  x   x   x   x   x  |
2 |  x   x   x   x   x  |
3 |  0   x   x   x   x  |
4 |  0   0   x   x   x  |
5 |  0   0   0   x   x  |
+---------------------+

For instance,

: A
1    2    3    4    5
+--------------------------+
1 |   3    2    1   -2   -5  |
2 |   4    2    1    0    3  |
3 |   4    4    0    1   -1  |
4 |   5    6    7   -2    4  |
5 |   6    7    1    2   -1  |
+--------------------------+

: hessenbergd(A, H=., Q=.)

: H
1              2              3              4
+------------------------------------------------------------
1 |             3    2.903464745    -.552977683    -4.78764119
2 |  -9.643650761    7.806451613    2.878001755      5.1085876
3 |             0   -3.454023879   -6.119229633   -.2347200215
4 |             0              0    1.404136249   -1.715823624
5 |             0              0              0   -2.668128952
+------------------------------------------------------------

5
----------------+
1    -1.530555451  |
2     5.580422694  |
3     1.467932097  |
4    -.9870601994  |
5     -.971398356  |
----------------+

: Q
1              2              3              4
+------------------------------------------------------------
1 |             1              0              0              0
2 |             0   -.4147806779   -.0368006164   -.4047768558
3 |             0   -.4147806779   -.4871239484   -.5692309155
4 |             0   -.5184758474    .8096135604   -.0748449196
5 |             0   -.6221710168   -.3253949238    .7117092805
+------------------------------------------------------------

5
----------------+
1               0  |
2    -.8140997488  |
3     .5163752637  |
4     .2647771074  |
5    -.0221645995  |
----------------+

Many algorithms use a Hessenberg decomposition in the process of finding
another decomposition with more structure.

Conformability

hessenbergd(A, H, Q):
input:
A:  n x n
output:
H:  n x n
Q:  n x n

_hessenbergd(A, Q):
input:
A:  n x n
output:
A:  n x n
Q:  n x n

Diagnostics

_hessenbergd() aborts with error if A is a view.

hessenbergd() and _hessenbergd() return missing results if A contains
missing values.

Source code

hessenbergd.mata, _hessenbergd.mata

```