Add complex floating-point data types

[kgryte]

This PR

• add complex64 and complex128 data types to the specification, as outlined in RFC: Adding complex number support to the specification #373.
• defines complex64 as a single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers.
• defines complex128 as a double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers.
• requires that the default complex floating-point data type match the default floating-point data type (i.e., if float32, the default complex floating-point data type must be complex64).
• adds complex64 and complex128 to the list of "numeric" data types.
• adds a new data type category: "complex floating-point data types" for use throughout the specification.
• adds a new data type category: "real-valued floating-point data types". This category is equivalent to the previous "floating-point data types". The "floating-point data types" category is updated to include both real-valued and complex floating-point data types.
• adds a new data type category: "real-valued data types". This category is equivalent to the previous "numeric" data type category.
• updates all current use of "numeric data type" to "real-valued data type" with the aim to add support for complex number data types to APIs on a case-by-case basis via subsequent PRs.
• updates all current use of "floating-point data type" to "real-valued floating-point data type" with the aim to add support for complex number data types to APIs on a case-by-case basis via subsequent PRs.
• updates to type promotion tables to follow in a subsequent PR.

[oleksandr-pavlyk]

Why aren't complex types considered numeric data types? Is this is because they lack inherent total order, than the "numeric data types" is a misnomer and should be renamed to "data types with canonical ordering" or some such

[kgryte]

@oleksandr-pavlyk Updated the PR. Had originally shied away from changing the dtypes belonging to "numeric" as this implied a change to the semantic meaning for purposes of the spec. However, after discussion, this was not seen as a problem. Added a "real-valued data types" category and have updated the spec accordingly.

[leofang]

Added a "real-valued data types" category and have updated the spec accordingly.

This is still confusing... A lot of dunder methods like __abs__, __mul__, ..., are well defined even for complex-valued arrays. I think we should only exclude a few like those involving ordering (__ge__, __le__, ...), modulo (__mod__), etc.

[kgryte]

@leofang For many of the APIs, "real-valued data types" is a placeholder and each API will be updated on an individual basis in subsequent PRs. The purpose of this PR is to solely update the list of data types. Because of the change to the data type categories (e.g., numeric), I updated the APIs to use the "real-valued data type" category to preserve the status quo.

[leofang]

Ah ok, I missed the updated PR description:

• updates all current use of "numeric data type" to "real-valued data type" with the aim to add support for complex number data types to APIs on a case-by-case basis via subsequent PRs.

Thanks, Athan!

[leofang]

LGTM!

[kgryte]

Thanks, @leofang!

I'll leave it open for another day or so before merging. And then we'll get the ball moving on the rest of the complex number support updates. 😅

[leofang]

Question: Is the complex-number support counted as extension or required? If it's extension, then does it mean all APIs supporting complex numbers become extension as well?

[kgryte]

@leofang Complex number support would be required. Because of how deeply intertwined dtype support is with all APIs in the spec, allowing complex number to be an extension does not seem to make sense (e.g., how would I ascertain whether a given array API supports complex numbers in a portable fashion?).

[kgryte]

As this PR has been approved and up for review for 4 weeks, will merge. Any further revisions may be addressed in follow-up PRs...