diff --git a/spec/API_specification/array_api/__init__.py b/spec/API_specification/array_api/__init__.py index 50fe5070b..49ab7e9e1 100644 --- a/spec/API_specification/array_api/__init__.py +++ b/spec/API_specification/array_api/__init__.py @@ -4,6 +4,7 @@ from .data_type_functions import * import array_api.data_types as dtype from .elementwise_functions import * +from .indexing_functions import * from .linear_algebra_functions import * from .manipulation_functions import * from .searching_functions import * diff --git a/spec/API_specification/array_api/indexing_functions.py b/spec/API_specification/array_api/indexing_functions.py new file mode 100644 index 000000000..65f2c3450 --- /dev/null +++ b/spec/API_specification/array_api/indexing_functions.py @@ -0,0 +1,27 @@ +from ._types import Union, array + +def take(x: array, indices: array, /, *, axis: int) -> array: + """ + Returns elements of an array along an axis. + + .. note:: + Conceptually, ``take(x, indices, axis=3)`` is equivalent to ``x[:,:,:,indices,...]``; however, explicit indexing via arrays of indices is not currently supported in this specification due to concerns regarding ``__setitem__`` and array mutation semantics. + + Parameters + ---------- + x: array + input array. + indices: array + array indices. The array must be one-dimensional and have an integer data type. + axis: int + axis over which to select values. If ``axis`` is negative, the function must determine the axis along which to select values by counting from the last dimension. + + If ``x`` is a one-dimensional array, providing an ``axis`` is optional; however, if ``x`` has more than one dimension, providing an ``axis`` is required. + + Returns + ------- + out: array + an array having the same data type as ``x``. The output array must have the same rank (i.e., number of dimensions) as ``x`` and must have the same shape as ``x``, except for the axis specified by ``axis`` whose size must equal the number of elements in ``indices``. + """ + +__all__ = ['take'] diff --git a/spec/API_specification/index.rst b/spec/API_specification/index.rst index 775344482..bbb96c8a9 100644 --- a/spec/API_specification/index.rst +++ b/spec/API_specification/index.rst @@ -16,6 +16,7 @@ API specification elementwise_functions function_and_method_signatures indexing + indexing_functions linear_algebra_functions manipulation_functions searching_functions diff --git a/spec/API_specification/indexing_functions.rst b/spec/API_specification/indexing_functions.rst new file mode 100644 index 000000000..264b787ae --- /dev/null +++ b/spec/API_specification/indexing_functions.rst @@ -0,0 +1,28 @@ +.. _indexing-functions: + +Indexing Functions +=================== + + Array API specification for functions for indexing arrays. + +A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions. + +- Positional parameters must be `positional-only `_ parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. +- Optional parameters must be `keyword-only `_ arguments. +- Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`. +- Unless stated otherwise, functions must support the data types defined in :ref:`data-types`. +- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. + +Objects in API +-------------- + +.. currentmodule:: array_api + +.. + NOTE: please keep the functions in alphabetical order + +.. autosummary:: + :toctree: generated + :template: method.rst + + take