Skip to content

Commit 2244ea1

Browse files
authored
Add specifications for array creation functions (#31)
1 parent 05026cd commit 2244ea1

File tree

2 files changed

+271
-0
lines changed

2 files changed

+271
-0
lines changed
Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# Creation Functions
2+
3+
> Array API specification for creating arrays.
4+
5+
A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
6+
7+
- 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.
8+
- Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
9+
10+
<!-- NOTE: please keep the functions in alphabetical order -->
11+
12+
### <a name="arange" href="#arange">#</a> arange(start, /, *, stop=None, step=1, dtype=None)
13+
14+
Returns evenly spaced values within the half-open interval `[start, stop)` as a one-dimensional array.
15+
16+
#### Parameters
17+
18+
- **start**: _Union\[ int, float ]_
19+
20+
- if `stop` is specified, the start of interval (inclusive); otherwise, the end of the interval (exclusive). If `stop` is not specified, the default starting value is `0`.
21+
22+
- **stop**: _Optional\[ Union\[ int, float ] ]_
23+
24+
- the end of the interval. Default: `None`.
25+
26+
_Note: this function cannot guarantee that the interval does not include the `stop` value in those cases where `step` is not an integer and floating-point rounding errors affect the length of the output array._
27+
28+
- **step**: _Union\[ int, float ]_
29+
30+
- the distance between two adjacent elements (`out[i+1] - out[i]`). Default: `1`.
31+
32+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
33+
34+
- output array data type. Default: `None`.
35+
36+
#### Returns
37+
38+
- **out**: _&lt;array&gt;_
39+
40+
- a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)`.
41+
42+
### <a name="empty" href="#empty">#</a> empty(shape, /, *, dtype=None)
43+
44+
Returns an uninitialized array having a specified `shape`.
45+
46+
#### Parameters
47+
48+
- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_
49+
50+
- output array shape.
51+
52+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
53+
54+
- output array data type. Default: `None`.
55+
56+
#### Returns
57+
58+
- **out**: _&lt;array&gt;_
59+
60+
- an array containing uninitialized data.
61+
62+
### <a name="empty_like" href="#empty_like">#</a> empty_like(x, /, *, dtype=None)
63+
64+
Returns an uninitialized array with the same `shape` as an input array `x`.
65+
66+
#### Parameters
67+
68+
- **x**: _&lt;array&gt;_
69+
70+
- input array from which to derive the output array shape.
71+
72+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
73+
74+
- output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`.
75+
76+
#### Returns
77+
78+
- **out**: _&lt;array&gt;_
79+
80+
- an array having the same shape as `x` and containing uninitialized data.
81+
82+
### <a name="eye" href="#eye">#</a> eye(N, /, *, M=None, k=0, dtype=None)
83+
84+
Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewhere.
85+
86+
#### Parameters
87+
88+
- **N**: _int_
89+
90+
- number of rows in the output array.
91+
92+
- **M**: _Optional\[ int ]_
93+
94+
- number of columns in the output array. If `None`, the default number of columns in the output array is `N`. Default: `None`.
95+
96+
- **k**: _Optional\[ int ]_
97+
98+
- index of the diagonal. A positive value refers to an upper diagonal, a negative value to a lower diagonal, and `0` to the main diagonal. Default: `0`.
99+
100+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
101+
102+
- output array data type. Default: `None`.
103+
104+
#### Returns
105+
106+
- **out**: _&lt;array&gt;_
107+
108+
- an array where all elements are equal to zero, except for the `k`th diagonal, whose values are equal to one.
109+
110+
### <a name="full" href="#full">#</a> full(shape, fill_value, /, *, dtype=None)
111+
112+
Returns a new array having a specified `shape` and filled with `fill_value`.
113+
114+
#### Parameters
115+
116+
- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_
117+
118+
- output array shape.
119+
120+
- **fill_value**: _Union\[ int, float ] ]_
121+
122+
- fill value.
123+
124+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
125+
126+
- output array data type. Default: `None`.
127+
128+
#### Returns
129+
130+
- **out**: _&lt;array&gt;_
131+
132+
- an array where every element is equal to `fill_value`.
133+
134+
### <a name="full_like" href="#full_like">#</a> full_like(x, fill_value, /, *, dtype=None)
135+
136+
Returns a new array filled with `fill_value` and having the same `shape` as an input array `x`.
137+
138+
#### Parameters
139+
140+
- **x**: _&lt;array&gt;_
141+
142+
- input array from which to derive the output array shape.
143+
144+
- **fill_value**: _Union\[ int, float ] ]_
145+
146+
- fill value.
147+
148+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
149+
150+
- output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`.
151+
152+
#### Returns
153+
154+
- **out**: _&lt;array&gt;_
155+
156+
- an array having the same shape as `x` and where every element is equal to `fill_value`.
157+
158+
### <a name="linspace" href="#linspace">#</a> linspace(start, stop, num, /, *, dtype=None, endpoint=True)
159+
160+
Returns evenly spaced numbers over a specified interval.
161+
162+
#### Parameters
163+
164+
- **start**: _Union\[ int, float ]_
165+
166+
- the start of the interval.
167+
168+
- **stop**: _Union\[ int, float ]_
169+
170+
- the end of the interval. If `endpoint` is `False`, the function must generate a sequence of `num+1` evenly spaced numbers starting with `start` and ending with `stop` and exclude the `stop` from the returned array such that the returned array consists of evenly spaced numbers over the half-open interval `[start, stop)`. If `endpoint` is `True`, the output array must consist of evenly spaced numbers over the closed interval `[start, stop]`. Default: `True`.
171+
172+
_Note: that the step size changes when `endpoint` is `False`._
173+
174+
- **num**: _int_
175+
176+
- number of samples. Must be a non-negative integer value; otherwise, the function must raise an exception.
177+
178+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
179+
180+
- output array data type. Default: `None`.
181+
182+
- **endpoint**: _Optional\[ bool ]_
183+
184+
- boolean indicating whether to include `stop` in the interval. Default: `True`.
185+
186+
#### Returns
187+
188+
- **out**: _&lt;array&gt;_
189+
190+
- a one-dimensional array containing evenly spaced values.
191+
192+
### <a name="ones" href="#ones">#</a> ones(shape, /, *, dtype=None)
193+
194+
Returns a new array having a specified `shape` and filled with ones.
195+
196+
#### Parameters
197+
198+
- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_
199+
200+
- output array shape.
201+
202+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
203+
204+
- output array data type. Default: `None`.
205+
206+
#### Returns
207+
208+
- **out**: _&lt;array&gt;_
209+
210+
- an array containing ones.
211+
212+
### <a name="ones_like" href="#ones_like">#</a> ones_like(x, /, *, dtype=None)
213+
214+
Returns a new array filled with ones and having the same `shape` as an input array `x`.
215+
216+
#### Parameters
217+
218+
- **x**: _&lt;array&gt;_
219+
220+
- input array from which to derive the output array shape.
221+
222+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
223+
224+
- output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`.
225+
226+
#### Returns
227+
228+
- **out**: _&lt;array&gt;_
229+
230+
- an array having the same shape as `x` and filled with ones.
231+
232+
### <a name="zeros" href="#zeros">#</a> zeros(shape, /, *, dtype=None)
233+
234+
Returns a new array having a specified `shape` and filled with zeros.
235+
236+
#### Parameters
237+
238+
- **shape**: _Union\[ int, Tuple\[ int, ... ] ]_
239+
240+
- output array shape.
241+
242+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
243+
244+
- output array data type. Default: `None`.
245+
246+
#### Returns
247+
248+
- **out**: _&lt;array&gt;_
249+
250+
- an array containing zeros.
251+
252+
### <a name="zeros_like" href="#zeros_like">#</a> zeros_like(x, /, *, dtype=None)
253+
254+
Returns a new array filled with zeros and having the same `shape` as an input array `x`.
255+
256+
#### Parameters
257+
258+
- **x**: _&lt;array&gt;_
259+
260+
- input array from which to derive the output array shape.
261+
262+
- **dtype**: _Optional\[ _&lt;dtype&gt;_ ]_
263+
264+
- output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`.
265+
266+
#### Returns
267+
268+
- **out**: _&lt;array&gt;_
269+
270+
- an array having the same shape as `x` and filled with zeros.

spec/API_specification/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ API specification
1313
casting
1414
broadcasting
1515
out_keyword
16+
creation_functions
1617
elementwise_functions
1718
statistical_functions
1819
searching_functions

0 commit comments

Comments
 (0)