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

Overview

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

The Array API Specification currently includes pow and sqrt, but does not include the IEEE 754 function cbrt.

• pow:

  array-api/src/array_api_stubs/_2022_12/elementwise_functions.py

  Line 1786 in 3d91878

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

• sqrt:

  array-api/src/array_api_stubs/_2022_12/elementwise_functions.py

  Line 2139 in 3d91878

  def sqrt(x: array, /) -> array:

While the cube root could be implemented in terms of pow, this is not desirable as the rational 1/3 is not typically equal to 1.0/3.0 due to limited floating-point precision. Cube root implementations are generally more accurate than the equivalent operation via pow.

Prior art

• NumPy: https://numpy.org/doc/stable/reference/generated/numpy.cbrt.html
• PyTorch: (not currently implemented)
• MXNet: https://mxnet.apache.org/versions/master/api/python/docs/api/np/generated/mxnet.np.cbrt.html
• TensorFlow: https://www.tensorflow.org/api_docs/python/tf/experimental/numpy/cbrt
• C99: https://en.cppreference.com/w/c/numeric/math/cbrt

Proposal:

def cbrt(x: array, /) -> array

cc @kgryte