ENH: Updates to numpy.array_api (#19937)

* Add __index__ to array_api and update __int__, __bool__, and __float__

The spec specifies that they should only work on arrays with corresponding
dtypes. __index__ is new in the spec since the initial PR, and works
identically to np.array.__index__.

* Add the to_device method to the array_api

This method is new since #18585. It does nothing in NumPy since NumPy does not
support non-CPU devices.

* Update transpose methods in the array_api

transpose() was renamed to matrix_transpose() and now operates on stacks of
matrices. A function to permute dimensions will be added once it is finalized
in the spec. The attribute mT was added and the T attribute was updated to
only operate on 2-dimensional arrays as per the spec.

* Restrict input dtypes in the array API statistical functions

* Add the dtype parameter to the array API sum() and prod()

* Add the function permute_dims() to the array_api namespace

permute_dims() is the replacement for transpose(), which was split into
permute_dims() and matrix_transpose().

* Add tril and triu to the array API namespace

* Fix the array_api Array.__repr__ to indent the array properly

* Make the Device type in the array_api just accept the string "cpu"

1 files changed, 34 insertions, 1 deletions

diff --git a/numpy/array_api/_statistical_functions.py b/numpy/array_api/_statistical_functions.py
index 63790b447..c5abf9468 100644
--- a/numpy/array_api/_statistical_functions.py
+++ b/numpy/array_api/_statistical_functions.py
@@ -1,8 +1,17 @@
 from __future__ import annotations
 
+from ._dtypes import (
+    _floating_dtypes,
+    _numeric_dtypes,
+)
 from ._array_object import Array
+from ._creation_functions import asarray
+from ._dtypes import float32, float64
 
-from typing import Optional, Tuple, Union
+from typing import TYPE_CHECKING, Optional, Tuple, Union
+
+if TYPE_CHECKING:
+    from ._typing import Dtype
 
 import numpy as np
 
@@ -14,6 +23,8 @@ def max(
     axis: Optional[Union[int, Tuple[int, ...]]] = None,
     keepdims: bool = False,
 ) -> Array:
+    if x.dtype not in _numeric_dtypes:
+        raise TypeError("Only numeric dtypes are allowed in max")
     return Array._new(np.max(x._array, axis=axis, keepdims=keepdims))
 
 
@@ -24,6 +35,8 @@ def mean(
     axis: Optional[Union[int, Tuple[int, ...]]] = None,
     keepdims: bool = False,
 ) -> Array:
+    if x.dtype not in _floating_dtypes:
+        raise TypeError("Only floating-point dtypes are allowed in mean")
     return Array._new(np.mean(x._array, axis=axis, keepdims=keepdims))
 
 
@@ -34,6 +47,8 @@ def min(
     axis: Optional[Union[int, Tuple[int, ...]]] = None,
     keepdims: bool = False,
 ) -> Array:
+    if x.dtype not in _numeric_dtypes:
+        raise TypeError("Only numeric dtypes are allowed in min")
     return Array._new(np.min(x._array, axis=axis, keepdims=keepdims))
 
 
@@ -42,8 +57,15 @@ def prod(
     /,
     *,
     axis: Optional[Union[int, Tuple[int, ...]]] = None,
+    dtype: Optional[Dtype] = None,
     keepdims: bool = False,
 ) -> Array:
+    if x.dtype not in _numeric_dtypes:
+        raise TypeError("Only numeric dtypes are allowed in prod")
+    # Note: sum() and prod() always upcast float32 to float64 for dtype=None
+    # We need to do so here before computing the product to avoid overflow
+    if dtype is None and x.dtype == float32:
+        x = asarray(x, dtype=float64)
     return Array._new(np.prod(x._array, axis=axis, keepdims=keepdims))
 
 
@@ -56,6 +78,8 @@ def std(
     keepdims: bool = False,
 ) -> Array:
     # Note: the keyword argument correction is different here
+    if x.dtype not in _floating_dtypes:
+        raise TypeError("Only floating-point dtypes are allowed in std")
     return Array._new(np.std(x._array, axis=axis, ddof=correction, keepdims=keepdims))
 
 
@@ -64,8 +88,15 @@ def sum(
     /,
     *,
     axis: Optional[Union[int, Tuple[int, ...]]] = None,
+    dtype: Optional[Dtype] = None,
     keepdims: bool = False,
 ) -> Array:
+    if x.dtype not in _numeric_dtypes:
+        raise TypeError("Only numeric dtypes are allowed in sum")
+    # Note: sum() and prod() always upcast float32 to float64 for dtype=None
+    # We need to do so here before summing to avoid overflow
+    if dtype is None and x.dtype == float32:
+        x = asarray(x, dtype=float64)
     return Array._new(np.sum(x._array, axis=axis, keepdims=keepdims))
 
 
@@ -78,4 +109,6 @@ def var(
     keepdims: bool = False,
 ) -> Array:
     # Note: the keyword argument correction is different here
+    if x.dtype not in _floating_dtypes:
+        raise TypeError("Only floating-point dtypes are allowed in var")
     return Array._new(np.var(x._array, axis=axis, ddof=correction, keepdims=keepdims))