RFC: add `nan_to_num` to the array API spec

[ogrisel]

numpy.nan_to_num has not been included in the array API spec so far.

However, it seems widely adopted by array libraries:

• torch.nan_to_num
• cupy.nan_to_num
• dask.array.nan_to_num
• jax.numpy.nan_to_num
• mlx.core.nan_to_num

At the time of writing, ndonnx does not implement this function.

I haven't checked in details, but from a cursory glance at the docs, libraries that implement this utility do seem quite consistent already.

[rgommers]

I think nan_to_num wasn't considered previously because it seems a bit niche and simply wasn't on anyone's radar. The function is also pretty ugly:

def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):

The copy is unnecessary, and the posinf/neginf seems rarely used. I'd also make the fill value mandatory to specify. If we'd implement this with array API standard primitives, I think it'd be something like:

def nan_to_num(x : array, /, *, fill_value: float | complex) -> array:
    if xp.isdtype(x.dtype, ('real floating', 'complex floating')):
        return xp.where(xp.isnan(x), x, fill_value)
    else:
        return x

Maybe it makes more sense to put that into array-api-extra?

[rgommers]

We discussed this in today's community meeting. The consensus there was that we should go ahead with adding this to array-api-extra, since it's a composite function that's easy to express, and a bit too niche to directly put in the standard.