Add `copysign` function to the standard

[steff456]

This RFC requests to include a new API in the array API specification for the purpose of returning a value with the magnitude of x but the sign of y.

Overview

Based on array comparison data, the API is available in the majority of libraries in the PyData ecosystem.

The Array API specification does not currently include a convenient method of copying the sign from one value to another value via the IEEE 754 function copysign. This function is commonly used in the implementations of transcendental functions involving argument reductions.

While this can be implemented in terms of where, doing so is overly cumbersome.

Prior art

• C99: https://en.cppreference.com/w/c/numeric/math/copysign
• NumPy: https://numpy.org/doc/stable/reference/generated/numpy.copysign.html
• PyTorch: https://pytorch.org/docs/stable/generated/torch.copysign.html
• MXNet: https://mxnet.apache.org/versions/master/api/python/docs/api/np/generated/mxnet.np.copysign.html#mxnet.np.copysign

Proposal:

def copysign(x1: array, x2:array, /) -> array

cc @kgryte

[rgommers]

This seems like a reasonable addition. Do TensorFlow and MXNet have alternatives or open feature requests?

[kgryte]

MXNet does have a copysign function. TF is the odd one out and does not appear to have a copysign API even in its experimental NumPy namespace.

[asmeurer]

I don't know if this can actually be replicated with where because of -0.0.