diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md deleted file mode 100644 index 36f59b4c7..000000000 --- a/spec/API_specification/manipulation_functions.md +++ /dev/null @@ -1,195 +0,0 @@ -# Manipulation Functions - -> Array API specification for manipulating 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](https://www.python.org/dev/peps/pep-0570/) 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](https://www.python.org/dev/peps/pep-3102/) arguments. -- Unless stated otherwise, functions must adhere to the type promotion rules defined in {ref}`type-promotion`. - -## Objects in API - - - -(function-concat)= -### concat(arrays, /, *, axis=0) - -Joins a sequence of arrays along an existing axis. - -#### Parameters - -- **arrays**: _Union\[Tuple\[ <array>, ... ], List\[ <array> ] ]_ - - - input arrays to join. The arrays must have the same shape, except in the dimension specified by `axis`. - -- **axis**: _Optional\[ int ]_ - - - axis along which the arrays will be joined. If `axis` is `None`, arrays must be flattened before concatenation. If `axis` is negative, the function must determine the axis along which to join by counting from the last dimension. Default: `0`. - -#### Returns - -- **out**: _<array>_ - - - an output array containing the concatenated values. If the input arrays have different data types, normal [type promotion rules](type_promotion.md) must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. - - ```{note} - - This specification leaves type promotion between data type families (i.e., `intxx` and `floatxx`) unspecified. - ``` - -(function-expand_dims)= -### expand_dims(x, /, axis) - -Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by `axis`. - -#### Parameters - -- **x**: _<array>_ - - - input array. - -- **axis**: _int_ - - - axis position. Must follow Python's indexing rules: zero-based and negative indices must be counted backward from the last dimension. If `x` has rank `N`, a valid `axis` must reside on the interval `[-N-1, N+1]`. An `IndexError` exception must be raised if provided an invalid `axis` position. - -#### Returns - -- **out**: _<array>_ - - - an expanded output array having the same data type as `x`. - -(function-flip)= -### flip(x, /, *, axis=None) - -Reverses the order of elements in an array along the given axis. The shape of the array must be preserved. - -#### Parameters - -- **x**: _<array>_ - - - input array. - -- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ - - - axis (or axes) along which to flip. If `axis` is `None`, the function must flip all input array axes. If `axis` is negative, the function must count from the last dimension. If provided more than one axis, the function must flip only the specified axes. Default: `None`. - -#### Returns - -- **out**: _<array>_ - - - an output array having the same data type and shape as `x` and whose elements, relative to `x`, are reordered. - -(function-permute-dims)= -### permute_dims(x, /, axes) - -Permutes the axes (dimensions) of an array `x`. - -#### Parameters - -- **x**: _<array>_ - - - input array. - -- **axes**: _Tuple\[ int, ... ]_ - - - tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. - -#### Returns - -- **out**: _<array>_ - - - an array containing the axes permutation. The returned array must have the same data type as `x`. - -(function-reshape)= -### reshape(x, /, shape) - -Reshapes an array without changing its data. - -#### Parameters - -- **x**: _<array>_ - - - input array to reshape. - -- **shape**: _Tuple\[ int, ... ]_ - - - a new shape compatible with the original shape. One shape dimension is allowed to be `-1`. When a shape dimension is `-1`, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions. - -#### Returns - -- **out**: _<array>_ - - - an output array having the same data type, elements, and underlying element order as `x`. - -(function-roll)= -### roll(x, /, shift, *, axis=None) - -Rolls array elements along a specified axis. Array elements that roll beyond the last position are re-introduced at the first position. Array elements that roll beyond the first position are re-introduced at the last position. - -#### Parameters - -- **x**: _<array>_ - - - input array. - -- **shift**: _Union\[ int, Tuple\[ int, ... ] ]_ - - - number of places by which the elements are shifted. If `shift` is a tuple, then `axis` must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element in `shift`. If `shift` is an `int` and `axis` a tuple, then the same `shift` must be used for all specified axes. If a shift is positive, then array elements must be shifted positively (toward larger indices) along the dimension of `axis`. If a shift is negative, then array elements must be shifted negatively (toward smaller indices) along the dimension of `axis`. - -- **axis**: _Optional\[ Union\[ int, Tuple\[ int, ... ] ] ]_ - - - axis (or axes) along which elements to shift. If `axis` is `None`, the array must be flattened, shifted, and then restored to its original shape. Default: `None`. - -#### Returns - -- **out**: _<array>_ - - - an output array having the same data type as `x` and whose elements, relative to `x`, are shifted. - -(function-squeeze)= -### squeeze(x, /, axis) - -Removes singleton dimensions (axes) from `x`. - -#### Parameters - -- **x**: _<array>_ - - - input array. - -- **axis**: _Union\[ int, Tuple\[ int, ... ] ]_ - - - axis (or axes) to squeeze. If a specified axis has a size greater than one, a `ValueError` must be raised. - -#### Returns - -- **out**: _<array>_ - - - an output array having the same data type and elements as `x`. - -(function-stack)= -### stack(arrays, /, *, axis=0) - -Joins a sequence of arrays along a new axis. - -#### Parameters - -- **arrays**: _Union\[Tuple\[ <array>, ... ], List\[ <array> ] ]_ - - - input arrays to join. Each array must have the same shape. - -- **axis**: _int_ - - - axis along which the arrays will be joined. Providing an `axis` specifies the index of the new axis in the dimensions of the result. For example, if `axis` is `0`, the new axis will be the first dimension and the output array will have shape `(N, A, B, C)`; if `axis` is `1`, the new axis will be the second dimension and the output array will have shape `(A, N, B, C)`; and, if `axis` is `-1`, the new axis will be the last dimension and the output array will have shape `(A, B, C, N)`. A valid `axis` must be on the interval `[-N, N)`, where `N` is the rank (number of dimensions) of `x`. If provided an `axis` outside of the required interval, the function must raise an exception. Default: `0`. - -#### Returns - -- **out**: _<array>_ - - - an output array having rank `N+1`, where `N` is the rank (number of dimensions) of `x`. If the input arrays have different data types, normal [type promotion rules](type_promotion.md) must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. - - ```{note} - - This specification leaves type promotion between data type families (i.e., `intxx` and `floatxx`) unspecified. - ``` diff --git a/spec/API_specification/manipulation_functions.rst b/spec/API_specification/manipulation_functions.rst new file mode 100644 index 000000000..f2fcbccc5 --- /dev/null +++ b/spec/API_specification/manipulation_functions.rst @@ -0,0 +1,31 @@ +Manipulation Functions +====================== + + Array API specification for manipulating 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. +- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`. + +Objects in API +-------------- + +.. currentmodule:: signatures.manipulation_functions + +.. + NOTE: please keep the functions in alphabetical order + +.. autosummary:: + :toctree: generated + :template: method.rst + + concat + expand_dims + flip + permute_dims + reshape + roll + squeeze + stack diff --git a/spec/API_specification/signatures/manipulation_functions.py b/spec/API_specification/signatures/manipulation_functions.py new file mode 100644 index 000000000..35e79e9d3 --- /dev/null +++ b/spec/API_specification/signatures/manipulation_functions.py @@ -0,0 +1,147 @@ +from ._types import List, Optional, Tuple, Union, array + +def concat(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: Optional[int] = 0) -> array: + """ + Joins a sequence of arrays along an existing axis. + + Parameters + ---------- + arrays: Union[Tuple[array, ...], List[array]] + input arrays to join. The arrays must have the same shape, except in the dimension specified by ``axis``. + axis: Optional[int] + axis along which the arrays will be joined. If ``axis`` is ``None``, arrays must be flattened before concatenation. If ``axis`` is negative, the function must determine the axis along which to join by counting from the last dimension. Default: ``0``. + + Returns + ------- + out: array + an output array containing the concatenated values. If the input arrays have different data types, normal :ref:`type-promotion` must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. + + .. note:: + This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified. + """ + +def expand_dims(x: array, /, *, axis: int = 0) -> array: + """ + Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by ``axis``. + + Parameters + ---------- + x: array + input array. + axis: int + axis position. Must follow Python's indexing rules: zero-based and negative indices must be counted backward from the last dimension. If ``x`` has rank ``N``, a valid ``axis`` must reside on the interval ``[-N-1, N+1]``. An ``IndexError`` exception must be raised if provided an invalid ``axis`` position. + + Returns + ------- + out: array + an expanded output array having the same data type as ``x``. + """ + +def flip(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> array: + """ + Reverses the order of elements in an array along the given axis. The shape of the array must be preserved. + + Parameters + ---------- + x: array + input array. + axis: Optional[Union[int, Tuple[int, ...]]] + axis (or axes) along which to flip. If ``axis`` is ``None``, the function must flip all input array axes. If ``axis`` is negative, the function must count from the last dimension. If provided more than one axis, the function must flip only the specified axes. Default: ``None``. + + Returns + ------- + out: array + an output array having the same data type and shape as ``x`` and whose elements, relative to ``x``, are reordered. + """ + +def permute_dims(x: array, /, axes: Tuple[int, ...]) -> array: + """ + Permutes the axes (dimensions) of an array ``x``. + + Parameters + ---------- + x: array + input array. + axes: Tuple[int, ...] + tuple containing a permutation of ``(0, 1, ..., N-1)`` where ``N`` is the number of axes (dimensions) of ``x``. + + Returns + ------- + out: array + an array containing the axes permutation. The returned array must have the same data type as ``x``. + """ + +def reshape(x: array, /, shape: Tuple[int, ...]) -> array: + """ + Reshapes an array without changing its data. + + Parameters + ---------- + x: array + input array to reshape. + shape: Tuple[int, ...] + a new shape compatible with the original shape. One shape dimension is allowed to be ``-1``. When a shape dimension is ``-1``, the corresponding output array shape dimension must be inferred from the length of the array and the remaining dimensions. + + Returns + ------- + out: array + an output array having the same data type, elements, and underlying element order as ``x``. + """ + +def roll(x: array, /, shift: Union[int, Tuple[int, ...]], *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> array: + """ + Rolls array elements along a specified axis. Array elements that roll beyond the last position are re-introduced at the first position. Array elements that roll beyond the first position are re-introduced at the last position. + + Parameters + ---------- + x: array + input array. + shift: Union[int, Tuple[int, ...]] + number of places by which the elements are shifted. If ``shift`` is a tuple, then ``axis`` must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element in ``shift``. If ``shift`` is an ``int`` and ``axis`` a tuple, then the same ``shift`` must be used for all specified axes. If a shift is positive, then array elements must be shifted positively (toward larger indices) along the dimension of ``axis``. If a shift is negative, then array elements must be shifted negatively (toward smaller indices) along the dimension of ``axis``. + axis: Optional[Union[int, Tuple[int, ...]]] + axis (or axes) along which elements to shift. If ``axis`` is ``None``, the array must be flattened, shifted, and then restored to its original shape. Default: ``None``. + + Returns + ------- + out: array + an output array having the same data type as ``x`` and whose elements, relative to ``x``, are shifted. + """ + +def squeeze(x: array, /, axis: Union[int, Tuple[int, ...]]) -> array: + """ + Removes singleton dimensions (axes) from ``x``. + + Parameters + ---------- + x: array + input array. + axis: Union[int, Tuple[int, ...]] + axis (or axes) to squeeze. If a specified axis has a size greater than one, a ``ValueError`` must be raised. + + Returns + ------- + out: array + an output array having the same data type and elements as ``x``. + """ + +def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) -> array: + """ + Joins a sequence of arrays along a new axis. + + Parameters + ---------- + arrays: Union[Tuple[array, ...], List[array]] + input arrays to join. Each array must have the same shape. + axis: int + axis along which the arrays will be joined. Providing an ``axis`` specifies the index of the new axis in the dimensions of the result. For example, if ``axis`` is ``0``, the new axis will be the first dimension and the output array will have shape ``(N, A, B, C)``; if ``axis`` is ``1``, the new axis will be the second dimension and the output array will have shape ``(A, N, B, C)``; and, if ``axis`` is ``-1``, the new axis will be the last dimension and the output array will have shape ``(A, B, C, N)``. A valid ``axis`` must be on the interval ``[-N, N)``, where ``N`` is the rank (number of dimensions) of ``x``. If provided an ``axis`` outside of the required interval, the function must raise an exception. Default: ``0``. + + Returns + -------- + out: array + an output array having rank ``N+1``, where ``N`` is the rank (number of dimensions) of ``x``. If the input arrays have different data types, normal :ref:`type-promotion` must apply. If the input arrays have the same data type, the output array must have the same data type as the input arrays. + + .. note:: + This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified. + """ + +__all__ = ['concat', 'expand_dims', 'flip', 'permute_dims', 'reshape', 'roll', 'squeeze', 'stack'] \ No newline at end of file