RFC: add `angle` for computing the argument of a complex number

[steff456]

This RFC requests to include a new API in the array API specification for the purpose of computing the argument of a complex number.

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 an API for computing the argument of a complex number.

Prior art

• NumPy: https://numpy.org/doc/stable/reference/generated/numpy.angle.html
• PyTorch: https://pytorch.org/docs/stable/generated/torch.angle.html
• TensorFlow: https://www.tensorflow.org/api_docs/python/tf/math/angle
• C99: https://en.cppreference.com/w/c/numeric/complex/carg

Proposal:

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

Questions

• okay with angle as name? arg? phase?
• only operate on complex arrays, similar to conj et al?

cc @kgryte

[ev-br]

angle is a thin wrapper on top of atan2. Here's the numpy implementation: https://github.com/numpy/numpy/blob/v2.1.0/numpy/lib/_function_base_impl.py#L1670-L1724

So it's literally atan2(xp.real(z), xp.imag(z)) for complex-valued z plus some additional gymnastics due to xp.imag(real.input) refusing to return zeros. So the decision on adding angle to the spec depends on the resoution of https://github.com/data-apis/array-api/issues/824, I'd say. (and I'm on record for making xp.imag(real input returning zeros, FWIW)

[lucascolley]

we can put this in array-api-extra if it doesn't make it into the standard for v2024