10000 PR: Transform manipulation_functions.md to rst (#354) · data-apis/array-api@28634c2 · GitHub
[go: up one dir, main page]
Skip to content

Commit 28634c2

Browse files
steff456steff456
authored
PR: Transform manipulation_functions.md to rst (#354)
* Transform manipulation_functions.md to rst * Update note directives
1 parent 533e693 commit 28634c2

File tree

3 files changed

+178
-195
lines changed

3 files changed

+178
-195
lines changed

‎spec/API_specification/manipulation_functions.md

Lines changed: 0 additions & 195 deletions
This file was deleted.

‎spec/API_specification/manipulation_functions.rst

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Manipulation Functions
2+
======================
3+
4+
Array API specification for manipulating arrays.
5+
6+
A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
7+
8+
- 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.
9+
- Optional parameters must be `keyword-only <https://www.python.org/dev/peps/pep-3102/>`_ arguments.
10+
- Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`.
11+
12+
Objects in API
13+
--------------
14+
15+
.. currentmodule:: signatures.manipulation_functions
16+
17+
..
18+
NOTE: please keep the functions in alphabetical order
19+
20+
.. autosummary::
21+
:toctree: generated
22+
:template: method.rst
23+
24+
concat
25+
expand_dims
26+
flip
27+
permute_dims
28+
reshape
29+
roll
30+
squeeze
31+
stack

‎spec/API_specification/signatures/manipulation_functions.py

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
from ._types import List, Optional, Tuple, Union, array
2+
3+
def concat(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: Optional[int] = 0) -> array:
4+
"""
5+
Joins a sequence of arrays along an existing axis.
6+
7+
Parameters
8+
----------
9+
arrays: Union[Tuple[array, ...], List[array]]
10+
input arrays to join. The arrays must have the same shape, except in the dimension specified by ``axis``.
11+
axis: Optional[int]
12+
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``.
13+
14+
Returns
15+
-------
16+
out: array
17+
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.
18+
19+
.. note::
20+
This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified.
21+
"""
22+
23+
def expand_dims(x: array, /, *, axis: int = 0) -> array:
24+
"""
25+
Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by ``axis``.
26+
27+
Parameters
28+
----------
29+
x: array
30+
input array.
31+
axis: int
32+
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.
33+
34+
Returns
35+
-------
36+
out: array
37+
an expanded output array having the same data type as ``x``.
38+
"""
39+
40+
def flip(x: array, /, *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> array:
41+
"""
42+
Reverses the order of elements in an array along the given axis. The shape of the array must be preserved.
43+
44+
Parameters
45+
----------
46+
x: array
47+
input array.
48+
axis: Optional[Union[int, Tuple[int, ...]]]
49+
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``.
50+
51+
Returns
52+
-------
53+
out: array
54+
an output array having the same data type and shape as ``x`` and whose elements, relative to ``x``, are reordered.
55+
"""
56+
57+
def permute_dims(x: array, /, axes: Tuple[int, ...]) -> array:
58+
"""
59+
Permutes the axes (dimensions) of an array ``x``.
60+
61+
Parameters
62+
----------
63+
x: array
64+
input array.
65+
axes: Tuple[int, ...]
66+
tuple containing a permutation of ``(0, 1, ..., N-1)`` where ``N`` is the number of axes (dimensions) of ``x``.
67+
68+
Returns
69+
-------
70+
out: array
71+
an array containing the axes permutation. The returned array must have the same data type as ``x``.
72+
"""
73+
74+
def reshape(x: array, /, shape: Tuple[int, ...]) -> array:
75+
"""
76+
Reshapes an array without changing its data.
77+
78+
Parameters
79+
----------
80+
x: array
81+
input array to reshape.
82+
shape: Tuple[int, ...]
83+
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.
84+
85+
Returns
86+
-------
87+
out: array
88+
an output array having the same data type, elements, and underlying element order as ``x``.
89+
"""
90+
91+
def roll(x: array, /, shift: Union[int, Tuple[int, ...]], *, axis: Optional[Union[int, Tuple[int, ...]]] = None) -> array:
92+
"""
93+
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.
94+
95+
Parameters
96+
----------
97+
x: array
98+
input array.
99+
shift: Union[int, Tuple[int, ...]]
100+
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``.
101+
axis: Optional[Union[int, Tuple[int, ...]]]
102+
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``.
103+
104+
Returns
105+
-------
106+
out: array
107+
an output array having the same data type as ``x`` and whose elements, relative to ``x``, are shifted.
108+
"""
109+
110+
def squeeze(x: array, /, axis: Union[int, Tuple[int, ...]]) -> array:
111+
"""
112+
Removes singleton dimensions (axes) from ``x``.
113+
114+
Parameters
115+
----------
116+
x: array
117+
input array.
118+
axis: Union[int, Tuple[int, ...]]
119+
axis (or axes) to squeeze. If a specified axis has a size greater than one, a ``ValueError`` must be raised.
120+
121+
Returns
122+
-------
123+
out: array
124+
an output array having the same data type and elements as ``x``.
125+
"""
126+
127+
def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) -> array:
128+
"""
129+
Joins a sequence of arrays along a new axis.
130+
131+
Parameters
132+
----------
133+
arrays: Union[Tuple[array, ...], List[array]]
134+
input arrays to join. Each array must have the same shape.
135+
axis: int
136+
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``.
137+
138+
Returns
139+
--------
140+
out: array
141+
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.
142+
143+
.. note::
144+
This specification leaves type promotion between data type families (i.e., ``intxx`` and ``floatxx``) unspecified.
145+
"""
146+
147+
__all__ = ['concat', 'expand_dims', 'flip', 'permute_dims', 'reshape', 'roll', 'squeeze', 'stack']

0 commit comments

Comments
 (0)
0