RFC: add `abs2` to compute the square of the absolute value

This RFC proposes to add a new API, abs2, to the standard for computing the square of the absolute value.

For complex numbers, the absolute value is the Euclidean norm of the real and imaginary components.

This API has particular value for complex numbers, as the alternative abs(x)**2 requires taking the square root and the alternative x*conj(x) potentially requires additional memory allocation before computation.

Background

This was originally discussed in the Array API issue tracker in gh-153 (comment) and included in RFC gh-373 for adding complex number support to the specification.

Prior to that, a proposal was made on the NumPy issue tracker (https://github.com/numpy/numpy/issues/13179) to add abs2 in response to an issue originally filed on NumPy in 2013.

The abs2 proposal was given additional life in late 2021 with an effort to add to SciPy under an abs_sq alias.

Part of the motivation for adding to SciPy is due to NumPy’s desire to avoid expanding its API. This desire stems from not having a clear process or criteria for determining what should and what should not be included in NumPy.

However, the array API standard provides NumPy with such a process, as decision making for new APIs is effectively punted to this standards body.

Accordingly, were the array API specification to add abs2, NumPy would follow suit.

This brings me to this proposal which seeks to add abs2 to the array API standard and effectively settle the question as to where abs2 should live.

And as abs2 has general applicably outside of NumPy and in other array libraries, abs2 seems like a reasonable and straightforward API to add to the standard.

Proposal

The API for abs2 would follow similar element-wise APIs…

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

Notes

• This proposal does not follow https://github.com/scipy/scipy/pull/15390 in naming the API abs_sq, as (1) IMO the increase in characters does not provide any additional clarity in terms of behavior or functionality and (2) abs2 follows precedent elsewhere (Julia and GSL).
• For real-valued numbers, the square of the absolute value is the same as the square x*x.

Prior Art

• C++ has a norm API since C++11. This is not an ideal name, as, while the value calculated by this function is the “field norm”, this is likely not to match user expectations concerning a “norm”, which is better represented by abs.
• GSL has abs2.
• Julia has abs2.

[leofang]

Anything involving calling sqrt is doomed, so let’s rule it out of the discussion.

AFAIR, “less memory throughput” has never been the primary goal of the API design, otherwise we’d have accepted the out= and in-place proposals, so this – plus you both were torn with finding the justification

There are nearly an infinite number of composed operations that potentially require additional memory allocation

and

although I might prefer to not have it in the main namespace

– made me think unless it’s really “a lot faster” (it’s a literal quote) it’s not worth keeping me torn too by considering it.

[rgommers]

However, we would like to look into the possibility of providing generic APIs for user defined functions (i.e., standardized ways for array API consumers to, e.g., element-wise, apply arbitrary functions to arrays).

Let’s open a new issue for tracking this. I’m not sure how actionable it is, but it’s worth investigating. And also that issue may serve as a reference/collection point for other requests for composite APIs.

Thanks for the input all!