DOC: Fix erroneous return type description for np.roots.

[stuartarchibald]

np.roots() does not always return complex roots, the
roots of a polynomial depend its coefficients and
therefore may be in the real or complex domain.

e.g.

>>> (np.roots([1,2,3])).dtype
dtype('complex128')
>>> (np.roots([1,2,])).dtype
dtype('float64')

[charris]

Thanks @stuartarchibald .

[charris]

I wonder if we shouldn't make this always complex? The reason is isn't always so is that eig casts the complex result to float when the imaginary part is zero.

[stuartarchibald]

@charris no problem, thanks for the merge.

From a numpy point of view, I think this does lead to moderate surprise as it seems, perhaps, a bit unusual. I don't think it'd massively hurt performance in the isolated call (obviously there may be knock-on effects) to consistently return a complex type, the actual computation can be done using a LAPACK routine that is suited to the input type and then the answer can manipulated into a complex type for return (i.e. don't do the "cast" you mention above).

I think the two places that this may feel strange to users are 1) if a user comes from Octave/Matlab 2) when a user is doing work that is guaranteed to be entirely in real space and a complex type suddenly appears (although obviously they could np.real() or similar the result). In general, I think there are more cases where eig* like functions wander into complex space, and there are the eig*h function as specialisations already for common cases where there are guarantees present over the class of problem.

From a somewhat biased Numba point of view numba/numba#1839, if the return types are solely a function of the argument types that really helps Numba. At present, anything using eig*() with a real space input has to raise if the answer goes into complex space, this is because Numba can't infer the return type as it depends on both the argument type and their actual values.