Add tests and documentation with improvement of downcast type compatibility (part of #845)

[jthielen]

As a part of #845, this PR adds tests for downcast type compatibility with Sparse's COO and NumPy's MaskedArray, along with more careful handling of downcast types throughout the library. Also included is new documentation on array type compatibility, including the type casting hierarchy digraph by @shoyer and @crusaderky.

While this PR doesn't fully bring Pint's downcast type compatibility to a completed state, I think this gets it "good enough" for the upcoming release, and the remaining issues are fairly well defined:

• MaskedArray non-commutativity (Inconsistency when multiplying NumPy masked arrays #633 / BUG: MaskedArray does not seem to respect ufunc dispatch hierarchy numpy/numpy#15200)
• Dask compatibility (Integration with Dask (add tests; implement the Dask collection interface on Quantity) #883)
• Addition of CuPy tests (Add tests with CuPy #964)

Because of that, I think this can close #845, but if @hgrecco you want that kept open until the above items are resolved, let me know.

• Closes Operating elementwise with numpy masked arrays #37; Closes Insuring interoperability of pint with other (non-unit) array-like types #845
• Executed black -t py36 . && isort -rc . && flake8 with no errors
• The change is fully covered by automated unit tests
• Documented in docs/ as appropriate
• Added an entry to the CHANGES file

[hgrecco]

I agree with closing 845 and, if needed opening more specific issues referencing the upstream repos

[hgrecco]

bors r+

[bors]

Build succeeded

• continuous-integration/travis-ci/push

[jthielen]

After testing this downstream with MetPy, the issue in #37 (comment) reappeared, making it so that multiplying by a Unit on the right gives an object MaskedArray of Quantities instead of a Quantity with MaskedArray magnitude. This unfortunately ends up being a pretty bad breaking change that makes the situation worse than before.

However, when I reverted the change to Unit replacing __array_wrap__/__array_prepare__ with __array_ufunc__, the Sparse test now fails, since Sparse.COO times Unit requires the multiply ufunc to be implemented on Unit (since Sparse rightly defers)!

So, unless I'm missing a fix that works for both Sparse and MaskedArray, there is a dilemma:

• Keep the change from this PR implementing __array_ufunc__ on Unit, which is more future-proof and compatible with hierarchy-obeying types like Sparse.COO, but exacerbates BUG: MaskedArray does not seem to respect ufunc dispatch hierarchy numpy/numpy#15200 and causes more issues with the commonly-used-but-problematic MaskedArray.
• Revert the change until BUG: MaskedArray does not seem to respect ufunc dispatch hierarchy numpy/numpy#15200 is resolved, which keeps the MaskedArray multiplication issue the same as it was, but prevents proper behavior with types that require __array_ufunc__ on Unit like Sparse.COO

Or, put another way, given that we can't have both, for which type of array would we rather have array * ureg.m work:

• Sparse.COO (and other ufunc-reliant types)?
• MaskedArray (as it was before)?

In either case, a follow-up PR to document the issue is likely needed (since the ideal behavior cannot be realized until numpy/numpy#15200 is resolved).

@hgrecco What are your thoughts on this?

[hgrecco]

This PR is good step into the right direction. __array_ufunc__ (or similar) is a much better protocol than the previous one and something that pint was waiting for several years. My suggestion would be to keep this PR, document the problem and alert users what is the problem. Hopefully, this will be fixed in numpy soon.