Proposal to standardize element-wise elementary mathematical functions

Based on the analysis of array library APIs, we know that evaluating element-wise elementary mathematical functions is both universally implemented and commonly used. Accordingly, this issue proposes to standardize the following elementary mathematical functions:

Special Functions

• abs (absolute)
• exp
• log
• sqrt

Rounding

• ceil
• floor
• trunc
• round

Trigonometry

• sin
• cos
• tan
• asin (arcsin)
• acos (arccos)
• atan (arctan)
• sinh
• cosh
• tanh
• asinh (arcsinh)
• acosh (arccosh)
• atanh (arctanh)

Criterion

1. Commonly implemented across array libraries.
2. Commonly used by array library consumers.
3. Operates on a single array (e.g., this criterion excludes atan2).

Questions

1. Naming conventions? The above is biased toward C naming conventions (e.g., atan vs arctan).
2. Are there any APIs listed above which should not be standardized?
3. Are there elementary mathematical functions not listed above which should be standardized? Preferably, any additions should be supported by usage data.
4. Should the standard mandate a minimum precision to ensure portability? (e.g., JavaScript’s lack of minimum precision specification offers a cautionary tale)

[kgryte]

We can also keep the keyword-only requirements. In which case, the universal signature would be

<name>(x, /, *, out=None)

[shoyer]

adequate coverage of non mutating operators (like jax’s non-mutating slice assign, for example).

Read up on that at https://jax.readthedocs.io/en/latest/notebooks/Common_Gotchas_in_JAX.html#🔪-In-Place-Updates.

We should update that doc page, but I’ll just note that JAX has a more recent improved syntax for indexing assignment: x.at[idx].set(y) vs x[idx] = y

One advantage of the non-mutating version is that JAX can have reliable assigning arithmetic on array slices with x.at[idx].add(y) (x[idx] += y doesn’t work if x[idx] returns a copy).

A disadvantage is that doing this sort thing inside a loop is almost always a bad idea unless you have a JIT compiler, because every indexing assignment operation makes a full copy. So the naive translation of an efficient Python loop that fills out an array row by row would now make a copy in each step. Instead, you’d have to rewrite that loop to use something like concatenate instead (which in my experience is already about as efficient as using indexing assignment).