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