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, /) -> array

Questions

• While 1/x may 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 including negative and positive), 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.