Add design document on complex number ordering

[kgryte]

This PR

• adds a design document on complex number ordering. As complex numbers have no natural order, the specification does not require that conforming implementations adopt any particular ordering convention. While ordering APIs are restricted to real-valued data types, conforming implementations are permitted to implement an ordering for reasons of backward compatibility; however, ordering is not guaranteed to be portable across implementations.
• adds notes to ordering APIs (less, less_equal, greater, greater_equal, argmin, argmax, argsort, sort, min, max) documenting that inequality comparison of complex numbers is unspecified and thus implementation-dependent.
• specifies that argsort and sort should only accept real-valued data types. The current specification does not restrict the input data types for argsort and sort, but does restrict argmin and argmax to real-valued data types. This PR updates argsort and sort to align with argmin and argmax, as boolean values have no natural ordering. The divergence was likely an oversight.

Prior Art

In general, because complex numbers have no natural ordering, ordering APIs supporting complex numbers inevitably lead to unintuitive results, as documented on the NumPy issue tracker. The general gist there is that ordering complex numbers should be deprecated, with only specialized support (with support for customized sort order) for complex number ordering when wanting to sort a complex number array.

• NumPy has an open PR for deprecating complex number ordering: MAINT: Deprecate Complex Ordering comparisons numpy/numpy#17030
  • Related issue: NumPy should warn (eventually raise an error?) on comparisons between complex numbers numpy/numpy#15981
• Confusion arising from NumPy diverging from Python behavior: complex-valued comparison incorrectly succeeds numpy/numpy#17361
• Confusion concerning complex ordering in np.argmax: numpy.argmax() doesn't behave intuitively with complex vectors numpy/numpy#10469
• Confusion concerning complex ordering in np.median: np.median on a complex array return incorrect value for the imaginary part numpy/numpy#12943
• Confusion concerning complex ordering in np.quantile: BUG: Quantile function on complex numbers doesn't error numpy/numpy#22652

[rgommers]

This LGTM, thanks @kgryte.

[rgommers]

The main points here, as listed in the PR description, were reviewed also in a call last Thursday, and there was general approval that this is the right approach. So in it goes.

[rgommers]

One thing to consider is to merge the content in this PR and the page on branch cuts in a single "complex number support" page. I'll add that to the list of content refactor tasks in gh-533.