Add support for computing the hypotenuse via hypot

[kgryte]

This RFC requests to include a new API in the array API specification for the purpose of computing the hypotenuse.

Based on array comparison data, the API is available across all major array libraries in the PyData ecosystem (note: TensorFlow implements hypot in its experimental numpy namespace).

While hypot can be implemented in userland using existing array API functions (e.g., sqrt(x1*x1 + x2*x2)), this function is typically implemented in a specialized manner to help prevent over/underflow.

Furthermore, need for this API arose when adding complex number support to the array API specification, particularly with regard to adding complex number support to abs, where the absolute value (magnitude) of a complex number is computed as hypot(real(z), imag(z)).

As this API already exists in the ecosystem and satisfies needs (e.g., numerical stability and complex number support), this API seems a good candidate for inclusion in the standard.

[rgommers]

This seems like a reasonable addition, given it's already commonly implemented (the linked data shows it is named differently in MXNet though). Are the signatures consistent among libraries?

Furthermore, need for this API arose when adding complex number support to the array API specification

That does not seem directly relevant here. For abs to use a hypot calculation internally, hypot does not have to be exposed as public API.

[kgryte]

That does not seem directly relevant here.

It does in order for the specification to be able to define special case behavior.

[kgryte]

Concerning special case behavior, according to IEEE 754, hypot handles NaN differently than would be the case for the naive implementation. Namely, if only one of x or y in hypot(x,y) is NaN and the other is infinity, the result is infinity. This also applies to abs when computing the absolute value of a complex number (see C99).

Wrt complex number support, while we could explicitly spell out complex number special case behavior for abs, the end result is that all libraries would effectively have to implement IEEE 754 hypot.

[kgryte]

In terms of API, all supporting libraries implement as a standard element-wise binary function: hypot(x1, x2), where x1 and x2 follow conventional broadcast rules.

[rgommers]

It does in order for the specification to be able to define special case behavior.

As discussed last Thursday, the special cases for abs can be put in the abs description. This is implemented in gh-546.

We're already nearing the end of 2022, and are close to finalizing the 2022 standard. hypot is not urgent enough to squeeze it in now, so let's defer deciding on that till later. There's a larger queue of suggested new APIs that needs considering in Q1.