Differences to the Python Array API Standard#

Overview#

There are a number of deliberate differences to the Python Array API standard in this implementation. Many of these differences originate from the fact that PyDims uses a dims property. Harmful and error-prone features are removed, and the API is adapted to named dimensions.

General differences#

  • axis keyword arguments are replaced by a dim keyword argument.

  • keepdims keyword arguments are omitted, since keeping singleton dimensions for future broadcasting is not required, thanks to named dimensions.

Array object#

  • The mT and T properties are not available. It is unclear if this is useful with named dimensions, in particular since we currently do not intend to use named dimensions for linear algebra. Named dimensions remove the other need for transposing axes, since axes are named and can be reordered automatically in operations.

Broadcasting#

The broadcasting rules of the Array API do not apply. In particular, we never broadcast a “singleton” dimension (dimension with size 1) to a larger dimension. Broadcasting is only performed via named dimensions. A dimension of size 1 is not considered compatible with a dimension of size > 1.

newaxis is not available.

Indexing#

Allowed keys#

We consider indexing without explicitly specifying the dimension harmful. Therefore, we do not support indexing with a tuple of integers or slices. Instead, a dict with dimension names as keys is required.

Exception: If the array has only one dimension, the dimension name can be omitted, i.e., a single integer or slice is allowed.

Return values#

Array libraries may return a scalar if the result is a scalar. Due to the addition of a unit property, we instead return a 0-D array (with a single element).

Manipulation functions#

  • reshape is not available since with named dimensions the reshape API is rarely required and likely error prone. Instead, we provide fold and flatten.

  • expand_dims is not available since adding singleton dimensions is rarely useful without the array API broadcasting behavior.