RFC: add `reciprocal` for computing the element-wise reciprocal
kgryte opened this issue · 2 comments
This RFC proposes the addition of a new API in the array API specification for computing the element-wise reciprocal.
Overview
Based on array comparison data, the API is available across all major array libraries in the PyData ecosystem.
reciprocal was originally identified in #187 as a potential standardization candidate and has been mentioned by downstream libraries (see Intheon case study).
Prior art
- NumPy: https://numpy.org/doc/stable/reference/generated/numpy.reciprocal.html
- Intended for floating-point data types.
- CuPy: https://docs.cupy.dev/en/stable/reference/generated/cupy.reciprocal.html
- Dask: https://docs.dask.org/en/stable/generated/dask.array.reciprocal.html
- PyTorch: https://pytorch.org/docs/stable/generated/torch.reciprocal.html
- Supports integral dtypes with internal promotion.
- TensorFlow: https://www.tensorflow.org/api_docs/python/tf/math/reciprocal
- JAX: https://jax.readthedocs.io/en/latest/_autosummary/jax.numpy.reciprocal.html
Proposal
def reciprocal(x: array, /) -> arrayQuestions
- While
1/xmay be appear to be a trivial operation not warranting a dedicated API, there can be benefits should the API be mapped to dedicated hardware instructions. One can argue that this is best dealt with at the compiler level and end users should not be concerned with potential micro-optimizations. However, for larger datasets, there can be real-world benefits to explicit avoidance of division operations and array libraries may choose to avoid relying on compiler magic to implement polynomial approximations to the reciprocal. Given that this is implemented by all considered array libraries and straightforward to implement (similar to the standard already includingnegativeandpositive), are there any reasons to not include this API? - Given that the output data type will be a floating-point data type, are we okay limiting (i.e., via the use of "should") input dtypes to floating-point? Libraries would be free, of course, to explicitly support other dtypes (e.g., as in PyTorch and TensorFlow), but that would not be guaranteed to be portable.
@oleksandr-pavlyk's comment that this is useful also to avoid dealing with moving a Python scalar to GPU/accelerator if it's written as 1/x and that's why it was added to dpctl seems like an additional reason to do this.
So +1 for adding this, with "should" for floating-point types only (as suggested). That way it's a straightforward signal that this is portable, without placing a new implementation burden on any known library.