DOC: Enhance description/usage for np.linalg.eig*h

[stuartarchibald]

Proposed documentation enhancement to the np.linalg.eig*h
routines.

The current documentation does not reflect the nature of the
underlying LAPACK routines and the way in which they interpet
the input. This documentation and examples are with view of
adding clarity to what is actually performed.

[wrwrwr]

EDIT: Obviously, -1 and 4 are eigenvalues for [[0, 2], [2, 3]] and the new example actually demonstrates a similar case.

These functions seem to give hardly explainable results if the matrix is non-symmetric, for instance:

eigvalsh([[0, 1], [2, 3]])
# array([-1.,  4.])

Hence, wouldn't it be better to either:

• add a check and raise an exception for non-symmetric / non-Hermitian matrices;
• add an explicit note that in the above cases the result is undefined.

[charris]

@wrwrwr I think the result is well defined, just possibly unexpected. The use of the upper/lower triangular part avoids the numerical difficulty of determining true symmetry and is also compatible with packed storage of Hermitean arrays.

[charris]

Hmm, this doesn't look deprecated in the code. @pv Is this a stray bit left over from the merge of the gufuncs?

[pv]

I have no recollection of this, but 74e1477 mentions lower so maybe the idea was to harmonize this with scipy's kwargs and replace the U/L with lower=True/False kwarg.

[charris]

"Same as lower," looks completely irrelevant. Hmm...

[pv]

cf signature https://docs.scipy.org/doc/scipy-0.18.1/reference/generated/scipy.linalg.eigvalsh.html#scipy.linalg.eigvalsh

[charris]

@pv, OK. I'll remove it until such time, if ever, it gets harmonized with scipy ;) Speaking of which, we might should do the same for the qr decomposition at some point.

[charris]

Thanks @stuartarchibald .